@thecat69/cache-ctrl 1.0.0 → 1.2.0

package/skills/cache-ctrl-local/SKILL.md

@@ -5,209 +5,127 @@ description: How to use cache-ctrl to detect file changes and manage the local c
 
 # cache-ctrl — Local Cache Usage
 
-Manage `.ai/local-context-gatherer_cache/context.json` to avoid redundant full-repo scans.
-Three tiers of access — use the best one available.
-
-## Availability Detection (run once at startup)
-
-1. Call `cache_ctrl_check_files` (built-in tool).
-   - Success → **use Tier 1** for all operations below.
-   - Failure (tool not found / permission denied) → continue to step 2.
-2. Run `bash: "which cache-ctrl"`.
-   - Exit 0 → **use Tier 2** for all operations below.
-   - Not found → **use Tier 3** for all operations below.
-
----
-
 ## Fact-Writing Rules
 
-Facts must be **concise observations** about a file — not reproductions of its content.
-
-- **Each fact string must be ≤ 300 characters** (schema hard limit: 800). If an observation needs more, split it into two facts or summarize.
-- **Max 30 facts per file.** Choose only the most architecturally meaningful observations.
-- **Never write**: raw import lines, function bodies, code snippets, or verbatim text from the file.
-- **Do write**: what the file exports, what pattern it uses, what dependencies it has, what its responsibility is.
-
-**Good fact** ✅:
-> `"Exports writeCommand — validates subject, merges per-path facts atomically, returns Result<WriteResult>"`
-
-**Bad fact** ❌:
-> `"import { ExternalCacheFileSchema, LocalCacheFileSchema } from '../types/cache.js'; import { ErrorCode, Result } from '../types/result.js'; import { WriteArgs, WriteResult } from '../types/commands.js'"` ← this is raw file content
-
-**Global facts** are for cross-cutting structural observations only (e.g. CLI entry pattern, installation steps). Max 20, each ≤ 300 chars. Only update global_facts when you re-read a structural file (AGENTS.md, install.sh, package.json, *.toml, opencode.json).
-
----
-
-## Mandatory: Write Before Return
+Per-file entries use the `FileFacts` object shape:
 
-**Every invocation must call `cache_ctrl_write` before returning.** Returning without writing is a failure — the orchestrator will detect the missing write and re-invoke you.
+```json
+{
+  "summary": "One-sentence description of what this file does",
+  "role": "implementation",
+  "importance": 2,
+  "facts": ["Concise observation 1", "Concise observation 2"]
+}
+```
 
-Sequential checklist (do not skip any step):
+Fields:
+- **`summary`** — mandatory. One sentence.
+- **`role`** — mandatory. One of: `entry-point`, `interface`, `implementation`, `test`, `config`.
+- **`importance`** — strongly recommended. `1` = core, `2` = supporting, `3` = peripheral.
+- **`facts`** — optional. Max 10 items, each ≤ 300 chars.
 
-1. Call `cache_ctrl_check_files` — identify changed/new files
-2. Read only the changed/new files (skip unchanged ones)
-3. Extract concise facts per file (follow Fact-Writing Rules above)
-4. **Call `cache_ctrl_write` — MANDATORY** (even if only 1 file changed, even if only global_facts changed)
-5. Return your summary
+Content quality rules:
+- **Never write** raw import lines, code snippets, or verbatim file content.
+- **Do write** concise architectural observations: purpose, key exports, constraints, dependencies, notable patterns.
+- Write facts as **enumerable observations** — one entry per distinct property, up to the 10-item limit.
 
-If there are no changed files, the cache already exists and is non-empty, **and you were not invoked after a cache invalidation**, you may skip the write — but only in this case.
+Good example ✅:
+> `"Delegates local writes to writeLocalCommand and preserves unrelated paths through per-path merge"`
 
----
+Bad example ❌:
+> `"import { ExternalCacheFileSchema } from '../types/cache.js'"` ← raw file content
 
-## Startup Workflow
+**Global facts** — cross-cutting structural observations only (CLI entry pattern, installation steps, etc.). Max 20, each ≤ 300 chars. Only update `global_facts` when re-reading a structural file: `AGENTS.md`, `install.sh`, `opencode.json`, `package.json`, `*.toml`.
 
-### 1. Check if tracked files changed
+## Scan Workflow
 
-**Tier 1:** Call `cache_ctrl_check_files` (no parameters).
-**Tier 2:** `cache-ctrl check-files`
-**Tier 3:** `read` `.ai/local-context-gatherer_cache/context.json`.
-  - File absent → cold start, proceed to scan.
-  - File present → check `timestamp`. If older than 1 hour, treat as stale and re-scan. Otherwise treat as fresh.
+1. Call `cache_ctrl_check_files` to identify changed and new files.
+2. Read only the changed/new files (skip unchanged ones).
+3. Extract `FileFacts` per file (follow Fact-Writing Rules above).
+4. Call `cache_ctrl_write_local` — **mandatory** (see Write-Before-Return Rule below for the skip exception).
+5. Return your summary.
 
-Result interpretation (Tier 1 & 2):
-- `status: "unchanged"` → tracked files are content-stable; skip re-scan and return cached context.
-- `status: "changed"` → at least one tracked file changed; proceed to **delta scan** (read content of `changed_files` + `new_files` only — do not re-read unchanged files).
-- `status: "unchanged"` with empty `tracked_files` → cold start, proceed to scan.
+> **⚠ Cache is non-exhaustive:** `status: "unchanged"` only confirms previously-tracked files are stable — it does not mean the file set is complete. Always check `new_files` and `deleted_git_files` in the response.
 
-The response also reports:
-- `new_files` — untracked non-ignored files absent from cache, plus git-tracked files absent from cache when the cache is non-empty (blank-slate caches skip git-tracked files to avoid false positives on cold start)
-- `deleted_git_files` — git-tracked files deleted from the working tree (reported by `git ls-files --deleted`)
+## Write-Before-Return Rule
 
-> **⚠ Cache is non-exhaustive**: `status: "unchanged"` only confirms that previously-tracked files are content-stable — it does not mean the file set is complete. Always check `new_files` and `deleted_git_files` in the response; if either is non-empty, include those paths in the next write to keep the cache up to date.
+**Every invocation that reads any file MUST call `cache_ctrl_write_local` before returning.**
 
-### 2. Invalidate before writing (optional)
+The only time you may skip the write is when ALL of the following are true:
 
-> Do this only if cache is really outdated and a full rescan is needed. Otherwise just proceed with next step (writing).
+| Condition | Required value |
+|---|---|
+| `changed_files` from `check_files` | `[]` |
+| `new_files` from `check_files` | `[]` |
+| No files were force-requested by caller | true |
+| Cache already exists and is non-empty | true |
+| This invocation was NOT triggered by a cache invalidation | true |
 
-**Tier 1:** Call `cache_ctrl_invalidate` with `agent: "local"`.
-**Tier 2:** `cache-ctrl invalidate local`
-**Tier 3:** Skip — overwriting the file in step 3 is sufficient.
+If any condition is not met, you **must** write.
 
-### 3. Write cache after scanning
+> **⛔ Write-or-fail:** Returning without writing after reading files is a critical failure — the cache will be stale. Even if you believe facts are unchanged, if you read a file, you write.
 
-**Always use the write tool/command — never edit the file directly.** Direct writes bypass schema validation and can silently corrupt the cache format.
+## `cache_ctrl_write_local` Reference
 
-> **Write is per-path merge**: Submitted `tracked_files` entries replace existing entries for the same paths. Paths not in the submission are preserved. Entries for files deleted from disk are evicted automatically (no agent action needed).
+Always use `cache_ctrl_write_local` — never write cache files directly.
 
-#### Input fields (`content` object)
+#### Input fields
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
 | `topic` | `string` | ✅ | Human description of what was scanned |
 | `description` | `string` | ✅ | One-liner for keyword search |
-| `tracked_files` | `Array<{ path: string }>` | ✅ | Paths to track; `mtime` and `hash` are auto-computed by the tool |
-| `global_facts` | `string[]` | optional | Repo-level facts; last-write-wins; see trigger rule below |
-| `facts` | `Record<string, string[]>` | optional | Per-file facts keyed by path; per-path merge |
-| `cache_miss_reason` | `string` | optional | Why the previous cache was discarded |
-
-> **Cold start vs incremental**: On first run (no existing cache), submit all relevant files. On subsequent runs, submit only new and changed files — the tool merges them in.
-
-> **Auto-set by the tool — do not include**: `timestamp` (current UTC), `mtime` (filesystem `lstat()`), and `hash` (SHA-256) per `tracked_files` entry.
-
-### Scope rule for `facts`
-
-Submit `facts` ONLY for files you actually read in this session (i.e., files present in
-your submitted `tracked_files`). Never reconstruct or re-submit facts for unchanged files —
-the tool preserves them automatically via per-path merge.
-
-Submitting a facts key for a path absent from submitted `tracked_files` is a
-VALIDATION_ERROR and the entire write is rejected.
+| `tracked_files` | `Array<{ path: string }>` | ✅ | `mtime` and `hash` are auto-computed |
+| `facts` | `Record<string, FileFacts>` | optional | Per-file structured facts; per-path merge |
+| `global_facts` | `string[]` | optional | Last-write-wins; see trigger rule above |
+| `cache_miss_reason` | `string` | optional | Why prior cache was discarded |
 
-### Fact completeness
+> **Auto-set by the tool — do not include:** `timestamp`, `mtime`, `hash`.
+> **Write is per-path merge:** Submitted paths replace existing entries for those paths. Other paths are preserved. Deleted-file entries are evicted automatically.
 
-When a file appears in `changed_files` or `new_files`, read the **whole file** before writing
-facts — not just the diff. A 2-line change does not support a complete re-description of the
-file, and submitting partial facts for a re-read path **permanently replaces** whatever was
-cached before.
+#### Scope rule for `facts`
 
-Write facts as **enumerable observations** — one entry per notable characteristic (purpose,
-structure, key dependencies, patterns, constraints, entry points). Do not bundle multiple
-distinct properties into a single string. A file should have as many fact entries as it has
-distinct notable properties, not a prose summary compressed into one or two lines.
+Submit `facts` ONLY for files you actually read in this session (files present in `tracked_files`). Never reconstruct or re-submit facts for unchanged files — the tool preserves them automatically.
 
-### When to submit `global_facts`
+Submitting a `facts` key for a path absent from `tracked_files` is a `VALIDATION_ERROR` and the entire write is rejected.
 
-Submit `global_facts` only when you re-read at least one structural file in this session:
-AGENTS.md, install.sh, opencode.json, package.json, *.toml config files.
+#### Fact completeness
 
-If none of those are in `changed_files` or `new_files`, omit `global_facts` from the write.
-The existing value is preserved automatically.
+When a file appears in `changed_files` or `new_files`, read the **whole file** before writing facts — not just the diff. Submitting partial facts for a re-read path **permanently replaces** whatever was cached.
 
-### Eviction
-
-Facts for files deleted from disk are evicted automatically on the next write — no agent
-action needed. `global_facts` is never evicted.
-
-#### Tier 1 — `cache_ctrl_write`
+#### Example
 
 ```json
 {
-  "agent": "local",
-  "content": {
-    "topic": "neovim plugin configuration scan",
-    "description": "Full scan of lua/plugins tree for neovim lazy.nvim setup",
-    "tracked_files": [
-      { "path": "lua/plugins/ui/bufferline.lua" },
-      { "path": "lua/plugins/lsp/nvim-lspconfig.lua" }
-    ]
+  "topic": "src/commands scan",
+  "description": "Scan of src/commands after write refactor",
+  "tracked_files": [
+    { "path": "src/commands/writeLocal.ts" }
+  ],
+  "facts": {
+    "src/commands/writeLocal.ts": {
+      "summary": "Thin router dispatching write calls based on agent type.",
+      "role": "implementation",
+      "importance": 2,
+      "facts": [
+        "Delegates to writeLocalCommand for agent=local",
+        "Delegates to writeExternalCommand for all other agents"
+      ]
+    }
   }
 }
 ```
 
-#### Tier 2 — CLI
-
-`cache-ctrl write local --data '<json>'` — pass the same `content` object as JSON string.
-
-#### Tier 3
-
-Not available — there is no direct-file fallback for writes. If neither Tier 1 nor Tier 2 is accessible, request access to one of them.
-
-### 4. Confirm cache (optional)
-
-**Tier 1:** Call `cache_ctrl_list` with `agent: "local"` to confirm the entry was written.
-**Tier 2:** `cache-ctrl list --agent local`
-**Tier 3:** `read` `.ai/local-context-gatherer_cache/context.json` and verify `timestamp` is current.
-
-Note: local entries show `is_stale: true` only when `cache_ctrl_check_files` detects actual changes (changed files, new non-ignored files, or deleted files). A freshly-written cache with no subsequent file changes will show `is_stale: false`.
-
----
-
-## Tool / Command Reference
-
-| Operation | Tier 1 (built-in) | Tier 2 (CLI) | Tier 3 (manual) |
-|---|---|---|---|
-| Detect file changes | `cache_ctrl_check_files` | `cache-ctrl check-files` | read `context.json`, check `timestamp` |
-| Invalidate cache | `cache_ctrl_invalidate` | `cache-ctrl invalidate local` | overwrite file in next step |
-| Confirm written | `cache_ctrl_list` | `cache-ctrl list --agent local` | `read` file, check `timestamp` |
-| Read facts (filtered) | `cache_ctrl_inspect` with `filter`, `folder`, or `searchFacts` | `cache-ctrl inspect local context --filter <kw>[,<kw>...]` / `--folder <path>` / `--search-facts <kw>[,<kw>...]` | `read` file, extract `facts`/`global_facts` |
-| Read all facts (rare) | `cache_ctrl_inspect` (no filter) | `cache-ctrl inspect local context` | `read` file directly |
-| Write cache | `cache_ctrl_write` | `cache-ctrl write local --data '<json>'` | ❌ not available |
-
-> **⚠ Always use at least one filter when reading facts for a specific task.** Three targeting options are available — use the most specific one that fits your task:
->
-> | Flag | What it matches | Best for |
-> |---|---|---|
-> | `--filter <kw>` | File path contains keyword | When you know which files by name/path segment |
-> | `--folder <path>` | File path starts with folder prefix (recursive) | When you need all files in a directory subtree |
-> | `--search-facts <kw>` | Any fact string contains keyword | When you need files related to a concept, pattern, or API |
->
-> The flags are AND-ed when combined. Omit all filters only when you genuinely need facts for the entire repository (rare — e.g. building a full index; only appropriate for ≤ ~20 tracked files). An unfiltered `inspect` on a large repo can return thousands of fact strings.
-
-> **`tracked_files` is never returned by `inspect` for the local agent.** It is internal operational metadata consumed by `check-files`. It will not appear in any inspect response.
-
-## server_time in Responses
-
-Every `cache_ctrl_*` tool call returns a `server_time` field at the outer JSON level:
-
-```json
-{ "ok": true, "value": { ... }, "server_time": "2026-04-05T12:34:56.789Z" }
-```
-
-Use this to assess how stale stored timestamps are — you do not need `bash` or system access to know the current time.
+## Eviction
 
-## Cache Location
+Facts for files deleted from disk are evicted automatically on the next write — no agent action needed. `global_facts` is never evicted.
 
-`.ai/local-context-gatherer_cache/context.json` — single file, no per-subject splitting.
+## Tool Reference
 
-No time-based TTL for Tier 1/2. Freshness determined by `cache_ctrl_check_files`.
-Tier 3 uses a 1-hour `timestamp` TTL as a rough proxy.
+| Operation | Tool |
+|---|---|
+| Detect file changes | `cache_ctrl_check_files` |
+| Invalidate cache | `cache_ctrl_invalidate` (agent: "local") |
+| Write cache | `cache_ctrl_write_local` |
+| Read facts (filtered) | `cache_ctrl_inspect` (agent: "local", filter / folder / search_facts) |
+| Confirm written | `cache_ctrl_list` (agent: "local") |

package/src/analysis/graphBuilder.ts

@@ -0,0 +1,85 @@
+import path from "node:path";
+
+import { extractSymbols } from "./symbolExtractor.js";
+
+/** Dependency metadata tracked for one source file node in the graph. */
+export interface GraphNode {
+  deps: string[];
+  defs: string[];
+}
+
+/** Directed dependency graph keyed by absolute source file path. */
+export type DependencyGraph = Map<string, GraphNode>;
+
+const RESOLUTION_EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx"];
+
+function resolveDependencyToKnownFile(depPath: string, knownFiles: Set<string>): string | null {
+  for (const extension of RESOLUTION_EXTENSIONS) {
+    const candidatePath = `${depPath}${extension}`;
+    if (knownFiles.has(candidatePath)) {
+      return candidatePath;
+    }
+  }
+
+  const basename = path.basename(depPath);
+  if (basename.endsWith(".js")) {
+    const withoutJs = depPath.slice(0, -3);
+    for (const extension of [".ts", ".tsx"]) {
+      const candidatePath = `${withoutJs}${extension}`;
+      if (knownFiles.has(candidatePath)) {
+        return candidatePath;
+      }
+    }
+  }
+
+  if (basename.endsWith(".jsx")) {
+    const withoutJsx = depPath.slice(0, -4);
+    const candidatePath = `${withoutJsx}.tsx`;
+    if (knownFiles.has(candidatePath)) {
+      return candidatePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Build a dependency graph for all source files under repoRoot.
+ *
+ * @param filePaths - Source file paths to include as graph nodes.
+ * @param repoRoot - Repository root for symbol extraction and import resolution.
+ * @returns Dependency graph keyed by resolved absolute file paths.
+ *
+ * Files not in the provided list are filtered from deps.
+ */
+export async function buildGraph(filePaths: string[], repoRoot: string): Promise<DependencyGraph> {
+  const absoluteFilePaths = filePaths.map((filePath) => path.resolve(filePath));
+  const knownFileSet = new Set(absoluteFilePaths);
+
+  const extractedSymbols = await Promise.all(
+    absoluteFilePaths.map(async (filePath) => ({
+      filePath,
+      symbols: await extractSymbols(filePath, repoRoot),
+    })),
+  );
+
+  const graph: DependencyGraph = new Map();
+
+  for (const { filePath, symbols } of extractedSymbols) {
+    const resolvedDependencies = new Set<string>();
+
+    for (const dependency of symbols.deps) {
+      const resolvedDependency = resolveDependencyToKnownFile(dependency, knownFileSet);
+      if (resolvedDependency !== null) {
+        resolvedDependencies.add(resolvedDependency);
+      }
+    }
+
+    graph.set(filePath, {
+      deps: [...resolvedDependencies],
+      defs: symbols.defs,
+    });
+  }
+
+  return graph;
+}

package/src/analysis/pageRank.ts

@@ -0,0 +1,164 @@
+import type { DependencyGraph } from "./graphBuilder.js";
+
+/** Tuning options for dependency-graph PageRank computation. */
+export interface PageRankOptions {
+  /** Damping factor (default 0.85) */
+  dampingFactor?: number;
+  /** Max iterations (default 100) */
+  maxIterations?: number;
+  /** Convergence threshold (default 1e-6) */
+  tolerance?: number;
+  /** Files to use as personalization seeds (boosts their rank and neighbors) */
+  seedFiles?: string[];
+}
+
+/**
+ * Compute Personalized PageRank over a dependency graph.
+ * Returns a map of file path → rank score (normalized, sums to 1.0).
+ * Higher rank = more central / more relevant to seed files.
+ */
+export function computePageRank(
+  graph: DependencyGraph,
+  options?: PageRankOptions,
+): Map<string, number> {
+  const nodes = [...graph.keys()];
+  const nodeCount = nodes.length;
+
+  if (nodeCount === 0) {
+    return new Map();
+  }
+
+  const dampingFactor = options?.dampingFactor ?? 0.85;
+  const maxIterations = options?.maxIterations ?? 100;
+  const tolerance = options?.tolerance ?? 1e-6;
+
+  const personalization = buildPersonalizationVector(nodes, options?.seedFiles);
+  const inLinks = buildInLinks(graph, nodes);
+
+  let ranks = new Map<string, number>();
+  const initialRank = 1 / nodeCount;
+  for (const node of nodes) {
+    ranks.set(node, initialRank);
+  }
+
+  for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+    const danglingRank = computeDanglingRank(graph, ranks);
+    const danglingContribution = dampingFactor * (danglingRank / nodeCount);
+
+    const nextRanks = new Map<string, number>();
+    let totalDelta = 0;
+
+    for (const node of nodes) {
+      const incomingNodes = inLinks.get(node) ?? [];
+      let incomingContribution = 0;
+
+      for (const sourceNode of incomingNodes) {
+        const sourceRank = ranks.get(sourceNode);
+        if (sourceRank === undefined) {
+          continue;
+        }
+
+        const outDegree = graph.get(sourceNode)?.deps.length ?? 0;
+        if (outDegree > 0) {
+          incomingContribution += sourceRank / outDegree;
+        }
+      }
+
+      const personalWeight = personalization.get(node) ?? 0;
+      const rank = (1 - dampingFactor) * personalWeight + dampingFactor * incomingContribution + danglingContribution;
+      nextRanks.set(node, rank);
+
+      const previousRank = ranks.get(node) ?? 0;
+      totalDelta += Math.abs(rank - previousRank);
+    }
+
+    ranks = nextRanks;
+
+    if (totalDelta < tolerance) {
+      break;
+    }
+  }
+
+  return normalizeRanks(ranks);
+}
+
+function buildInLinks(graph: DependencyGraph, nodes: string[]): Map<string, string[]> {
+  const inLinks = new Map<string, string[]>();
+  for (const node of nodes) {
+    inLinks.set(node, []);
+  }
+
+  for (const [sourceNode, graphNode] of graph.entries()) {
+    for (const targetNode of graphNode.deps) {
+      const targetInLinks = inLinks.get(targetNode);
+      if (targetInLinks) {
+        targetInLinks.push(sourceNode);
+      }
+    }
+  }
+
+  return inLinks;
+}
+
+function buildPersonalizationVector(nodes: string[], seedFiles: string[] | undefined): Map<string, number> {
+  const vector = new Map<string, number>();
+
+  const seedSet = new Set(seedFiles ?? []);
+  const validSeeds = nodes.filter((node) => seedSet.has(node));
+
+  if (validSeeds.length > 0) {
+    const seedWeight = 1 / validSeeds.length;
+    for (const node of nodes) {
+      vector.set(node, 0);
+    }
+    for (const seed of validSeeds) {
+      vector.set(seed, seedWeight);
+    }
+    return vector;
+  }
+
+  const uniformWeight = 1 / nodes.length;
+  for (const node of nodes) {
+    vector.set(node, uniformWeight);
+  }
+  return vector;
+}
+
+function computeDanglingRank(graph: DependencyGraph, ranks: Map<string, number>): number {
+  let danglingRank = 0;
+
+  for (const [node, graphNode] of graph.entries()) {
+    if (graphNode.deps.length > 0) {
+      continue;
+    }
+    danglingRank += ranks.get(node) ?? 0;
+  }
+
+  return danglingRank;
+}
+
+function normalizeRanks(ranks: Map<string, number>): Map<string, number> {
+  let totalRank = 0;
+  for (const value of ranks.values()) {
+    totalRank += value;
+  }
+
+  if (totalRank <= 0) {
+    const normalized = new Map<string, number>();
+    const size = ranks.size;
+    if (size === 0) {
+      return normalized;
+    }
+    const uniformRank = 1 / size;
+    for (const node of ranks.keys()) {
+      normalized.set(node, uniformRank);
+    }
+    return normalized;
+  }
+
+  const normalized = new Map<string, number>();
+  for (const [node, value] of ranks.entries()) {
+    normalized.set(node, value / totalRank);
+  }
+  return normalized;
+}