@thecat69/cache-ctrl 1.0.0 → 1.1.1

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

@@ -6,16 +6,9 @@ description: How to use cache-ctrl to check staleness, search, and manage the ex
 # cache-ctrl — External Cache Usage
 
 Manage `.ai/external-context-gatherer_cache/` to avoid redundant HTTP fetches.
-Three tiers of access — use the best one available.
+Two tiers of access — use the best one available.
 
-## Availability Detection (run once at startup)
-
-1. Call `cache_ctrl_list` (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.
+> Availability Detection: see `cache-ctrl-caller`.
 
 ---
 
@@ -25,7 +18,6 @@ Three tiers of access — use the best one available.
 
 **Tier 1:** Call `cache_ctrl_list` with `agent: "external"`.
 **Tier 2:** `cache-ctrl list --agent external`
-**Tier 3:** `glob` `.ai/external-context-gatherer_cache/*.json` → for each match, `read` the file and check `fetched_at`. Stale if `fetched_at` is empty or older than 24 hours.
 
 - Entry for target subject is fresh → **skip fetching, return cached content**.
 - Entry is stale or absent → proceed to step 2.
@@ -34,10 +26,9 @@ For borderline cases (entry recently turned stale):
 
 **Tier 1:** Call `cache_ctrl_check_freshness` with the subject keyword.
 **Tier 2:** `cache-ctrl check-freshness <subject-keyword>`
-**Tier 3:** Re-read the file and compare `fetched_at` with current time. If within the last hour, treat as fresh.
 
-- `overall: "fresh"` (Tier 1/2) or fresh by timestamp (Tier 3) → skip fetch.
-- `overall: "stale"` / `"error"` or stale by timestamp → proceed to fetch.
+- `overall: "fresh"` (Tier 1/2) → skip fetch.
+- `overall: "stale"` / `"error"` → proceed to fetch.
 
 ### 2. Search before creating a new subject
 
@@ -45,30 +36,23 @@ Before fetching a brand-new subject, check whether related info is already cache
 
 **Tier 1:** Call `cache_ctrl_search` with relevant keywords.
 **Tier 2:** `cache-ctrl search <keyword> [<keyword>...]`
-**Tier 3:** `glob` `.ai/external-context-gatherer_cache/*.json` → `read` each file, scan the `subject` and `description` fields for keyword matches.
 
 ### 3. Write cache after fetching
 
-**Always use the write tool/command — never write cache files directly via `edit`.** Direct writes bypass schema validation and can silently corrupt the cache format.
+**Always use the write tool/command — never write cache files directly.** Direct writes bypass schema validation and can silently corrupt the cache format.
 
-**Tier 1:** Call `cache_ctrl_write` with:
+**Tier 1:** Call `cache_ctrl_write_external` with:
 ```json
 {
-  "agent": "external",
   "subject": "<subject>",
-  "content": {
-    "subject": "<subject>",
-    "description": "<one-line summary>",
-    "fetched_at": "<ISO 8601 now>",
-    "sources": [{ "type": "<type>", "url": "<canonical-url>" }],
-    "header_metadata": {}
-  }
+  "description": "<one-line summary>",
+  "fetched_at": "<ISO 8601 now>",
+  "sources": [{ "type": "<type>", "url": "<canonical-url>" }],
+  "header_metadata": {}
 }
 ```
 
-**Tier 2:** `cache-ctrl write external <subject> --data '<json>'`
-
-**Tier 3:** Same as Tier 2 — there is no direct-file fallback for writes. If neither Tier 1 nor Tier 2 is available, request access to one of them.
+**Tier 2:** `cache-ctrl write-external <subject> --data '<json>'`
 
 #### ExternalCacheFile schema
 
@@ -98,20 +82,19 @@ All fields are validated on write. Unknown extra fields are allowed and preserve
 
 **Tier 1:** Call `cache_ctrl_invalidate` with `agent: "external"` and the subject keyword.
 **Tier 2:** `cache-ctrl invalidate external <subject-keyword>`
-**Tier 3:** `read` the file, set `fetched_at` to `""`, `edit` it back.
 
 ---
 
 ## Tool / Command Reference
 
-| Operation | Tier 1 (built-in) | Tier 2 (CLI) | Tier 3 (manual) |
-|---|---|---|---|
-| List entries | `cache_ctrl_list` | `cache-ctrl list --agent external` | `glob` + `read` each JSON |
-| HTTP freshness check | `cache_ctrl_check_freshness` | `cache-ctrl check-freshness <subject>` | compare `fetched_at` with now |
-| Search entries | `cache_ctrl_search` | `cache-ctrl search <kw>...` | `glob` + scan `subject`/`description` |
-| View full entry | `cache_ctrl_inspect` | `cache-ctrl inspect external <subject>` | `read` file directly |
-| Invalidate entry | `cache_ctrl_invalidate` | `cache-ctrl invalidate external <subject>` | set `fetched_at` to `""` via `edit` |
-| Write entry | `cache_ctrl_write` | `cache-ctrl write external <subject> --data '<json>'` | ❌ not available |
+| Operation | Tier 1 (built-in) | Tier 2 (CLI) |
+|---|---|---|
+| List entries | `cache_ctrl_list` | `cache-ctrl list --agent external` |
+| HTTP freshness check | `cache_ctrl_check_freshness` | `cache-ctrl check-freshness <subject>` |
+| Search entries | `cache_ctrl_search` | `cache-ctrl search <kw>...` |
+| View full entry | `cache_ctrl_inspect` | `cache-ctrl inspect external <subject>` |
+| Invalidate entry | `cache_ctrl_invalidate` | `cache-ctrl invalidate external <subject>` |
+| Write entry | `cache_ctrl_write_external` | `cache-ctrl write-external <subject> --data '<json>'` |
 
 ## Cache Location
 
@@ -119,12 +102,4 @@ All fields are validated on write. Unknown extra fields are allowed and preserve
 
 Staleness threshold: `fetched_at` is empty **or** older than 24 hours.
 
-## 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 `fetched_at` timestamps are — you do not need `bash` or system access to know the current time.
+> All `cache_ctrl_*` tools return `server_time`; see `cache-ctrl-caller` for freshness-decision usage.

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

@@ -6,67 +6,91 @@ 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.
+Two 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.
+> Availability Detection: see `cache-ctrl-caller`.
 
 ---
 
 ## Fact-Writing Rules
+Per-file `facts` entries are no longer flat string arrays. Each path now maps to a
+**`FileFacts` object**:
+
+```json
+{
+  "summary": "One-sentence description of what this file does",
+  "role": "implementation",
+  "importance": 2,
+  "facts": ["Concise observation 1", "Concise observation 2"]
+}
+```
+
+Required and recommended fields:
+
+- **`summary` is mandatory** when writing a file entry. Keep it to one sentence.
+- **`role` is mandatory** when writing a file entry. Must be one of:
+  - `entry-point`
+  - `interface`
+  - `implementation`
+  - `test`
+  - `config`
+- **`importance` is optional but strongly recommended**:
+  - `1` = core module
+  - `2` = supporting module
+  - `3` = peripheral/config module
+- **`facts` is optional** and capped at **10 items**, each **≤ 300 chars**.
 
-Facts must be **concise observations** about a file — not reproductions of its content.
+Content quality rules:
 
-- **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.
+- **Never write** raw import lines, function bodies, code snippets, or verbatim text from the file.
+- **Do write** concise architectural observations: purpose, key exports, constraints, dependencies, notable patterns.
 
-**Good fact** ✅:
-> `"Exports writeCommand — validates subject, merges per-path facts atomically, returns Result<WriteResult>"`
+**Good `facts[]` item** ✅:
+> `"Delegates local writes to writeLocalCommand and preserves unrelated paths through per-path merge"`
 
-**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
+**Bad `facts[]` item** ❌:
+> `"import { ExternalCacheFileSchema, LocalCacheFileSchema } from '../types/cache.js'; import { ErrorCode, Result } from '../types/result.js'"` ← 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
-
-**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.
+**Every invocation that reads any file MUST call `cache_ctrl_write_local` before returning — no exceptions, no edge cases.**
 
 Sequential checklist (do not skip any step):
 
 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)
+4. **Call `cache_ctrl_write_local` — MANDATORY. NO EXCEPTIONS.** (even if only 1 file changed, even if only global_facts changed, even if you believe the facts are identical to what is cached)
 5. Return your summary
 
-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.
+> **⛔ Write-or-fail rule**: If you read any file in steps 2–3, you MUST call `cache_ctrl_write_local` in step 4. Returning without writing after reading files is a critical failure — the cache will be stale and the orchestrator will detect the missing write and re-invoke you. Even if zero files were read, you must still consult the decision table below before deciding to skip the write.
+
+**The only time you may skip `cache_ctrl_write_local` is when ALL of the following are true simultaneously:**
+
+| Condition | Required value |
+|---|---|
+| `changed_files` from `cache_ctrl_check_files` | empty `[]` |
+| `new_files` from `cache_ctrl_check_files` | empty `[]` |
+| No files were force-requested by the caller | true |
+| Cache already exists and is non-empty | true |
+| This invocation was NOT triggered by a cache invalidation | true |
+
+If any one of these conditions is not met, you **must** write.
 
 ---
 
 ## Startup Workflow
-
 ### 1. Check if tracked files changed
 
 **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.
 
 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: "changed"` → at least one tracked file changed; proceed to **delta scan**.
 - `status: "unchanged"` with empty `tracked_files` → cold start, proceed to scan.
 
 The response also reports:
@@ -76,20 +100,17 @@ The response also reports:
 > **⚠ 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.
 
 ### 2. Invalidate before writing (optional)
-
 > Do this only if cache is really outdated and a full rescan is needed. Otherwise just proceed with next step (writing).
 
 **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.
 
 ### 3. Write cache after scanning
-
-**Always use the write tool/command — never edit the file directly.** Direct writes bypass schema validation and can silently corrupt the cache format.
+**Always use the write tool/command — never write the file directly.** Direct writes bypass schema validation and can silently corrupt the cache format.
 
 > **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).
 
-#### Input fields (`content` object)
+#### Input fields (top-level args)
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
@@ -97,7 +118,7 @@ The response also reports:
 | `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 |
+| `facts` | `Record<string, FileFacts>` | optional | Per-file structured 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.
@@ -105,7 +126,6 @@ The response also reports:
 > **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.
@@ -114,7 +134,6 @@ Submitting a facts key for a path absent from submitted `tracked_files` is a
 VALIDATION_ERROR and the entire write is rejected.
 
 ### Fact completeness
-
 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
@@ -123,10 +142,30 @@ cached before.
 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.
+distinct notable properties, up to the 10-item limit.
 
-### When to submit `global_facts`
+Each per-file `facts` entry MUST include `summary` + `role`, should include `importance`,
+and may include an optional `facts[]` list.
 
+#### `cache_ctrl_write_local` facts shape example (`FileFacts`)
+
+```json
+{
+  "facts": {
+    "src/commands/writeLocal.ts": {
+      "summary": "Thin router dispatching write calls to writeLocal or writeExternal based on agent type.",
+      "role": "implementation",
+      "importance": 2,
+      "facts": [
+        "Delegates to writeLocalCommand for agent=local",
+        "Delegates to writeExternalCommand for all other agents"
+      ]
+    }
+  }
+}
+```
+
+### When to submit `global_facts`
 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.
 
@@ -134,80 +173,50 @@ If none of those are in `changed_files` or `new_files`, omit `global_facts` from
 The existing value is preserved automatically.
 
 ### 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`
+#### Tier 1 — `cache_ctrl_write_local`
 
 ```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": "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" }
+  ]
 }
 ```
 
 #### 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.
+`cache-ctrl write-local --data '<json>'` — pass the same top-level fields as the JSON value.
 
 ### 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`.
+Note: local entries show `is_stale: true` only when `cache_ctrl_check_files` detects actual changes.
 
 ---
 
 ## Tool / Command Reference
+| Operation | Tier 1 (built-in) | Tier 2 (CLI) |
+|---|---|---|
+| Detect file changes | `cache_ctrl_check_files` | `cache-ctrl check-files` |
+| Invalidate cache | `cache_ctrl_invalidate` | `cache-ctrl invalidate local` |
+| Confirm written | `cache_ctrl_list` | `cache-ctrl list --agent local` |
+| 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 all facts (rare) | `cache_ctrl_inspect` (no filter) | `cache-ctrl inspect local context` |
+| Write cache | `cache_ctrl_write_local` | `cache-ctrl write-local --data '<json>'` |
 
-| 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" }
-```
+> For `inspect` filter targeting options, see `cache-ctrl-caller`.
 
-Use this to assess how stale stored timestamps are — you do not need `bash` or system access to know the current time.
+> All `cache_ctrl_*` tools return `server_time`; see `cache-ctrl-caller` for freshness-decision usage.
 
 ## Cache Location
 
 `.ai/local-context-gatherer_cache/context.json` — single file, no per-subject splitting.
 
 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.

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,167 @@
+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) {
+      if (!inLinks.has(targetNode)) {
+        continue;
+      }
+      const targetInLinks = inLinks.get(targetNode);
+      if (targetInLinks !== undefined) {
+        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;
+}