cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/cli/tool.js

@@ -0,0 +1,384 @@
+"use strict";
+/**
+ * Direct CLI Tool Commands
+ *
+ * Exposes GitNexus tools (context, impact, trace, cypher, detect-changes) as direct CLI commands.
+ * Bypasses MCP entirely — invokes LocalBackend directly for minimal overhead.
+ *
+ * Usage:
+ *   cgraph context --name "validateUser"
+ *   cgraph impact --target "AuthService" --direction upstream
+ *   cgraph cypher "MATCH (n:Function) RETURN n.name LIMIT 10"
+ *
+ * Note: Output goes to stdout via fs.writeSync(fd 1), bypassing LadybugDB's
+ * native module which captures the Node.js process.stdout stream during init.
+ * See the output() function for details (#324).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextCommand = contextCommand;
+exports.impactCommand = impactCommand;
+exports.cypherCommand = cypherCommand;
+exports.detectChangesCommand = detectChangesCommand;
+exports.traceCommand = traceCommand;
+exports.routeMapCommand = routeMapCommand;
+exports.shapeCheckCommand = shapeCheckCommand;
+exports.toolMapCommand = toolMapCommand;
+exports.apiImpactCommand = apiImpactCommand;
+const node_fs_1 = require("node:fs");
+const local_backend_js_1 = require("../mcp/local/local-backend.js");
+const cli_message_js_1 = require("./cli-message.js");
+const detect_changes_format_js_1 = require("./detect-changes-format.js");
+let _backend = null;
+let _backendProjectRoot;
+/**
+ * Resolve the tool backend, scoped to an optional `--path` project root.
+ *
+ * Discovery (spec §8): when `projectRoot` is omitted the backend walks up from
+ * `process.cwd()` for the nearest `.cgraphx/code/`; when supplied (CLI `--path`) it
+ * pins that root. A long-lived process that later calls with a different root
+ * rebuilds the backend so the two roots never share a singleton.
+ */
+async function getBackend(projectRoot) {
+    if (_backend && _backendProjectRoot === projectRoot)
+        return _backend;
+    _backend = new local_backend_js_1.LocalBackend({ projectRoot });
+    _backendProjectRoot = projectRoot;
+    const ok = await _backend.init();
+    if (!ok) {
+        // Surface the directory discovery actually searched so the user knows where
+        // to run `cgraph analyze` (spec §8 — project-root index, no global registry).
+        const searchedPath = projectRoot ?? process.cwd();
+        (0, cli_message_js_1.cliErrorKey)('tool.noIndexed', { searchedPath });
+        process.exit(1);
+    }
+    return _backend;
+}
+/**
+ * Write tool output to stdout using low-level fd write.
+ *
+ * LadybugDB's native module captures Node.js process.stdout during init,
+ * but the underlying OS file descriptor 1 (stdout) remains intact.
+ * By using fs.writeSync(1, ...) we bypass the Node.js stream layer
+ * and write directly to the real stdout fd (#324).
+ *
+ * Falls back to stderr if the fd write fails (e.g., broken pipe).
+ */
+function output(data) {
+    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    try {
+        (0, node_fs_1.writeSync)(1, text + '\n');
+    }
+    catch (err) {
+        if (err?.code === 'EPIPE') {
+            // Consumer closed the pipe (e.g., `cgraph cypher ... | head -1`)
+            // Exit cleanly per Unix convention
+            process.exit(0);
+        }
+        // Fallback: stderr (previous behavior, works on all platforms)
+        process.stderr.write(text + '\n');
+    }
+    // Backend failures come back as `{ error }` payloads rather than throws
+    // (#2469). Every tool command routes its result through here, so this is
+    // the one place that keeps scripted callers honest: print the payload,
+    // then exit non-zero.
+    if (data &&
+        typeof data === 'object' &&
+        'error' in data &&
+        typeof data.error === 'string' &&
+        data.error.trim().length > 0) {
+        process.exitCode = 1;
+    }
+}
+/**
+ * Parse a `--limit` CLI option into a positive row cap, or `undefined` when the
+ * flag is absent, non-numeric, zero, or negative.
+ *
+ * Treating invalid / 0 / negative input as "no limit" — rather than the old
+ * `options.limit ? Math.max(0, parseInt(...)) : undefined` path, where a string
+ * like `"abc"` is truthy and yields `NaN`, then `slice(0, NaN)` silently EMPTIES
+ * the result with exit 0 — keeps the guardrail commands (impact / context /
+ * detect-changes) honest: a bad `--limit` shows everything, never nothing.
+ */
+function parseLimit(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/**
+ * Parse an `--offset` CLI option into a non-negative pagination start, or
+ * `undefined` when the flag is absent or invalid. Mirrors {@link parseLimit};
+ * offset `0` is valid ("start at the beginning"), so the guard is `>= 0`.
+ */
+function parseOffset(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+async function contextCommand(name, options) {
+    // Reject a `--`-prefixed uid swallowed from a following flag (see impactCommand).
+    if (options?.uid?.startsWith('--')) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.context');
+        process.exit(1);
+    }
+    if (!name?.trim() && !options?.uid) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.context');
+        process.exit(1);
+    }
+    const limit = parseLimit(options?.limit);
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('context', {
+        name: name || undefined,
+        uid: options?.uid,
+        file_path: options?.file,
+        include_content: options?.content ?? false,
+        repo: options?.repo,
+        branch: options?.branch,
+    });
+    if (limit !== undefined) {
+        // Bound every array-valued category under incoming/outgoing (calls, accesses,
+        // imports, extends, uses, …) — categorize() buckets by relType, so the prior
+        // hardcoded calls/accesses missed the rest (e.g. incoming.accesses) — plus
+        // typed_properties and processes, so --limit caps the whole context payload.
+        for (const dir of [result.incoming, result.outgoing]) {
+            if (!dir)
+                continue;
+            for (const key of Object.keys(dir)) {
+                const bucket = dir[key];
+                if (Array.isArray(bucket))
+                    dir[key] = bucket.slice(0, limit);
+            }
+        }
+        if (Array.isArray(result.typed_properties))
+            result.typed_properties = result.typed_properties.slice(0, limit);
+        if (Array.isArray(result.processes))
+            result.processes = result.processes.slice(0, limit);
+    }
+    output(result);
+}
+async function impactCommand(target, options) {
+    // A `--`-prefixed uid means Commander swallowed a following flag as the uid
+    // value (e.g. `impact --uid --file x` → uid === '--file'). Reject it rather
+    // than forwarding a garbage uid that would silently resolve to not-found.
+    if (options?.uid?.startsWith('--')) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.impact');
+        process.exit(1);
+    }
+    // Target is an optional positional: a uid alone is enough to resolve (parity
+    // with `context [name]`). Only error when neither a target nor a uid is given.
+    if (!target?.trim() && !options?.uid) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.impact');
+        process.exit(1);
+    }
+    // Soft-validate --kind: an unknown kind is a no-op hint (the backend scores
+    // it but it matches nothing), so warn and proceed rather than rejecting —
+    // parity with the lenient MCP surface and forward-compatible with new labels.
+    if (options?.kind && !local_backend_js_1.VALID_NODE_LABELS.has(options.kind)) {
+        (0, cli_message_js_1.cliWarnKey)('tool.warn.unknownKind', { kind: options.kind });
+    }
+    try {
+        const backend = await getBackend(options?.path);
+        const parsedLimit = parseLimit(options?.limit);
+        const parsedOffset = parseOffset(options?.offset);
+        const result = await backend.callTool('impact', {
+            target: target || undefined,
+            target_uid: options?.uid,
+            file_path: options?.file,
+            kind: options?.kind,
+            direction: options?.direction || 'upstream',
+            maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
+            includeTests: options?.includeTests ?? false,
+            repo: options?.repo,
+            branch: options?.branch,
+            limit: parsedLimit,
+            offset: parsedOffset,
+            summaryOnly: options?.summaryOnly ?? undefined,
+        });
+        // Client-side cap of the affected-list payload to --limit (parity with the
+        // other tool commands). The backend already paginates byDepth per level to
+        // the same limit, so byDepth needs no client-side re-slice.
+        if (parsedLimit !== undefined) {
+            if (Array.isArray(result.affected_processes))
+                result.affected_processes = result.affected_processes.slice(0, parsedLimit);
+            if (Array.isArray(result.affected_modules))
+                result.affected_modules = result.affected_modules.slice(0, parsedLimit);
+        }
+        output(result);
+    }
+    catch (err) {
+        // Belt-and-suspenders: catch infrastructure failures (getBackend, callTool transport)
+        // The backend's impact() already returns structured errors for graph query failures
+        output({
+            error: (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed unexpectedly',
+            target: { name: target },
+            direction: options?.direction || 'upstream',
+            suggestion: 'Try reducing --depth or using cgraph context <symbol> as a fallback',
+        });
+        process.exit(1);
+    }
+}
+async function cypherCommand(query, options) {
+    if (!query?.trim()) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.cypher');
+        process.exit(1);
+    }
+    const limit = parseLimit(options?.limit);
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('cypher', {
+        // #2175: canonical param is statement; the backend still accepts legacy "query".
+        statement: query,
+        repo: options?.repo,
+        branch: options?.branch,
+    });
+    if (limit !== undefined) {
+        if (Array.isArray(result)) {
+            // Non-tabular result: a raw row array.
+            result.splice(limit);
+        }
+        else if (result && typeof result === 'object' && typeof result.row_count === 'number') {
+            // Tabular result: { markdown, row_count }. The markdown is a table built as
+            // [header, separator, ...dataRows].join('\n'), so slice it to `limit` data
+            // rows (keeping the 2 header lines) and report a row_count that matches what
+            // is actually printed — otherwise `--limit 2` over 50 rows prints all 50 but
+            // claims row_count: 2.
+            if (typeof result.markdown === 'string' && result.row_count > limit) {
+                result.markdown = result.markdown
+                    .split('\n')
+                    .slice(0, 2 + limit)
+                    .join('\n');
+            }
+            result.row_count = Math.min(result.row_count, limit);
+        }
+    }
+    output(result);
+}
+async function detectChangesCommand(options) {
+    const limit = parseLimit(options?.limit);
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('detect_changes', {
+        scope: options?.scope || 'unstaged',
+        base_ref: options?.baseRef,
+        repo: options?.repo,
+        branch: options?.branch,
+    });
+    if (limit !== undefined) {
+        if (Array.isArray(result.changed_symbols))
+            result.changed_symbols = result.changed_symbols.slice(0, limit);
+        if (Array.isArray(result.affected_processes))
+            result.affected_processes = result.affected_processes.slice(0, limit);
+    }
+    output((0, detect_changes_format_js_1.formatDetectChangesResult)(result));
+}
+async function traceCommand(from, to, options) {
+    if (options?.fromUid?.startsWith('--') || options?.toUid?.startsWith('--')) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.trace');
+        process.exit(1);
+    }
+    if (options?.file !== undefined &&
+        options?.fromFile !== undefined &&
+        options.file !== options.fromFile) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.trace');
+        process.exit(1);
+    }
+    if ((!from?.trim() && !options?.fromUid) || (!to?.trim() && !options?.toUid)) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.trace');
+        process.exit(1);
+    }
+    // Reject a non-numeric / non-positive --depth up front rather than forwarding
+    // NaN (which the backend would silently treat as the default).
+    if (options?.depth !== undefined) {
+        const parsedDepth = Number(options.depth);
+        if (!Number.isInteger(parsedDepth) || parsedDepth < 1) {
+            (0, cli_message_js_1.cliErrorKey)('tool.usage.trace');
+            process.exit(1);
+        }
+    }
+    try {
+        const backend = await getBackend(options?.path);
+        const fromFile = options?.fromFile ?? options?.file;
+        const result = await backend.callTool('trace', {
+            from: from || undefined,
+            from_uid: options?.fromUid,
+            from_file: fromFile,
+            to: to || undefined,
+            to_uid: options?.toUid,
+            to_file: options?.toFile,
+            maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
+            includeTests: options?.includeTests ?? false,
+            repo: options?.repo,
+            branch: options?.branch,
+        });
+        output(result);
+    }
+    catch (err) {
+        output({
+            status: 'error',
+            error: (err instanceof Error ? err.message : String(err)) || 'Trace analysis failed unexpectedly',
+            from: { name: from },
+            to: { name: to },
+            suggestion: 'Try cgraph context <symbol> to see connections, or check if an interface bridges them.',
+        });
+        process.exit(1);
+    }
+}
+// ─── 契约族四命令(只读查询,单索引免 repo) ────────────────────────
+// 与 backend 的 route_map / shape_check / tool_map / api_impact 工具一一对应,
+// 入参逐字对齐 local-backend.ts 的签名。结果统一经 output() 写 stdout;
+// backend 失败回包 { error } 时 output() 已置 exitCode=1(tool.ts 既有语义)。
+/**
+ * API 路由 → handler → 消费方映射。
+ *
+ * workspace 配置声明的前端 HTTP 消费关系也会并入;无配置时仅返回后端侧
+ * 路由与已知消费方,空结果语义由 backend message 字段提示。
+ */
+async function routeMapCommand(route, options) {
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('route_map', {
+        route: route || undefined,
+    });
+    output(result);
+}
+/**
+ * 接口响应形状 vs 消费方属性访问的不匹配检测。
+ *
+ * 与 routeMap 同样依赖 workspace 配置补全前端消费关系;无配置时只检后端侧。
+ */
+async function shapeCheckCommand(route, options) {
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('shape_check', {
+        route: route || undefined,
+    });
+    output(result);
+}
+/**
+ * MCP/RPC 工具定义与 handler 映射。
+ */
+async function toolMapCommand(tool, options) {
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('tool_map', {
+        tool: tool || undefined,
+    });
+    output(result);
+}
+/**
+ * 针对 API 路由 handler 的改动前影响报告。
+ *
+ * <target> 缺省映射到 route 名(backend `route` 入参);`--file` 提供 handler
+ * 文件路径时改走 backend `file` 入参(route 优先,与 backend 一致)。必须至少
+ * 给出 target 或 --file 之一,否则报用法错误(与 impactCommand 的 target/uid
+ * 校验同构)。
+ */
+async function apiImpactCommand(target, options) {
+    if (!target?.trim() && !options?.file) {
+        (0, cli_message_js_1.cliErrorKey)('tool.usage.apiImpact');
+        process.exit(1);
+    }
+    const backend = await getBackend(options?.path);
+    const result = await backend.callTool('api_impact', {
+        route: target || undefined,
+        file: options?.file,
+        method: options?.method,
+    });
+    output(result);
+}