pncat/dist/index.d.mts

Enhanced pnpm catalogs management with advanced workspace dependency control.

import { PackageJson } from 'pkg-types';
import { PnpmWorkspaceYamlSchema, PnpmWorkspaceYaml } from 'pnpm-workspace-yaml';

declare const MODE_CHOICES: readonly ["detect", "migrate", "add", "remove", "clean", "revert"];
declare const DEPS_FIELDS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies", "pnpm.overrides", "resolutions", "pnpm-workspace"];

interface CatalogRule {
    name: string;
    match: string | RegExp | (string | RegExp)[];
    depFields?: DepType[];
    priority?: number;
    specifierRules?: SpecifierRule[];
}
interface SpecifierRule {
    /**
     * Semver range, e.g., ">=3.0.0", "<3.0.0"
     */
    specifier: string;
    /**
     * Specific packages this version range applies to.
     * If not specified, applies to all packages matched by the parent CatalogRule.
     */
    match?: string | RegExp | (string | RegExp)[];
    /**
     * Complete catalog name, takes priority over suffix
     */
    name?: string;
    /**
     * Catalog suffix, e.g., "v3", "v2"
     */
    suffix?: string;
}
interface SpecifierOptions {
    /**
     * Whether to skip complex version ranges (e.g., "||", "-", ">=16.0.0")
     * @default true
     */
    skipComplexRanges?: boolean;
    /**
     * List of specific range types to skip (overrides skipComplexRanges)
     * Example: ["||", "-", ">=", "<", "x", "*", "pre-release"]
     */
    skipRangeTypes?: SpecifierRangeType[];
    /**
     * Whether to allow pre-release versions (e.g., "4.0.0-beta")
     * @default true
     */
    allowPreReleases?: boolean;
    /**
     * Whether to allow wildcard versions (e.g., "3.x", "*")
     * @default false
     */
    allowWildcards?: boolean;
}
type SpecifierRangeType = '||' | '-' | '>=' | '<=' | '>' | '<' | 'x' | '*' | 'pre-release';

type RangeMode = typeof MODE_CHOICES[number];
type DepType = typeof DEPS_FIELDS[number];
type DepFieldOptions = Partial<Record<DepType, boolean>>;
type DepFilter = (name: string, specifier: string) => boolean;
interface CommandOptions {
    cwd?: string;
    mode?: RangeMode;
    /**
     * Recursively search for package.json in subdirectories
     */
    recursive?: boolean;
    /**
     * Force the execution of the command
     */
    force?: boolean;
    /**
     * Prompt for confirmation
     */
    yes?: boolean;
    /**
     * Run pnpm install after command
     */
    install?: boolean;
    /**
     * Show complete pnpm-workspace.yaml instead of only the diff
     */
    verbose?: boolean;
}
interface ConfigOptions {
    /**
     * Only included dependencies will be checked for catalog
     */
    include?: string | string[];
    /**
     * Exclude dependencies to be checked, will override --include options
     */
    exclude?: string | string[];
    /**
     * Paths to ignore
     */
    ignorePaths?: string | string[];
    /**
     * Ignore other workspaces
     */
    ignoreOtherWorkspaces?: boolean;
    /**
     * Install from a specific catalog, auto detect if not provided
     */
    catalog?: string;
    /**
     * Fields in package.json to be checked
     * By default check `dependencies`, `devDependencies` and `peerDependencies`
     */
    depFields?: DepFieldOptions;
    /**
     * Allowed protocols in specifier to not be converted to catalog
     */
    allowedProtocols?: string[];
}
interface CatalogOptions extends CommandOptions, ConfigOptions {
    /**
     * Rules to group and name dependencies in the catalog output
     */
    catalogRules?: CatalogRule[];
    /**
     * Options to control how specifier ranges are processed
     */
    specifierOptions?: SpecifierOptions;
}

interface RawDep {
    name: string;
    specifier: string;
    source: DepType;
    /**
     * Path of dependency in the package.json
     */
    parents?: string[];
    /**
     * Is the dependency a catalog
     */
    catalog: boolean;
    /**
     * Is the dependency can be cataloged
     */
    catalogable: boolean;
    /**
     * Inference catalog name by catalog rules
     */
    catalogName: string;
    /**
     * Is the dependency updated by catalog rules
     */
    update?: boolean;
}
interface BasePackageMeta {
    /**
     * Package name
     */
    name: string;
    /**
     * Is private package
     */
    private?: boolean;
    /**
     * Package version
     */
    version?: string;
    /**
     * Absolute filepath
     */
    filepath: string;
    /**
     * Relative filepath to the root project
     */
    relative: string;
    /**
     * Dependencies
     */
    deps: RawDep[];
}
interface PackageJsonMeta extends BasePackageMeta {
    /**
     * Package type
     */
    type: 'package.json';
    /**
     * Raw package.json Object
     */
    raw: PackageJson;
}
interface PnpmWorkspaceMeta extends BasePackageMeta {
    type: 'pnpm-workspace.yaml';
    raw: PnpmWorkspaceYamlSchema;
    context: PnpmWorkspaceYaml;
}
type PackageMeta = PackageJsonMeta | PnpmWorkspaceMeta;
interface ParsedSpec {
    name: string;
    specifier?: string;
    catalogName?: string;
    specifierSource?: 'user' | 'catalog' | 'workspace' | 'npm';
}

declare class PnpmCatalogManager {
    private loaded;
    private loadTask;
    private options;
    private packages;
    private packageRegistry;
    private catalogRegistry;
    private packageDepIndex;
    private catalogDepIndex;
    private depUsageIndex;
    constructor(options: CatalogOptions);
    /**
     * Reset the catalog manager, clear all indexes and loaded packages
     */
    reset(): void;
    /**
     * Get the catalog options
     */
    getOptions(): CatalogOptions;
    /**
     * Get the current working directory
     */
    getCwd(): string;
    /**
     * Load packages from the current working directory
     */
    loadPackages(): Promise<PackageMeta[]>;
    /**
     * Get the names of monorepo packages
     */
    getWorkspacePackages(): string[];
    /**
     * Get the dependencies of a package
     */
    getPackageDeps(pkgName: string): RawDep[];
    /**
     * Get a dependency of a package
     */
    getPackageDep(depName: string, pkgName: string): RawDep | null;
    /**
     * Remove a dependency from a package
     */
    removePackageDep(depName: string, catalogName: string, isRecursive?: boolean, updatedPackages?: Map<string, PackageJsonMeta>): Promise<{
        updatedPackages: Map<string, PackageJsonMeta>;
        catalogDeletable: boolean;
    }>;
    /**
     * Get the dependencies of a catalog
     */
    getCatalogDeps(catalogName: string): RawDep[];
    /**
     * Get a dependency of a catalog
     */
    getCatalogDep(depName: string, catalogName: string): RawDep | null;
    /**
     * Get the packages that use a dependency
     */
    getDepPackages(depName: string): string[];
    /**
     * Infer the catalog name for a dependency
     */
    inferCatalogName(dep: Omit<RawDep, 'catalogName'>): string;
    /**
     * Check if a specifier is a catalog specifier
     */
    isCatalogSpecifier(specifier: string): boolean;
    /**
     * Extract the catalog name from a specifier
     */
    extractCatalogName(specifier: string): string;
    /**
     * Check if a specifier is a catalog package name
     */
    isCatalogPackageName(pkgName: string): boolean;
    /**
     * Extract the catalog name from a package name
     */
    extractCatalogNameFromPackageName(pkgName: string): string;
    /**
     * Resolve a dependency, update the catalog name if needed
     */
    resolveDep(dep: RawDep, force?: boolean): RawDep;
    /**
     * Resolve a catalog dependency, get the specifier from the catalog
     */
    resolveCatalogDep(dep: RawDep): RawDep | null;
    /**
     * Check if a catalog dependency is in a package
     */
    isDepInPackage(catalogDep: RawDep): boolean;
    /**
     * Check if a package dependency is in a catalog
     */
    isDepInCatalog(pkgDep: RawDep): boolean;
    /**
     * Create indexes for the loaded packages
     */
    private createIndexes;
    /**
     * Set the package dependency index
     */
    private setPackageDepIndex;
    /**
     * Set the pnpm workspace dependency index
     */
    private setCatalogDepIndex;
    /**
     * Set the dependency usage index
     */
    private setDepUsageIndex;
}

declare const DEFAULT_CATALOG_RULES: CatalogRule[];

declare function inferCatalogName(dep: Omit<RawDep, 'catalogName'>, options: CatalogOptions): string;

interface MergeOptions {
    mergeDefaults?: boolean;
    arrayMerge?: (target: CatalogRule[], source: CatalogRule[]) => CatalogRule[];
}
declare function mergeCatalogRules(options: MergeOptions, ...rules: CatalogRule[][]): CatalogRule[];
declare function mergeCatalogRules(...rules: CatalogRule[][]): CatalogRule[];

declare function defineConfig(config: Partial<CatalogOptions>): Partial<CatalogOptions>;

export { DEFAULT_CATALOG_RULES, PnpmCatalogManager, defineConfig, inferCatalogName, mergeCatalogRules };
export type { BasePackageMeta, CatalogOptions, CatalogRule, CommandOptions, ConfigOptions, DepFieldOptions, DepFilter, DepType, MergeOptions, PackageJsonMeta, PackageMeta, ParsedSpec, PnpmWorkspaceMeta, RangeMode, RawDep, SpecifierOptions, SpecifierRangeType, SpecifierRule };