@mxpicture/build-api 0.2.55 → 0.2.57

package/dist/deps/FixWorkspaceDeps.js

@@ -2,18 +2,74 @@ import { relative } from "path";
 import { logError, logInfo, logSuccess } from "../logger/Logger.js";
 import { DepsReplacementMode, } from "../types/types.deps.js";
 import { initWorkspace, workspace } from "../workspace/Workspace.js";
+/**
+ * Fix or restore workspace dependency references across all packages.
+ *
+ * @remarks
+ * Initializes the workspace from the given repository root, selects the
+ * appropriate replacement strategy ({@link FixWorkspaceDepsVersion} or
+ * {@link FixWorkspaceDepsFile}), and executes the full fix/restore run.
+ *
+ * @param p - Parameters specifying the repo root, processing mode, and replacement strategy.
+ * @returns A promise that resolves when all workspace dependencies have been processed and written.
+ *
+ * @example
+ * ```ts
+ * await runFixDeps({
+ *   repoRoot: "/path/to/repo",
+ *   mode: DepsProcessMode.fix,
+ *   replacement: DepsReplacementMode.version,
+ * });
+ * ```
+ */
 export const runFixDeps = async (p) => {
     initWorkspace(p.repoRoot);
     return instanceFixDeps(p).run();
 };
+/**
+ * Create the appropriate {@link IFixWorkspaceDeps} instance for the given replacement mode.
+ *
+ * @remarks
+ * Acts as a factory function that returns a {@link FixWorkspaceDepsVersion}
+ * when the replacement mode is `version`, or a {@link FixWorkspaceDepsFile}
+ * when it is `file`.
+ *
+ * @param p - Object containing the processing mode and replacement strategy.
+ * @returns A concrete {@link IFixWorkspaceDeps} subclass ready to execute.
+ */
 export const instanceFixDeps = (p) => p.replacement === DepsReplacementMode.version
     ? new FixWorkspaceDepsVersion(p.mode)
     : new FixWorkspaceDepsFile(p.mode);
+/**
+ * Abstract base class for fixing or restoring workspace dependency references.
+ *
+ * @remarks
+ * Implements the template-method pattern: subclasses provide concrete
+ * {@link IFixWorkspaceDeps.fixVersion | fixVersion} and
+ * {@link IFixWorkspaceDeps.restoreVersion | restoreVersion} implementations
+ * while the base class orchestrates reading, processing, and writing all
+ * workspace packages.
+ */
 export class IFixWorkspaceDeps {
     mode;
+    /**
+     * Create a new workspace dependency fixer.
+     *
+     * @param mode - Whether to `fix` (replace `workspace:*`) or `restore` (revert to `workspace:*`).
+     */
     constructor(mode) {
         this.mode = mode;
     }
+    /**
+     * Execute the full fix or restore operation across every workspace package.
+     *
+     * @remarks
+     * Reads the workspace, builds a version map and map entries, iterates over
+     * each package to apply the appropriate transformation, and writes all
+     * modified `package.json` files back to disk.
+     *
+     * @returns A promise that resolves when all packages have been written.
+     */
     async run() {
         if (this.mode === "fix")
             logInfo("🔧 Fixing workspace dependencies...\n");
@@ -53,7 +109,12 @@ export class IFixWorkspaceDeps {
         else
             logSuccess("✅ Done restoring workspace dependencies!");
     }
-    // Replace workspace:* with file:...
+    /**
+     * Process a single dependency map, replacing matching versions in place.
+     *
+     * @param deps - The dependency record (e.g. `dependencies`, `devDependencies`) to mutate.
+     * @param p - Contextual data for the consuming package and workspace.
+     */
     handleDependencies(deps, p) {
         if (!deps)
             return;
@@ -66,12 +127,27 @@ export class IFixWorkspaceDeps {
             deps[name] = newVersion;
         }
     }
+    /**
+     * Process all dependency groups for a single consuming package.
+     *
+     * @param p - Contextual data including the consuming package, map entries, and version map.
+     */
     runSingle(p) {
         this.handleDependencies(p.consumingPkg.content.dependencies, p);
         this.handleDependencies(p.consumingPkg.content.devDependencies, p);
         this.handleDependencies(p.consumingPkg.content.peerDependencies, p);
     }
-    // Build a map of package names to their versions
+    /**
+     * Build pairwise mapping entries between all workspace packages.
+     *
+     * @remarks
+     * Produces a cartesian product (excluding self-pairs) of packages, computing
+     * the relative filesystem path from each source package to every other
+     * target package.
+     *
+     * @param pkgs - The list of workspace packages.
+     * @returns An array of {@link MapEntry} objects describing each package-to-package relationship.
+     */
     buildMapEntries(pkgs) {
         const versionEntries = [];
         for (const fromPkg of pkgs)
@@ -85,7 +161,22 @@ export class IFixWorkspaceDeps {
         return versionEntries;
     }
 }
+/**
+ * Workspace dependency fixer that replaces `workspace:*` with caret version ranges.
+ *
+ * @remarks
+ * During a `fix` pass, `workspace:*` is replaced with `^{resolved-version}`.
+ * During a `restore` pass, caret-prefixed versions that match the workspace
+ * version map are reverted back to `workspace:*`.
+ */
 export class FixWorkspaceDepsVersion extends IFixWorkspaceDeps {
+    /**
+     * Replace a `workspace:*` reference with a caret version range.
+     *
+     * @param p - Data about the dependency being processed.
+     * @returns A string like `^1.2.3`, or `null` if the dependency is not `workspace:*`.
+     * @throws Error if the package cannot be found in the workspace version map.
+     */
     fixVersion(p) {
         if (p.version !== "workspace:*")
             return null;
@@ -96,6 +187,12 @@ export class FixWorkspaceDepsVersion extends IFixWorkspaceDeps {
         }
         return `^${actualVersion}`;
     }
+    /**
+     * Restore a caret version range back to `workspace:*`.
+     *
+     * @param p - Data about the dependency being processed.
+     * @returns The string `workspace:*` if the version matches the expected caret range, or `null` otherwise.
+     */
     restoreVersion(p) {
         if (p.workspacePackages.has(p.pkg) && p.version.startsWith("^")) {
             // Verify the version matches what fix script would have created
@@ -107,7 +204,22 @@ export class FixWorkspaceDepsVersion extends IFixWorkspaceDeps {
         return null;
     }
 }
+/**
+ * Workspace dependency fixer that replaces `workspace:*` with `file:` protocol paths.
+ *
+ * @remarks
+ * During a `fix` pass, `workspace:*` is replaced with a relative `file:` path
+ * pointing to the dependency's package directory.
+ * During a `restore` pass, any `file:`-prefixed version is reverted to `workspace:*`.
+ */
 export class FixWorkspaceDepsFile extends IFixWorkspaceDeps {
+    /**
+     * Replace a `workspace:*` reference with a relative `file:` path.
+     *
+     * @param p - Data about the dependency being processed.
+     * @returns A string like `file:../sibling-pkg`, or `null` if the dependency is not `workspace:*`.
+     * @throws Error if no map entry can be found for the dependency.
+     */
     fixVersion(p) {
         if (p.version !== "workspace:*")
             return null;
@@ -119,6 +231,12 @@ export class FixWorkspaceDepsFile extends IFixWorkspaceDeps {
         }
         return `file:${mapEntry.relPath}`;
     }
+    /**
+     * Restore a `file:` path reference back to `workspace:*`.
+     *
+     * @param p - Data about the dependency being processed.
+     * @returns The string `workspace:*` if the version uses the `file:` protocol, or `null` otherwise.
+     */
     restoreVersion(p) {
         if (!p.version.startsWith("file:"))
             return null;

package/dist/deps/FixWorkspaceDeps.js.map

@@ -1 +1 @@
-{"version":3,"file":"FixWorkspaceDeps.js","sourceRoot":"","sources":["../../src/deps/FixWorkspaceDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAEL,mBAAmB,GAIpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAAE,CAAyB,EAAE,EAAE;IAC5D,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC1B,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAClC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAG/B,EAAE,EAAE,CACH,CAAC,CAAC,WAAW,KAAK,mBAAmB,CAAC,OAAO;IAC3C,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC,CAAC,IAAI,CAAC;IACrC,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAEvC,MAAM,OAAgB,iBAAiB;IACF;IAAnC,YAAmC,IAAqB;QAArB,SAAI,GAAJ,IAAI,CAAiB;IAAG,CAAC;IAKrD,KAAK,CAAC,GAAG;QACd,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK;YAAE,OAAO,CAAC,uCAAuC,CAAC,CAAC;;YACrE,OAAO,CAAC,0CAA0C,CAAC,CAAC;QAEzD,MAAM,EAAE,GAAG,MAAM,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QAE9C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC7C,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACtD,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,CAAC,iBAAiB,CAAC,CAAC;QAC3B,KAAK,MAAM,GAAG,IAAI,UAAU;YAC1B,OAAO,CACL,KAAK,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,QAAQ,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAC9E,CAAC;QACJ,OAAO,EAAE,CAAC;QAEV,KAAK,MAAM,YAAY,IAAI,IAAI,EAAE,CAAC;YAChC,OAAO,CAAC,iBAAiB,YAAY,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC;YAEzD,IAAI,CAAC;gBACH,IAAI,CAAC,SAAS,CAAC;oBACb,YAAY;oBACZ,UAAU;oBACV,UAAU;oBACV,iBAAiB;iBAClB,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,QAAQ,CAAC,sBAAsB,YAAY,CAAC,OAAO,CAAC,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;gBAClE,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QAED,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;QACjB,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK;YACrB,UAAU,CAAC,uCAAuC,CAAC,CAAC;;YACjD,UAAU,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,oCAAoC;IAC1B,kBAAkB,CAC1B,IAAwC,EACxC,CAAuB;QAEvB,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;QAE5E,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACnD,MAAM,UAAU,GAAG,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACzD,IAAI,CAAC,UAAU;gBAAE,SAAS;YAC1B,OAAO,CAAC,gBAAgB,IAAI,KAAK,OAAO,MAAM,UAAU,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC;QAC1B,CAAC;IACH,CAAC;IAES,SAAS,CAAC,CAAuB;QACzC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QAChE,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,iDAAiD;IACvC,eAAe,CAAC,IAAW;QACnC,MAAM,cAAc,GAAe,EAAE,CAAC;QACtC,KAAK,MAAM,OAAO,IAAI,IAAI;YACxB,KAAK,MAAM,KAAK,IAAI,IAAI;gBACtB,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,CAAC,IAAI;oBAC7C,cAAc,CAAC,IAAI,CAAC;wBAClB,OAAO;wBACP,KAAK;wBACL,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC;qBACpD,CAAC,CAAC;QACT,OAAO,cAAc,CAAC;IACxB,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,iBAAiB;IACzC,UAAU,CAAC,CAAuB;QACnD,IAAI,CAAC,CAAC,OAAO,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QAC7C,MAAM,aAAa,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,QAAQ,CACN,4DAA4D,CAAC,CAAC,GAAG,EAAE,CACpE,CAAC;YACF,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,aAAa,EAAE,CAAC;IAC7B,CAAC;IAEkB,cAAc,CAAC,CAAuB;QACvD,IAAI,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAChE,gEAAgE;YAChE,MAAM,aAAa,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC9C,IAAI,aAAa,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,aAAa,EAAE,EAAE,CAAC;gBACvD,OAAO,aAAa,CAAC;YACvB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,iBAAiB;IACtC,UAAU,CAAC,CAAuB;QACnD,IAAI,CAAC,CAAC,OAAO,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QAE7C,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,CAAC,IAAI,CAChC,CAAC,QAAQ,EAAE,EAAE,CACX,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI;YAC7D,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CACxC,CAAC;QACF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,CACN,4DAA4D,CAAC,CAAC,GAAG,EAAE,CACpE,CAAC;YACF,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,QAAQ,QAAQ,CAAC,OAAO,EAAE,CAAC;IACpC,CAAC;IAEkB,cAAc,CAAC,CAAuB;QACvD,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAChD,OAAO,aAAa,CAAC;IACvB,CAAC;CACF","sourcesContent":["import { relative } from \"path\";\nimport { logError, logInfo, logSuccess } from \"../logger/Logger.js\";\nimport { Pkg } from \"../pkg/Pkg.js\";\nimport {\n  DepsProcessMode,\n  DepsReplacementMode,\n  FixWorkspaceDepsData,\n  FixWorkspaceDepsMain,\n  FixWorkspaceDepsParams,\n} from \"../types/types.deps.js\";\nimport { MapEntry } from \"../types/types.package.js\";\nimport { initWorkspace, workspace } from \"../workspace/Workspace.js\";\n\nexport const runFixDeps = async (p: FixWorkspaceDepsParams) => {\n  initWorkspace(p.repoRoot);\n  return instanceFixDeps(p).run();\n};\n\nexport const instanceFixDeps = (p: {\n  mode: DepsProcessMode;\n  replacement: DepsReplacementMode;\n}) =>\n  p.replacement === DepsReplacementMode.version\n    ? new FixWorkspaceDepsVersion(p.mode)\n    : new FixWorkspaceDepsFile(p.mode);\n\nexport abstract class IFixWorkspaceDeps {\n  public constructor(public readonly mode: DepsProcessMode) {}\n\n  protected abstract fixVersion(p: FixWorkspaceDepsData): string | null;\n  protected abstract restoreVersion(p: FixWorkspaceDepsData): string | null;\n\n  public async run() {\n    if (this.mode === \"fix\") logInfo(\"🔧 Fixing workspace dependencies...\\n\");\n    else logInfo(\"🔧 Restoring workspace dependencies...\\n\");\n\n    const ws = await workspace().read();\n    const pkgs = ws.packages;\n    const mapEntries = this.buildMapEntries(pkgs);\n\n    const versionMap = new Map<string, string>();\n    const workspacePackages = new Set<string>();\n    for (const pkg of pkgs) {\n      versionMap.set(pkg.content.name, pkg.content.version);\n      workspacePackages.add(pkg.content.name);\n    }\n\n    logInfo(\"📋 Version map:\");\n    for (const map of mapEntries)\n      logInfo(\n        `  ${map.fromPkg.content.name} --> ${map.toPkg.content.name}: ${map.relPath}`,\n      );\n    logInfo();\n\n    for (const consumingPkg of pkgs) {\n      logInfo(`📦 Processing ${consumingPkg.content.name}...`);\n\n      try {\n        this.runSingle({\n          consumingPkg,\n          mapEntries,\n          versionMap,\n          workspacePackages,\n        });\n      } catch (err) {\n        logError(`\\nError processing ${consumingPkg.content.name}:`, err);\n        throw err;\n      }\n    }\n\n    await ws.write();\n    if (this.mode === \"fix\")\n      logSuccess(\"✅ Done fixing workspace dependencies!\");\n    else logSuccess(\"✅ Done restoring workspace dependencies!\");\n  }\n\n  // Replace workspace:* with file:...\n  protected handleDependencies(\n    deps: Record<string, string> | undefined,\n    p: FixWorkspaceDepsMain,\n  ): void {\n    if (!deps) return;\n\n    const handler = this.mode === \"fix\" ? this.fixVersion : this.restoreVersion;\n\n    for (const [name, version] of Object.entries(deps)) {\n      const newVersion = handler({ ...p, pkg: name, version });\n      if (!newVersion) continue;\n      logInfo(`  ✓ Replaced ${name}: ${version} → ${newVersion}`);\n      deps[name] = newVersion;\n    }\n  }\n\n  protected runSingle(p: FixWorkspaceDepsMain): void {\n    this.handleDependencies(p.consumingPkg.content.dependencies, p);\n    this.handleDependencies(p.consumingPkg.content.devDependencies, p);\n    this.handleDependencies(p.consumingPkg.content.peerDependencies, p);\n  }\n\n  // Build a map of package names to their versions\n  protected buildMapEntries(pkgs: Pkg[]): MapEntry[] {\n    const versionEntries: MapEntry[] = [];\n    for (const fromPkg of pkgs)\n      for (const toPkg of pkgs)\n        if (fromPkg.content.name !== toPkg.content.name)\n          versionEntries.push({\n            fromPkg,\n            toPkg,\n            relPath: relative(fromPkg.filePath, toPkg.filePath),\n          });\n    return versionEntries;\n  }\n}\n\nexport class FixWorkspaceDepsVersion extends IFixWorkspaceDeps {\n  protected override fixVersion(p: FixWorkspaceDepsData): string | null {\n    if (p.version !== \"workspace:*\") return null;\n    const actualVersion = p.versionMap.get(p.pkg);\n    if (!actualVersion) {\n      logError(\n        `  ERROR: Could not find version for workspace dependency ${p.pkg}`,\n      );\n      throw new Error(`Cannot resolve workspace dependency: ${p.pkg}`);\n    }\n    return `^${actualVersion}`;\n  }\n\n  protected override restoreVersion(p: FixWorkspaceDepsData): string | null {\n    if (p.workspacePackages.has(p.pkg) && p.version.startsWith(\"^\")) {\n      // Verify the version matches what fix script would have created\n      const actualVersion = p.versionMap.get(p.pkg);\n      if (actualVersion && p.version === `^${actualVersion}`) {\n        return \"workspace:*\";\n      }\n    }\n    return null;\n  }\n}\n\nexport class FixWorkspaceDepsFile extends IFixWorkspaceDeps {\n  protected override fixVersion(p: FixWorkspaceDepsData): string | null {\n    if (p.version !== \"workspace:*\") return null;\n\n    const mapEntry = p.mapEntries.find(\n      (mapEntry) =>\n        mapEntry.fromPkg.content.name === p.consumingPkg.content.name &&\n        mapEntry.toPkg.content.name === p.pkg,\n    );\n    if (!mapEntry) {\n      logError(\n        `  ERROR: Could not find version for workspace dependency ${p.pkg}`,\n      );\n      throw new Error(`Cannot resolve workspace dependency: ${p.pkg}`);\n    }\n\n    return `file:${mapEntry.relPath}`;\n  }\n\n  protected override restoreVersion(p: FixWorkspaceDepsData): string | null {\n    if (!p.version.startsWith(\"file:\")) return null;\n    return \"workspace:*\";\n  }\n}\n"]}
+{"version":3,"file":"FixWorkspaceDeps.js","sourceRoot":"","sources":["../../src/deps/FixWorkspaceDeps.ts"],"names":[],"mappings":"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","sourcesContent":["import { relative } from \"path\";\nimport { logError, logInfo, logSuccess } from \"../logger/Logger.js\";\nimport { Pkg } from \"../pkg/Pkg.js\";\nimport {\n  DepsProcessMode,\n  DepsReplacementMode,\n  FixWorkspaceDepsData,\n  FixWorkspaceDepsMain,\n  FixWorkspaceDepsParams,\n} from \"../types/types.deps.js\";\nimport { MapEntry } from \"../types/types.package.js\";\nimport { initWorkspace, workspace } from \"../workspace/Workspace.js\";\n\n/**\n * Fix or restore workspace dependency references across all packages.\n *\n * @remarks\n * Initializes the workspace from the given repository root, selects the\n * appropriate replacement strategy ({@link FixWorkspaceDepsVersion} or\n * {@link FixWorkspaceDepsFile}), and executes the full fix/restore run.\n *\n * @param p - Parameters specifying the repo root, processing mode, and replacement strategy.\n * @returns A promise that resolves when all workspace dependencies have been processed and written.\n *\n * @example\n * ```ts\n * await runFixDeps({\n *   repoRoot: \"/path/to/repo\",\n *   mode: DepsProcessMode.fix,\n *   replacement: DepsReplacementMode.version,\n * });\n * ```\n */\nexport const runFixDeps = async (p: FixWorkspaceDepsParams) => {\n  initWorkspace(p.repoRoot);\n  return instanceFixDeps(p).run();\n};\n\n/**\n * Create the appropriate {@link IFixWorkspaceDeps} instance for the given replacement mode.\n *\n * @remarks\n * Acts as a factory function that returns a {@link FixWorkspaceDepsVersion}\n * when the replacement mode is `version`, or a {@link FixWorkspaceDepsFile}\n * when it is `file`.\n *\n * @param p - Object containing the processing mode and replacement strategy.\n * @returns A concrete {@link IFixWorkspaceDeps} subclass ready to execute.\n */\nexport const instanceFixDeps = (p: {\n  mode: DepsProcessMode;\n  replacement: DepsReplacementMode;\n}) =>\n  p.replacement === DepsReplacementMode.version\n    ? new FixWorkspaceDepsVersion(p.mode)\n    : new FixWorkspaceDepsFile(p.mode);\n\n/**\n * Abstract base class for fixing or restoring workspace dependency references.\n *\n * @remarks\n * Implements the template-method pattern: subclasses provide concrete\n * {@link IFixWorkspaceDeps.fixVersion | fixVersion} and\n * {@link IFixWorkspaceDeps.restoreVersion | restoreVersion} implementations\n * while the base class orchestrates reading, processing, and writing all\n * workspace packages.\n */\nexport abstract class IFixWorkspaceDeps {\n  /**\n   * Create a new workspace dependency fixer.\n   *\n   * @param mode - Whether to `fix` (replace `workspace:*`) or `restore` (revert to `workspace:*`).\n   */\n  public constructor(public readonly mode: DepsProcessMode) {}\n\n  /**\n   * Compute the replacement version string when fixing a dependency.\n   *\n   * @param p - Data about the dependency being processed.\n   * @returns The replacement version string, or `null` if no replacement is needed.\n   */\n  protected abstract fixVersion(p: FixWorkspaceDepsData): string | null;\n\n  /**\n   * Compute the original version string when restoring a dependency.\n   *\n   * @param p - Data about the dependency being processed.\n   * @returns The restored version string, or `null` if no restoration is needed.\n   */\n  protected abstract restoreVersion(p: FixWorkspaceDepsData): string | null;\n\n  /**\n   * Execute the full fix or restore operation across every workspace package.\n   *\n   * @remarks\n   * Reads the workspace, builds a version map and map entries, iterates over\n   * each package to apply the appropriate transformation, and writes all\n   * modified `package.json` files back to disk.\n   *\n   * @returns A promise that resolves when all packages have been written.\n   */\n  public async run() {\n    if (this.mode === \"fix\") logInfo(\"🔧 Fixing workspace dependencies...\\n\");\n    else logInfo(\"🔧 Restoring workspace dependencies...\\n\");\n\n    const ws = await workspace().read();\n    const pkgs = ws.packages;\n    const mapEntries = this.buildMapEntries(pkgs);\n\n    const versionMap = new Map<string, string>();\n    const workspacePackages = new Set<string>();\n    for (const pkg of pkgs) {\n      versionMap.set(pkg.content.name, pkg.content.version);\n      workspacePackages.add(pkg.content.name);\n    }\n\n    logInfo(\"📋 Version map:\");\n    for (const map of mapEntries)\n      logInfo(\n        `  ${map.fromPkg.content.name} --> ${map.toPkg.content.name}: ${map.relPath}`,\n      );\n    logInfo();\n\n    for (const consumingPkg of pkgs) {\n      logInfo(`📦 Processing ${consumingPkg.content.name}...`);\n\n      try {\n        this.runSingle({\n          consumingPkg,\n          mapEntries,\n          versionMap,\n          workspacePackages,\n        });\n      } catch (err) {\n        logError(`\\nError processing ${consumingPkg.content.name}:`, err);\n        throw err;\n      }\n    }\n\n    await ws.write();\n    if (this.mode === \"fix\")\n      logSuccess(\"✅ Done fixing workspace dependencies!\");\n    else logSuccess(\"✅ Done restoring workspace dependencies!\");\n  }\n\n  /**\n   * Process a single dependency map, replacing matching versions in place.\n   *\n   * @param deps - The dependency record (e.g. `dependencies`, `devDependencies`) to mutate.\n   * @param p - Contextual data for the consuming package and workspace.\n   */\n  protected handleDependencies(\n    deps: Record<string, string> | undefined,\n    p: FixWorkspaceDepsMain,\n  ): void {\n    if (!deps) return;\n\n    const handler = this.mode === \"fix\" ? this.fixVersion : this.restoreVersion;\n\n    for (const [name, version] of Object.entries(deps)) {\n      const newVersion = handler({ ...p, pkg: name, version });\n      if (!newVersion) continue;\n      logInfo(`  ✓ Replaced ${name}: ${version} → ${newVersion}`);\n      deps[name] = newVersion;\n    }\n  }\n\n  /**\n   * Process all dependency groups for a single consuming package.\n   *\n   * @param p - Contextual data including the consuming package, map entries, and version map.\n   */\n  protected runSingle(p: FixWorkspaceDepsMain): void {\n    this.handleDependencies(p.consumingPkg.content.dependencies, p);\n    this.handleDependencies(p.consumingPkg.content.devDependencies, p);\n    this.handleDependencies(p.consumingPkg.content.peerDependencies, p);\n  }\n\n  /**\n   * Build pairwise mapping entries between all workspace packages.\n   *\n   * @remarks\n   * Produces a cartesian product (excluding self-pairs) of packages, computing\n   * the relative filesystem path from each source package to every other\n   * target package.\n   *\n   * @param pkgs - The list of workspace packages.\n   * @returns An array of {@link MapEntry} objects describing each package-to-package relationship.\n   */\n  protected buildMapEntries(pkgs: Pkg[]): MapEntry[] {\n    const versionEntries: MapEntry[] = [];\n    for (const fromPkg of pkgs)\n      for (const toPkg of pkgs)\n        if (fromPkg.content.name !== toPkg.content.name)\n          versionEntries.push({\n            fromPkg,\n            toPkg,\n            relPath: relative(fromPkg.filePath, toPkg.filePath),\n          });\n    return versionEntries;\n  }\n}\n\n/**\n * Workspace dependency fixer that replaces `workspace:*` with caret version ranges.\n *\n * @remarks\n * During a `fix` pass, `workspace:*` is replaced with `^{resolved-version}`.\n * During a `restore` pass, caret-prefixed versions that match the workspace\n * version map are reverted back to `workspace:*`.\n */\nexport class FixWorkspaceDepsVersion extends IFixWorkspaceDeps {\n  /**\n   * Replace a `workspace:*` reference with a caret version range.\n   *\n   * @param p - Data about the dependency being processed.\n   * @returns A string like `^1.2.3`, or `null` if the dependency is not `workspace:*`.\n   * @throws Error if the package cannot be found in the workspace version map.\n   */\n  protected override fixVersion(p: FixWorkspaceDepsData): string | null {\n    if (p.version !== \"workspace:*\") return null;\n    const actualVersion = p.versionMap.get(p.pkg);\n    if (!actualVersion) {\n      logError(\n        `  ERROR: Could not find version for workspace dependency ${p.pkg}`,\n      );\n      throw new Error(`Cannot resolve workspace dependency: ${p.pkg}`);\n    }\n    return `^${actualVersion}`;\n  }\n\n  /**\n   * Restore a caret version range back to `workspace:*`.\n   *\n   * @param p - Data about the dependency being processed.\n   * @returns The string `workspace:*` if the version matches the expected caret range, or `null` otherwise.\n   */\n  protected override restoreVersion(p: FixWorkspaceDepsData): string | null {\n    if (p.workspacePackages.has(p.pkg) && p.version.startsWith(\"^\")) {\n      // Verify the version matches what fix script would have created\n      const actualVersion = p.versionMap.get(p.pkg);\n      if (actualVersion && p.version === `^${actualVersion}`) {\n        return \"workspace:*\";\n      }\n    }\n    return null;\n  }\n}\n\n/**\n * Workspace dependency fixer that replaces `workspace:*` with `file:` protocol paths.\n *\n * @remarks\n * During a `fix` pass, `workspace:*` is replaced with a relative `file:` path\n * pointing to the dependency's package directory.\n * During a `restore` pass, any `file:`-prefixed version is reverted to `workspace:*`.\n */\nexport class FixWorkspaceDepsFile extends IFixWorkspaceDeps {\n  /**\n   * Replace a `workspace:*` reference with a relative `file:` path.\n   *\n   * @param p - Data about the dependency being processed.\n   * @returns A string like `file:../sibling-pkg`, or `null` if the dependency is not `workspace:*`.\n   * @throws Error if no map entry can be found for the dependency.\n   */\n  protected override fixVersion(p: FixWorkspaceDepsData): string | null {\n    if (p.version !== \"workspace:*\") return null;\n\n    const mapEntry = p.mapEntries.find(\n      (mapEntry) =>\n        mapEntry.fromPkg.content.name === p.consumingPkg.content.name &&\n        mapEntry.toPkg.content.name === p.pkg,\n    );\n    if (!mapEntry) {\n      logError(\n        `  ERROR: Could not find version for workspace dependency ${p.pkg}`,\n      );\n      throw new Error(`Cannot resolve workspace dependency: ${p.pkg}`);\n    }\n\n    return `file:${mapEntry.relPath}`;\n  }\n\n  /**\n   * Restore a `file:` path reference back to `workspace:*`.\n   *\n   * @param p - Data about the dependency being processed.\n   * @returns The string `workspace:*` if the version uses the `file:` protocol, or `null` otherwise.\n   */\n  protected override restoreVersion(p: FixWorkspaceDepsData): string | null {\n    if (!p.version.startsWith(\"file:\")) return null;\n    return \"workspace:*\";\n  }\n}\n"]}

package/dist/git/GitChanges.d.ts

@@ -1,32 +1,79 @@
 import { GitChangedResult, GitChangedContentsResult } from "../types/types.git.js";
+/**
+ * Creates and initialises a singleton {@link GitChanges} instance.
+ *
+ * @remarks
+ * The baseline reference (`sinceRef`) is resolved in the following priority
+ * order: explicit argument → latest tag → latest commit hash → `"HEAD~1"`.
+ *
+ * @param repoRoot - Absolute path to the repository working directory.
+ * @param sinceRef - Optional explicit git reference to use as the baseline.
+ * @returns The initialised {@link GitChanges} singleton.
+ */
 export declare const initGitChanges: (repoRoot: string, sinceRef?: string) => Promise<GitChanges>;
+/**
+ * Returns the current {@link GitChanges} singleton.
+ *
+ * @returns The previously initialised {@link GitChanges} instance.
+ * @throws If {@link initGitChanges} has not been called yet.
+ */
 export declare const gitChanges: () => GitChanges;
+/**
+ * Provides methods for detecting and reading files that changed since a git reference.
+ *
+ * @remarks
+ * Prefer the {@link initGitChanges} / {@link gitChanges} helpers over direct
+ * construction — they manage a singleton and resolve the baseline reference
+ * automatically.
+ */
 export declare class GitChanges {
     readonly rootDir: string;
+    /** The baseline git reference. Set via {@link sinceRef}. */
     protected _sinceRef: string | null;
+    /**
+     * Creates a new instance bound to the given repository root.
+     *
+     * @param rootDir - Absolute path to the repository working directory.
+     */
     constructor(rootDir: string);
+    /**
+     * Sets the baseline git reference used by change-detection methods.
+     *
+     * @param sinceRef - A valid git ref (SHA, tag, or branch name).
+     */
     set sinceRef(sinceRef: string);
+    /**
+     * Gets the baseline git reference.
+     *
+     * @returns The current baseline ref string.
+     * @throws If `sinceRef` has not been set.
+     */
     get sinceRef(): string;
     /**
-     * Checks if a specific file or directory has been changed since a given git commit.
-     * Includes both committed and uncommitted changes (staged + unstaged).
+     * Checks whether a file or directory has changed since the baseline ref.
+     *
+     * @remarks
+     * The comparison includes both committed and uncommitted changes
+     * (staged and unstaged).
      *
-     * @param target - Relative path to the file or directory to check.
-     * @param sinceRef - The git commit hash (or ref like a tag/branch) to compare against.
-     * @returns A result object indicating whether changes were detected.
+     * @param path - Relative path (from {@link rootDir}) to the file or directory to check.
+     * @returns A {@link GitChangedResult} indicating whether changes were detected
+     *          and which files were affected.
+     * @throws If the resolved target path does not exist on disk.
      */
     hasChanged(path: string): Promise<GitChangedResult>;
     /**
-     * Reads the current content of all files that have changed since a given git commit
-     * within a specific file or directory scope.
-     * Includes both committed and uncommitted changes (staged + unstaged).
+     * Reads the current content of all files that have changed since the baseline ref.
      *
-     * Deleted files are excluded from the result since they no longer exist on disk.
+     * @remarks
+     * The comparison is scoped to {@link rootDir} and includes both committed
+     * and uncommitted changes (staged and unstaged). Deleted files are excluded
+     * because they no longer exist on disk.
      *
-     * @param target - Relative path to the file or directory to check.
-     * @param sinceRef - The git commit hash (or ref like a tag/branch) to compare against.
-     * @param cwd - The working directory of the git repository (defaults to process.cwd()).
-     * @returns A result object containing the current content of each changed file.
+     * @param readContent - When `true`, each file's content is read from disk;
+     *                      when `false` or omitted, `content` is set to `null`.
+     * @returns A {@link GitChangedContentsResult} containing metadata and
+     *          optionally the content of each changed file.
      */
     readChangedFiles(readContent?: boolean): Promise<GitChangedContentsResult>;
 }

package/dist/git/GitChanges.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GitChanges.d.ts","sourceRoot":"","sources":["../../src/git/GitChanges.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EAEzB,MAAM,uBAAuB,CAAC;AAK/B,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,WAAW,MAAM,wBAQvE,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAI7B,CAAC;AAEF,qBAAa,UAAU;aAGc,OAAO,EAAE,MAAM;IAFlD,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAEP,OAAO,EAAE,MAAM;IAElD,IAAW,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAEnC;IAED,IAAW,QAAQ,IAAI,MAAM,CAG5B;IAED;;;;;;;OAOG;IACU,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsBhE;;;;;;;;;;;OAWG;IACU,gBAAgB,CAC3B,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,wBAAwB,CAAC;CA6BrC"}
+{"version":3,"file":"GitChanges.d.ts","sourceRoot":"","sources":["../../src/git/GitChanges.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EAEzB,MAAM,uBAAuB,CAAC;AAK/B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,WAAW,MAAM,wBAQvE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,QAAO,UAI7B,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,UAAU;aASc,OAAO,EAAE,MAAM;IARlD,4DAA4D;IAC5D,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE1C;;;;OAIG;gBACgC,OAAO,EAAE,MAAM;IAElD;;;;OAIG;IACH,IAAW,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAEnC;IAED;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,MAAM,CAG5B;IAED;;;;;;;;;;;OAWG;IACU,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsBhE;;;;;;;;;;;;OAYG;IACU,gBAAgB,CAC3B,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,wBAAwB,CAAC;CA6BrC"}

package/dist/git/GitChanges.js

@@ -3,6 +3,17 @@ import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { lastCommitHash, lastTag, verifiedGit } from "./git.util.js";
 let __instance = null;
+/**
+ * Creates and initialises a singleton {@link GitChanges} instance.
+ *
+ * @remarks
+ * The baseline reference (`sinceRef`) is resolved in the following priority
+ * order: explicit argument → latest tag → latest commit hash → `"HEAD~1"`.
+ *
+ * @param repoRoot - Absolute path to the repository working directory.
+ * @param sinceRef - Optional explicit git reference to use as the baseline.
+ * @returns The initialised {@link GitChanges} singleton.
+ */
 export const initGitChanges = async (repoRoot, sinceRef) => {
     __instance = new GitChanges(repoRoot);
     __instance.sinceRef =
@@ -12,32 +23,67 @@ export const initGitChanges = async (repoRoot, sinceRef) => {
             "HEAD~1";
     return __instance;
 };
+/**
+ * Returns the current {@link GitChanges} singleton.
+ *
+ * @returns The previously initialised {@link GitChanges} instance.
+ * @throws If {@link initGitChanges} has not been called yet.
+ */
 export const gitChanges = () => {
     if (!__instance)
         throw new Error("GitChanges not initialized. initGitChanges[Ref]()");
     return __instance;
 };
+/**
+ * Provides methods for detecting and reading files that changed since a git reference.
+ *
+ * @remarks
+ * Prefer the {@link initGitChanges} / {@link gitChanges} helpers over direct
+ * construction — they manage a singleton and resolve the baseline reference
+ * automatically.
+ */
 export class GitChanges {
     rootDir;
+    /** The baseline git reference. Set via {@link sinceRef}. */
     _sinceRef = null;
+    /**
+     * Creates a new instance bound to the given repository root.
+     *
+     * @param rootDir - Absolute path to the repository working directory.
+     */
     constructor(rootDir) {
         this.rootDir = rootDir;
     }
+    /**
+     * Sets the baseline git reference used by change-detection methods.
+     *
+     * @param sinceRef - A valid git ref (SHA, tag, or branch name).
+     */
     set sinceRef(sinceRef) {
         this._sinceRef = sinceRef;
     }
+    /**
+     * Gets the baseline git reference.
+     *
+     * @returns The current baseline ref string.
+     * @throws If `sinceRef` has not been set.
+     */
     get sinceRef() {
         if (!this._sinceRef)
             throw new Error("SinceRef missing");
         return this._sinceRef;
     }
     /**
-     * Checks if a specific file or directory has been changed since a given git commit.
-     * Includes both committed and uncommitted changes (staged + unstaged).
+     * Checks whether a file or directory has changed since the baseline ref.
+     *
+     * @remarks
+     * The comparison includes both committed and uncommitted changes
+     * (staged and unstaged).
      *
-     * @param target - Relative path to the file or directory to check.
-     * @param sinceRef - The git commit hash (or ref like a tag/branch) to compare against.
-     * @returns A result object indicating whether changes were detected.
+     * @param path - Relative path (from {@link rootDir}) to the file or directory to check.
+     * @returns A {@link GitChangedResult} indicating whether changes were detected
+     *          and which files were affected.
+     * @throws If the resolved target path does not exist on disk.
      */
     async hasChanged(path) {
         const sinceRef = this.sinceRef;
@@ -57,16 +103,17 @@ export class GitChanges {
         };
     }
     /**
-     * Reads the current content of all files that have changed since a given git commit
-     * within a specific file or directory scope.
-     * Includes both committed and uncommitted changes (staged + unstaged).
+     * Reads the current content of all files that have changed since the baseline ref.
      *
-     * Deleted files are excluded from the result since they no longer exist on disk.
+     * @remarks
+     * The comparison is scoped to {@link rootDir} and includes both committed
+     * and uncommitted changes (staged and unstaged). Deleted files are excluded
+     * because they no longer exist on disk.
      *
-     * @param target - Relative path to the file or directory to check.
-     * @param sinceRef - The git commit hash (or ref like a tag/branch) to compare against.
-     * @param cwd - The working directory of the git repository (defaults to process.cwd()).
-     * @returns A result object containing the current content of each changed file.
+     * @param readContent - When `true`, each file's content is read from disk;
+     *                      when `false` or omitted, `content` is set to `null`.
+     * @returns A {@link GitChangedContentsResult} containing metadata and
+     *          optionally the content of each changed file.
      */
     async readChangedFiles(readContent) {
         const sinceRef = this.sinceRef;

package/dist/git/GitChanges.js.map

@@ -1 +1 @@
-{"version":3,"file":"GitChanges.js","sourceRoot":"","sources":["../../src/git/GitChanges.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport {\n  GitChangedResult,\n  GitChangedContentsResult,\n  GitChangedContent,\n} from \"../types/types.git.js\";\nimport { lastCommitHash, lastTag, verifiedGit } from \"./git.util.js\";\n\nlet __instance: GitChanges | null = null;\n\nexport const initGitChanges = async (repoRoot: string, sinceRef?: string) => {\n  __instance = new GitChanges(repoRoot);\n  __instance.sinceRef =\n    sinceRef ??\n    (await lastTag(repoRoot)) ??\n    (await lastCommitHash(repoRoot)) ??\n    \"HEAD~1\";\n  return __instance;\n};\n\nexport const gitChanges = (): GitChanges => {\n  if (!__instance)\n    throw new Error(\"GitChanges not initialized. initGitChanges[Ref]()\");\n  return __instance;\n};\n\nexport class GitChanges {\n  protected _sinceRef: string | null = null;\n\n  public constructor(public readonly rootDir: string) {}\n\n  public set sinceRef(sinceRef: string) {\n    this._sinceRef = sinceRef;\n  }\n\n  public get sinceRef(): string {\n    if (!this._sinceRef) throw new Error(\"SinceRef missing\");\n    return this._sinceRef;\n  }\n\n  /**\n   * Checks if a specific file or directory has been changed since a given git commit.\n   * Includes both committed and uncommitted changes (staged + unstaged).\n   *\n   * @param target - Relative path to the file or directory to check.\n   * @param sinceRef - The git commit hash (or ref like a tag/branch) to compare against.\n   * @returns A result object indicating whether changes were detected.\n   */\n  public async hasChanged(path: string): Promise<GitChangedResult> {\n    const sinceRef = this.sinceRef;\n    const resolvedTarget = resolve(this.rootDir, path);\n\n    if (!existsSync(resolvedTarget)) {\n      throw new Error(`Target path does not exist: ${resolvedTarget}`);\n    }\n\n    const git = await verifiedGit(this.rootDir, sinceRef);\n\n    // Compare commit to working directory (includes uncommitted changes)\n    const diff = await git.diffSummary([sinceRef, \"--\", path]);\n    const changedFiles = diff.files.map((file) => file.file);\n\n    return {\n      path,\n      sinceRef,\n      hasChanged: changedFiles.length > 0,\n      changedFiles,\n    };\n  }\n\n  /**\n   * Reads the current content of all files that have changed since a given git commit\n   * within a specific file or directory scope.\n   * Includes both committed and uncommitted changes (staged + unstaged).\n   *\n   * Deleted files are excluded from the result since they no longer exist on disk.\n   *\n   * @param target - Relative path to the file or directory to check.\n   * @param sinceRef - The git commit hash (or ref like a tag/branch) to compare against.\n   * @param cwd - The working directory of the git repository (defaults to process.cwd()).\n   * @returns A result object containing the current content of each changed file.\n   */\n  public async readChangedFiles(\n    readContent?: boolean,\n  ): Promise<GitChangedContentsResult> {\n    const sinceRef = this.sinceRef;\n    const git = await verifiedGit(this.rootDir, sinceRef);\n\n    // Compare commit to working directory (includes uncommitted changes)\n    const diff = await git.diffSummary([sinceRef, \"--\", this.rootDir]);\n\n    const files: GitChangedContent[] = [];\n\n    for (const entry of diff.files) {\n      const repoFilePath = entry.file;\n      const absFilePath = resolve(this.rootDir, repoFilePath);\n\n      // Skip deleted files — they no longer exist on disk\n      if (!existsSync(absFilePath)) {\n        continue;\n      }\n\n      // Read from the file system to capture uncommitted changes\n      const content = readContent ? await readFile(absFilePath, \"utf-8\") : null;\n      files.push({ absFilePath, content, repoFilePath });\n    }\n\n    return {\n      path: this.rootDir,\n      sinceRef,\n      files,\n    };\n  }\n}\n"]}
+{"version":3,"file":"GitChanges.js","sourceRoot":"","sources":["../../src/git/GitChanges.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport {\n  GitChangedResult,\n  GitChangedContentsResult,\n  GitChangedContent,\n} from \"../types/types.git.js\";\nimport { lastCommitHash, lastTag, verifiedGit } from \"./git.util.js\";\n\nlet __instance: GitChanges | null = null;\n\n/**\n * Creates and initialises a singleton {@link GitChanges} instance.\n *\n * @remarks\n * The baseline reference (`sinceRef`) is resolved in the following priority\n * order: explicit argument → latest tag → latest commit hash → `\"HEAD~1\"`.\n *\n * @param repoRoot - Absolute path to the repository working directory.\n * @param sinceRef - Optional explicit git reference to use as the baseline.\n * @returns The initialised {@link GitChanges} singleton.\n */\nexport const initGitChanges = async (repoRoot: string, sinceRef?: string) => {\n  __instance = new GitChanges(repoRoot);\n  __instance.sinceRef =\n    sinceRef ??\n    (await lastTag(repoRoot)) ??\n    (await lastCommitHash(repoRoot)) ??\n    \"HEAD~1\";\n  return __instance;\n};\n\n/**\n * Returns the current {@link GitChanges} singleton.\n *\n * @returns The previously initialised {@link GitChanges} instance.\n * @throws If {@link initGitChanges} has not been called yet.\n */\nexport const gitChanges = (): GitChanges => {\n  if (!__instance)\n    throw new Error(\"GitChanges not initialized. initGitChanges[Ref]()\");\n  return __instance;\n};\n\n/**\n * Provides methods for detecting and reading files that changed since a git reference.\n *\n * @remarks\n * Prefer the {@link initGitChanges} / {@link gitChanges} helpers over direct\n * construction — they manage a singleton and resolve the baseline reference\n * automatically.\n */\nexport class GitChanges {\n  /** The baseline git reference. Set via {@link sinceRef}. */\n  protected _sinceRef: string | null = null;\n\n  /**\n   * Creates a new instance bound to the given repository root.\n   *\n   * @param rootDir - Absolute path to the repository working directory.\n   */\n  public constructor(public readonly rootDir: string) {}\n\n  /**\n   * Sets the baseline git reference used by change-detection methods.\n   *\n   * @param sinceRef - A valid git ref (SHA, tag, or branch name).\n   */\n  public set sinceRef(sinceRef: string) {\n    this._sinceRef = sinceRef;\n  }\n\n  /**\n   * Gets the baseline git reference.\n   *\n   * @returns The current baseline ref string.\n   * @throws If `sinceRef` has not been set.\n   */\n  public get sinceRef(): string {\n    if (!this._sinceRef) throw new Error(\"SinceRef missing\");\n    return this._sinceRef;\n  }\n\n  /**\n   * Checks whether a file or directory has changed since the baseline ref.\n   *\n   * @remarks\n   * The comparison includes both committed and uncommitted changes\n   * (staged and unstaged).\n   *\n   * @param path - Relative path (from {@link rootDir}) to the file or directory to check.\n   * @returns A {@link GitChangedResult} indicating whether changes were detected\n   *          and which files were affected.\n   * @throws If the resolved target path does not exist on disk.\n   */\n  public async hasChanged(path: string): Promise<GitChangedResult> {\n    const sinceRef = this.sinceRef;\n    const resolvedTarget = resolve(this.rootDir, path);\n\n    if (!existsSync(resolvedTarget)) {\n      throw new Error(`Target path does not exist: ${resolvedTarget}`);\n    }\n\n    const git = await verifiedGit(this.rootDir, sinceRef);\n\n    // Compare commit to working directory (includes uncommitted changes)\n    const diff = await git.diffSummary([sinceRef, \"--\", path]);\n    const changedFiles = diff.files.map((file) => file.file);\n\n    return {\n      path,\n      sinceRef,\n      hasChanged: changedFiles.length > 0,\n      changedFiles,\n    };\n  }\n\n  /**\n   * Reads the current content of all files that have changed since the baseline ref.\n   *\n   * @remarks\n   * The comparison is scoped to {@link rootDir} and includes both committed\n   * and uncommitted changes (staged and unstaged). Deleted files are excluded\n   * because they no longer exist on disk.\n   *\n   * @param readContent - When `true`, each file's content is read from disk;\n   *                      when `false` or omitted, `content` is set to `null`.\n   * @returns A {@link GitChangedContentsResult} containing metadata and\n   *          optionally the content of each changed file.\n   */\n  public async readChangedFiles(\n    readContent?: boolean,\n  ): Promise<GitChangedContentsResult> {\n    const sinceRef = this.sinceRef;\n    const git = await verifiedGit(this.rootDir, sinceRef);\n\n    // Compare commit to working directory (includes uncommitted changes)\n    const diff = await git.diffSummary([sinceRef, \"--\", this.rootDir]);\n\n    const files: GitChangedContent[] = [];\n\n    for (const entry of diff.files) {\n      const repoFilePath = entry.file;\n      const absFilePath = resolve(this.rootDir, repoFilePath);\n\n      // Skip deleted files — they no longer exist on disk\n      if (!existsSync(absFilePath)) {\n        continue;\n      }\n\n      // Read from the file system to capture uncommitted changes\n      const content = readContent ? await readFile(absFilePath, \"utf-8\") : null;\n      files.push({ absFilePath, content, repoFilePath });\n    }\n\n    return {\n      path: this.rootDir,\n      sinceRef,\n      files,\n    };\n  }\n}\n"]}

package/dist/git/git.util.d.ts

@@ -1,15 +1,70 @@
 import { SimpleGit } from "simple-git";
 import { GitCommitHash } from "../types/types.git.js";
 /**
- * Creates a SimpleGit instance and verifies the cwd is a repo
- * and the commit ref is valid.
+ * Returns a verified {@link SimpleGit} instance for the given repository root.
+ *
+ * @remarks
+ * Instances are cached by `rootDir` and `commitRef` pair. On the first call
+ * for a given pair the function verifies that `rootDir` is a git repository
+ * and, when supplied, that `commitRef` resolves to a valid object.
+ *
+ * @param rootDir - Absolute path to the repository working directory.
+ * @param commitRef - Optional git ref (SHA, tag, branch) to validate.
+ * @returns A {@link SimpleGit} instance bound to `rootDir`.
+ * @throws If `rootDir` is not a git repository or `commitRef` is invalid.
  */
 export declare const verifiedGit: (rootDir: string, commitRef?: string) => Promise<SimpleGit>;
+/**
+ * Retrieves the most recent tag in the repository.
+ *
+ * @param rootDir - Absolute path to the repository working directory.
+ * @returns The name of the latest tag, or `null` if no tags exist.
+ */
 export declare const lastTag: (rootDir: string) => Promise<string | null>;
+/**
+ * Retrieves all tags in the repository.
+ *
+ * @param rootDir - Absolute path to the repository working directory.
+ * @returns An array of tag names.
+ */
 export declare const tags: (rootDir: string) => Promise<string[]>;
+/**
+ * Retrieves the hash of the most recent commit on the current branch.
+ *
+ * @param rootDir - Absolute path to the repository working directory.
+ * @returns The SHA hash of the latest commit, or `null` if the log is empty.
+ */
 export declare const lastCommitHash: (rootDir: string) => Promise<string | null>;
+/**
+ * Retrieves the full commit log as an array of {@link GitCommitHash} objects.
+ *
+ * @param rootDir - Absolute path to the repository working directory.
+ * @returns An array of commit hashes with dates and optional diff data.
+ */
 export declare const commitHashs: (rootDir: string) => Promise<GitCommitHash[]>;
+/**
+ * Resolves a git reference, falling back to a secondary ref if the primary is invalid.
+ *
+ * @remarks
+ * Attempts to verify `ref` against the repository. If verification fails
+ * (e.g. the ref does not exist), `fallback` is verified and returned instead.
+ * An error is thrown only when *both* refs are invalid.
+ *
+ * @param ref - The preferred git reference to validate.
+ * @param fallback - A fallback git reference used when `ref` is invalid.
+ * @param rootDir - Absolute path to the repository working directory.
+ * @returns The verified git reference string (`ref` or `fallback`).
+ * @throws If neither `ref` nor `fallback` resolves to a valid git object.
+ */
 export declare const ensureCommitRef: (ref: string, fallback: string, rootDir: string) => Promise<string>;
-/** @internal test-only */
+/**
+ * Resets the internal cache of verified git entries.
+ *
+ * @remarks
+ * This is intended for test cleanup only and should never be called in
+ * production code.
+ *
+ * @internal
+ */
 export declare const __resetGitEntries: () => void;
 //# sourceMappingURL=git.util.d.ts.map

package/dist/git/git.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.util.d.ts","sourceRoot":"","sources":["../../src/git/git.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAUtD;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,SAAS,MAAM,EACf,YAAY,MAAM,KACjB,OAAO,CAAC,SAAS,CAUnB,CAAC;AAqBF,eAAO,MAAM,OAAO,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CACT,CAAC;AAE7D,eAAO,MAAM,IAAI,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CACZ,CAAC;AAElD,eAAO,MAAM,cAAc,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CACX,CAAC;AAElE,eAAO,MAAM,WAAW,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,aAAa,EAAE,CAKtE,CAAC;AAEN,eAAO,MAAM,eAAe,GAC1B,KAAK,MAAM,EACX,UAAU,MAAM,EAChB,SAAS,MAAM,KACd,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,iBAAiB,YAE7B,CAAC"}
+{"version":3,"file":"git.util.d.ts","sourceRoot":"","sources":["../../src/git/git.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAUtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GACtB,SAAS,MAAM,EACf,YAAY,MAAM,KACjB,OAAO,CAAC,SAAS,CAUnB,CAAC;AAqBF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CACT,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CACZ,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CACX,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,aAAa,EAAE,CAKtE,CAAC;AAEN;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,MAAM,EACX,UAAU,MAAM,EAChB,SAAS,MAAM,KACd,OAAO,CAAC,MAAM,CAQhB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,YAE7B,CAAC"}