@mxpicture/build-api 0.2.56 → 0.2.58

package/dist/pkg/ExportExtractor.js

@@ -0,0 +1,180 @@
+import { dirname, relative } from "node:path";
+import ts from "typescript";
+import { glob } from "glob";
+import { createRequire } from "node:module";
+import { resolve as resolveExports } from "resolve.exports";
+import { readPackageJson } from "./pkg.fs.js";
+import { initWorkspace } from "../workspace/Workspace.js";
+import { createSourceFileMap } from "../code/code.common.js";
+import { writeFile } from "node:fs/promises";
+import { jsonStringify, JsonStringifyFormat } from "../common/common.json.js";
+const require = createRequire(import.meta.url);
+export const runExportExtractor = async (params) => {
+    initWorkspace(params.repoRoot);
+    const exp = new ExportExtractor(params.package);
+    const result = await exp.run();
+    if (params.json) {
+        await exp.writeJson(params.json, result);
+    }
+    else {
+        const content = await exp.toJson(result);
+        console.log(content);
+    }
+};
+export class ExportExtractor {
+    pkg;
+    /**
+     * Analyze an installed package and produce
+     * a structured API representation.
+     *
+     * @param pkg package name
+     */
+    constructor(pkg) {
+        this.pkg = pkg;
+    }
+    /**
+     * Analyze an installed package and build its API model.
+     */
+    async run() {
+        const root = this.resolvePackageRoot(this.pkg);
+        const pkgJson = await readPackageJson(root);
+        let entrypoints = this.resolveEntrypoints(this.pkg, pkgJson);
+        entrypoints = await this.expandWildcardEntrypoints(root, entrypoints);
+        const runtimeExports = await this.inspectRuntimeExports(entrypoints);
+        const typeExports = await this.parseTypeExports(root);
+        return {
+            packageRoot: root,
+            entrypoints,
+            runtimeExports,
+            typeExports,
+        };
+    }
+    async writeJson(filePath, content) {
+        return writeFile(filePath, await this.toJson(content));
+    }
+    async toJson(content) {
+        return jsonStringify(content, JsonStringifyFormat.jsonStringify);
+    }
+    /**
+     * Resolve the root directory of an installed package.
+     */
+    resolvePackageRoot(pkg) {
+        const pkgJson = require.resolve(`${pkg}/package.json`);
+        return dirname(pkgJson);
+    }
+    /**
+     * Resolve entrypoints using the Node exports algorithm.
+     */
+    resolveEntrypoints(pkg, pkgJson) {
+        const entrypoints = [];
+        if (!pkgJson.exports) {
+            entrypoints.push({ id: pkg });
+            return entrypoints;
+        }
+        const keys = Object.keys(pkgJson.exports);
+        for (const key of keys) {
+            try {
+                const resolved = resolveExports(pkgJson, key, {
+                    conditions: ["node", "import", "require", "default"],
+                });
+                if (!resolved)
+                    continue;
+                const files = Array.isArray(resolved) ? resolved : [resolved];
+                for (const file of files) {
+                    const specifier = key === "." ? pkg : `${pkg}/${key.replace("./", "")}`;
+                    entrypoints.push({
+                        id: specifier,
+                        file,
+                    });
+                }
+            }
+            catch { }
+        }
+        return entrypoints;
+    }
+    /**
+     * Expand wildcard export patterns.
+     */
+    async expandWildcardEntrypoints(root, entrypoints) {
+        return (await Promise.allSettled(entrypoints.map(async (entry) => {
+            if (!entry.file?.includes("*"))
+                return [entry];
+            const pattern = entry.file;
+            const files = await glob.glob(pattern, {
+                cwd: root,
+                absolute: true,
+            });
+            return files.map((file) => ({
+                id: relative(root, file).replace(/\.(js|mjs|cjs)$/, ""),
+                file,
+            }));
+        })))
+            .filter((r) => r.status === "fulfilled")
+            .flatMap((r) => r.value);
+    }
+    /**
+     * Dynamically import a module supporting ESM and CommonJS.
+     */
+    async loadModule(id) {
+        try {
+            return await import(id);
+        }
+        catch {
+            return require(id);
+        }
+    }
+    /**
+     * Extract runtime exports from entrypoints.
+     */
+    async inspectRuntimeExports(entrypoints) {
+        return (await Promise.allSettled(entrypoints.map(async (entry) => {
+            const mod = await this.loadModule(entry.id);
+            return Object.keys(mod).map((name) => ({
+                name,
+                kind: typeof mod[name],
+                source: entry.id,
+            }));
+        })))
+            .filter((r) => r.status === "fulfilled")
+            .flatMap((r) => r.value);
+    }
+    /**
+     * Parse TypeScript declaration files to extract exported types.
+     */
+    async parseTypeExports(root) {
+        const nodes = [];
+        const filePaths = await glob.glob("**/*.d.ts", {
+            cwd: root,
+            absolute: true,
+        });
+        const srcMap = createSourceFileMap(filePaths);
+        for (const filePath of filePaths) {
+            const file = srcMap.get(filePath);
+            if (!file)
+                continue;
+            ts.forEachChild(file.sourceFile, (node) => {
+                if (ts.isInterfaceDeclaration(node) ||
+                    ts.isTypeAliasDeclaration(node) ||
+                    ts.isClassDeclaration(node) ||
+                    ts.isFunctionDeclaration(node)) {
+                    if (!node.name)
+                        return;
+                    nodes.push({
+                        name: node.name.text,
+                        kind: ts.SyntaxKind[node.kind],
+                        source: filePath,
+                    });
+                }
+                if (ts.isEnumDeclaration(node)) {
+                    nodes.push({
+                        name: node.name.text,
+                        kind: "enum",
+                        source: filePath,
+                    });
+                }
+            });
+        }
+        return nodes;
+    }
+}
+//# sourceMappingURL=ExportExtractor.js.map

package/dist/pkg/ExportExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExportExtractor.js","sourceRoot":"","sources":["../../src/pkg/ExportExtractor.ts"],"names":[],"mappings":"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","sourcesContent":["import { dirname, relative } from \"node:path\";\nimport ts from \"typescript\";\nimport { glob } from \"glob\";\nimport { createRequire } from \"node:module\";\nimport { resolve as resolveExports } from \"resolve.exports\";\nimport { readPackageJson } from \"./pkg.fs.js\";\nimport {\n  EntryPoint,\n  ExportExtractorParams,\n  ExportNode,\n  PackageAPI,\n} from \"../types/types.exports.js\";\nimport { initWorkspace } from \"../workspace/Workspace.js\";\nimport { PackageJson } from \"../types/types.package.js\";\nimport { createSourceFileMap } from \"../code/code.common.js\";\nimport { writeFile } from \"node:fs/promises\";\nimport { jsonStringify, JsonStringifyFormat } from \"../common/common.json.js\";\n\nconst require = createRequire(import.meta.url);\n\nexport const runExportExtractor = async (params: ExportExtractorParams) => {\n  initWorkspace(params.repoRoot);\n\n  const exp = new ExportExtractor(params.package);\n  const result = await exp.run();\n  if (params.json) {\n    await exp.writeJson(params.json, result);\n  } else {\n    const content = await exp.toJson(result);\n    console.log(content);\n  }\n};\n\nexport class ExportExtractor {\n  /**\n   * Analyze an installed package and produce\n   * a structured API representation.\n   *\n   * @param pkg package name\n   */\n  public constructor(public readonly pkg: string) {}\n\n  /**\n   * Analyze an installed package and build its API model.\n   */\n  public async run(): Promise<PackageAPI> {\n    const root = this.resolvePackageRoot(this.pkg);\n    const pkgJson = await readPackageJson(root);\n\n    let entrypoints = this.resolveEntrypoints(this.pkg, pkgJson);\n    entrypoints = await this.expandWildcardEntrypoints(root, entrypoints);\n\n    const runtimeExports = await this.inspectRuntimeExports(entrypoints);\n    const typeExports = await this.parseTypeExports(root);\n\n    return {\n      packageRoot: root,\n      entrypoints,\n      runtimeExports,\n      typeExports,\n    };\n  }\n\n  public async writeJson(filePath: string, content: PackageAPI): Promise<void> {\n    return writeFile(filePath, await this.toJson(content));\n  }\n\n  public async toJson(content: PackageAPI): Promise<string> {\n    return jsonStringify(content, JsonStringifyFormat.jsonStringify);\n  }\n\n  /**\n   * Resolve the root directory of an installed package.\n   */\n  protected resolvePackageRoot(pkg: string): string {\n    const pkgJson = require.resolve(`${pkg}/package.json`);\n    return dirname(pkgJson);\n  }\n\n  /**\n   * Resolve entrypoints using the Node exports algorithm.\n   */\n  protected resolveEntrypoints(\n    pkg: string,\n    pkgJson: PackageJson,\n  ): EntryPoint[] {\n    const entrypoints: EntryPoint[] = [];\n\n    if (!pkgJson.exports) {\n      entrypoints.push({ id: pkg });\n      return entrypoints;\n    }\n\n    const keys = Object.keys(pkgJson.exports);\n\n    for (const key of keys) {\n      try {\n        const resolved = resolveExports(pkgJson, key, {\n          conditions: [\"node\", \"import\", \"require\", \"default\"],\n        });\n\n        if (!resolved) continue;\n\n        const files = Array.isArray(resolved) ? resolved : [resolved];\n\n        for (const file of files) {\n          const specifier =\n            key === \".\" ? pkg : `${pkg}/${key.replace(\"./\", \"\")}`;\n\n          entrypoints.push({\n            id: specifier,\n            file,\n          });\n        }\n      } catch {}\n    }\n\n    return entrypoints;\n  }\n\n  /**\n   * Expand wildcard export patterns.\n   */\n  protected async expandWildcardEntrypoints(\n    root: string,\n    entrypoints: EntryPoint[],\n  ): Promise<EntryPoint[]> {\n    return (\n      await Promise.allSettled(\n        entrypoints.map(async (entry) => {\n          if (!entry.file?.includes(\"*\")) return [entry];\n\n          const pattern = entry.file;\n          const files = await glob.glob(pattern, {\n            cwd: root,\n            absolute: true,\n          });\n\n          return files.map((file) => ({\n            id: relative(root, file).replace(/\\.(js|mjs|cjs)$/, \"\"),\n            file,\n          }));\n        }),\n      )\n    )\n      .filter((r) => r.status === \"fulfilled\")\n      .flatMap((r) => r.value);\n  }\n\n  /**\n   * Dynamically import a module supporting ESM and CommonJS.\n   */\n  protected async loadModule(id: string): Promise<Record<string, unknown>> {\n    try {\n      return await import(id);\n    } catch {\n      return require(id);\n    }\n  }\n\n  /**\n   * Extract runtime exports from entrypoints.\n   */\n  protected async inspectRuntimeExports(\n    entrypoints: EntryPoint[],\n  ): Promise<ExportNode[]> {\n    return (\n      await Promise.allSettled(\n        entrypoints.map(async (entry) => {\n          const mod = await this.loadModule(entry.id);\n          return Object.keys(mod).map((name) => ({\n            name,\n            kind: typeof mod[name],\n            source: entry.id,\n          }));\n        }),\n      )\n    )\n      .filter((r) => r.status === \"fulfilled\")\n      .flatMap((r) => r.value);\n  }\n\n  /**\n   * Parse TypeScript declaration files to extract exported types.\n   */\n  protected async parseTypeExports(root: string): Promise<ExportNode[]> {\n    const nodes: ExportNode[] = [];\n\n    const filePaths = await glob.glob(\"**/*.d.ts\", {\n      cwd: root,\n      absolute: true,\n    });\n\n    const srcMap = createSourceFileMap(filePaths);\n\n    for (const filePath of filePaths) {\n      const file = srcMap.get(filePath);\n      if (!file) continue;\n\n      ts.forEachChild(file.sourceFile, (node) => {\n        if (\n          ts.isInterfaceDeclaration(node) ||\n          ts.isTypeAliasDeclaration(node) ||\n          ts.isClassDeclaration(node) ||\n          ts.isFunctionDeclaration(node)\n        ) {\n          if (!node.name) return;\n\n          nodes.push({\n            name: node.name.text,\n            kind: ts.SyntaxKind[node.kind],\n            source: filePath,\n          });\n        }\n\n        if (ts.isEnumDeclaration(node)) {\n          nodes.push({\n            name: node.name.text,\n            kind: \"enum\",\n            source: filePath,\n          });\n        }\n      });\n    }\n\n    return nodes;\n  }\n}\n"]}

package/dist/pkg/Pkg.d.ts

@@ -1,24 +1,93 @@
 import { PackageJson } from "../types/types.package.js";
+/**
+ * Represents a single npm package within a repository workspace.
+ *
+ * @remarks
+ * Wraps a `package.json` file with lazy-load semantics, change-tracking, and
+ * convenience accessors for common directory paths (source, dist, repo-relative).
+ * Content is only read from disk on the first call to {@link Pkg.read} or {@link Pkg.readSync},
+ * and writes are skipped when no modifications have been made.
+ */
 export declare class Pkg {
     readonly repoRoot: string;
     readonly repoPath: string;
+    /** Absolute path to the `package.json` file. */
     readonly filePath: string;
+    /** Absolute path to the package directory. */
     readonly dirPath: string;
+    /** Absolute path to the package `src` directory. */
     readonly srcPath: string;
+    /** Absolute path to the package `dist` directory. */
     readonly distPath: string;
+    /** Repository-relative path to the `package.json` file. */
     readonly repoFilePath: string;
+    /** Repository-relative path to the package directory. */
     readonly repoDirPath: string;
+    /** Repository-relative path to the package `src` directory. */
     readonly repoSrcPath: string;
+    /** Repository-relative path to the package `dist` directory. */
     readonly repoDistPath: string;
     protected _content: PackageJson | null;
     protected originalContent: PackageJson | null;
+    /**
+     * Creates a new Pkg instance for a package at the given repository-relative path.
+     *
+     * @param repoRoot - Absolute path to the repository root.
+     * @param repoPath - Repository-relative path to the package directory.
+     */
     constructor(repoRoot: string, repoPath: string);
+    /**
+     * Returns the loaded package.json content.
+     *
+     * @remarks
+     * Throws if content has not yet been loaded via {@link Pkg.read} or {@link Pkg.readSync}.
+     *
+     * @returns The parsed {@link PackageJson} object.
+     */
     get content(): PackageJson;
     protected set content(c: PackageJson);
+    /**
+     * Checks whether the in-memory content has been modified since it was last read.
+     *
+     * @returns `true` if the current content differs from the original on-disk content.
+     */
     modified(): boolean;
+    /**
+     * Asynchronously reads the `package.json` from disk.
+     *
+     * @remarks
+     * The file is only read once; subsequent calls return the cached content.
+     *
+     * @returns A promise resolving to the parsed {@link PackageJson}.
+     */
     read(): Promise<PackageJson>;
+    /**
+     * Synchronously reads the `package.json` from disk.
+     *
+     * @remarks
+     * The file is only read once; subsequent calls return the cached content.
+     *
+     * @returns The parsed {@link PackageJson}.
+     */
     readSync(): PackageJson;
+    /**
+     * Writes the `package.json` back to disk if it has been modified.
+     *
+     * @remarks
+     * Skips the write and logs an informational message when no changes have been made.
+     *
+     * @returns A promise that resolves when the write operation completes (or is skipped).
+     */
     write(): Promise<void>;
+    /**
+     * Collects all dependency versions declared in the package.
+     *
+     * @remarks
+     * Merges `dependencies`, `devDependencies`, and `peerDependencies` into a
+     * single record. Reads the package from disk if not already loaded.
+     *
+     * @returns A promise resolving to a record mapping package names to their version specifiers.
+     */
     packageVersions(): Promise<Record<string, string>>;
     protected updateOriginal(content?: PackageJson): void;
 }

package/dist/pkg/Pkg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Pkg.d.ts","sourceRoot":"","sources":["../../src/pkg/Pkg.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAUxD,qBAAa,GAAG;aAaI,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,MAAM;IAblC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAQ;IAC9C,SAAS,CAAC,eAAe,EAAE,WAAW,GAAG,IAAI,CAAQ;gBAGnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM;IAYlC,IAAW,OAAO,IAAI,WAAW,CAGhC;IAED,SAAS,KAAK,OAAO,CAAC,CAAC,EAAE,WAAW,EAEnC;IAEM,QAAQ,IAAI,OAAO;IAIb,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;IAQlC,QAAQ,IAAI,WAAW;IAMjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAgB/D,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;CAGtD"}
+{"version":3,"file":"Pkg.d.ts","sourceRoot":"","sources":["../../src/pkg/Pkg.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAUxD;;;;;;;;GAQG;AACH,qBAAa,GAAG;aA2BI,QAAQ,EAAE,MAAM;aAChB,QAAQ,EAAE,MAAM;IA3BlC,gDAAgD;IAChD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,8CAA8C;IAC9C,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,oDAAoD;IACpD,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,qDAAqD;IACrD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,2DAA2D;IAC3D,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,yDAAyD;IACzD,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,+DAA+D;IAC/D,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,gEAAgE;IAChE,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAQ;IAC9C,SAAS,CAAC,eAAe,EAAE,WAAW,GAAG,IAAI,CAAQ;IAErD;;;;;OAKG;gBAEe,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM;IAYlC;;;;;;;OAOG;IACH,IAAW,OAAO,IAAI,WAAW,CAGhC;IAED,SAAS,KAAK,OAAO,CAAC,CAAC,EAAE,WAAW,EAEnC;IAED;;;;OAIG;IACI,QAAQ,IAAI,OAAO;IAI1B;;;;;;;OAOG;IACU,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC;IAQzC;;;;;;;OAOG;IACI,QAAQ,IAAI,WAAW;IAM9B;;;;;;;OAOG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IASnC;;;;;;;;OAQG;IACU,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAgB/D,SAAS,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;CAGtD"}

package/dist/pkg/Pkg.js

@@ -2,19 +2,42 @@ import { join, relative } from "node:path";
 import { logInfo, logSuccess } from "../logger/Logger.js";
 import { ensurePkgJsonPath, readPackageJson, readPackageJsonSync, writePackageJson, } from "./pkg.fs.js";
 import { jsonClone, jsonEqual } from "../common/common.json.js";
+/**
+ * Represents a single npm package within a repository workspace.
+ *
+ * @remarks
+ * Wraps a `package.json` file with lazy-load semantics, change-tracking, and
+ * convenience accessors for common directory paths (source, dist, repo-relative).
+ * Content is only read from disk on the first call to {@link Pkg.read} or {@link Pkg.readSync},
+ * and writes are skipped when no modifications have been made.
+ */
 export class Pkg {
     repoRoot;
     repoPath;
+    /** Absolute path to the `package.json` file. */
     filePath;
+    /** Absolute path to the package directory. */
     dirPath;
+    /** Absolute path to the package `src` directory. */
     srcPath;
+    /** Absolute path to the package `dist` directory. */
     distPath;
+    /** Repository-relative path to the `package.json` file. */
     repoFilePath;
+    /** Repository-relative path to the package directory. */
     repoDirPath;
+    /** Repository-relative path to the package `src` directory. */
     repoSrcPath;
+    /** Repository-relative path to the package `dist` directory. */
     repoDistPath;
     _content = null;
     originalContent = null;
+    /**
+     * Creates a new Pkg instance for a package at the given repository-relative path.
+     *
+     * @param repoRoot - Absolute path to the repository root.
+     * @param repoPath - Repository-relative path to the package directory.
+     */
     constructor(repoRoot, repoPath) {
         this.repoRoot = repoRoot;
         this.repoPath = repoPath;
@@ -27,6 +50,14 @@ export class Pkg {
         this.repoSrcPath = relative(repoRoot, this.srcPath);
         this.repoDistPath = relative(repoRoot, this.distPath);
     }
+    /**
+     * Returns the loaded package.json content.
+     *
+     * @remarks
+     * Throws if content has not yet been loaded via {@link Pkg.read} or {@link Pkg.readSync}.
+     *
+     * @returns The parsed {@link PackageJson} object.
+     */
     get content() {
         if (!this._content)
             throw new Error(`Content not loaded. ${this.filePath}`);
@@ -35,19 +66,48 @@ export class Pkg {
     set content(c) {
         this._content = c;
     }
+    /**
+     * Checks whether the in-memory content has been modified since it was last read.
+     *
+     * @returns `true` if the current content differs from the original on-disk content.
+     */
     modified() {
         return !jsonEqual(this.content, this.originalContent);
     }
+    /**
+     * Asynchronously reads the `package.json` from disk.
+     *
+     * @remarks
+     * The file is only read once; subsequent calls return the cached content.
+     *
+     * @returns A promise resolving to the parsed {@link PackageJson}.
+     */
     async read() {
         if (!this._content)
             this.updateOriginal((this.content = await readPackageJson(this.filePath)));
         return this.content;
     }
+    /**
+     * Synchronously reads the `package.json` from disk.
+     *
+     * @remarks
+     * The file is only read once; subsequent calls return the cached content.
+     *
+     * @returns The parsed {@link PackageJson}.
+     */
     readSync() {
         if (!this._content)
             this.updateOriginal((this.content = readPackageJsonSync(this.filePath)));
         return this.content;
     }
+    /**
+     * Writes the `package.json` back to disk if it has been modified.
+     *
+     * @remarks
+     * Skips the write and logs an informational message when no changes have been made.
+     *
+     * @returns A promise that resolves when the write operation completes (or is skipped).
+     */
     async write() {
         if (this.content && this.modified()) {
             await writePackageJson(this.filePath, this.content);
@@ -57,6 +117,15 @@ export class Pkg {
             logInfo(`  ⏭️ No changes in package.json. ${this.repoFilePath}\n`);
         }
     }
+    /**
+     * Collects all dependency versions declared in the package.
+     *
+     * @remarks
+     * Merges `dependencies`, `devDependencies`, and `peerDependencies` into a
+     * single record. Reads the package from disk if not already loaded.
+     *
+     * @returns A promise resolving to a record mapping package names to their version specifiers.
+     */
     async packageVersions() {
         const pkgJson = await this.read();
         let versions = {};

package/dist/pkg/Pkg.js.map

@@ -1 +1 @@
-{"version":3,"file":"Pkg.js","sourceRoot":"","sources":["../../src/pkg/Pkg.ts"],"names":[],"mappings":"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","sourcesContent":["import { join, relative } from \"node:path\";\nimport { PackageJson } from \"../types/types.package.js\";\nimport { logInfo, logSuccess } from \"../logger/Logger.js\";\nimport {\n  ensurePkgJsonPath,\n  readPackageJson,\n  readPackageJsonSync,\n  writePackageJson,\n} from \"./pkg.fs.js\";\nimport { jsonClone, jsonEqual } from \"../common/common.json.js\";\n\nexport class Pkg {\n  public readonly filePath: string;\n  public readonly dirPath: string;\n  public readonly srcPath: string;\n  public readonly distPath: string;\n  public readonly repoFilePath: string;\n  public readonly repoDirPath: string;\n  public readonly repoSrcPath: string;\n  public readonly repoDistPath: string;\n  protected _content: PackageJson | null = null;\n  protected originalContent: PackageJson | null = null;\n\n  public constructor(\n    public readonly repoRoot: string,\n    public readonly repoPath: string,\n  ) {\n    this.dirPath = join(repoRoot, repoPath);\n    this.filePath = ensurePkgJsonPath(this.dirPath);\n    this.srcPath = join(repoRoot, repoPath, \"src\");\n    this.distPath = join(repoRoot, repoPath, \"dist\");\n    this.repoFilePath = relative(repoRoot, this.filePath);\n    this.repoDirPath = relative(repoRoot, this.dirPath);\n    this.repoSrcPath = relative(repoRoot, this.srcPath);\n    this.repoDistPath = relative(repoRoot, this.distPath);\n  }\n\n  public get content(): PackageJson {\n    if (!this._content) throw new Error(`Content not loaded. ${this.filePath}`);\n    return this._content;\n  }\n\n  protected set content(c: PackageJson) {\n    this._content = c;\n  }\n\n  public modified(): boolean {\n    return !jsonEqual(this.content, this.originalContent);\n  }\n\n  public async read(): Promise<PackageJson> {\n    if (!this._content)\n      this.updateOriginal(\n        (this.content = await readPackageJson(this.filePath)),\n      );\n    return this.content;\n  }\n\n  public readSync(): PackageJson {\n    if (!this._content)\n      this.updateOriginal((this.content = readPackageJsonSync(this.filePath)));\n    return this.content;\n  }\n\n  public async write(): Promise<void> {\n    if (this.content && this.modified()) {\n      await writePackageJson(this.filePath, this.content);\n      logSuccess(`  ✅ package.json updated ${this.repoFilePath}\\n`);\n    } else {\n      logInfo(`  ⏭️ No changes in package.json. ${this.repoFilePath}\\n`);\n    }\n  }\n\n  public async packageVersions(): Promise<Record<string, string>> {\n    const pkgJson = await this.read();\n    let versions: Record<string, string> = {};\n\n    if (pkgJson.dependencies)\n      versions = { ...versions, ...pkgJson.dependencies };\n\n    if (pkgJson.devDependencies)\n      versions = { ...versions, ...pkgJson.devDependencies };\n\n    if (pkgJson.peerDependencies)\n      versions = { ...versions, ...pkgJson.peerDependencies };\n\n    return versions;\n  }\n\n  protected updateOriginal(content?: PackageJson): void {\n    this.originalContent = jsonClone(content ?? this.content);\n  }\n}\n"]}
+{"version":3,"file":"Pkg.js","sourceRoot":"","sources":["../../src/pkg/Pkg.ts"],"names":[],"mappings":"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","sourcesContent":["import { join, relative } from \"node:path\";\nimport { PackageJson } from \"../types/types.package.js\";\nimport { logInfo, logSuccess } from \"../logger/Logger.js\";\nimport {\n  ensurePkgJsonPath,\n  readPackageJson,\n  readPackageJsonSync,\n  writePackageJson,\n} from \"./pkg.fs.js\";\nimport { jsonClone, jsonEqual } from \"../common/common.json.js\";\n\n/**\n * Represents a single npm package within a repository workspace.\n *\n * @remarks\n * Wraps a `package.json` file with lazy-load semantics, change-tracking, and\n * convenience accessors for common directory paths (source, dist, repo-relative).\n * Content is only read from disk on the first call to {@link Pkg.read} or {@link Pkg.readSync},\n * and writes are skipped when no modifications have been made.\n */\nexport class Pkg {\n  /** Absolute path to the `package.json` file. */\n  public readonly filePath: string;\n  /** Absolute path to the package directory. */\n  public readonly dirPath: string;\n  /** Absolute path to the package `src` directory. */\n  public readonly srcPath: string;\n  /** Absolute path to the package `dist` directory. */\n  public readonly distPath: string;\n  /** Repository-relative path to the `package.json` file. */\n  public readonly repoFilePath: string;\n  /** Repository-relative path to the package directory. */\n  public readonly repoDirPath: string;\n  /** Repository-relative path to the package `src` directory. */\n  public readonly repoSrcPath: string;\n  /** Repository-relative path to the package `dist` directory. */\n  public readonly repoDistPath: string;\n  protected _content: PackageJson | null = null;\n  protected originalContent: PackageJson | null = null;\n\n  /**\n   * Creates a new Pkg instance for a package at the given repository-relative path.\n   *\n   * @param repoRoot - Absolute path to the repository root.\n   * @param repoPath - Repository-relative path to the package directory.\n   */\n  public constructor(\n    public readonly repoRoot: string,\n    public readonly repoPath: string,\n  ) {\n    this.dirPath = join(repoRoot, repoPath);\n    this.filePath = ensurePkgJsonPath(this.dirPath);\n    this.srcPath = join(repoRoot, repoPath, \"src\");\n    this.distPath = join(repoRoot, repoPath, \"dist\");\n    this.repoFilePath = relative(repoRoot, this.filePath);\n    this.repoDirPath = relative(repoRoot, this.dirPath);\n    this.repoSrcPath = relative(repoRoot, this.srcPath);\n    this.repoDistPath = relative(repoRoot, this.distPath);\n  }\n\n  /**\n   * Returns the loaded package.json content.\n   *\n   * @remarks\n   * Throws if content has not yet been loaded via {@link Pkg.read} or {@link Pkg.readSync}.\n   *\n   * @returns The parsed {@link PackageJson} object.\n   */\n  public get content(): PackageJson {\n    if (!this._content) throw new Error(`Content not loaded. ${this.filePath}`);\n    return this._content;\n  }\n\n  protected set content(c: PackageJson) {\n    this._content = c;\n  }\n\n  /**\n   * Checks whether the in-memory content has been modified since it was last read.\n   *\n   * @returns `true` if the current content differs from the original on-disk content.\n   */\n  public modified(): boolean {\n    return !jsonEqual(this.content, this.originalContent);\n  }\n\n  /**\n   * Asynchronously reads the `package.json` from disk.\n   *\n   * @remarks\n   * The file is only read once; subsequent calls return the cached content.\n   *\n   * @returns A promise resolving to the parsed {@link PackageJson}.\n   */\n  public async read(): Promise<PackageJson> {\n    if (!this._content)\n      this.updateOriginal(\n        (this.content = await readPackageJson(this.filePath)),\n      );\n    return this.content;\n  }\n\n  /**\n   * Synchronously reads the `package.json` from disk.\n   *\n   * @remarks\n   * The file is only read once; subsequent calls return the cached content.\n   *\n   * @returns The parsed {@link PackageJson}.\n   */\n  public readSync(): PackageJson {\n    if (!this._content)\n      this.updateOriginal((this.content = readPackageJsonSync(this.filePath)));\n    return this.content;\n  }\n\n  /**\n   * Writes the `package.json` back to disk if it has been modified.\n   *\n   * @remarks\n   * Skips the write and logs an informational message when no changes have been made.\n   *\n   * @returns A promise that resolves when the write operation completes (or is skipped).\n   */\n  public async write(): Promise<void> {\n    if (this.content && this.modified()) {\n      await writePackageJson(this.filePath, this.content);\n      logSuccess(`  ✅ package.json updated ${this.repoFilePath}\\n`);\n    } else {\n      logInfo(`  ⏭️ No changes in package.json. ${this.repoFilePath}\\n`);\n    }\n  }\n\n  /**\n   * Collects all dependency versions declared in the package.\n   *\n   * @remarks\n   * Merges `dependencies`, `devDependencies`, and `peerDependencies` into a\n   * single record. Reads the package from disk if not already loaded.\n   *\n   * @returns A promise resolving to a record mapping package names to their version specifiers.\n   */\n  public async packageVersions(): Promise<Record<string, string>> {\n    const pkgJson = await this.read();\n    let versions: Record<string, string> = {};\n\n    if (pkgJson.dependencies)\n      versions = { ...versions, ...pkgJson.dependencies };\n\n    if (pkgJson.devDependencies)\n      versions = { ...versions, ...pkgJson.devDependencies };\n\n    if (pkgJson.peerDependencies)\n      versions = { ...versions, ...pkgJson.peerDependencies };\n\n    return versions;\n  }\n\n  protected updateOriginal(content?: PackageJson): void {\n    this.originalContent = jsonClone(content ?? this.content);\n  }\n}\n"]}

package/dist/pkg/SyncPkgVersion.d.ts

@@ -1,10 +1,45 @@
 import { BumpParams, SyncPkgVersionParams } from "../types/types.package.js";
 import { Pkg } from "./Pkg.js";
+/**
+ * Initializes the workspace and runs the package-version synchronization workflow.
+ *
+ * @remarks
+ * This is a convenience entry point that constructs a {@link SyncPkgVersion} instance
+ * and immediately invokes its {@link SyncPkgVersion.run} method.
+ *
+ * @param params - Configuration for the sync operation, including repo root, bump flags, and tag options.
+ * @returns A promise that resolves when all package versions have been synchronized.
+ */
 export declare const runSyncPkgVersion: (params: SyncPkgVersionParams) => Promise<void>;
+/**
+ * Synchronizes version numbers across all workspace packages.
+ *
+ * @remarks
+ * Determines the highest version from existing git tags and current package versions,
+ * optionally bumps it according to the provided {@link BumpParams}, then writes the
+ * new version to every workspace package. When tagging is enabled, an annotated git
+ * tag is created and pushed.
+ */
 export declare class SyncPkgVersion {
     protected readonly bump: BumpParams | null;
     protected readonly noTag: boolean;
+    /**
+     * Creates a new SyncPkgVersion instance.
+     *
+     * @param bump - The semver component to bump, or `null` to skip bumping.
+     * @param noTag - When `true`, skips creating and pushing a git tag.
+     */
     constructor(bump: BumpParams | null, noTag: boolean);
+    /**
+     * Executes the full version synchronization workflow.
+     *
+     * @remarks
+     * The workflow reads all workspace packages, collects existing git tag versions,
+     * determines the maximum version, optionally bumps it, writes the new version
+     * to all packages, and optionally creates and pushes an annotated git tag.
+     *
+     * @returns A promise that resolves when the synchronization is complete.
+     */
     run(): Promise<void>;
     protected read(): Promise<Pkg[]>;
     protected write(): Promise<void>;

package/dist/pkg/SyncPkgVersion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SyncPkgVersion.d.ts","sourceRoot":"","sources":["../../src/pkg/SyncPkgVersion.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAUnC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,eAAO,MAAM,iBAAiB,GAAU,QAAQ,oBAAoB,kBAOnE,CAAC;AAEF,qBAAa,cAAc;IAEvB,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAC1C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO;gBADd,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,KAAK,EAAE,OAAO;IAGtB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;cAyDjB,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;cAKtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvC"}
+{"version":3,"file":"SyncPkgVersion.d.ts","sourceRoot":"","sources":["../../src/pkg/SyncPkgVersion.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAUnC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAU,QAAQ,oBAAoB,kBAOnE,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAQvB,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAC1C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO;IARnC;;;;;OAKG;gBAEkB,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,KAAK,EAAE,OAAO;IAGnC;;;;;;;;;OASG;IACU,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;cAyDjB,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;cAKtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvC"}

package/dist/pkg/SyncPkgVersion.js

@@ -1,17 +1,52 @@
 import { bumpVersion, compareVersions, compareVersionsGT, concatVersion, splitVersion, } from "./pkg.common.js";
 import { tags, verifiedGit } from "../git/git.util.js";
 import { initWorkspace, workspace } from "../workspace/Workspace.js";
+/**
+ * Initializes the workspace and runs the package-version synchronization workflow.
+ *
+ * @remarks
+ * This is a convenience entry point that constructs a {@link SyncPkgVersion} instance
+ * and immediately invokes its {@link SyncPkgVersion.run} method.
+ *
+ * @param params - Configuration for the sync operation, including repo root, bump flags, and tag options.
+ * @returns A promise that resolves when all package versions have been synchronized.
+ */
 export const runSyncPkgVersion = async (params) => {
     initWorkspace(params.repoRoot);
     return new SyncPkgVersion(params.noBump ? null : (params.bump ?? { patch: true }), !!params.noTag).run();
 };
+/**
+ * Synchronizes version numbers across all workspace packages.
+ *
+ * @remarks
+ * Determines the highest version from existing git tags and current package versions,
+ * optionally bumps it according to the provided {@link BumpParams}, then writes the
+ * new version to every workspace package. When tagging is enabled, an annotated git
+ * tag is created and pushed.
+ */
 export class SyncPkgVersion {
     bump;
     noTag;
+    /**
+     * Creates a new SyncPkgVersion instance.
+     *
+     * @param bump - The semver component to bump, or `null` to skip bumping.
+     * @param noTag - When `true`, skips creating and pushing a git tag.
+     */
     constructor(bump, noTag) {
         this.bump = bump;
         this.noTag = noTag;
     }
+    /**
+     * Executes the full version synchronization workflow.
+     *
+     * @remarks
+     * The workflow reads all workspace packages, collects existing git tag versions,
+     * determines the maximum version, optionally bumps it, writes the new version
+     * to all packages, and optionally creates and pushes an annotated git tag.
+     *
+     * @returns A promise that resolves when the synchronization is complete.
+     */
     async run() {
         const packages = await this.read();
         const existingTags = await tags(workspace().repoRoot);

package/dist/pkg/SyncPkgVersion.js.map

@@ -1 +1 @@
-{"version":3,"file":"SyncPkgVersion.js","sourceRoot":"","sources":["../../src/pkg/SyncPkgVersion.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BumpParams,\n  PackageVersion,\n  SyncPkgVersionParams,\n} from \"../types/types.package.js\";\nimport {\n  bumpVersion,\n  compareVersions,\n  compareVersionsGT,\n  concatVersion,\n  splitVersion,\n} from \"./pkg.common.js\";\nimport { tags, verifiedGit } from \"../git/git.util.js\";\nimport { initWorkspace, workspace } from \"../workspace/Workspace.js\";\nimport { Pkg } from \"./Pkg.js\";\n\nexport const runSyncPkgVersion = async (params: SyncPkgVersionParams) => {\n  initWorkspace(params.repoRoot);\n\n  return new SyncPkgVersion(\n    params.noBump ? null : (params.bump ?? { patch: true }),\n    !!params.noTag,\n  ).run();\n};\n\nexport class SyncPkgVersion {\n  public constructor(\n    protected readonly bump: BumpParams | null,\n    protected readonly noTag: boolean,\n  ) {}\n\n  public async run(): Promise<void> {\n    const packages = await this.read();\n    const existingTags = await tags(workspace().repoRoot);\n    const tagVersions: PackageVersion[] = [];\n\n    for (const existingTag of existingTags) {\n      try {\n        tagVersions.push(splitVersion(existingTag));\n      } catch {}\n    }\n\n    // descending\n    tagVersions.sort((a, b) => compareVersions(a, b) * -1);\n    packages.sort(\n      (a, b) => compareVersions(a.content.version, b.content.version) * -1,\n    );\n\n    const tagMaxVersion = tagVersions.shift() ?? {\n      major: 0,\n      minor: 0,\n      patch: 0,\n      prefix: null,\n    };\n    tagMaxVersion.prefix = null;\n\n    const pkg = packages.length > 0 ? packages[0] : null;\n    const pkgMaxVersion = pkg\n      ? splitVersion(pkg.content.version)\n      : {\n          major: 0,\n          minor: 0,\n          patch: 0,\n          prefix: null,\n        };\n    pkgMaxVersion.prefix = null;\n\n    let maxVersion = compareVersionsGT(tagMaxVersion, pkgMaxVersion)\n      ? tagMaxVersion\n      : pkgMaxVersion;\n\n    // bump\n    if (this.bump) maxVersion = bumpVersion(maxVersion, this.bump);\n    const newVersion = concatVersion(maxVersion);\n\n    // set/update\n    for (const entry of packages) entry.content.version = newVersion;\n\n    await this.write();\n\n    // create tag\n    if (!this.noTag) {\n      const git = await verifiedGit(workspace().repoRoot);\n      await git.addAnnotatedTag(`v${newVersion}`, `Release v${newVersion}`);\n      await git.pushTags();\n    }\n  }\n\n  protected async read(): Promise<Pkg[]> {\n    const ws = await workspace().read();\n    return [ws.rootPackage, ...ws.packages];\n  }\n\n  protected async write(): Promise<void> {\n    return workspace().write();\n  }\n}\n"]}
+{"version":3,"file":"SyncPkgVersion.js","sourceRoot":"","sources":["../../src/pkg/SyncPkgVersion.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BumpParams,\n  PackageVersion,\n  SyncPkgVersionParams,\n} from \"../types/types.package.js\";\nimport {\n  bumpVersion,\n  compareVersions,\n  compareVersionsGT,\n  concatVersion,\n  splitVersion,\n} from \"./pkg.common.js\";\nimport { tags, verifiedGit } from \"../git/git.util.js\";\nimport { initWorkspace, workspace } from \"../workspace/Workspace.js\";\nimport { Pkg } from \"./Pkg.js\";\n\n/**\n * Initializes the workspace and runs the package-version synchronization workflow.\n *\n * @remarks\n * This is a convenience entry point that constructs a {@link SyncPkgVersion} instance\n * and immediately invokes its {@link SyncPkgVersion.run} method.\n *\n * @param params - Configuration for the sync operation, including repo root, bump flags, and tag options.\n * @returns A promise that resolves when all package versions have been synchronized.\n */\nexport const runSyncPkgVersion = async (params: SyncPkgVersionParams) => {\n  initWorkspace(params.repoRoot);\n\n  return new SyncPkgVersion(\n    params.noBump ? null : (params.bump ?? { patch: true }),\n    !!params.noTag,\n  ).run();\n};\n\n/**\n * Synchronizes version numbers across all workspace packages.\n *\n * @remarks\n * Determines the highest version from existing git tags and current package versions,\n * optionally bumps it according to the provided {@link BumpParams}, then writes the\n * new version to every workspace package. When tagging is enabled, an annotated git\n * tag is created and pushed.\n */\nexport class SyncPkgVersion {\n  /**\n   * Creates a new SyncPkgVersion instance.\n   *\n   * @param bump - The semver component to bump, or `null` to skip bumping.\n   * @param noTag - When `true`, skips creating and pushing a git tag.\n   */\n  public constructor(\n    protected readonly bump: BumpParams | null,\n    protected readonly noTag: boolean,\n  ) {}\n\n  /**\n   * Executes the full version synchronization workflow.\n   *\n   * @remarks\n   * The workflow reads all workspace packages, collects existing git tag versions,\n   * determines the maximum version, optionally bumps it, writes the new version\n   * to all packages, and optionally creates and pushes an annotated git tag.\n   *\n   * @returns A promise that resolves when the synchronization is complete.\n   */\n  public async run(): Promise<void> {\n    const packages = await this.read();\n    const existingTags = await tags(workspace().repoRoot);\n    const tagVersions: PackageVersion[] = [];\n\n    for (const existingTag of existingTags) {\n      try {\n        tagVersions.push(splitVersion(existingTag));\n      } catch {}\n    }\n\n    // descending\n    tagVersions.sort((a, b) => compareVersions(a, b) * -1);\n    packages.sort(\n      (a, b) => compareVersions(a.content.version, b.content.version) * -1,\n    );\n\n    const tagMaxVersion = tagVersions.shift() ?? {\n      major: 0,\n      minor: 0,\n      patch: 0,\n      prefix: null,\n    };\n    tagMaxVersion.prefix = null;\n\n    const pkg = packages.length > 0 ? packages[0] : null;\n    const pkgMaxVersion = pkg\n      ? splitVersion(pkg.content.version)\n      : {\n          major: 0,\n          minor: 0,\n          patch: 0,\n          prefix: null,\n        };\n    pkgMaxVersion.prefix = null;\n\n    let maxVersion = compareVersionsGT(tagMaxVersion, pkgMaxVersion)\n      ? tagMaxVersion\n      : pkgMaxVersion;\n\n    // bump\n    if (this.bump) maxVersion = bumpVersion(maxVersion, this.bump);\n    const newVersion = concatVersion(maxVersion);\n\n    // set/update\n    for (const entry of packages) entry.content.version = newVersion;\n\n    await this.write();\n\n    // create tag\n    if (!this.noTag) {\n      const git = await verifiedGit(workspace().repoRoot);\n      await git.addAnnotatedTag(`v${newVersion}`, `Release v${newVersion}`);\n      await git.pushTags();\n    }\n  }\n\n  protected async read(): Promise<Pkg[]> {\n    const ws = await workspace().read();\n    return [ws.rootPackage, ...ws.packages];\n  }\n\n  protected async write(): Promise<void> {\n    return workspace().write();\n  }\n}\n"]}

package/dist/pkg/UpdatePackages.d.ts

@@ -1,9 +1,45 @@
 import { PackageJson, UpdatePackagesParams } from "../types/types.package.js";
+/**
+ * Initializes the workspace and runs the package-update workflow.
+ *
+ * @remarks
+ * This is a convenience entry point that constructs an {@link UpdatePackages} instance
+ * and immediately invokes its {@link UpdatePackages.run} method.
+ *
+ * @param params - Configuration for the update, including the repo root and a glob pattern to select packages.
+ * @returns A promise that resolves when all matching packages have been updated and verified.
+ */
 export declare const runUpdatePackages: (params: UpdatePackagesParams) => Promise<void>;
+/**
+ * Bulk-updates dependencies matching a glob pattern across all workspace packages.
+ *
+ * @remarks
+ * The update pipeline performs five sequential steps:
+ * 1. Discover matching dependencies across every workspace package.
+ * 2. Run `pnpm update -r --latest` for the matched packages.
+ * 3. Deduplicate the dependency tree with `pnpm dedupe`.
+ * 4. Remove stale duplicate versions from `node_modules/.pnpm`.
+ * 5. Verify that all workspaces converge on the same version for each package.
+ */
 export declare class UpdatePackages {
     protected readonly pattern: string;
     protected patternWoSlash: string;
+    /**
+     * Creates a new UpdatePackages instance.
+     *
+     * @param pattern - A glob pattern used to match dependency names (e.g. `"@angular/*"`).
+     */
     constructor(pattern: string);
+    /**
+     * Executes the full package-update pipeline.
+     *
+     * @remarks
+     * Discovers matching packages, updates them, deduplicates, cleans old versions,
+     * and verifies consistency. Exits the process with code 1 if version
+     * inconsistencies are detected after the update.
+     *
+     * @returns A promise that resolves when the pipeline completes successfully.
+     */
     run(): Promise<void>;
     protected exec(command: string): Promise<string>;
     protected getPackages(): Promise<Set<string>>;