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

package/dist/runtime/commands/index-cmd.js

@@ -0,0 +1,459 @@
+/**
+ * `pugi index` - local symbol index CLI surface.
+ *
+ * Operator entry point for the Pugi-native symbol index living at
+ * `.pugi/codegraph.db`. Four subcommands today, all wired against the
+ * scaffold DB layer in `core/codegraph/db.ts`:
+ *
+ *  - `pugi index`                       - full (re)index of the workspace.
+ *                                          Today: opens the DB, runs the
+ *                                          v1 migration, and reports the
+ *                                          stub parser state. PR L1
+ *                                          replaces this with a real
+ *                                          tree-sitter walk.
+ *  - `pugi index --watch`               - start the file watcher. Not
+ *                                          implemented in this PR; exits
+ *                                          with rc=3 + a pointer at
+ *                                          PR L2 which ships chokidar
+ *                                          + 2s debounce.
+ *  - `pugi index search <query>`        - FTS5 query against
+ *                                          `symbols_fts`. Works on top
+ *                                          of an empty index too -
+ *                                          returns zero matches.
+ *  - `pugi index definition <symbol>`   - exact-name lookup. Same shape
+ *                                          as `--search`.
+ *  - `pugi index callers <symbol>`      - reverse-edge query. Empty
+ *                                          today because the stub
+ *                                          parser emits no edges.
+ *
+ * The command is intentionally narrow - every information surface
+ * (count, freshness, language coverage) routes through the existing
+ * `/codegraph-status` slash that already ships in `runtime/commands/
+ * codegraph-status.ts`. This file owns the indexing verbs; status
+ * lives over there.
+ *
+ * Exit codes:
+ *  0 - success / "nothing to do" idempotent path
+ *  1 - runtime failure (db error, IO error)
+ *  2 - invalid CLI args (unknown subcommand, missing required positional)
+ *  3 - not implemented yet (parser stub, watcher) - pointer in stderr
+ */
+import { resolve } from 'node:path';
+import { closeIndex, countSymbols, findCallers, findDefinition, openIndex, resolveIndexPath, searchSymbols, } from '../../core/codegraph/db.js';
+import { reindexWorkspace } from '../../core/codegraph/reindex.js';
+import { startWatcher } from '../../core/codegraph/watcher.js';
+import { INDEXED_LANGUAGES } from '../../core/codegraph/types.js';
+/**
+ * Single entry-point. Returns the process exit code; the caller in
+ * `runtime/cli.ts` propagates it via `process.exitCode` (mirrors the
+ * `dispatchFlatten` pattern).
+ */
+export async function runIndexCommand(args, ctx) {
+    const sub = parseArgs(args);
+    switch (sub.kind) {
+        case 'help':
+            return printHelp(ctx);
+        case 'unknown':
+            return printUnknown(ctx, sub.raw);
+        case 'reindex':
+            return runReindex(ctx, sub.watch);
+        case 'search':
+            return runSearch(ctx, sub.query);
+        case 'definition':
+            return runDefinition(ctx, sub.symbol);
+        case 'callers':
+            return runCallers(ctx, sub.symbol);
+    }
+}
+/**
+ * Parse the argv tail (everything after `pugi index`). Pure - exported
+ * for the spec to pin canonical shapes.
+ */
+export function parseArgs(args) {
+    if (args.length === 0) {
+        return { kind: 'reindex', watch: false };
+    }
+    const [head, ...rest] = args;
+    if (!head)
+        return { kind: 'reindex', watch: false };
+    if (head === '--help' || head === '-h' || head === 'help') {
+        return { kind: 'help' };
+    }
+    if (head === '--watch' || head === '-w') {
+        return { kind: 'reindex', watch: true };
+    }
+    if (head === 'search') {
+        const query = rest.join(' ').trim();
+        if (query.length === 0)
+            return { kind: 'unknown', raw: 'search (missing query)' };
+        return { kind: 'search', query };
+    }
+    if (head === 'definition') {
+        const symbol = rest.join(' ').trim();
+        if (symbol.length === 0)
+            return { kind: 'unknown', raw: 'definition (missing symbol)' };
+        return { kind: 'definition', symbol };
+    }
+    if (head === 'callers') {
+        const symbol = rest.join(' ').trim();
+        if (symbol.length === 0)
+            return { kind: 'unknown', raw: 'callers (missing symbol)' };
+        return { kind: 'callers', symbol };
+    }
+    return { kind: 'unknown', raw: head };
+}
+function printHelp(ctx) {
+    ctx.writeOutput({ command: 'index', sub: 'help', subcommands: ['search', 'definition', 'callers'] }, [
+        'pugi index - local symbol index (CodeGraph-style).',
+        '',
+        'Usage:',
+        '  pugi index                        Re-index the workspace.',
+        '  pugi index --watch                Live auto-sync via chokidar (2s debounce).',
+        '  pugi index search <query>         FTS5 search across symbol names.',
+        '  pugi index definition <symbol>    Find the definition of <symbol>.',
+        '  pugi index callers <symbol>       List call sites referencing <symbol>.',
+        '',
+        `Languages (v1): ${INDEXED_LANGUAGES.join(', ')}.`,
+        'Storage: .pugi/codegraph.db (gitignored, regenerable).',
+        'Design memo: docs/research/2026-06-05-pugi-index-codegraph-design.md',
+    ].join('\n'));
+    return 0;
+}
+function printUnknown(ctx, raw) {
+    ctx.writeOutput({ command: 'index', error: 'unknown-subcommand', got: raw }, `pugi index: unknown subcommand "${raw}". Allowed: search, definition, callers, --watch, --help.`);
+    return 2;
+}
+async function runReindex(ctx, watch) {
+    if (watch) {
+        return runWatch(ctx);
+    }
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const summary = await reindexWorkspace(db, { quiet: true });
+        const symCount = countSymbols(db);
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'reindex',
+            watch: false,
+            status: 'ok',
+            dbPath: db.dbPath,
+            schemaVersion: db.version,
+            filesScanned: summary.filesScanned,
+            filesIndexed: summary.filesIndexed,
+            symbolsInserted: summary.symbolsInserted,
+            edgesInserted: summary.edgesInserted,
+            edgesOrphaned: summary.edgesOrphaned,
+            totalSymbols: symCount,
+            elapsedMs: summary.totalMs,
+        }, [
+            `Index DB ready at ${db.dbPath} (schema v${db.version}).`,
+            `Scanned ${summary.filesScanned} files, indexed ${summary.filesIndexed}.`,
+            `Symbols inserted: ${summary.symbolsInserted}. Edges inserted: ${summary.edgesInserted} (${summary.edgesOrphaned} orphans dropped).`,
+            `Elapsed: ${summary.totalMs} ms. Total symbols on disk: ${symCount}.`,
+        ].join('\n'));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'reindex', error: 'db_error', message }, `pugi index failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+/**
+ * `pugi index --watch` runtime: do one full re-index up-front so the
+ * index reflects the workspace as it stood at startup, then hand off
+ * к the chokidar watcher and block until SIGINT / SIGTERM. The DB
+ * handle stays open для the watcher's lifetime - the watcher writes
+ * incrementally, the operator quits with Ctrl+C, we close.
+ */
+async function runWatch(ctx) {
+    const writeStderr = ctx.writeStderr ?? ((text) => void process.stderr.write(text));
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        // Baseline reindex so the watcher starts on a known-current index.
+        // Reindex is idempotent + cheap on subsequent runs (no-op for
+        // unchanged files via the sha256 fingerprint).
+        const summary = await reindexWorkspace(db, { quiet: true });
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'reindex',
+            watch: true,
+            status: 'watching',
+            dbPath: db.dbPath,
+            schemaVersion: db.version,
+            filesScanned: summary.filesScanned,
+            filesIndexed: summary.filesIndexed,
+            symbolsInserted: summary.symbolsInserted,
+            edgesInserted: summary.edgesInserted,
+            baselineMs: summary.totalMs,
+        }, [
+            `Baseline index ready (${summary.filesIndexed} files, ${summary.symbolsInserted} symbols, ${summary.edgesInserted} edges).`,
+            `watching ${ctx.workspaceRoot}...`,
+            '  Press Ctrl+C to stop.',
+        ].join('\n'));
+        const handle = startWatcher({
+            db,
+            workspaceRoot: ctx.workspaceRoot,
+            writeStderr,
+        });
+        // Set up SIGINT / SIGTERM traps. Resolve the promise that gates
+        // `runWatch` once the handle has fully closed.
+        return await new Promise((resolvePromise) => {
+            let shuttingDown = false;
+            const shutdown = async (signal) => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                try {
+                    await handle.close();
+                    writeStderr(`pugi index --watch: stopped (${signal}).\n`);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    writeStderr(`pugi index --watch: shutdown error: ${message}\n`);
+                }
+                finally {
+                    if (db)
+                        closeIndex(db);
+                    db = null;
+                    process.off('SIGINT', sigintListener);
+                    process.off('SIGTERM', sigtermListener);
+                    resolvePromise(0);
+                }
+            };
+            const sigintListener = () => void shutdown('SIGINT');
+            const sigtermListener = () => void shutdown('SIGTERM');
+            process.on('SIGINT', sigintListener);
+            process.on('SIGTERM', sigtermListener);
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'reindex', watch: true, error: 'watcher_failed', message }, `pugi index --watch failed: ${message}`);
+        if (db)
+            closeIndex(db);
+        return 1;
+    }
+}
+function runSearch(ctx, query) {
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        // Wrap a bare identifier in a prefix-match phrase so operators
+        // can type `pugi index search foo` and find `fooBar`. FTS5 will
+        // happily accept a more specific raw expression too (e.g.
+        // `foo*` or `"exact phrase"`) - we only inject the convenience
+        // wrapping when the input looks like a plain identifier.
+        const wrapped = wrapSearchQuery(query);
+        const results = searchSymbols(db, wrapped, { limit: 50 });
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'search',
+            query,
+            matches: results.length,
+            results: results.map(serializeSearchResult),
+        }, renderSearchText(query, results, db.dbPath));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'search', error: 'query_failed', message }, `pugi index search failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function runDefinition(ctx, symbol) {
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const result = findDefinition(db, symbol);
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'definition',
+            symbol,
+            result: serializeDefinitionResult(result),
+        }, renderDefinitionText(symbol, result));
+        return result.kind === 'found' ? 0 : 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'definition', error: 'query_failed', message }, `pugi index definition failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function runCallers(ctx, symbol) {
+    let db = null;
+    try {
+        db = openIndex(ctx.workspaceRoot);
+        const def = findDefinition(db, symbol);
+        if (def.kind !== 'found' || def.definition.id === undefined) {
+            ctx.writeOutput({
+                command: 'index',
+                sub: 'callers',
+                symbol,
+                matches: 0,
+                note: 'definition_not_found',
+            }, `pugi index callers: no definition known for "${symbol}". Run \`pugi index\` first or check the spelling.`);
+            return 0;
+        }
+        const callers = findCallers(db, def.definition.id);
+        ctx.writeOutput({
+            command: 'index',
+            sub: 'callers',
+            symbol,
+            definitionId: def.definition.id,
+            matches: callers.length,
+            callers: callers.map(serializeCallerResult),
+        }, renderCallersText(symbol, callers));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.writeOutput({ command: 'index', sub: 'callers', error: 'query_failed', message }, `pugi index callers failed: ${message}`);
+        return 1;
+    }
+    finally {
+        if (db)
+            closeIndex(db);
+    }
+}
+function serializeSearchResult(r) {
+    return {
+        name: r.symbol.name,
+        kind: r.symbol.kind,
+        file: r.symbol.file,
+        line: r.symbol.line,
+        col: r.symbol.column,
+        scope: r.symbol.scope,
+        signature: r.symbol.signature ?? null,
+        rank: r.rank,
+    };
+}
+function serializeDefinitionResult(r) {
+    if (r.kind === 'not_found')
+        return { found: false, name: r.name };
+    return {
+        found: true,
+        definition: serializeSymbol(r.definition),
+        disambiguations: r.disambiguations.map(serializeSymbol),
+    };
+}
+function serializeCallerResult(c) {
+    return {
+        name: c.caller.name,
+        kind: c.caller.kind,
+        file: c.caller.file,
+        line: c.caller.line,
+        col: c.caller.column,
+        scope: c.caller.scope,
+        edgeKind: c.edge.kind,
+    };
+}
+function serializeSymbol(s) {
+    return {
+        id: s.id,
+        name: s.name,
+        kind: s.kind,
+        file: s.file,
+        line: s.line,
+        col: s.column,
+        scope: s.scope,
+        signature: s.signature ?? null,
+    };
+}
+function renderSearchText(query, results, dbPath) {
+    if (results.length === 0) {
+        return [
+            `pugi index search "${query}" - 0 matches.`,
+            `Index DB: ${dbPath}`,
+            'Hint: the parser stub does not extract symbols yet. PR L1 wires real tree-sitter extraction.',
+        ].join('\n');
+    }
+    const lines = [
+        `pugi index search "${query}" - ${results.length} matches:`,
+        '',
+    ];
+    for (const r of results) {
+        lines.push(` ${r.symbol.name}  [${r.symbol.kind}]  ${r.symbol.file}:${r.symbol.line}  rank=${r.rank.toFixed(2)}`);
+    }
+    return lines.join('\n');
+}
+function renderDefinitionText(symbol, result) {
+    if (result.kind === 'not_found') {
+        return [
+            `pugi index definition "${symbol}" - not found.`,
+            'Hint: PR L1 wires the parser; until then the index is empty unless seeded by tests.',
+        ].join('\n');
+    }
+    const d = result.definition;
+    const head = ` ${d.name}  [${d.kind}]  ${d.file}:${d.line}`;
+    if (result.disambiguations.length === 0)
+        return head;
+    return [
+        head,
+        `Also found in ${result.disambiguations.length} other locations:`,
+        ...result.disambiguations.map((s) => `  - ${s.file}:${s.line}  [${s.kind}]`),
+    ].join('\n');
+}
+function renderCallersText(symbol, callers) {
+    if (callers.length === 0) {
+        return `pugi index callers "${symbol}" - 0 call sites.`;
+    }
+    const lines = [
+        `pugi index callers "${symbol}" - ${callers.length} call sites:`,
+        '',
+    ];
+    for (const c of callers) {
+        lines.push(` ${c.caller.name}  ${c.caller.file}:${c.caller.line}  edge=${c.edge.kind}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve the absolute workspace root from a relative input. Exported so
+ * the cli.ts dispatcher can call this once and pass an already-absolute
+ * path to the context. Pure - no IO.
+ */
+export function resolveWorkspaceRoot(input) {
+    return resolve(input);
+}
+/**
+ * Best-effort prefix wrap for FTS5. When the operator types a plain
+ * identifier (`fooBar`, `my_func`, `Greeter`), wrap it as a prefix
+ * match. When the input already looks like an FTS5 expression
+ * (contains `*` / `"` / `:` / leading `+` `-`), pass it through
+ * untouched. Exported so the spec can pin the behaviour.
+ *
+ * `unicode61` (the FTS5 default tokenizer) splits on punctuation
+ * other than ASCII letters/digits; an unquoted identifier with
+ * `_` или `-` would be tokenised к multiple terms. We avoid that
+ * by quoting before appending `*` for prefix-match.
+ */
+export function wrapSearchQuery(query) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return trimmed;
+    if (/["*:+\-^()]/.test(trimmed))
+        return trimmed;
+    // Single identifier-like token: quote + prefix.
+    if (!/\s/.test(trimmed)) {
+        return `"${trimmed}"*`;
+    }
+    return trimmed;
+}
+// Re-export `resolveIndexPath` from db.ts for callers that want to know
+// where the DB lives without opening it (e.g. `pugi doctor`).
+export { resolveIndexPath };
+//# sourceMappingURL=index-cmd.js.map