@thecat69/cache-ctrl 1.0.0 → 1.1.1

package/src/analysis/symbolExtractor.ts

@@ -0,0 +1,240 @@
+import { readFile } from "node:fs/promises";
+import { dirname, extname, resolve, sep } from "node:path";
+
+import { parse } from "@typescript-eslint/typescript-estree";
+
+export interface FileSymbols {
+  /** Resolved file paths this file imports from (relative imports only, resolved to absolute) */
+  deps: string[];
+  /** Exported symbol names declared in this file */
+  defs: string[];
+}
+
+interface AstNode {
+  type: string;
+  [key: string]: unknown;
+}
+
+const SUPPORTED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx"]);
+
+function isAstNode(value: unknown): value is AstNode {
+  return typeof value === "object" && value !== null && "type" in value;
+}
+
+function walkAst(value: unknown, visitor: (node: AstNode) => void): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      walkAst(item, visitor);
+    }
+    return;
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return;
+  }
+
+  if (isAstNode(value)) {
+    visitor(value);
+  }
+
+  for (const child of Object.values(value)) {
+    walkAst(child, visitor);
+  }
+}
+
+function collectPatternIdentifiers(pattern: unknown, defs: Set<string>): void {
+  if (!isAstNode(pattern)) {
+    return;
+  }
+
+  if (pattern.type === "Identifier") {
+    const name = pattern.name;
+    if (typeof name === "string") {
+      defs.add(name);
+    }
+    return;
+  }
+
+  if (pattern.type === "RestElement") {
+    collectPatternIdentifiers(pattern.argument, defs);
+    return;
+  }
+
+  if (pattern.type === "AssignmentPattern") {
+    collectPatternIdentifiers(pattern.left, defs);
+    return;
+  }
+
+  if (pattern.type === "ArrayPattern") {
+    const elements = pattern.elements;
+    if (Array.isArray(elements)) {
+      for (const element of elements) {
+        collectPatternIdentifiers(element, defs);
+      }
+    }
+    return;
+  }
+
+  if (pattern.type === "ObjectPattern") {
+    const properties = pattern.properties;
+    if (!Array.isArray(properties)) {
+      return;
+    }
+
+    for (const property of properties) {
+      if (!isAstNode(property)) {
+        continue;
+      }
+
+      if (property.type === "Property") {
+        collectPatternIdentifiers(property.value, defs);
+      }
+
+      if (property.type === "RestElement") {
+        collectPatternIdentifiers(property.argument, defs);
+      }
+    }
+  }
+}
+
+function collectNamesFromDeclaration(declaration: unknown, defs: Set<string>): void {
+  if (!isAstNode(declaration)) {
+    return;
+  }
+
+  if (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") {
+    const id = declaration.id;
+    if (isAstNode(id) && id.type === "Identifier") {
+      const name = id.name;
+      if (typeof name === "string") {
+        defs.add(name);
+      }
+    }
+    return;
+  }
+
+  if (declaration.type === "VariableDeclaration") {
+    const declarations = declaration.declarations;
+    if (!Array.isArray(declarations)) {
+      return;
+    }
+
+    for (const variableDeclarator of declarations) {
+      if (!isAstNode(variableDeclarator) || variableDeclarator.type !== "VariableDeclarator") {
+        continue;
+      }
+      collectPatternIdentifiers(variableDeclarator.id, defs);
+    }
+    return;
+  }
+
+  const id = declaration.id;
+  if (isAstNode(id) && id.type === "Identifier") {
+    const name = id.name;
+    if (typeof name === "string") {
+      defs.add(name);
+    }
+  }
+}
+
+function collectExportSpecifierName(specifier: unknown): string | null {
+  if (!isAstNode(specifier)) {
+    return null;
+  }
+
+  const exported = specifier.exported;
+  if (!isAstNode(exported)) {
+    return null;
+  }
+
+  if (exported.type === "Identifier") {
+    return typeof exported.name === "string" ? exported.name : null;
+  }
+
+  if (exported.type === "Literal") {
+    return typeof exported.value === "string" ? exported.value : null;
+  }
+
+  return null;
+}
+
+/**
+ * Extract import dependencies and export definitions from a source file.
+ * Returns an empty FileSymbols if the file cannot be parsed.
+ * Never throws.
+ */
+export async function extractSymbols(filePath: string, repoRoot: string): Promise<FileSymbols> {
+  try {
+    const extension = extname(filePath).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(extension)) {
+      return { deps: [], defs: [] };
+    }
+
+    const sourceCode = await readFile(filePath, "utf8");
+    const ast = parse(sourceCode, {
+      jsx: true,
+      range: false,
+      loc: false,
+      sourceType: "module",
+      errorOnUnknownASTType: false,
+    });
+
+    const normalizedRepoRoot = resolve(repoRoot);
+    const repoPrefix = `${normalizedRepoRoot}${sep}`;
+    const dependencies = new Set<string>();
+    const definitions = new Set<string>();
+
+    walkAst(ast, (node) => {
+      if (node.type === "ImportDeclaration") {
+        const source = node.source;
+        if (!isAstNode(source) || source.type !== "Literal") {
+          return;
+        }
+
+        const importValue = source.value;
+        if (typeof importValue !== "string") {
+          return;
+        }
+
+        if (!importValue.startsWith(".") && !importValue.startsWith("/")) {
+          return;
+        }
+
+        const resolvedDependency = resolve(dirname(filePath), importValue);
+        if (resolvedDependency === normalizedRepoRoot || resolvedDependency.startsWith(repoPrefix)) {
+          dependencies.add(resolvedDependency);
+        }
+        return;
+      }
+
+      if (node.type === "ExportNamedDeclaration") {
+        collectNamesFromDeclaration(node.declaration, definitions);
+
+        const specifiers = node.specifiers;
+        if (!Array.isArray(specifiers)) {
+          return;
+        }
+
+        for (const specifier of specifiers) {
+          const name = collectExportSpecifierName(specifier);
+          if (name !== null) {
+            definitions.add(name);
+          }
+        }
+        return;
+      }
+
+      if (node.type === "ExportDefaultDeclaration") {
+        definitions.add("default");
+        collectNamesFromDeclaration(node.declaration, definitions);
+      }
+    });
+
+    return {
+      deps: [...dependencies],
+      defs: [...definitions],
+    };
+  } catch {
+    return { deps: [], defs: [] };
+  }
+}

package/src/cache/cacheManager.ts

@@ -11,6 +11,14 @@ const LOCK_RETRY_INTERVAL_MS = 50;
 const LOCK_TIMEOUT_MS = 5000;
 const LOCK_STALE_AGE_MS = 30_000;
 
+/**
+ * Resolves the repository root by walking upward until a `.git` directory is found.
+ *
+ * @param startDir - Directory where upward detection starts.
+ * @returns Absolute path to detected repo root, or `startDir` when no `.git` is found.
+ * @remarks Uses a parent-directory walk; on filesystem root fallback it intentionally
+ * returns `startDir` so CLI behavior remains deterministic outside git repositories.
+ */
 export async function findRepoRoot(startDir: string): Promise<string> {
   let current = startDir;
   while (true) {
@@ -28,6 +36,7 @@ export async function findRepoRoot(startDir: string): Promise<string> {
   }
 }
 
+/** Resolves the on-disk cache directory for a given agent namespace. */
 export function resolveCacheDir(agent: AgentType, repoRoot: string): string {
   if (agent === "external") {
     return join(repoRoot, ".ai", "external-context-gatherer_cache");
@@ -35,6 +44,14 @@ export function resolveCacheDir(agent: AgentType, repoRoot: string): string {
   return join(repoRoot, ".ai", "local-context-gatherer_cache");
 }
 
+/**
+ * Reads and JSON-parses one cache file.
+ *
+ * @param filePath - Absolute cache file path.
+ * @returns Parsed object on success, or typed read/parse failures.
+ * @remarks Returns `FILE_NOT_FOUND` when the file is absent, and `PARSE_ERROR` when the
+ * file exists but contains invalid JSON. Low-level I/O failures return `FILE_READ_ERROR`.
+ */
 export async function readCache(filePath: string): Promise<Result<Record<string, unknown>>> {
   try {
     const content = await readFile(filePath, "utf-8");
@@ -53,6 +70,17 @@ export async function readCache(filePath: string): Promise<Result<Record<string,
   }
 }
 
+/**
+ * Writes cache content using advisory locking and atomic rename.
+ *
+ * @param filePath - Absolute cache file path to write.
+ * @param updates - Partial updates (`merge`) or full replacement payload (`replace`).
+ * @param mode - `merge` overlays updates onto existing JSON; `replace` writes payload as-is.
+ * @remarks In `merge` mode the function performs read-modify-write preserving unknown fields.
+ * Writes use temp-file + `rename()` for atomic visibility. A per-file advisory lock is
+ * acquired before mutation and released in `finally`, preventing concurrent writers from
+ * interleaving updates.
+ */
 export async function writeCache(
   filePath: string,
   updates: Partial<ExternalCacheFile> | Partial<LocalCacheFile> | Record<string, unknown>,
@@ -101,6 +129,13 @@ export async function writeCache(
   }
 }
 
+/**
+ * Lists JSON cache files for an agent namespace.
+ *
+ * @param agent - Cache namespace to inspect.
+ * @param repoRoot - Repository root used to resolve cache directory paths.
+ * @returns Absolute `.json` file paths; returns an empty array when directory is absent.
+ */
 export async function listCacheFiles(agent: AgentType, repoRoot: string): Promise<Result<string[]>> {
   const cacheDir = resolveCacheDir(agent, repoRoot);
   try {
@@ -157,6 +192,15 @@ export async function loadExternalCacheEntries(repoRoot: string): Promise<Result
   return { ok: true, value: entries };
 }
 
+/**
+ * Acquires an advisory lock file for a cache path.
+ *
+ * @param filePath - Cache file path whose lock (`.lock`) should be acquired.
+ * @returns `ok: true` when lock is acquired, otherwise typed lock failure.
+ * @remarks Uses atomic `O_EXCL` create semantics to guarantee single-writer lock acquisition.
+ * Existing locks are checked for staleness via lock age and PID liveness (`process.kill(pid, 0)`).
+ * Retries every 50ms and fails with `LOCK_TIMEOUT` after 5 seconds.
+ */
 export async function acquireLock(filePath: string): Promise<Result<void>> {
   const lockPath = `${filePath}.lock`;
   const start = Date.now();
@@ -197,6 +241,12 @@ export async function acquireLock(filePath: string): Promise<Result<void>> {
   }
 }
 
+/**
+ * Releases a previously acquired advisory lock file.
+ *
+ * @param filePath - Cache file path whose `.lock` file should be removed.
+ * @remarks `ENOENT` is intentionally ignored to keep release fire-and-forget safe.
+ */
 export async function releaseLock(filePath: string): Promise<void> {
   const lockPath = `${filePath}.lock`;
   try {
@@ -204,7 +254,7 @@ export async function releaseLock(filePath: string): Promise<void> {
   } catch (err) {
     const error = err as NodeJS.ErrnoException;
     if (error.code !== "ENOENT") {
-      console.warn(`[cache-ctrl] Warning: failed to release lock ${lockPath}: ${error.message}`);
+      process.stderr.write(`[cache-ctrl] Warning: failed to release lock ${lockPath}: ${error.message}\n`);
     }
   }
 }
@@ -220,7 +270,7 @@ async function isLockStale(lockPath: string): Promise<boolean> {
     const content = await readFile(lockPath, "utf-8");
     const pidStr = content.trim();
     const pid = parseInt(pidStr, 10);
-    if (isNaN(pid) || pid <= 0 || pid >= 4_194_304) {
+    if (Number.isNaN(pid) || pid <= 0 || pid >= 4_194_304) {
       return true;
     }
 

package/src/cache/externalCache.ts

@@ -1,51 +1,42 @@
-import { readdir } from "node:fs/promises";
-import { join } from "node:path";
-import type { ExternalCacheFile, CacheEntry } from "../types/cache.js";
-import { ExternalCacheFileSchema } from "../types/cache.js";
+import type { ExternalCacheFile, HeaderMeta } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
-import { readCache, listCacheFiles } from "./cacheManager.js";
+import { loadExternalCacheEntries } from "./cacheManager.js";
 import { scoreEntry } from "../search/keywordSearch.js";
-import { getFileStem } from "../utils/fileStem.js";
 
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
-export function resolveExternalCacheDir(repoRoot: string): string {
-  return join(repoRoot, ".ai", "external-context-gatherer_cache");
-}
-
-export async function resolveExternalFiles(repoRoot: string): Promise<Result<string[]>> {
-  const cacheDir = resolveExternalCacheDir(repoRoot);
-  try {
-    const entries = await readdir(cacheDir);
-    return {
-      ok: true,
-      value: entries
-        .filter((name) => name.endsWith(".json") && !name.endsWith(".lock"))
-        .map((name) => join(cacheDir, name)),
-    };
-  } catch (err) {
-    const error = err as NodeJS.ErrnoException;
-    if (error.code === "ENOENT") {
-      return { ok: true, value: [] };
-    }
-    return { ok: false, error: `Failed to list external cache directory: ${error.message}`, code: ErrorCode.FILE_READ_ERROR };
-  }
-}
-
-export function isExternalStale(entry: ExternalCacheFile, maxAgeMs?: number): boolean {
-  if (!entry.fetched_at) return true;
+/**
+ * Checks whether an external `fetched_at` timestamp exceeds staleness threshold.
+ *
+ * @param fetchedAt - ISO timestamp string stored in cache entry.
+ * @param maxAgeMs - Optional max age override in milliseconds.
+ * @returns `true` when timestamp is empty or older than the threshold.
+ */
+export function isFetchedAtStale(fetchedAt: string, maxAgeMs?: number): boolean {
+  if (!fetchedAt) return true;
   const threshold = maxAgeMs ?? DEFAULT_MAX_AGE_MS;
-  const age = Date.now() - new Date(entry.fetched_at).getTime();
+  const age = Date.now() - new Date(fetchedAt).getTime();
   return age > threshold;
 }
 
-export interface HeaderMeta {
-  etag?: string;
-  last_modified?: string;
-  checked_at: string;
-  status: "fresh" | "stale" | "unchecked";
+/**
+ * Evaluates staleness for a full external cache entry.
+ *
+ * @param entry - External cache entry.
+ * @param maxAgeMs - Optional max age override in milliseconds.
+ * @returns `true` when entry should be considered stale.
+ */
+export function isExternalStale(entry: ExternalCacheFile, maxAgeMs?: number): boolean {
+  return isFetchedAtStale(entry.fetched_at ?? "", maxAgeMs);
 }
 
+/**
+ * Merges newly fetched header metadata into an external cache entry.
+ *
+ * @param existing - Existing external cache entry.
+ * @param updates - Per-URL header metadata updates.
+ * @returns New entry with merged `header_metadata`.
+ */
 export function mergeHeaderMetadata(
   existing: ExternalCacheFile,
   updates: Record<string, HeaderMeta>,
@@ -59,6 +50,13 @@ export function mergeHeaderMetadata(
   };
 }
 
+/**
+ * Formats human-readable age text from an external `fetched_at` timestamp.
+ *
+ * @param fetchedAt - ISO timestamp string from cache entry.
+ * @returns Relative age string such as `"just now"`, `"2 hours ago"`, or `"invalidated"`.
+ * @remarks Returns `"invalidated"` sentinel when `fetchedAt` is empty.
+ */
 export function getAgeHuman(fetchedAt: string): string {
   if (!fetchedAt) return "invalidated";
 
@@ -89,39 +87,18 @@ export function getAgeHuman(fetchedAt: string): string {
  * Returns NO_MATCH if no entry scores above zero.
  */
 export async function resolveTopExternalMatch(repoRoot: string, subject: string): Promise<Result<string>> {
-  const filesResult = await listCacheFiles("external", repoRoot);
-  if (!filesResult.ok) return filesResult;
-
-  const candidates: Array<{ filePath: string; entry: CacheEntry }> = [];
-  for (const filePath of filesResult.value) {
-    const readResult = await readCache(filePath);
-    if (!readResult.ok) continue;
-    const parseResult = ExternalCacheFileSchema.safeParse(readResult.value);
-    if (!parseResult.success) continue;
-    const data = parseResult.data;
-    const stem = getFileStem(filePath);
-    const entrySubject = data.subject ?? stem;
-    candidates.push({
-      filePath,
-      entry: {
-        file: filePath,
-        agent: "external",
-        subject: entrySubject,
-        description: data.description,
-        fetched_at: data.fetched_at ?? "",
-      },
-    });
-  }
+  const entriesResult = await loadExternalCacheEntries(repoRoot);
+  if (!entriesResult.ok) return entriesResult;
 
   const keywords = [subject];
-  const scored = candidates
-    .map((c) => ({ ...c, score: scoreEntry(c.entry, keywords) }))
-    .filter((c) => c.score > 0)
+  const scored = entriesResult.value
+    .map((entry) => ({ entry, score: scoreEntry(entry, keywords) }))
+    .filter((candidate) => candidate.score > 0)
     .sort((a, b) => b.score - a.score);
 
   if (scored.length === 0) {
     return { ok: false, error: `No cache entry matched keyword "${subject}"`, code: ErrorCode.NO_MATCH };
   }
 
-  return { ok: true, value: scored[0]!.filePath };
+  return { ok: true, value: scored[0]!.entry.file };
 }

package/src/cache/graphCache.ts

@@ -0,0 +1,12 @@
+import { join } from "node:path";
+
+import { resolveLocalCacheDir } from "./localCache.js";
+
+export type { GraphCacheFile } from "../types/cache.js";
+
+/**
+ * Resolves the absolute path to graph.json.
+ */
+export function resolveGraphCachePath(repoRoot: string): string {
+  return join(resolveLocalCacheDir(repoRoot), "graph.json");
+}

package/src/cache/localCache.ts

@@ -1,9 +1,11 @@
 import { join } from "node:path";
 
+/** Resolves the local cache directory path under the repository root. */
 export function resolveLocalCacheDir(repoRoot: string): string {
   return join(repoRoot, ".ai", "local-context-gatherer_cache");
 }
 
+/** Resolves the local context cache file path (`context.json`). */
 export function resolveLocalCachePath(repoRoot: string): string {
   return join(resolveLocalCacheDir(repoRoot), "context.json");
 }

package/src/commands/checkFiles.ts

@@ -6,9 +6,13 @@ import { getGitTrackedFiles, getGitDeletedFiles, getUntrackedNonIgnoredFiles } f
 import { LocalCacheFileSchema } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { CheckFilesResult } from "../types/commands.js";
+import { toUnknownResult } from "../utils/errors.js";
 
-const toPosix = (p: string) => p.split(sep).join(posix.sep);
-
+/**
+ * Compares local tracked files against stored baselines and git file-set deltas.
+ * @returns Promise<Result<CheckFilesResult["value"]>>; common failures include FILE_NOT_FOUND,
+ * PARSE_ERROR, FILE_READ_ERROR, and UNKNOWN.
+ */
 export async function checkFilesCommand(): Promise<Result<CheckFilesResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -77,7 +81,6 @@ export async function checkFilesCommand(): Promise<Result<CheckFilesResult["valu
       },
     };
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: msg, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/checkFreshness.ts

@@ -1,13 +1,20 @@
 import { findRepoRoot, readCache, writeCache } from "../cache/cacheManager.js";
 import { isExternalStale, mergeHeaderMetadata, resolveTopExternalMatch } from "../cache/externalCache.js";
 import { checkFreshness } from "../http/freshnessChecker.js";
-import type { ExternalCacheFile } from "../types/cache.js";
+import type { ExternalCacheFile, HeaderMeta } from "../types/cache.js";
 import { ExternalCacheFileSchema } from "../types/cache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { CheckFreshnessArgs, CheckFreshnessResult } from "../types/commands.js";
-import type { HeaderMeta } from "../cache/externalCache.js";
 import { getFileStem } from "../utils/fileStem.js";
-
+import { toUnknownResult } from "../utils/errors.js";
+
+/**
+ * Performs HTTP freshness checks for the matched external cache entry sources.
+ *
+ * @param args - {@link CheckFreshnessArgs} command arguments.
+ * @returns Promise<Result<CheckFreshnessResult["value"]>>; common failures include
+ * NO_MATCH, URL_NOT_FOUND, PARSE_ERROR, FILE_READ_ERROR/FILE_WRITE_ERROR, and UNKNOWN.
+ */
 export async function checkFreshnessCommand(args: CheckFreshnessArgs): Promise<Result<CheckFreshnessResult["value"]>> {
   try {
     const repoRoot = await findRepoRoot(process.cwd());
@@ -33,21 +40,15 @@ export async function checkFreshnessCommand(args: CheckFreshnessArgs): Promise<R
 
     // Determine which URLs to check
     const sources = cacheEntry.sources ?? [];
-    let urlsToCheck = sources;
-
-    if (args.url) {
-      const found = sources.find((s) => s.url === args.url);
-      if (!found) {
-        return {
-          ok: false,
-          error: `URL not found in sources for subject '${subject}'`,
-          code: ErrorCode.URL_NOT_FOUND,
-        };
-      }
-      urlsToCheck = [found];
-    } else {
-      urlsToCheck = sources;
+    const specificSource = args.url ? sources.find((source) => source.url === args.url) : undefined;
+    if (args.url && !specificSource) {
+      return {
+        ok: false,
+        error: `URL not found in sources for subject '${subject}'`,
+        code: ErrorCode.URL_NOT_FOUND,
+      };
     }
+    const urlsToCheck = specificSource ? [specificSource] : sources;
 
     // Check freshness for each URL
     const sourceResults: Array<{
@@ -117,7 +118,6 @@ export async function checkFreshnessCommand(args: CheckFreshnessArgs): Promise<R
       },
     };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }

package/src/commands/flush.ts

@@ -3,7 +3,15 @@ import { findRepoRoot, listCacheFiles } from "../cache/cacheManager.js";
 import { resolveLocalCachePath } from "../cache/localCache.js";
 import { ErrorCode, type Result } from "../types/result.js";
 import type { FlushArgs, FlushResult } from "../types/commands.js";
+import { toUnknownResult } from "../utils/errors.js";
 
+/**
+ * Deletes cache files for one or both agent namespaces.
+ *
+ * @param args - {@link FlushArgs} command arguments.
+ * @returns Promise<Result<FlushResult["value"]>>; common failures include
+ * CONFIRMATION_REQUIRED, FILE_WRITE_ERROR, FILE_READ_ERROR, and UNKNOWN.
+ */
 export async function flushCommand(args: FlushArgs): Promise<Result<FlushResult["value"]>> {
   if (!args.confirm) {
     return {
@@ -49,7 +57,6 @@ export async function flushCommand(args: FlushArgs): Promise<Result<FlushResult[
 
     return { ok: true, value: { deleted, count: deleted.length } };
   } catch (err) {
-    const error = err as Error;
-    return { ok: false, error: error.message, code: ErrorCode.UNKNOWN };
+    return toUnknownResult(err);
   }
 }