flavor-code 1.2.11 → 1.2.13

package/README.md

@@ -35,6 +35,7 @@ Flavor Code connects to OpenAI, Anthropic, or compatible services and works with
 | 🧭 | **Controlled progress on complex tasks** | Task plans, sub-agents, steering, follow-ups, `/loop`, and `/goal` |
 | ⏪ | **Traceable, resumable results** | Full timeline, checkpoints, rewind, traces, diffs, and failure audits |
 | 🧠 | **Local long-term context** | Memory, Skills, plugins, and project guides stored on your machine |
+| 🔎 | **Code graph navigation** | A local AST code-graph index (`.flavor/astgraph/`) powers `ast_search`/`ast_callers`/`ast_impact` queries for precise symbol lookup and reachability tracing |
 | 🎨 | **E2E requirement-to-delivery** | From a rough requirement or a design export to a delivered product: PRD, interactive prototype, visual implementation, API integration, autonomous acceptance, and scored delivery (Electron only) |
 | 🛡️ | **Clear permission boundaries** | Independent control over read, write, Shell, network, and destructive actions; Docker supported |
 
@@ -152,41 +153,41 @@ Common commands:
 | `/memory`, `/remember`, `/forget`, `/forget-cold` | Manage long-term memory; `/forget-cold` purges cold entries and their files |
 | `/mcp` | View and manage MCP servers |
 | `/loop <goal>` | Run an autonomous loop with verification |
-| `/goal <objective>` | Run the plan, execute, adversarial-review workflow |
-| `/pals`, `/chat`, `/co-work` | Discover and collaborate with other local CLI instances |
-| `/audit` | View tool failure audits |
-
-You can submit steering or queue follow-ups while a run is in progress; once the current model response finishes, the task picks up new instructions at safe boundaries.
-
-#### CLI pals and cross-project work
-
-Interactive CLI instances on the same Windows or macOS user account can collaborate over local-only IPC (Windows named pipes or Unix sockets; no TCP fallback). Give each window a memorable alias:
-
-```bash
-# terminal A, in project A
-flavor --pal-name A
-
-# terminal B, in project B
-flavor --pal-name B
-```
-
-Useful commands:
-
-```text
-/pals                              # aliases and per-process UUIDs
-/pals --verbose                    # also show project paths and timestamps
-/pals rename api                   # rename this active instance
-/chat B Update the API and tests   # deliver to B and start its agent safely
-/co-work B Upgrade B, then adapt A # negotiate one plan before parallel work
-/co-work status [co-work-uuid]
-/co-work cancel <co-work-uuid> [reason]
-```
-
-`/chat` is bidirectional and task-oriented. If B is idle, the attributed message starts a normal model turn; if B is already running, it becomes steering, or a follow-up when another local submission is pending. Remote text is converted to a safe non-slash prompt, so `/exit`-like text is not dispatched as a local command. B can answer with `/chat A ...`.
-
-`/co-work` first places both agents in planning and waits for both to accept the same hashed plan and declare READY. Early READY intents are retained, and only the broker's exactly-once START event opens parallel execution. Each agent works only in its own project, receives only its assigned tasks, and reports bounded completion evidence. The broker-selected integration owner verifies all assertions and emits END or FAIL through `CoWorkIntegrate`. Communication uses authenticated, bounded local IPC with no TCP listener; peer input cannot approve tools or access the other workspace. UUID/alias routing and the protocol already support a third active client; durable artifact exchange, broker-restart journaling/recovery, and large-group coordination are later hardening work. See the [CLI pals specification](./docs/specs/2026-08-14-cli-pals-cowork.md).
-
-### Electron Desktop
+| `/goal <objective>` | Run the plan, execute, adversarial-review workflow |
+| `/pals`, `/chat`, `/co-work` | Discover and collaborate with other local CLI instances |
+| `/audit` | View tool failure audits |
+
+You can submit steering or queue follow-ups while a run is in progress; once the current model response finishes, the task picks up new instructions at safe boundaries.
+
+#### CLI pals and cross-project work
+
+Interactive CLI instances on the same Windows or macOS user account can collaborate over local-only IPC (Windows named pipes or Unix sockets; no TCP fallback). Give each window a memorable alias:
+
+```bash
+# terminal A, in project A
+flavor --pal-name A
+
+# terminal B, in project B
+flavor --pal-name B
+```
+
+Useful commands:
+
+```text
+/pals                              # aliases and per-process UUIDs
+/pals --verbose                    # also show project paths and timestamps
+/pals rename api                   # rename this active instance
+/chat B Update the API and tests   # deliver to B and start its agent safely
+/co-work B Upgrade B, then adapt A # negotiate one plan before parallel work
+/co-work status [co-work-uuid]
+/co-work cancel <co-work-uuid> [reason]
+```
+
+`/chat` is bidirectional and task-oriented. If B is idle, the attributed message starts a normal model turn; if B is already running, it becomes steering, or a follow-up when another local submission is pending. Remote text is converted to a safe non-slash prompt, so `/exit`-like text is not dispatched as a local command. B can answer with `/chat A ...`.
+
+`/co-work` first places both agents in planning and waits for both to accept the same hashed plan and declare READY. Early READY intents are retained, and only the broker's exactly-once START event opens parallel execution. Each agent works only in its own project, receives only its assigned tasks, and reports bounded completion evidence. The broker-selected integration owner verifies all assertions and emits END or FAIL through `CoWorkIntegrate`. Communication uses authenticated, bounded local IPC with no TCP listener; peer input cannot approve tools or access the other workspace. UUID/alias routing and the protocol already support a third active client; durable artifact exchange, broker-restart journaling/recovery, and large-group coordination are later hardening work. See the [CLI pals specification](./docs/specs/2026-08-14-cli-pals-cowork.md).
+
+### Electron Desktop
 
 ```bash
 npm run desktop:dev      # dev mode

package/README.zh-CN.md

@@ -35,6 +35,7 @@ Flavor Code 接入 OpenAI、Anthropic 或兼容服务，在受控工作区内使
 | 🧭 | **复杂任务可控推进** | 任务计划、子 Agent、steering、follow-up、`/loop` 和 `/goal` |
 | ⏪ | **结果可追溯、可恢复** | 完整时间线、checkpoint、rewind、trace、Diff 和失败审计 |
 | 🧠 | **本地长期上下文** | 记忆、Skill、插件和项目指南均保存在本机 |
+| 🔎 | **代码图导航** | 本地 AST 代码图索引（`.flavor/astgraph/`），通过 `ast_search`/`ast_callers`/`ast_impact` 等查询精确定位符号、追踪可达性 |
 | 🎨 | **E2E 需求到交付** | 从粗需求或设计稿到可交付产品：PRD、交互原型、视觉还原、接口联调、自主验收与评分交付（仅 Electron） |
 | 🛡️ | **明确的权限边界** | 分别控制读、写、Shell、网络和破坏性操作，也可使用 Docker |
 
@@ -152,41 +153,41 @@ OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-
 | `/memory`、`/remember`、`/forget`、`/forget-cold` | 管理长期记忆；`/forget-cold` 清空 cold 记忆及其文件 |
 | `/mcp` | 查看和管理 MCP 服务 |
 | `/loop <goal>` | 运行带验证的自治循环 |
-| `/goal <objective>` | 运行规划、执行、对抗审查流程 |
-| `/pals`、`/chat`、`/co-work` | 发现并协作其他本机 CLI 实例 |
-| `/audit` | 查看工具失败审计 |
-
-运行中可以提交 steering 或排队 follow-up；当前模型响应结束后，任务会在安全边界处接收新指令。
-
-#### CLI Pals 与跨项目协作
-
-同一 Windows 或 macOS 用户下的交互式 CLI 可以通过纯本地 IPC 协作（Windows named pipe 或 Unix socket，不回退到 TCP）。先给每个窗口一个容易识别的别名：
-
-```bash
-# 终端 A，位于项目 A
-flavor --pal-name A
-
-# 终端 B，位于项目 B
-flavor --pal-name B
-```
-
-常用命令：
-
-```text
-/pals                              # 查看别名和每进程 UUID
-/pals --verbose                    # 额外显示项目路径和时间
-/pals rename api                   # 重命名当前活动实例
-/chat B 更新 API 和测试             # 投递给 B，并安全启动其 Agent
-/co-work B 先升级 B，再兼容 A        # 先协商同一计划，再并行开工
-/co-work status [co-work-uuid]
-/co-work cancel <co-work-uuid> [reason]
-```
-
-`/chat` 支持双向任务通信。B 空闲时，带来源标识的消息会启动正常模型回合；B 正在运行时，消息会成为 steering；已有本地提交待运行时则成为 follow-up。远端文本会转换成安全的非斜杠 prompt，因此 `/exit` 一类文本不会被当成本地命令分派。B 可以用 `/chat A ...` 回复。
-
-`/co-work` 会先让双方进入规划，等待双方接受同一个哈希计划并声明 READY；较早的 READY 意图会被保留，只有 broker 恰好一次的 START 事件才会放行并行执行。每个 Agent 只在自己的项目内工作，只接收分配给自己的任务，并提交有界的完成证据。broker 指定的集成负责人会检查所有断言，再通过 `CoWorkIntegrate` 广播 END 或 FAIL。通信使用经过认证、有大小上限的本机 IPC，不开放 TCP 监听；peer 输入不能代替本机工具审批，也不能访问另一工作区。UUID/别名路由和协议已能支持第三个活动实例；持久化成果物交换、broker 重启日志与恢复、大规模多方协调属于后续强化。详见 [CLI Pals 规范](./docs/specs/2026-08-14-cli-pals-cowork.md)。
-
-### Electron 桌面端
+| `/goal <objective>` | 运行规划、执行、对抗审查流程 |
+| `/pals`、`/chat`、`/co-work` | 发现并协作其他本机 CLI 实例 |
+| `/audit` | 查看工具失败审计 |
+
+运行中可以提交 steering 或排队 follow-up；当前模型响应结束后，任务会在安全边界处接收新指令。
+
+#### CLI Pals 与跨项目协作
+
+同一 Windows 或 macOS 用户下的交互式 CLI 可以通过纯本地 IPC 协作（Windows named pipe 或 Unix socket，不回退到 TCP）。先给每个窗口一个容易识别的别名：
+
+```bash
+# 终端 A，位于项目 A
+flavor --pal-name A
+
+# 终端 B，位于项目 B
+flavor --pal-name B
+```
+
+常用命令：
+
+```text
+/pals                              # 查看别名和每进程 UUID
+/pals --verbose                    # 额外显示项目路径和时间
+/pals rename api                   # 重命名当前活动实例
+/chat B 更新 API 和测试             # 投递给 B，并安全启动其 Agent
+/co-work B 先升级 B，再兼容 A        # 先协商同一计划，再并行开工
+/co-work status [co-work-uuid]
+/co-work cancel <co-work-uuid> [reason]
+```
+
+`/chat` 支持双向任务通信。B 空闲时，带来源标识的消息会启动正常模型回合；B 正在运行时，消息会成为 steering；已有本地提交待运行时则成为 follow-up。远端文本会转换成安全的非斜杠 prompt，因此 `/exit` 一类文本不会被当成本地命令分派。B 可以用 `/chat A ...` 回复。
+
+`/co-work` 会先让双方进入规划，等待双方接受同一个哈希计划并声明 READY；较早的 READY 意图会被保留，只有 broker 恰好一次的 START 事件才会放行并行执行。每个 Agent 只在自己的项目内工作，只接收分配给自己的任务，并提交有界的完成证据。broker 指定的集成负责人会检查所有断言，再通过 `CoWorkIntegrate` 广播 END 或 FAIL。通信使用经过认证、有大小上限的本机 IPC，不开放 TCP 监听；peer 输入不能代替本机工具审批，也不能访问另一工作区。UUID/别名路由和协议已能支持第三个活动实例；持久化成果物交换、broker 重启日志与恢复、大规模多方协调属于后续强化。详见 [CLI Pals 规范](./docs/specs/2026-08-14-cli-pals-cowork.md)。
+
+### Electron 桌面端
 
 ```bash
 npm run desktop:dev      # 开发模式

package/dist/{app-MXWPZBEU.js → app-Z3YWFIBB.js}

@@ -15,7 +15,7 @@ import {
   packageVersion,
   redactErrorText,
   transcriptReducer
-} from "./chunk-OT5XIN6G.js";
+} from "./chunk-Y5MZDG7I.js";
 import "./chunk-XFCJXRJ2.js";
 import {
   Box_default,
@@ -1249,8 +1249,10 @@ function buildSlashCandidates(commands, plugins, skills) {
   for (const command of commands) {
     candidates.set(command.name, { name: command.name, kind: "command", description: command.description });
   }
-  for (const name of plugins) {
-    if (!candidates.has(name)) candidates.set(name, { name, kind: "plugin" });
+  for (const plugin of plugins) {
+    if (!candidates.has(plugin.name)) {
+      candidates.set(plugin.name, plugin.description === void 0 ? { name: plugin.name, kind: "plugin" } : { name: plugin.name, kind: "plugin", description: plugin.description });
+    }
   }
   for (const skill of skills) {
     if (!candidates.has(skill.name)) {

package/dist/astgraph/db.mjs

@@ -0,0 +1,237 @@
+// astgraph graph database — SQLite-backed node/edge graph (codegraph-inspired).
+// Uses node:sqlite with WAL mode so concurrent readers never block on a writer.
+
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS schema_versions (
+    version INTEGER PRIMARY KEY,
+    applied_at INTEGER NOT NULL,
+    description TEXT
+);
+
+CREATE TABLE IF NOT EXISTS files (
+    path TEXT PRIMARY KEY,
+    content_hash TEXT NOT NULL,
+    language TEXT NOT NULL,
+    size INTEGER NOT NULL,
+    modified_at INTEGER NOT NULL DEFAULT 0,
+    indexed_at INTEGER NOT NULL DEFAULT 0,
+    node_count INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS nodes (
+    id TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    name TEXT NOT NULL,
+    qualified_name TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    language TEXT NOT NULL,
+    start_line INTEGER NOT NULL,
+    end_line INTEGER NOT NULL,
+    signature TEXT,
+    docstring TEXT,
+    is_exported INTEGER NOT NULL DEFAULT 0,
+    is_async INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source TEXT NOT NULL,
+    target TEXT NOT NULL,
+    kind TEXT NOT NULL,
+    line INTEGER,
+    col INTEGER,
+    FOREIGN KEY (source) REFERENCES nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (target) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS unresolved_refs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_node_id TEXT,
+    reference_name TEXT NOT NULL,
+    reference_kind TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    col INTEGER NOT NULL,
+    file_path TEXT NOT NULL DEFAULT '',
+    module_specifier TEXT,
+    status TEXT NOT NULL DEFAULT 'pending',
+    FOREIGN KEY (from_node_id) REFERENCES nodes(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
+CREATE INDEX IF NOT EXISTS idx_nodes_lower_name ON nodes(lower(name));
+CREATE INDEX IF NOT EXISTS idx_nodes_file_path ON nodes(file_path);
+CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS idx_edges_source_kind ON edges(source, kind);
+CREATE INDEX IF NOT EXISTS idx_edges_target_kind ON edges(target, kind);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_identity
+  ON edges(source, target, kind, IFNULL(line, -1), IFNULL(col, -1));
+CREATE INDEX IF NOT EXISTS idx_unresolved_from ON unresolved_refs(from_node_id);
+CREATE INDEX IF NOT EXISTS idx_unresolved_name ON unresolved_refs(reference_name);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+    name,
+    qualified_name,
+    signature,
+    docstring,
+    content='nodes',
+    content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS nodes_ai AFTER INSERT ON nodes BEGIN
+    INSERT INTO nodes_fts(rowid, name, qualified_name, signature, docstring)
+    VALUES (NEW.rowid, NEW.name, NEW.qualified_name, NEW.signature, NEW.docstring);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_ad AFTER DELETE ON nodes BEGIN
+    INSERT INTO nodes_fts(nodes_fts, rowid, name, qualified_name, signature, docstring)
+    VALUES ('delete', OLD.rowid, OLD.name, OLD.qualified_name, OLD.signature, OLD.docstring);
+END;
+
+CREATE TRIGGER IF NOT EXISTS nodes_au AFTER UPDATE ON nodes BEGIN
+    INSERT INTO nodes_fts(nodes_fts, rowid, name, qualified_name, signature, docstring)
+    VALUES ('delete', OLD.rowid, OLD.name, OLD.qualified_name, OLD.signature, OLD.docstring);
+    INSERT INTO nodes_fts(rowid, name, qualified_name, signature, docstring)
+    VALUES (NEW.rowid, NEW.name, NEW.qualified_name, NEW.signature, NEW.docstring);
+END;
+
+CREATE TABLE IF NOT EXISTS project_metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+`;
+
+/** Open (creating when absent) the graph database at `path`. Returns a DatabaseSync. */
+export function openDb(path) {
+  if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA synchronous = NORMAL");
+  db.exec(SCHEMA);
+  const version = db.prepare("SELECT COUNT(*) AS count FROM schema_versions").get();
+  if (version.count === 0) {
+    db.prepare("INSERT INTO schema_versions(version, applied_at, description) VALUES (?, ?, ?)")
+      .run(1, Date.now(), "Initial astgraph schema");
+  }
+  return db;
+}
+
+/** Insert or replace the tracking record for one source file. */
+export function upsertFileRecord(db, record) {
+  db.prepare(`
+    INSERT INTO files(path, content_hash, language, size, modified_at, indexed_at, node_count)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(path) DO UPDATE SET
+      content_hash = excluded.content_hash,
+      language = excluded.language,
+      size = excluded.size,
+      modified_at = excluded.modified_at,
+      indexed_at = excluded.indexed_at,
+      node_count = excluded.node_count
+  `).run(
+    record.path, record.contentHash, record.language, record.size,
+    record.modifiedAt ?? Date.now(), record.indexedAt ?? Date.now(), record.nodeCount ?? 0,
+  );
+}
+
+/** Read the tracking record for one source file, or undefined when absent. */
+export function getFileRecord(db, path) {
+  const row = db.prepare("SELECT * FROM files WHERE path = ?").get(path);
+  if (row === undefined) return undefined;
+  return {
+    path: row.path, contentHash: row.content_hash, language: row.language,
+    size: row.size, modifiedAt: row.modified_at, indexedAt: row.indexed_at,
+    nodeCount: row.node_count,
+  };
+}
+
+/** Delete a file record; nodes cascade (and with them edges + refs + FTS rows). */
+export function deleteFileRecord(db, path) {
+  db.prepare("DELETE FROM nodes WHERE file_path = ?").run(path);
+  db.prepare("DELETE FROM files WHERE path = ?").run(path);
+}
+
+/**
+ * Replace every node belonging to a file. Runs inside one transaction; the FTS
+ * triggers keep nodes_fts in sync.
+ */
+export function replaceNodes(db, filePath, nodes) {
+  const insert = db.prepare(`
+    INSERT OR REPLACE INTO nodes(
+      id, kind, name, qualified_name, file_path, language,
+      start_line, end_line, signature, docstring, is_exported, is_async
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const clear = db.prepare("DELETE FROM nodes WHERE file_path = ?");
+  db.exec("BEGIN");
+  try {
+    clear.run(filePath);
+    for (const node of nodes) {
+      insert.run(
+        node.id, node.kind, node.name, node.qualifiedName, node.filePath, node.language,
+        node.startLine, node.endLine, node.signature ?? null, node.docstring ?? null,
+        node.isExported ? 1 : 0, node.isAsync ? 1 : 0,
+      );
+    }
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+/** Insert one edge; duplicate (source, target, kind, line, col) rows are ignored. */
+export function insertEdge(db, edge) {
+  db.prepare(`
+    INSERT OR IGNORE INTO edges(source, target, kind, line, col) VALUES (?, ?, ?, ?, ?)
+  `).run(edge.source, edge.target, edge.kind, edge.line ?? null, edge.col ?? null);
+}
+
+/** Delete every edge whose source OR target belongs to a file. */
+export function deleteEdgesForFile(db, filePath) {
+  db.prepare(`
+    DELETE FROM edges WHERE source IN (SELECT id FROM nodes WHERE file_path = ?)
+       OR target IN (SELECT id FROM nodes WHERE file_path = ?)
+  `).run(filePath, filePath);
+}
+
+/** Insert one unresolved cross-file reference (status 'pending'). */
+export function insertUnresolvedRef(db, ref) {
+  db.prepare(`
+    INSERT INTO unresolved_refs(from_node_id, reference_name, reference_kind, line, col, file_path, module_specifier, status)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 'pending')
+  `).run(ref.fromNodeId, ref.referenceName, ref.referenceKind, ref.line, ref.col, ref.filePath, ref.moduleSpecifier ?? null);
+}
+
+/** Delete every unresolved reference originating from a file. */
+export function deleteUnresolvedRefsForFile(db, filePath) {
+  db.prepare("DELETE FROM unresolved_refs WHERE file_path = ?").run(filePath);
+}
+
+/** Summary counters used by /ast status. */
+export function stats(db) {
+  const files = db.prepare("SELECT COUNT(*) AS count FROM files").get().count;
+  const nodes = db.prepare("SELECT COUNT(*) AS count FROM nodes").get().count;
+  const edges = db.prepare("SELECT COUNT(*) AS count FROM edges").get().count;
+  const unresolved = db.prepare("SELECT COUNT(*) AS count FROM unresolved_refs WHERE status = 'pending'").get().count;
+  return { files, nodes, edges, unresolved };
+}
+
+/** Store a provenance metadata value. */
+export function setMetadata(db, key, value) {
+  db.prepare(`
+    INSERT INTO project_metadata(key, value, updated_at) VALUES (?, ?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+  `).run(key, value, Date.now());
+}
+
+/** Read a provenance metadata value, or undefined when absent. */
+export function getMetadata(db, key) {
+  const row = db.prepare("SELECT value FROM project_metadata WHERE key = ?").get(key);
+  return row?.value;
+}

package/dist/astgraph/extract.mjs

@@ -0,0 +1,239 @@
+// astgraph TypeScript/JavaScript structural extractor.
+// Walks the tree-sitter syntax tree and produces:
+//   nodes — functions, classes, methods, interfaces, type aliases, variables
+//   edges — intra-file calls / extends / implements
+//   refs  — cross-file references (imports + unresolved calls/heritage) resolved later
+//
+// Lines are 1-based in all outputs so they match editor/Read tool coordinates.
+
+import { parseSource } from "./grammars.mjs";
+
+const DECLARATION_KINDS = new Map([
+  ["function_declaration", "function"],
+  ["class_declaration", "class"],
+  ["interface_declaration", "interface"],
+  ["type_alias_declaration", "type"],
+]);
+
+/** Extract the doc text from a `/** ... */` or `// ...` comment node. */
+function docstringFrom(commentNode) {
+  if (commentNode === null || commentNode.type !== "comment") return undefined;
+  const text = commentNode.text;
+  if (text.startsWith("/**") || text.startsWith("/*!")) {
+    return text
+      .replace(/^\/\*+[!*]?/, "")
+      .replace(/\*+\/$/, "")
+      .split("\n")
+      .map((line) => line.replace(/^\s*\*+\s?/, "").trim())
+      .filter((line) => line.length > 0)
+      .join("\n") || undefined;
+  }
+  if (text.startsWith("//")) return text.replace(/^\/\/+\s?/, "").trim() || undefined;
+  return undefined;
+}
+
+function firstLine(text, limit = 240) {
+  const line = text.split("\n")[0].trim();
+  return line.length > limit ? `${line.slice(0, limit)}…` : line;
+}
+
+function signatureOf(node) {
+  const text = node.text;
+  const brace = text.indexOf("{");
+  const head = brace >= 0 ? text.slice(0, brace) : text.split("\n")[0];
+  return firstLine(head.replace(/\s+/g, " "));
+}
+
+function nameOf(node) {
+  const nameNode = node.childForFieldName("name");
+  return nameNode === null ? undefined : nameNode.text;
+}
+
+function isAsync(node) {
+  return node.children.some((child) => child.type === "async");
+}
+
+export async function extract(source, filePath, language) {
+  const tree = await parseSource(source, language);
+
+  /** @type {Array<object>} */
+  const nodes = [];
+  /** @type {Array<object>} */
+  const edges = [];
+  /** @type {Array<object>} */
+  const refs = [];
+  /** Map local symbol name → node id (methods registered as name only for call matching). */
+  const localNames = new Map();
+  /** Map imported binding name → module specifier. */
+  const imports = new Map();
+  /** Map declaration AST node id → node record, for enclosing-scope lookup.
+   *  Keyed by numeric node.id because web-tree-sitter returns fresh node object
+   *  instances on every navigation (parent/childForFieldName), so object identity
+   *  cannot be used as a Map key. */
+  const scopeByNodeId = new Map();
+
+  const makeNode = (astNode, kind, name, qualifiedName, exported, extra = {}) => {
+    // The docstring lives on the top-level statement's preceding sibling (comments
+    // attach to program/export_statement, not to the inner declaration node).
+    const docSource = extra.docSource ?? astNode;
+    const record = {
+      id: `${filePath}#${qualifiedName}`,
+      kind,
+      name,
+      qualifiedName,
+      filePath,
+      language,
+      startLine: astNode.startPosition.row + 1,
+      endLine: astNode.endPosition.row + 1,
+      signature: signatureOf(astNode),
+      docstring: docstringFrom(docSource.previousSibling),
+      isExported: exported,
+      isAsync: extra.isAsync ?? false,
+      ...extra,
+    };
+    delete record.docSource;
+    nodes.push(record);
+    scopeByNodeId.set(astNode.id, record);
+    if (!localNames.has(name)) localNames.set(name, record.id);
+    return record;
+  };
+
+  const collectDeclaration = (statement, exported) => {
+    const inner = statement.type === "export_statement" ? statement.namedChildren.find((child) => DECLARATION_KINDS.has(child.type) || child.type === "lexical_declaration" || child.type === "abstract_class_declaration") : statement;
+    const target = inner ?? statement;
+    const kind = DECLARATION_KINDS.get(target.type);
+    if (kind !== undefined) {
+      const name = nameOf(target);
+      if (name !== undefined) {
+        // Comments attach to the top-level statement (export_statement / declaration),
+        // so the docstring is read from the statement's preceding sibling.
+        makeNode(target, kind, name, name, exported, {
+          ...(kind === "function" ? { isAsync: isAsync(target) } : {}),
+          docSource: statement,
+        });
+        if (target.type === "class_declaration" || target.type === "abstract_class_declaration") collectClassMembers(target, exported);
+        collectHeritage(target, exported);
+      }
+      return;
+    }
+    if (target.type === "lexical_declaration") {
+      for (const declarator of target.namedChildren.filter((child) => child.type === "variable_declarator")) {
+        const name = declarator.childForFieldName("name")?.text;
+        const value = declarator.childForFieldName("value");
+        if (name === undefined || value === null) continue;
+        const isFunction = value.type === "arrow_function" || value.type === "function_expression" || value.type === "function";
+        makeNode(declarator, isFunction ? "function" : "variable", name, name, exported, {
+          isAsync: isFunction && value.children.some((child) => child.type === "async"),
+          docSource: statement,
+        });
+      }
+    }
+  };
+
+  const collectClassMembers = (classNode, classExported) => {
+    const className = nameOf(classNode);
+    const body = classNode.childForFieldName("body");
+    if (body === null) return;
+    for (const member of body.namedChildren) {
+      if (member.type !== "method_definition") continue;
+      const name = member.childForFieldName("name")?.text;
+      if (name === undefined) continue;
+      const qualified = `${className}.${name}`;
+      makeNode(member, "method", name, qualified, classExported, { isAsync: isAsync(member) });
+    }
+  };
+
+  const collectHeritage = (classNode, _exported) => {
+    const heritage = classNode.namedChildren.find((child) => child.type === "class_heritage");
+    if (heritage === undefined) return;
+    const sourceName = nameOf(classNode);
+    if (sourceName === undefined) return;
+    const sourceId = `${filePath}#${sourceName}`;
+    for (const clause of heritage.namedChildren) {
+      const kind = clause.type === "extends_clause" ? "extends" : clause.type === "implements_clause" ? "implements" : undefined;
+      if (kind === undefined) continue;
+      for (const typeNode of clause.namedChildren.filter((child) => child.type === "type_identifier" || child.type === "identifier")) {
+        const typeName = typeNode.text;
+        if (localNames.has(typeName)) {
+          edges.push({ source: sourceId, target: localNames.get(typeName), kind, line: typeNode.startPosition.row + 1, col: typeNode.startPosition.column });
+        } else {
+          refs.push({
+            fromNodeId: sourceId, referenceName: typeName, referenceKind: kind,
+            line: typeNode.startPosition.row + 1, col: typeNode.startPosition.column,
+            filePath, moduleSpecifier: undefined,
+          });
+        }
+      }
+    }
+  };
+
+  // Pass 1 — top-level declarations and imports.
+  for (const statement of tree.rootNode.namedChildren) {
+    if (statement.type === "import_statement") {
+      const sourceNode = statement.childForFieldName("source");
+      const moduleSpecifier = sourceNode === null ? undefined : sourceNode.text.replace(/^["']|["']$/g, "");
+      for (const clause of statement.namedChildren.filter((child) => child.type === "import_clause")) {
+        for (const named of clause.namedChildren.filter((child) => child.type === "named_imports")) {
+          for (const specifier of named.namedChildren.filter((child) => child.type === "import_specifier")) {
+            const nameNode = specifier.childForFieldName("name");
+            if (nameNode === null) continue;
+            const importedName = nameNode.text;
+            imports.set(importedName, moduleSpecifier);
+            refs.push({
+              fromNodeId: null, referenceName: importedName, referenceKind: "import",
+              line: nameNode.startPosition.row + 1, col: nameNode.startPosition.column,
+              filePath, moduleSpecifier,
+            });
+          }
+        }
+        const defaultName = clause.namedChildren.find((child) => child.type === "identifier");
+        if (defaultName !== undefined) {
+          imports.set(defaultName.text, moduleSpecifier);
+          refs.push({
+            fromNodeId: null, referenceName: defaultName.text, referenceKind: "import",
+            line: defaultName.startPosition.row + 1, col: defaultName.startPosition.column,
+            filePath, moduleSpecifier,
+          });
+        }
+      }
+      continue;
+    }
+    collectDeclaration(statement, statement.type === "export_statement");
+  }
+
+  // Pass 2 — call expressions anywhere in the file.
+  const enclosingScope = (node) => {
+    let cursor = node.parent;
+    while (cursor !== null) {
+      const record = scopeByNodeId.get(cursor.id);
+      if (record !== undefined) return record;
+      cursor = cursor.parent;
+    }
+    return undefined;
+  };
+
+  const visitCalls = (node) => {
+    if (node.type === "call_expression") {
+      const callee = node.childForFieldName("function");
+      if (callee !== null && callee.type === "identifier") {
+        const name = callee.text;
+        const scope = enclosingScope(node);
+        if (scope !== undefined) {
+          if (localNames.has(name) && localNames.get(name) !== scope.id) {
+            edges.push({ source: scope.id, target: localNames.get(name), kind: "calls", line: callee.startPosition.row + 1, col: callee.startPosition.column });
+          } else if (!localNames.has(name)) {
+            refs.push({
+              fromNodeId: scope.id, referenceName: name, referenceKind: "call",
+              line: callee.startPosition.row + 1, col: callee.startPosition.column,
+              filePath, moduleSpecifier: imports.get(name),
+            });
+          }
+        }
+      }
+    }
+    for (const child of node.namedChildren) visitCalls(child);
+  };
+  visitCalls(tree.rootNode);
+
+  return { nodes, edges, refs, imports: Object.fromEntries(imports) };
+}