@thecat69/cache-ctrl 1.0.0 → 1.1.1

package/src/commands/map.ts

@@ -0,0 +1,87 @@
+import { findRepoRoot, readCache } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { LocalCacheFileSchema } from "../types/cache.js";
+import type { MapArgs, MapDepth, MapResult } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+/**
+ * Returns a semantic map view of local context cache content.
+ *
+ * @param args - {@link MapArgs} command arguments.
+ * @returns Promise<Result<MapResult["value"]>>; common failures include FILE_NOT_FOUND,
+ * PARSE_ERROR, FILE_READ_ERROR, and UNKNOWN.
+ */
+export async function mapCommand(args: MapArgs): Promise<Result<MapResult["value"]>> {
+  try {
+    const depth: MapDepth = args.depth ?? "overview";
+    const repoRoot = await findRepoRoot(process.cwd());
+    const contextPath = resolveLocalCachePath(repoRoot);
+
+    const readResult = await readCache(contextPath);
+    if (!readResult.ok) {
+      if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
+        return {
+          ok: false,
+          error: "context.json not found — run local-context-gatherer to populate the cache",
+          code: ErrorCode.FILE_NOT_FOUND,
+        };
+      }
+      return readResult;
+    }
+
+    const parseResult = LocalCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) {
+      return {
+        ok: false,
+        error: `Malformed local cache file: ${contextPath}`,
+        code: ErrorCode.PARSE_ERROR,
+      };
+    }
+
+    const parsed = parseResult.data;
+    const allFacts = parsed.facts ?? {};
+    const folderPrefix = args.folder;
+    const filteredFacts =
+      folderPrefix !== undefined
+        ? Object.fromEntries(
+            Object.entries(allFacts).filter(
+              ([filePath]) => filePath === folderPrefix || filePath.startsWith(`${folderPrefix}/`),
+            ),
+          )
+        : allFacts;
+
+    const files = Object.entries(filteredFacts)
+      .map(([path, fileFacts]) => ({
+        path,
+        ...(fileFacts.summary !== undefined ? { summary: fileFacts.summary } : {}),
+        ...(fileFacts.role !== undefined ? { role: fileFacts.role } : {}),
+        ...(fileFacts.importance !== undefined ? { importance: fileFacts.importance } : {}),
+        ...(depth === "full" && fileFacts.facts !== undefined ? { facts: fileFacts.facts } : {}),
+      }))
+      .sort((a, b) => {
+        const aImportance = a.importance ?? Number.POSITIVE_INFINITY;
+        const bImportance = b.importance ?? Number.POSITIVE_INFINITY;
+        if (aImportance !== bImportance) {
+          return aImportance - bImportance;
+        }
+        return a.path.localeCompare(b.path);
+      });
+
+    return {
+      ok: true,
+      value: {
+        depth,
+        global_facts: parsed.global_facts ?? [],
+        files,
+        ...((depth === "modules" || depth === "full") && parsed.modules !== undefined
+          ? { modules: parsed.modules }
+          : {}),
+        total_files: files.length,
+        ...(args.folder !== undefined ? { folder_filter: args.folder } : {}),
+      },
+    };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/prune.ts

@@ -6,17 +6,32 @@ import { ExternalCacheFileSchema } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { PruneArgs, PruneResult } from "../types/commands.js";
 import { getFileStem } from "../utils/fileStem.js";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Parses duration text in `<number><unit>` form.
+ *
+ * @param duration - Duration string where unit is one of `s`, `m`, `h`, `d`.
+ * @returns Milliseconds value, or `null` when format is invalid.
+ */
 export function parseDurationMs(duration: string): number | null {
-  const match = /^(\d+)(h|d)$/.exec(duration);
+  const match = /^(\d+)(s|m|h|d)$/.exec(duration);
   if (!match) return null;
   const value = parseInt(match[1]!, 10);
   const unit = match[2]!;
+  if (unit === "s") return value * 1_000;
+  if (unit === "m") return value * 60_000;
   if (unit === "h") return value * 3_600_000;
-  if (unit === "d") return value * 86_400_000;
-  return null;
+  return value * 86_400_000;
 }
 
+/**
+ * Prunes stale cache entries by invalidating or deleting them.
+ *
+ * @param args - {@link PruneArgs} command arguments.
+ * @returns Promise<Result<PruneResult["value"]>>; common failures include INVALID_ARGS,
+ * FILE_READ_ERROR, FILE_WRITE_ERROR, and UNKNOWN.
+ */
 export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -82,9 +97,7 @@ export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult[
         // Only invalidate if the file already exists
         const readResult = await readCache(localPath);
         if (!readResult.ok) {
-          if (readResult.code === ErrorCode.FILE_NOT_FOUND) {
-            // Nothing to prune — skip silently
-          } else {
+          if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
             return readResult;
           }
         } else {
@@ -104,7 +117,6 @@ export async function pruneCommand(args: PruneArgs): Promise<Result<PruneResult[
       },
     };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/search.ts

@@ -5,7 +5,15 @@ import type { CacheEntry } from "../types/cache.js";
 import { LocalCacheFileSchema } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { SearchArgs, SearchResult } from "../types/commands.js";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Searches cache entries across namespaces using keyword-based scoring.
+ *
+ * @param args - {@link SearchArgs} command arguments.
+ * @returns Promise<Result<SearchResult["value"]>>; common failures include FILE_READ_ERROR
+ * (external directory listing), PARSE_ERROR (malformed local cache), and UNKNOWN.
+ */
 export async function searchCommand(args: SearchArgs): Promise<Result<SearchResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -51,7 +59,6 @@ export async function searchCommand(args: SearchArgs): Promise<Result<SearchResu
       })),
     };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/touch.ts

@@ -3,8 +3,16 @@ import { resolveTopExternalMatch } from "../cache/externalCache.js";
 import { resolveLocalCachePath } from "../cache/localCache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { TouchArgs, TouchResult } from "../types/commands.js";
+import { toUnknownResult } from "../utils/errors.js";
 import { validateSubject } from "../utils/validate.js";
 
+/**
+ * Marks cache entries fresh by setting timestamps to current UTC time.
+ *
+ * @param args - {@link TouchArgs} command arguments.
+ * @returns Promise<Result<TouchResult["value"]>>; common failures include INVALID_ARGS,
+ * NO_MATCH, FILE_WRITE_ERROR, and UNKNOWN.
+ */
 export async function touchCommand(args: TouchArgs): Promise<Result<TouchResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -41,7 +49,6 @@ export async function touchCommand(args: TouchArgs): Promise<Result<TouchResult[
 
     return { ok: true, value: { touched, new_timestamp: newTimestamp } };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/version.ts

@@ -0,0 +1,14 @@
+import type { VersionArgs, VersionResult } from "../types/commands.js";
+import type { Result } from "../types/result.js";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+/**
+ * Returns the package version from `package.json`.
+ *
+ * @param args - {@link VersionArgs} command arguments (unused).
+ * @returns `Result<VersionResult["value"]>` containing the CLI version.
+ */
+export function versionCommand(_args: VersionArgs = {}): Result<VersionResult["value"]> {
+  return { ok: true, value: { version: packageJson.version } };
+}

package/src/commands/watch.ts

@@ -0,0 +1,253 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+
+import { buildGraph, type DependencyGraph } from "../analysis/graphBuilder.js";
+import { findRepoRoot, writeCache } from "../cache/cacheManager.js";
+import { resolveGraphCachePath } from "../cache/graphCache.js";
+import { getGitTrackedFiles } from "../files/gitFiles.js";
+import type { GraphCacheFile } from "../types/cache.js";
+import type { WatchArgs } from "../types/commands.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+
+const WATCH_DEBOUNCE_MS = 200;
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+
+type TrackedFilesProvider = (repoRoot: string) => Promise<string[]>;
+type WatchEvent = "rename" | "change";
+type BunWatchCallback = (event: WatchEvent, filename: string | null) => void;
+
+interface WatcherHandle {
+  close?: () => void;
+  stop?: () => void;
+}
+
+type BunWatchFunction = (
+  watchPath: string,
+  options: { recursive: boolean },
+  callback: BunWatchCallback,
+) => WatcherHandle;
+
+function resolveBunWatch(): Result<BunWatchFunction> {
+  const watchFn = Reflect.get(Object(Bun), "watch");
+  if (typeof watchFn !== "function") {
+    return {
+      ok: false,
+      error: "Bun.watch is not available in this runtime",
+      code: ErrorCode.UNKNOWN,
+    };
+  }
+  return { ok: true, value: watchFn };
+}
+
+/**
+ * Checks whether a file path is a supported source file for graph analysis.
+ *
+ * @param filePath - Absolute or relative file path.
+ * @returns `true` when extension is one of `.ts`, `.tsx`, `.js`, `.jsx`.
+ */
+export function isSourceFile(filePath: string): boolean {
+  const extension = path.extname(filePath).toLowerCase();
+  return SOURCE_EXTENSIONS.has(extension);
+}
+
+/**
+ * Converts in-memory dependency graph nodes into graph cache file shape.
+ *
+ * @param graph - Dependency graph to serialize.
+ * @returns `GraphCacheFile["files"]` payload suitable for `graph.json`.
+ */
+export function serializeGraphToCache(graph: DependencyGraph): GraphCacheFile["files"] {
+  const files: GraphCacheFile["files"] = {};
+
+  for (const [filePath, node] of graph.entries()) {
+    files[filePath] = {
+      rank: 0.0,
+      deps: node.deps,
+      defs: node.defs,
+    };
+  }
+
+  return files;
+}
+
+/**
+ * Resolves tracked source files to safe absolute paths for graph building.
+ *
+ * @param repoRoot - Repository root used for path resolution.
+ * @param trackedFilesProvider - Optional provider for tracked paths (defaults to git).
+ * @returns Absolute, de-duplicated source file paths constrained to `repoRoot`.
+ */
+export async function resolveSourceFilePaths(
+  repoRoot: string,
+  trackedFilesProvider: TrackedFilesProvider = getGitTrackedFiles,
+): Promise<string[]> {
+  const trackedFiles = await trackedFilesProvider(repoRoot);
+  const normalizedRepoRoot = path.resolve(repoRoot);
+  const repoPrefix = `${normalizedRepoRoot}${path.sep}`;
+  const sourcePaths = new Set<string>();
+
+  await Promise.all(
+    trackedFiles.filter(isSourceFile).map(async (relPath) => {
+      const absolutePath = path.join(normalizedRepoRoot, relPath);
+      try {
+        const resolvedPath = await realpath(absolutePath);
+        if (resolvedPath === normalizedRepoRoot || resolvedPath.startsWith(repoPrefix)) {
+          sourcePaths.add(resolvedPath);
+        }
+      } catch {
+        // Ignore missing or unreadable paths from tracked files.
+      }
+    }),
+  );
+
+  return [...sourcePaths];
+}
+
+async function rebuildGraphCache(repoRoot: string, changedPath: string | undefined, verbose: boolean): Promise<void> {
+  try {
+    const sourceFilePaths = await resolveSourceFilePaths(repoRoot);
+    const graph = await buildGraph(sourceFilePaths, repoRoot);
+    const graphCachePath = resolveGraphCachePath(repoRoot);
+    const graphPayload: GraphCacheFile = {
+      files: serializeGraphToCache(graph),
+      computed_at: new Date().toISOString(),
+    };
+    const writeResult = await writeCache(graphCachePath, graphPayload, "replace");
+    if (!writeResult.ok) {
+      process.stderr.write(`[watch] Failed to update graph cache: ${writeResult.error}\n`);
+      return;
+    }
+    if (verbose) {
+      if (changedPath !== undefined) {
+        process.stdout.write(`[watch] Graph updated: ${graph.size} files, changed: ${changedPath}\n`);
+      } else {
+        process.stdout.write(`[watch] Initial graph computed: ${graph.size} files\n`);
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[watch] Failed to rebuild graph: ${message}\n`);
+  }
+}
+
+/**
+ * Starts the long-running graph watch daemon.
+ *
+ * @param args - {@link WatchArgs} command arguments.
+ * @returns Promise<Result<never>>; common failures include FILE_WRITE_ERROR via wrapped
+ * UNKNOWN, runtime unavailability errors, and UNKNOWN.
+ */
+export async function watchCommand(args: WatchArgs): Promise<Result<never>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    const initialSourceFiles = await resolveSourceFilePaths(repoRoot);
+    const initialGraph = await buildGraph(initialSourceFiles, repoRoot);
+    const graphCachePath = resolveGraphCachePath(repoRoot);
+    const initialPayload: GraphCacheFile = {
+      files: serializeGraphToCache(initialGraph),
+      computed_at: new Date().toISOString(),
+    };
+    const initialWriteResult = await writeCache(graphCachePath, initialPayload, "replace");
+    if (!initialWriteResult.ok) {
+      const errorMessage = `[watch] Failed to write initial graph cache: ${initialWriteResult.error}`;
+      process.stderr.write(`${errorMessage}\n`);
+      return {
+        ok: false,
+        error: errorMessage,
+        code: ErrorCode.UNKNOWN,
+      };
+    }
+    if (args.verbose) {
+      process.stdout.write(`[watch] Initial graph computed: ${initialGraph.size} files\n`);
+    }
+
+    let pendingChangedPath: string | undefined;
+    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+    let rebuildInProgress = false;
+    let rebuildQueued = false;
+
+    const triggerRebuild = async (): Promise<void> => {
+      if (rebuildInProgress) {
+        rebuildQueued = true;
+        return;
+      }
+
+      rebuildInProgress = true;
+      try {
+        do {
+          rebuildQueued = false;
+          const changedPath = pendingChangedPath;
+          pendingChangedPath = undefined;
+          await rebuildGraphCache(repoRoot, changedPath, args.verbose === true);
+        } while (rebuildQueued);
+      } finally {
+        rebuildInProgress = false;
+      }
+    };
+
+    const scheduleRebuild = (changedPath: string): void => {
+      pendingChangedPath = changedPath;
+
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer);
+      }
+
+      debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        void triggerRebuild();
+      }, WATCH_DEBOUNCE_MS);
+    };
+
+    const watchResult = resolveBunWatch();
+    if (!watchResult.ok) {
+      process.stderr.write(`[watch] ${watchResult.error}\n`);
+      return watchResult;
+    }
+
+    const watcher = watchResult.value(repoRoot, { recursive: true }, (_event, filename) => {
+      if (filename === null) {
+        return;
+      }
+
+      const absolutePath = path.join(repoRoot, filename);
+      if (!isSourceFile(absolutePath)) {
+        return;
+      }
+
+      if (args.verbose) {
+        process.stdout.write(`[watch] File changed: ${absolutePath}, recomputing...\n`);
+      }
+
+      scheduleRebuild(absolutePath);
+    });
+
+    const shutdown = (): void => {
+      if (debounceTimer !== undefined) {
+        clearTimeout(debounceTimer);
+      }
+      if (args.verbose) {
+        process.stdout.write("[watch] Shutting down\n");
+      }
+      if (typeof watcher.close === "function") {
+        watcher.close();
+      } else if (typeof watcher.stop === "function") {
+        watcher.stop();
+      }
+      process.exit(0);
+    };
+
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+
+    return new Promise<never>(() => {
+      // Keep command alive until signal-based shutdown.
+    });
+  } catch (err) {
+    const unknownError = toUnknownResult(err);
+    const message = unknownError.error;
+    process.stderr.write(`[watch] Failed to start watcher: ${message}\n`);
+    return unknownError;
+  }
+}

package/src/commands/writeExternal.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+
+import { findRepoRoot, resolveCacheDir, writeCache } from "../cache/cacheManager.js";
+import type { WriteArgs, WriteResult } from "../types/commands.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+import { formatZodError, validateSubject } from "../utils/validate.js";
+
+/**
+ * Validates and writes one external cache entry.
+ *
+ * @param args - {@link WriteArgs} command arguments for the external agent.
+ * @returns Promise<Result<WriteResult["value"]>>; common failures include INVALID_ARGS,
+ * VALIDATION_ERROR, FILE_WRITE_ERROR, LOCK_TIMEOUT/LOCK_ERROR, and UNKNOWN.
+ */
+export async function writeExternalCommand(args: WriteArgs): Promise<Result<WriteResult["value"]>> {
+  try {
+    if (!args.subject) {
+      return { ok: false, error: "subject is required for external agent", code: ErrorCode.INVALID_ARGS };
+    }
+
+    const subjectValidation = validateSubject(args.subject);
+    if (!subjectValidation.ok) return subjectValidation;
+
+    if (args.content["subject"] !== undefined && args.content["subject"] !== args.subject) {
+      return {
+        ok: false,
+        error: `content.subject "${String(args.content["subject"])}" does not match subject argument "${args.subject}"`,
+        code: ErrorCode.VALIDATION_ERROR,
+      };
+    }
+
+    const contentWithSubject = { ...args.content, subject: args.subject };
+
+    const parsed = ExternalCacheFileSchema.safeParse(contentWithSubject);
+    if (!parsed.success) {
+      const message = formatZodError(parsed.error);
+      return { ok: false, error: `Validation failed: ${message}`, code: ErrorCode.VALIDATION_ERROR };
+    }
+
+    const repoRoot = await findRepoRoot(process.cwd());
+    const cacheDir = resolveCacheDir("external", repoRoot);
+    const filePath = join(cacheDir, `${args.subject}.json`);
+    const writeResult = await writeCache(filePath, contentWithSubject);
+    if (!writeResult.ok) return writeResult;
+    return { ok: true, value: { file: filePath } };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/commands/writeLocal.ts

@@ -0,0 +1,123 @@
+import { join } from "node:path";
+
+import { findRepoRoot, readCache, resolveCacheDir, writeCache } from "../cache/cacheManager.js";
+import { filterExistingFiles, resolveTrackedFileStats } from "../files/changeDetector.js";
+import type { WriteArgs, WriteResult } from "../types/commands.js";
+import { type FileFacts, LocalCacheFileSchema, type TrackedFile, TrackedFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
+import { formatZodError } from "../utils/validate.js";
+
+function evictFactsForDeletedPaths(
+  facts: Record<string, unknown>,
+  survivingFiles: TrackedFile[],
+): Record<string, unknown> {
+  const survivingPaths = new Set(survivingFiles.map((file) => file.path));
+  return Object.fromEntries(Object.entries(facts).filter(([path]) => survivingPaths.has(path)));
+}
+
+function hasStringPath(entry: unknown): entry is { path: string } {
+  if (typeof entry !== "object" || entry === null) {
+    return false;
+  }
+  const pathValue = Reflect.get(entry, "path");
+  return typeof pathValue === "string";
+}
+
+function getSubmittedTrackedPaths(rawTrackedFiles: unknown): string[] {
+  if (!Array.isArray(rawTrackedFiles)) return [];
+
+  return rawTrackedFiles.filter(hasStringPath).map((entry) => entry.path);
+}
+
+function toPlainObjectRecord(rawValue: unknown): Record<string, unknown> {
+  if (typeof rawValue === "object" && rawValue !== null && !Array.isArray(rawValue)) {
+    return Object.fromEntries(Object.entries(rawValue));
+  }
+  return {};
+}
+
+/**
+ * Validates and writes local context cache content with per-path merge semantics.
+ *
+ * @param args - {@link WriteArgs} command arguments for the local agent.
+ * @returns Promise<Result<WriteResult["value"]>>; common failures include VALIDATION_ERROR,
+ * FILE_READ_ERROR/FILE_WRITE_ERROR, LOCK_TIMEOUT/LOCK_ERROR, and UNKNOWN.
+ */
+export async function writeLocalCommand(args: WriteArgs): Promise<Result<WriteResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+
+    const contentWithTimestamp: Record<string, unknown> = {
+      ...args.content,
+      timestamp: new Date().toISOString(),
+    };
+
+    const submittedPaths = getSubmittedTrackedPaths(contentWithTimestamp["tracked_files"]);
+    const guardedPaths = new Set(submittedPaths);
+    const resolvedTrackedFiles = await resolveTrackedFileStats(submittedPaths.map((path) => ({ path })), repoRoot);
+    const survivingSubmitted = resolvedTrackedFiles.filter((trackedFile) => trackedFile.mtime !== 0);
+
+    const submittedFacts = toPlainObjectRecord(contentWithTimestamp["facts"]);
+    const rawSubmittedFacts = contentWithTimestamp["facts"];
+    if (typeof rawSubmittedFacts === "object" && rawSubmittedFacts !== null && !Array.isArray(rawSubmittedFacts)) {
+      const violatingPaths = Object.keys(submittedFacts).filter((path) => !guardedPaths.has(path));
+      if (violatingPaths.length > 0) {
+        return {
+          ok: false,
+          error: `facts contains paths not in submitted tracked_files: ${violatingPaths.join(", ")}`,
+          code: ErrorCode.VALIDATION_ERROR,
+        };
+      }
+    }
+
+    const localCacheDir = resolveCacheDir("local", repoRoot);
+    const filePath = join(localCacheDir, "context.json");
+
+    const readResult = await readCache(filePath);
+    let existingContent: Record<string, unknown> = {};
+    let existingTrackedFiles: TrackedFile[] = [];
+    let existingFacts: Record<string, FileFacts> = {};
+
+    if (readResult.ok) {
+      existingContent = readResult.value;
+      const localParseResult = LocalCacheFileSchema.safeParse(existingContent);
+      if (localParseResult.success) {
+        existingTrackedFiles = localParseResult.data.tracked_files;
+        existingFacts = localParseResult.data.facts ?? {};
+      } else {
+        const trackedFilesResult = TrackedFileSchema.array().safeParse(existingContent["tracked_files"]);
+        existingTrackedFiles = trackedFilesResult.success ? trackedFilesResult.data : [];
+      }
+    } else if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
+      return { ok: false, error: readResult.error, code: readResult.code };
+    }
+
+    const submittedTrackedPaths = new Set(survivingSubmitted.map((trackedFile) => trackedFile.path));
+    const existingNotSubmitted = existingTrackedFiles.filter((trackedFile) => !submittedTrackedPaths.has(trackedFile.path));
+    const survivingExisting = await filterExistingFiles(existingNotSubmitted, repoRoot);
+    const mergedTrackedFiles = [...survivingExisting, ...survivingSubmitted];
+
+    const rawMergedFacts = { ...existingFacts, ...submittedFacts };
+    const mergedFacts = evictFactsForDeletedPaths(rawMergedFacts, mergedTrackedFiles);
+
+    const processedContent: Record<string, unknown> = {
+      ...existingContent,
+      ...contentWithTimestamp,
+      tracked_files: mergedTrackedFiles,
+      facts: mergedFacts,
+    };
+
+    const parsed = LocalCacheFileSchema.safeParse(processedContent);
+    if (!parsed.success) {
+      const message = formatZodError(parsed.error);
+      return { ok: false, error: `Validation failed: ${message}`, code: ErrorCode.VALIDATION_ERROR };
+    }
+
+    const writeResult = await writeCache(filePath, processedContent, "replace");
+    if (!writeResult.ok) return writeResult;
+    return { ok: true, value: { file: filePath } };
+  } catch (err) {
+    return toUnknownResult(err);
+  }
+}

package/src/files/changeDetector.ts

@@ -3,12 +3,26 @@ import { createHash } from "node:crypto";
 import { resolve, isAbsolute } from "node:path";
 import type { TrackedFile } from "../types/cache.js";
 
+/**
+ * Comparison outcome for one tracked file baseline.
+ *
+ * `status` and `reason` are coupled: `changed` uses `mtime`/`hash`, `missing` uses `missing`,
+ * and `unchanged` omits `reason`. `missing` covers both deleted files and traversal-rejected
+ * paths blocked by path-safety guards.
+ */
 export interface FileComparisonResult {
   path: string;
   status: "changed" | "unchanged" | "missing";
   reason?: "mtime" | "hash" | "missing";
 }
 
+/**
+ * Compares one tracked file against current filesystem state.
+ *
+ * Uses `mtime` as a fast path and falls back to SHA-256 hash comparison when stored hash is
+ * available and `mtime` changed. Paths that escape `repoRoot` are rejected by traversal guard
+ * and reported as `missing`. `ENOENT` is also reported as `missing`.
+ */
 export async function compareTrackedFile(file: TrackedFile, repoRoot: string): Promise<FileComparisonResult> {
   const absolutePath = resolveTrackedFilePath(file.path, repoRoot);
 
@@ -47,6 +61,7 @@ export async function compareTrackedFile(file: TrackedFile, repoRoot: string): P
   }
 }
 
+/** Computes SHA-256 hex digest for a file's current bytes. */
 export async function computeFileHash(filePath: string): Promise<string> {
   const content = await readFile(filePath);
   return createHash("sha256").update(content).digest("hex");