@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

package/dist/core/codegraph/queries/javascript.scm

@@ -0,0 +1,56 @@
+; JavaScript symbol + edge query - used by core/codegraph/parser.ts.
+;
+; Capture-name convention matches the TS query; the extractor is
+; language-agnostic at the capture-parsing layer.
+;
+; tree-sitter-javascript covers JS + JSX in a single grammar. .mjs and
+; .cjs route here too. We intentionally do NOT extract `var` declarations -
+; they leak across enclosing scopes and the resulting Symbol rows would
+; be misleading. `let` / `const` only.
+;
+; SymbolKind coverage:
+;   function   - function_declaration, generator_function_declaration
+;   class      - class_declaration
+;   method     - method_definition
+;   variable   - lexical_declaration single-identifier binding
+;   import     - import_specifier / default-import identifier
+;
+; (No interface / type kinds in JS - they live in TS-only.)
+;
+; EdgeKind coverage:
+;   calls      - call_expression bare ID + member-access function
+;   extends    - class extends parent identifier
+
+(function_declaration
+  name: (identifier) @symbol.function.name) @symbol.function.def
+
+(generator_function_declaration
+  name: (identifier) @symbol.function.name) @symbol.function.def
+
+(class_declaration
+  name: (identifier) @symbol.class.name) @symbol.class.def
+
+(method_definition
+  name: (property_identifier) @symbol.method.name) @symbol.method.def
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @symbol.variable.name)) @symbol.variable.def
+
+(import_specifier
+  name: (identifier) @symbol.import.name) @symbol.import.def
+
+(import_clause
+  (identifier) @symbol.import.name) @symbol.import.def
+
+(call_expression
+  function: (identifier) @edge.calls.target)
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @edge.calls.target))
+
+(class_declaration
+  name: (identifier) @edge.extends.from
+  (class_heritage
+    (identifier) @edge.extends.target))

package/dist/core/codegraph/queries/python.scm

@@ -0,0 +1,55 @@
+; Python symbol + edge query - used by core/codegraph/parser.ts.
+;
+; SymbolKind coverage:
+;   function   - function_definition (top-level OR nested - parser.ts
+;                computes scope by walking parents so nested defs
+;                appear as `Class.method` etc.)
+;   class      - class_definition
+;   variable   - top-level identifier assignment
+;   import     - import_from_statement / import_statement names
+;
+; EdgeKind coverage:
+;   calls      - call where the function is an identifier or attribute
+;   extends    - class superclass argument list (`class C(A, B):`)
+;
+; Python has no `implements` concept in the grammar (Protocols + ABCs
+; are runtime checks), so that edge kind stays empty here.
+
+(function_definition
+  name: (identifier) @symbol.function.name) @symbol.function.def
+
+(class_definition
+  name: (identifier) @symbol.class.name) @symbol.class.def
+
+; Top-level single-target assignments: `FOO = 1`. Restricted to the
+; simplest left side to avoid noise from destructuring.
+(expression_statement
+  (assignment
+    left: (identifier) @symbol.variable.name)) @symbol.variable.def
+
+; `from x import a, b as c` - names captured per identifier.
+(import_from_statement
+  name: (dotted_name (identifier) @symbol.import.name)) @symbol.import.def
+
+(import_from_statement
+  name: (aliased_import (dotted_name (identifier) @symbol.import.name))) @symbol.import.def
+
+; `import foo` (single name).
+(import_statement
+  name: (dotted_name (identifier) @symbol.import.name)) @symbol.import.def
+
+; Call expressions: bare identifier OR attribute (`foo.bar()`).
+(call
+  function: (identifier) @edge.calls.target)
+
+(call
+  function: (attribute
+    attribute: (identifier) @edge.calls.target))
+
+; Class superclass: `class C(A, B):` - emit one extends edge per
+; argument identifier. The scope walk in parser.ts resolves the
+; enclosing class as the source.
+(class_definition
+  name: (identifier) @edge.extends.from
+  superclasses: (argument_list
+    (identifier) @edge.extends.target))

package/dist/core/codegraph/queries/rust.scm

@@ -0,0 +1,63 @@
+; Rust symbol + edge query - used by core/codegraph/parser.ts.
+;
+; SymbolKind coverage:
+;   function   - function_item (`fn foo`). Methods (inside impl_item)
+;                also map to `function` for v1; the scope walk in
+;                parser.ts disambiguates via the dotted path.
+;   class      - struct_item. Rust has no `class`; struct is the
+;                closest analog so `code_callers` queries work
+;                consistently across languages.
+;   interface  - trait_item.
+;   type       - enum_item, type_item (type alias).
+;   variable   - const_item / static_item at the top level.
+;   import     - use_declaration terminal identifier.
+;
+; EdgeKind coverage:
+;   calls      - call_expression with identifier OR field-expression call.
+;   extends    - impl_item that implements a trait for a type. Rust
+;                does not inherit; we reuse `extends` here to model
+;                trait-implementation as the closest cross-language analog.
+
+(function_item
+  name: (identifier) @symbol.function.name) @symbol.function.def
+
+(struct_item
+  name: (type_identifier) @symbol.class.name) @symbol.class.def
+
+(trait_item
+  name: (type_identifier) @symbol.interface.name) @symbol.interface.def
+
+(enum_item
+  name: (type_identifier) @symbol.type.name) @symbol.type.def
+
+(type_item
+  name: (type_identifier) @symbol.type.name) @symbol.type.def
+
+; const FOO: T = 1; / static FOO: T = 1;
+(const_item
+  name: (identifier) @symbol.variable.name) @symbol.variable.def
+
+(static_item
+  name: (identifier) @symbol.variable.name) @symbol.variable.def
+
+; Imports: tree-sitter-rust models `use a::b::c` as nested
+; scoped_use_list / scoped_identifier. We capture the simplest forms.
+(use_declaration
+  argument: (identifier) @symbol.import.name) @symbol.import.def
+
+(use_declaration
+  argument: (scoped_identifier
+    name: (identifier) @symbol.import.name)) @symbol.import.def
+
+; Calls: bare and method.
+(call_expression
+  function: (identifier) @edge.calls.target)
+
+(call_expression
+  function: (field_expression
+    field: (field_identifier) @edge.calls.target))
+
+; `impl Trait for Type { ... }` - emit a `extends` edge from Type -> Trait.
+(impl_item
+  trait: (type_identifier) @edge.extends.target
+  type: (type_identifier) @edge.extends.from)

package/dist/core/codegraph/queries/typescript.scm

@@ -0,0 +1,91 @@
+; TypeScript symbol + edge query - used by core/codegraph/parser.ts.
+;
+; Capture naming convention drives the extractor:
+;   @symbol.<kind>.def    binds to the AST node spanning the whole declaration
+;                          (used for line/column anchor).
+;   @symbol.<kind>.name   binds to the identifier node (used for `name`).
+;   @edge.<kind>.from     enclosing definition that originates the edge.
+;   @edge.<kind>.target   identifier whose name resolves to the edge target.
+;
+; tree-sitter-typescript ships separate grammars for typescript and tsx; both
+; share the bulk of node names below. The same query runs against both
+; languages - the extractor wires both grammars to this file.
+;
+; SymbolKind coverage (per types.ts):
+;   function   - function_declaration, generator_function_declaration
+;   class      - class_declaration, abstract_class_declaration
+;   method     - method_definition, abstract_method_signature
+;   interface  - interface_declaration
+;   type       - type_alias_declaration, enum_declaration
+;   variable   - lexical_declaration single-identifier binding (let/const)
+;   import     - import_specifier (named imports) and default-import identifier
+;
+; EdgeKind coverage:
+;   calls      - call_expression where function is identifier or member.
+;   extends    - class extends_clause target
+;   implements - class implements_clause target (TS-only)
+
+; --- functions ---
+(function_declaration
+  name: (identifier) @symbol.function.name) @symbol.function.def
+
+(generator_function_declaration
+  name: (identifier) @symbol.function.name) @symbol.function.def
+
+; --- classes ---
+(class_declaration
+  name: (type_identifier) @symbol.class.name) @symbol.class.def
+
+(abstract_class_declaration
+  name: (type_identifier) @symbol.class.name) @symbol.class.def
+
+; --- methods (inside class bodies) ---
+(method_definition
+  name: (property_identifier) @symbol.method.name) @symbol.method.def
+
+(abstract_method_signature
+  name: (property_identifier) @symbol.method.name) @symbol.method.def
+
+; --- interfaces ---
+(interface_declaration
+  name: (type_identifier) @symbol.interface.name) @symbol.interface.def
+
+; --- types / enums ---
+(type_alias_declaration
+  name: (type_identifier) @symbol.type.name) @symbol.type.def
+
+(enum_declaration
+  name: (identifier) @symbol.type.name) @symbol.type.def
+
+; --- top-level variables (let / const single binding) ---
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @symbol.variable.name)) @symbol.variable.def
+
+; --- imports ---
+(import_specifier
+  name: (identifier) @symbol.import.name) @symbol.import.def
+
+(import_clause
+  (identifier) @symbol.import.name) @symbol.import.def
+
+; --- calls (edges) ---
+(call_expression
+  function: (identifier) @edge.calls.target)
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @edge.calls.target))
+
+; --- class extends / implements (edges) ---
+(class_declaration
+  name: (type_identifier) @edge.extends.from
+  (class_heritage
+    (extends_clause
+      value: [(identifier) (type_identifier)] @edge.extends.target)))
+
+(class_declaration
+  name: (type_identifier) @edge.implements.from
+  (class_heritage
+    (implements_clause
+      [(type_identifier) (generic_type) (predefined_type)] @edge.implements.target)))

package/dist/core/codegraph/reindex.js

@@ -0,0 +1,218 @@
+/**
+ * Pugi local symbol index - reindex orchestrator (PR L1).
+ *
+ * Wires the workspace walk against `parser.parseFile` and writes the
+ * results into `db.ts`. The orchestrator is the only consumer of
+ * `PendingEdge` - it resolves names to SQLite row ids per file and
+ * drops orphans before calling `insertEdges`. The contract types in
+ * `types.ts` stay frozen.
+ *
+ * Workspace walk is intentionally minimal:
+ *  - Use `tinyglobby` to enumerate `**\/*.{ext}` for the v1 extension
+ *    set (see `parser.PARSEABLE_EXTENSIONS`).
+ *  - Always skip `node_modules`, `.git`, `dist`, `build`, `.next`,
+ *    `.turbo`, `.cache`, `coverage`, and `.pugi` itself - these are
+ *    the same exclusions the existing `core/repo-map/scanner.ts`
+ *    uses, kept inline here so the codegraph module can ship without
+ *    pulling the broader scanner dependency tree.
+ *  - Symlinks are not followed - same default as the rest of Pugi.
+ *
+ * The orchestrator returns a structured summary so the CLI layer
+ * can render a single-line operator-facing recap without parsing
+ * stdout. Every counter the operator might want is exposed.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { glob } from 'tinyglobby';
+import { deleteFile, insertEdges, insertSymbols, upsertFile, } from './db.js';
+import { PARSEABLE_EXTENSIONS, parseFile } from './parser.js';
+/** Default directories pruned from the walk. */
+const PRUNE_DIRS = Object.freeze([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '.turbo',
+    '.cache',
+    'coverage',
+    '.pugi',
+]);
+/**
+ * Walk the workspace, parse every supported file, and write symbols +
+ * edges into the open `IndexDB`. The DB is assumed to be open already -
+ * the caller (the CLI command) owns its lifecycle.
+ */
+export async function reindexWorkspace(db, opts = {}) {
+    const start = Date.now();
+    const root = db.workspaceRoot;
+    const patterns = PARSEABLE_EXTENSIONS.map((ext) => `**/*${ext}`);
+    const matches = await glob(patterns, {
+        cwd: root,
+        ignore: PRUNE_DIRS.map((d) => `**/${d}/**`),
+        onlyFiles: true,
+        dot: false,
+        followSymbolicLinks: false,
+    });
+    /**
+     * Per-file index of name -> rowId after symbols are inserted. We
+     * use a Map per file so edges within a file can resolve their
+     * source side via `fromName`. Cross-file targets resolve via the
+     * cross-file global map.
+     */
+    const filesOut = [];
+    const work = [];
+    /** Cross-file map: target name -> first matching SQLite id. */
+    const globalNameMap = new Map();
+    let symbolsInserted = 0;
+    for (const m of matches) {
+        const abs = resolve(root, m);
+        const relPath = m.split(sep).join('/');
+        let bytes;
+        try {
+            bytes = readFileSync(abs, 'utf8');
+        }
+        catch {
+            // Disappeared mid-walk or unreadable - skip.
+            continue;
+        }
+        const result = await parseFile(abs, {
+            relPath,
+            quiet: opts.quiet === true,
+            sourceOverride: bytes,
+        });
+        // Delete prior rows for this file before re-inserting. Cheap on
+        // first run because the file row does not exist; cheap on
+        // re-runs because of `idx_symbols_file`.
+        deleteFile(db, relPath);
+        if (result.symbols.length === 0) {
+            // Still record the file fingerprint when applicable so the
+            // watcher's sha256 short-circuit works on subsequent runs.
+            if (result.language !== null) {
+                upsertFile(db, {
+                    path: relPath,
+                    sha256: sha256(bytes),
+                    lastIndexedAt: new Date().toISOString(),
+                    symbolCount: 0,
+                });
+            }
+            filesOut.push({
+                file: relPath,
+                language: result.language,
+                symbolCount: 0,
+                edgeCount: 0,
+                parseMs: result.parseMs,
+            });
+            continue;
+        }
+        const ids = insertSymbols(db, result.symbols);
+        symbolsInserted += ids.length;
+        const nameMap = new Map();
+        for (let i = 0; i < result.symbols.length; i += 1) {
+            const sym = result.symbols[i];
+            const id = ids[i];
+            if (!sym || id === undefined)
+                continue;
+            // Per-file canonical key includes scope so two `speak()`
+            // methods on different classes do not collide.
+            nameMap.set(scopedKey(sym.name, sym.scope), id);
+            nameMap.set(sym.name, id);
+            // Cross-file: keep the first definition we see. A later file
+            // with the same name does not overwrite - we want stability,
+            // not last-write-wins.
+            if (!globalNameMap.has(sym.name)) {
+                globalNameMap.set(sym.name, id);
+            }
+        }
+        upsertFile(db, {
+            path: relPath,
+            sha256: sha256(bytes),
+            lastIndexedAt: new Date().toISOString(),
+            symbolCount: ids.length,
+        });
+        work.push({
+            file: relPath,
+            pendingEdges: result.pendingEdges,
+            nameMap,
+            parseMs: result.parseMs,
+        });
+        filesOut.push({
+            file: relPath,
+            language: result.language,
+            symbolCount: ids.length,
+            // edgeCount filled in pass 2.
+            edgeCount: 0,
+            parseMs: result.parseMs,
+        });
+    }
+    // Second pass: resolve edges. Caller side prefers per-file scope
+    // match, falls back to bare name match. Target side prefers
+    // per-file match first (intra-file refs), then global (cross-file
+    // best effort).
+    let edgesInserted = 0;
+    let edgesOrphaned = 0;
+    for (let i = 0; i < work.length; i += 1) {
+        const item = work[i];
+        if (!item)
+            continue;
+        const resolved = [];
+        for (const pe of item.pendingEdges) {
+            const fromId = item.nameMap.get(scopedKey(pe.fromName, pe.fromScope)) ??
+                item.nameMap.get(pe.fromName);
+            if (fromId === undefined) {
+                // Caller side did not resolve - this means the .scm query
+                // captured an edge whose source declaration is not in the
+                // symbol table. Should not happen for well-formed files;
+                // we drop quietly.
+                edgesOrphaned += 1;
+                continue;
+            }
+            const toId = item.nameMap.get(pe.toName) ?? globalNameMap.get(pe.toName);
+            if (toId === undefined) {
+                // Target name was not found in this file's symbol table OR
+                // the cross-file map. Drop silently - the agent's
+                // code_callers query simply will not see this edge.
+                edgesOrphaned += 1;
+                continue;
+            }
+            // Self-recursion is a real edge: `fn foo() { foo(); }`. Keep
+            // it - PR L4 PageRank treats self-loops correctly, and the
+            // `code_callers` MCP tool already filters by edge kind so the
+            // self-loop does not pollute the caller list.
+            resolved.push({
+                fromSymbolId: fromId,
+                toSymbolId: toId,
+                kind: pe.kind,
+            });
+        }
+        if (resolved.length > 0) {
+            insertEdges(db, resolved);
+            edgesInserted += resolved.length;
+            const outIdx = filesOut.findIndex((f) => f.file === item.file);
+            if (outIdx >= 0) {
+                const existing = filesOut[outIdx];
+                if (existing) {
+                    filesOut[outIdx] = { ...existing, edgeCount: resolved.length };
+                }
+            }
+        }
+    }
+    return {
+        filesScanned: matches.length,
+        filesIndexed: work.length,
+        symbolsInserted,
+        edgesInserted,
+        edgesOrphaned,
+        totalMs: Date.now() - start,
+        files: filesOut,
+    };
+}
+/** Compose a stable per-file scope+name lookup key. */
+function scopedKey(name, scope) {
+    return scope.length > 0 ? `${scope}.${name}` : name;
+}
+function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+//# sourceMappingURL=reindex.js.map

package/dist/core/codegraph/resolve-edges.js

@@ -0,0 +1,107 @@
+/**
+ * Pugi local symbol index - edge resolution helper (PR L2).
+ *
+ * Shared between `reindex.ts` (workspace walker) and `watcher.ts` (chokidar
+ * incremental updater). Resolves the name-keyed `PendingEdge[]` produced by
+ * the parser into row-id-keyed `Edge[]` that `db.ts:insertEdges` accepts.
+ *
+ * Why factored out:
+ *
+ *  - PR L2 originally inlined this in two places; the duplicated bodies
+ *    drifted on the third change. One reusable resolver keeps the
+ *    invariants (per-file scoped key precedence, global fall-through,
+ *    orphan handling) in one location.
+ *  - The watcher's "global name map" is the live DB rather than an
+ *    in-memory map built across the full walk - we expose a lookup
+ *    callback so each caller plugs in its own source of truth.
+ *
+ * Resolution policy mirrors `reindex.ts:resolveEdges` exactly:
+ *
+ *   1. Caller side prefers per-file `scope.name` exact, falls back to
+ *      bare `name`. Unresolved caller -> orphan, edge dropped.
+ *   2. Target side prefers the same per-file map (intra-file ref), then
+ *      asks the cross-file lookup (db query or in-memory map).
+ *   3. Self-recursive edges (`fn foo() { foo() }`) are kept - PR L4
+ *      PageRank treats self-loops correctly and the `code_callers` MCP
+ *      tool filters by edge kind so it does not pollute caller lists.
+ */
+/**
+ * Compose `scope.name` for map lookup. Mirrors `reindex.ts:scopedKey`.
+ * Empty scope collapses to the bare name so the empty-scope branch
+ * doesn't need a separate key form.
+ */
+export function scopedKey(name, scope) {
+    return scope.length > 0 ? `${scope}.${name}` : name;
+}
+/**
+ * Resolve a parser file's `PendingEdge[]` against the per-file name
+ * map plus a cross-file lookup. The two callers wire `crossFile`
+ * differently:
+ *
+ *  - reindex walker: in-memory `Map<name, id>` accumulated across the
+ *    full pass (`globalNameMap`).
+ *  - chokidar watcher: SQLite `SELECT id FROM symbols WHERE name = ?`
+ *    closure over the open `IndexDB`.
+ *
+ * The function is pure given those inputs - no IO, no DB writes. The
+ * caller decides what to do with the resolved batch.
+ */
+export function resolvePendingEdges(pendingEdges, perFile, crossFile) {
+    const resolved = [];
+    let orphaned = 0;
+    for (const pe of pendingEdges) {
+        const fromId = perFile.get(scopedKey(pe.fromName, pe.fromScope)) ??
+            perFile.get(pe.fromName);
+        if (fromId === undefined) {
+            // Caller side did not resolve. The .scm query captured an edge
+            // whose source declaration is not in the file's symbol table -
+            // should not happen for well-formed files; drop quietly.
+            orphaned += 1;
+            continue;
+        }
+        let toId = perFile.get(pe.toName);
+        if (toId === undefined) {
+            const fromCross = crossFile(pe.toName);
+            if (fromCross !== null)
+                toId = fromCross;
+        }
+        if (toId === undefined) {
+            // Target was not in this file's symbol table OR the cross-file
+            // source. Drop silently - the `code_callers` MCP tool will just
+            // not see this edge.
+            orphaned += 1;
+            continue;
+        }
+        resolved.push({
+            fromSymbolId: fromId,
+            toSymbolId: toId,
+            kind: pe.kind,
+        });
+    }
+    return { resolved, orphaned };
+}
+/**
+ * Build the per-file `nameMap` from a freshly-inserted symbol batch
+ * and the row ids returned by `insertSymbols`. Mirrors the inline
+ * loop в `reindex.ts` so both call sites stay consistent.
+ *
+ * The two map entries per symbol intentional: the scoped key
+ * (`Class.method`) is the canonical one, the bare-name entry is the
+ * fallback for the very common case where the .scm query captured a
+ * top-level caller. Last-write-wins on the bare-name key matches the
+ * walker's first-write behavior because both forms point at the same
+ * row id for the same file.
+ */
+export function buildPerFileNameMap(symbols, ids) {
+    const map = new Map();
+    for (let i = 0; i < symbols.length; i += 1) {
+        const sym = symbols[i];
+        const id = ids[i];
+        if (!sym || id === undefined)
+            continue;
+        map.set(scopedKey(sym.name, sym.scope), id);
+        map.set(sym.name, id);
+    }
+    return map;
+}
+//# sourceMappingURL=resolve-edges.js.map

package/dist/core/codegraph/types.js

@@ -0,0 +1,34 @@
+/**
+ * Pugi local symbol index - type definitions.
+ *
+ * Companion to `db.ts` (SQLite + FTS5 wrapper) and `parser.ts` (tree-sitter
+ * extractor, stub today, real impl in follow-up PR L1). These types are the
+ * cross-module contract: the parser produces `Symbol[]` + `Edge[]`, the db
+ * layer inserts them, the MCP tools consume the query result types.
+ *
+ * Distinct from the third-party CodeGraph install scaffold that already
+ * lives in the same directory (`detect-repo.ts`, `offer-hook.ts`,
+ * `install.ts`, `decision-store.ts`). Those manage adoption of the upstream
+ * colbymchenry/codegraph MCP server. This file is the Pugi-native index.
+ * See the design memo at
+ * `docs/research/2026-06-05-pugi-index-codegraph-design.md` for the full
+ * architecture rationale.
+ *
+ * Naming convention: every type defined here is `Symbol` / `Edge` /
+ * `IndexedFile` / `*Result` / `*Options`. The interface is intentionally
+ * narrow - five v1 languages, four MCP tools, one SQLite database file.
+ */
+/**
+ * Schema version tracked in the `_migrations` table. v1 ships with this
+ * PR (files + symbols + edges + FTS5 virtual + triggers). Bumping this
+ * MUST land a matching `applyMigration(N, db)` branch in `db.ts`.
+ */
+export const INDEX_SCHEMA_VERSION = 1;
+export const INDEXED_LANGUAGES = Object.freeze([
+    'typescript',
+    'javascript',
+    'python',
+    'go',
+    'rust',
+]);
+//# sourceMappingURL=types.js.map