cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/cli/lazy-action.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Creates a lazy-loaded CLI action that defers module import until invocation.
+ * The generic constraints ensure the export name is a valid key of the module
+ * at compile time — catching typos when used with concrete module imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLazyAction = createLazyAction;
+exports.createLbugLazyAction = createLbugLazyAction;
+exports.createAnalyzerLbugLazyAction = createAnalyzerLbugLazyAction;
+const native_check_js_1 = require("../core/lbug/native-check.js");
+function isCallable(value) {
+    return typeof value === 'function';
+}
+function createLazyAction(loader, exportName) {
+    return async (...args) => {
+        const module = await loader();
+        const action = module[exportName];
+        if (!isCallable(action)) {
+            throw new Error(`Lazy action export not found: ${exportName}`);
+        }
+        await action(...args);
+    };
+}
+function createLbugLazyAction(loader, exportName) {
+    return async (...args) => {
+        const check = (0, native_check_js_1.checkLbugNative)();
+        if (!check.ok) {
+            process.stderr.write(`\n  ${check.message?.replace(/\n/g, '\n  ')}\n\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const module = await loader();
+        const action = module[exportName];
+        if (!isCallable(action)) {
+            throw new Error(`Lazy action export not found: ${exportName}`);
+        }
+        await action(...args);
+    };
+}
+/**
+ * Analyze-specific lazy action. Unlike the generic LadybugDB wrapper, this
+ * captures the complete analyzer receipt before probing/loading native code or
+ * evaluating the analyzer module graph. The target export receives that start
+ * receipt as its first argument and threads it to runFullAnalysis.
+ */
+function createAnalyzerLbugLazyAction(identityLoader, loader, exportName, analyzerModuleUrl) {
+    return async (...args) => {
+        const identityModule = await identityLoader();
+        const prepared = await identityModule.captureAnalyzerIdentityBeforeLoad(analyzerModuleUrl, async () => {
+            const check = (0, native_check_js_1.checkLbugNative)();
+            if (!check.ok)
+                return { check, module: null };
+            return { check, module: await loader() };
+        });
+        if (!prepared.loaded.check.ok) {
+            process.stderr.write(`\n  ${prepared.loaded.check.message?.replace(/\n/g, '\n  ')}\n\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const action = prepared.loaded.module?.[exportName];
+        if (!isCallable(action)) {
+            throw new Error(`Lazy action export not found: ${exportName}`);
+        }
+        await action(prepared.runnerIdentity, ...args);
+    };
+}

package/dist/core/code/engine/cli/optional-grammars.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Optional grammar availability check.
+ *
+ * tree-sitter-dart, -proto, -swift, and -kotlin are vendored under vendor/ and
+ * loaded from there by absolute path (NEVER copied into node_modules — see
+ * core/tree-sitter/vendored-grammars.ts / #2111). Each ships committed platform
+ * prebuilds activated via node-gyp-build. All can be skipped via
+ * CGRAPH_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
+ * soft-fail when no prebuild matches the host platform (and a source build was
+ * unavailable / not attempted).
+ *
+ * Either path produces the same observable: the .node binding is absent
+ * at runtime. This helper detects that condition and surfaces a single
+ * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt
+ * support is unavailable instead of silently getting a degraded index.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOptionalGrammarExtensions = getOptionalGrammarExtensions;
+exports.detectMissingOptionalGrammars = detectMissingOptionalGrammars;
+exports.warnMissingOptionalGrammars = warnMissingOptionalGrammars;
+const index_js_1 = require("../../shared/index.js");
+const parser_loader_js_1 = require("../core/tree-sitter/parser-loader.js");
+const vendored_grammars_js_1 = require("../core/tree-sitter/vendored-grammars.js");
+const cli_message_js_1 = require("./cli-message.js");
+const OPTIONAL_GRAMMARS = [
+    {
+        name: 'tree-sitter-dart',
+        pkg: 'tree-sitter-dart',
+        extensions: ['.dart'],
+        language: index_js_1.SupportedLanguages.Dart,
+    },
+    { name: 'tree-sitter-proto', pkg: 'tree-sitter-proto', extensions: ['.proto'] },
+    {
+        name: 'tree-sitter-swift',
+        pkg: 'tree-sitter-swift',
+        extensions: ['.swift'],
+        language: index_js_1.SupportedLanguages.Swift,
+    },
+    {
+        name: 'tree-sitter-kotlin',
+        pkg: 'tree-sitter-kotlin',
+        extensions: ['.kt', '.kts'],
+        language: index_js_1.SupportedLanguages.Kotlin,
+    },
+];
+/**
+ * The file extensions backed by an optional grammar — the single source for
+ * the `analyze` preflight glob (so the glob can't drift from this list).
+ */
+function getOptionalGrammarExtensions() {
+    return [...new Set(OPTIONAL_GRAMMARS.flatMap((g) => g.extensions))];
+}
+/**
+ * Returns the list of optional grammars whose native binding cannot be
+ * loaded. Actually `require()`s the package — `require.resolve` would
+ * locate the entry path even when the `.node` binding is absent (the
+ * package directory exists without a working `.node` binding), giving false
+ * negatives for the exact users we want to warn:
+ * those who installed with `CGRAPH_SKIP_OPTIONAL_GRAMMARS=1` or whose
+ * native rebuild soft-failed for missing toolchain.
+ *
+ * Node's module cache memoizes `require()` for us — calling this multiple
+ * times is cheap. The catch distinguishes "missing" (MODULE_NOT_FOUND or
+ * the typical node-gyp-build "could not find any binding" pattern) from
+ * "broken" (SyntaxError, EACCES, native crash). Broken bindings surface a
+ * separate stderr line so users get an actionable message instead of a
+ * misleading "reinstall" hint.
+ */
+function detectMissingOptionalGrammars() {
+    const missing = [];
+    for (const g of OPTIONAL_GRAMMARS) {
+        // Deliberate runtime opt-out comes first: even an installed binding is
+        // treated as unavailable, with a `skipped` reason so the warning says so
+        // instead of suggesting a reinstall (#2101 review).
+        if (g.language !== undefined && (0, parser_loader_js_1.isGrammarRuntimeSkipped)(g.language)) {
+            missing.push({ name: g.name, extensions: g.extensions, reason: 'skipped' });
+            continue;
+        }
+        try {
+            (0, vendored_grammars_js_1.requireVendoredGrammar)(g.pkg);
+        }
+        catch (err) {
+            const code = err?.code;
+            const msg = err instanceof Error ? err.message : String(err);
+            const looksMissing = code === 'MODULE_NOT_FOUND' ||
+                code === 'ERR_MODULE_NOT_FOUND' ||
+                /could not find|no native build|prebuilds/i.test(msg);
+            if (!looksMissing) {
+                // Present but broken — surface so the user doesn't get a misleading
+                // "reinstall" recovery message that wouldn't actually help. cliWarn
+                // writes plain text to stderr AND tees a structured logger.warn
+                // record; the merged repo-wide ESLint pino-migration rule forbids
+                // direct `console.error` in CLI code (only `console.log` is allowed
+                // there for tool-data stdout output).
+                (0, cli_message_js_1.cliWarn)(`GitNexus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`, { grammar: g.name, extensions: g.extensions, error: msg });
+            }
+            missing.push({ name: g.name, extensions: g.extensions, reason: 'missing' });
+        }
+    }
+    return missing;
+}
+/**
+ * Log a one-line stderr warning for each missing grammar. Safe to call
+ * unconditionally — silent if all grammars are present.
+ *
+ * `relevantExtensions`, if provided, filters the warning to grammars whose
+ * extensions appear in the set (e.g. an analyze run can pass the set of
+ * extensions actually present in the target repo so users without any
+ * .dart/.proto files don't see noise).
+ */
+function warnMissingOptionalGrammars(opts) {
+    const missing = detectMissingOptionalGrammars();
+    if (missing.length === 0)
+        return;
+    const ctx = opts?.context ? ` [${opts.context}]` : '';
+    // Hoist the optional set into a local so the closure below can narrow
+    // its type; references to `opts?.relevantExtensions` inside `.some()`
+    // lose the outer null-check narrowing and require a non-null assertion.
+    const relevantExtensions = opts?.relevantExtensions;
+    for (const g of missing) {
+        if (relevantExtensions && !g.extensions.some((e) => relevantExtensions.has(e))) {
+            continue;
+        }
+        const exts = g.extensions.join('/');
+        const message = g.reason === 'skipped'
+            ? `GitNexus${ctx}: optional grammar "${g.name}" is disabled via CGRAPH_SKIP_OPTIONAL_GRAMMARS — ${exts} files will not be parsed. Unset the variable to re-enable.`
+            : `GitNexus${ctx}: optional grammar "${g.name}" is unavailable — ${exts} files will not be parsed. Reinstall without CGRAPH_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`;
+        (0, cli_message_js_1.cliWarn)(message, {
+            grammar: g.name,
+            extensions: g.extensions,
+            reason: g.reason,
+            context: opts?.context,
+        });
+    }
+}

package/dist/core/code/engine/cli/resolve-invocation.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * npm 11.x npx-install-crash nudge for the `analyze` command (#1939).
+ *
+ * The cgraph/pnpm/bun/npx selection itself lives in the canonical helper
+ * (scripts/resolve-analyze-cmd.cjs) — self-contained CJS so the invocation
+ * decision has one source of truth. We reuse it here via createRequire instead
+ * of re-implementing it. This module adds only the npm-version probe and the
+ * warning, which are CLI-only. The relative path resolves identically from
+ * src/cli/ (tsx, vitest) and dist/cli/ (shipped), since both sit one level under
+ * the package root and `scripts/` is published.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NPX_REF = void 0;
+exports.getNpmMajorVersion = getNpmMajorVersion;
+exports.warnIfNpm11NpxRisk = warnIfNpm11NpxRisk;
+const node_child_process_1 = require("node:child_process");
+const node_module_1 = require("node:module");
+const { resolveInvocationMode, formatDocumentationDlxCommand, NPX_REF } = (0, node_module_1.createRequire)(__filename)('../../scripts/resolve-analyze-cmd.cjs');
+exports.NPX_REF = NPX_REF;
+// Fail loud at module load if the canonical cjs export shape drifts (e.g. a
+// renamed export), rather than as a late TypeError inside warnIfNpm11NpxRisk.
+if (typeof resolveInvocationMode !== 'function' ||
+    typeof formatDocumentationDlxCommand !== 'function' ||
+    typeof NPX_REF !== 'string') {
+    throw new Error('resolve-analyze-cmd.cjs must export resolveInvocationMode (function), formatDocumentationDlxCommand (function), and NPX_REF (string)');
+}
+// Re-implemented here (rather than reusing the cjs export) so vitest's
+// `vi.mock('node:child_process')` intercepts it — the cjs uses bare
+// `require('child_process')`, which the mock cannot reach. Timeout matches the
+// cjs PROBE_TIMEOUT_MS (1s) so this CLI probe shares the same hook-budget cap;
+// `npm --version` is a sub-second local call.
+function getNpmMajorVersion() {
+    try {
+        const output = (0, node_child_process_1.execFileSync)('npm', ['--version'], {
+            encoding: 'utf-8',
+            timeout: 1000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+            // Windows `npm` is a `.cmd` shim; without a shell execFileSync ENOENTs
+            // (CVE-2024-27980) and the npm-11 npx-crash warning below would never
+            // fire on Windows. Mirrors probeVersion in resolve-analyze-cmd.cjs.
+            shell: process.platform === 'win32',
+        });
+        // Read the first version-shaped line so a Corepack/update banner on stdout
+        // doesn't defeat the parse (mirrors the cjs probeVersion hardening).
+        const major = output
+            .split('\n')
+            .map((l) => l.trim())
+            .find((l) => /^v?\d+\./.test(l))
+            ?.match(/^v?(\d+)\./);
+        return major ? Number(major[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * One-line stderr nudge when an npm 11+ user is on the npx install path (#1939).
+ * Skipped when a global `gitnexus`, `pnpm` or `bunx` is already preferred, so it
+ * never nags users who are not exposed to the npx/arborist crash. "Preferred"
+ * means usable, not merely on PATH: a `bunx` shim that no longer runs fails the
+ * cjs liveness probe, resolves back to `npx`, and so still gets warned here —
+ * without that, a broken bunx would suppress the warning AND emit a command that
+ * cannot run.
+ */
+function warnIfNpm11NpxRisk() {
+    if (resolveInvocationMode() !== 'npx')
+        return;
+    const major = getNpmMajorVersion();
+    if (major === null || major < 11)
+        return;
+    process.stderr.write(`Warning: npm ${major}.x can crash while installing gitnexus via npx ` +
+        `(npm/arborist "node.target is null"). Prefer: ${formatDocumentationDlxCommand('analyze')} ` +
+        `or npm install -g ${NPX_REF}. See https://github.com/abhigyanpatwari/GitNexus/issues/1939\n`);
+}

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

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Status Command
+ *
+ * Shows the indexing status of the current repository.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusCommand = void 0;
+const path_1 = __importDefault(require("path"));
+const node_url_1 = require("node:url");
+const repo_manager_js_1 = require("../storage/repo-manager.js");
+const git_js_1 = require("../storage/git.js");
+const analyzer_identity_js_1 = require("../core/analyzer-identity.js");
+const index_freshness_js_1 = require("../core/index-freshness.js");
+const index_js_1 = require("./i18n/index.js");
+const statusCommand = async (options = {}) => {
+    const cwd = process.cwd();
+    // 先按 cwd 解析最近 `.cgraphx/code/` 索引(spec §8 cwd-based discovery),这样
+    // plain-folder 索引(根无 .git)也能被识别,而不被下方的 git 检查提前挡掉。
+    const repo = await (0, repo_manager_js_1.findRepo)(cwd);
+    if (!repo) {
+        // 无索引。非 git 目录 → not-a-git-repo;git 目录 → 未索引引导。
+        if (!(0, git_js_1.isGitRepo)(cwd)) {
+            if (options.json) {
+                console.log(JSON.stringify({ schemaVersion: 1, error: 'not-git-repository' }));
+                return;
+            }
+            console.log((0, index_js_1.t)('status.notGitRepo'));
+            return;
+        }
+        // Check if there's a stale KuzuDB index that needs migration
+        const repoRoot = (0, git_js_1.getGitRoot)(cwd) ?? cwd;
+        const { storagePath } = (0, repo_manager_js_1.getStoragePaths)(repoRoot);
+        const staleKuzu = await (0, repo_manager_js_1.hasKuzuIndex)(storagePath);
+        if (options.json) {
+            console.log(JSON.stringify({
+                schemaVersion: 1,
+                repository: repoRoot,
+                error: staleKuzu ? 'stale-kuzu-index' : 'not-indexed',
+            }));
+            return;
+        }
+        if (staleKuzu) {
+            console.log((0, index_js_1.t)('status.staleKuzu'));
+            console.log((0, index_js_1.t)('status.rebuildLadybug'));
+        }
+        else {
+            console.log((0, index_js_1.t)('status.repoNotIndexed'));
+            console.log((0, index_js_1.t)('common.runAnalyzeShort'));
+        }
+        return;
+    }
+    // plain-folder 索引(根无 .git):报告索引但不报告 commit 新鲜度(spec §4)。
+    // currentCommit 为空、无分支,故跳过 commit/branch 比较与脏树检查。
+    if (!(0, git_js_1.isGitRepo)(repo.repoPath)) {
+        const currentRunnerIdentity = (0, analyzer_identity_js_1.resolveAnalyzerRunnerIdentity)((0, node_url_1.pathToFileURL)(__filename).href);
+        const runnerIdentityIsCurrent = (0, analyzer_identity_js_1.analyzerRunnerIdentitiesEqual)(repo.meta.runnerIdentity, currentRunnerIdentity);
+        const incompleteReasons = (0, index_freshness_js_1.getIndexIncompleteReasons)(repo.meta);
+        const isUpToDate = runnerIdentityIsCurrent && incompleteReasons.length === 0;
+        if (options.json) {
+            console.log(JSON.stringify({
+                schemaVersion: 1,
+                repository: repo.repoPath,
+                mode: 'plain-folder',
+                index: {
+                    indexedAt: repo.meta.indexedAt,
+                    runnerIdentity: repo.meta.runnerIdentity ?? null,
+                    runnerIdentityStatus: runnerIdentityIsCurrent ? 'current' : 'stale-or-unknown',
+                    incompleteReasons,
+                },
+                current: { runnerIdentity: currentRunnerIdentity },
+                status: isUpToDate ? 'up-to-date' : 'stale',
+            }));
+            return;
+        }
+        console.log(`${(0, index_js_1.t)('status.repository')}: ${repo.repoPath}`);
+        console.log((0, index_js_1.t)('status.plainFolderMode'));
+        console.log(`${(0, index_js_1.t)('status.indexed')}: ${new Date(repo.meta.indexedAt).toLocaleString()}`);
+        console.log(`${(0, index_js_1.t)('status.indexRunnerIdentity')}: ${JSON.stringify(repo.meta.runnerIdentity ?? null)}`);
+        if (incompleteReasons.length > 0) {
+            console.log(`Index incomplete reasons: ${JSON.stringify(incompleteReasons)}`);
+        }
+        console.log(`${(0, index_js_1.t)('status.currentRunnerIdentity')}: ${JSON.stringify(currentRunnerIdentity)}`);
+        console.log(`${(0, index_js_1.t)('status.status')}: ${isUpToDate ? (0, index_js_1.t)('status.upToDate') : (0, index_js_1.t)('status.stale')}`);
+        return;
+    }
+    const currentCommit = (0, git_js_1.getCurrentCommit)(repo.repoPath);
+    const currentBranch = (0, git_js_1.getCurrentBranch)(repo.repoPath);
+    // Pick the index matching the checked-out branch (#2106/#2354). A pinned
+    // `--branch` sub-index for the current branch wins; otherwise report the
+    // flat workspace index, which follows the checked-out working tree — the
+    // commit comparison below then says whether it needs a re-analyze. Legacy/
+    // no-branch metas and detached HEAD also fall through to the flat index.
+    let activeMeta = repo.meta;
+    let workspaceLagsBranch = false;
+    if (currentBranch && repo.meta.branch && currentBranch !== repo.meta.branch) {
+        const { metaPath } = (0, repo_manager_js_1.getStoragePaths)(repo.repoPath, currentBranch);
+        const branchMeta = await (0, repo_manager_js_1.loadMeta)(path_1.default.dirname(metaPath));
+        if (branchMeta)
+            activeMeta = branchMeta;
+        else
+            workspaceLagsBranch = true;
+    }
+    const currentRunnerIdentity = (0, analyzer_identity_js_1.resolveAnalyzerRunnerIdentity)((0, node_url_1.pathToFileURL)(__filename).href);
+    const runnerIdentityIsCurrent = (0, analyzer_identity_js_1.analyzerRunnerIdentitiesEqual)(activeMeta.runnerIdentity, currentRunnerIdentity);
+    const incompleteReasons = (0, index_freshness_js_1.getIndexIncompleteReasons)(activeMeta);
+    // A matching HEAD is not enough: `analyze` re-indexes a dirty working tree,
+    // so a repo with uncommitted source changes is stale even at the same commit.
+    // Skip the check for non-git folders (currentCommit === '') to match analyze.
+    const isUpToDate = currentCommit === activeMeta.lastCommit &&
+        runnerIdentityIsCurrent &&
+        incompleteReasons.length === 0 &&
+        (currentCommit === '' || !(0, git_js_1.isWorkingTreeDirty)(repo.repoPath));
+    if (options.json) {
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            repository: repo.repoPath,
+            branch: currentBranch,
+            workspaceIndexBranch: workspaceLagsBranch ? (repo.meta.branch ?? null) : null,
+            index: {
+                indexedAt: activeMeta.indexedAt,
+                commit: activeMeta.lastCommit,
+                runnerIdentity: activeMeta.runnerIdentity ?? null,
+                runnerIdentityStatus: runnerIdentityIsCurrent ? 'current' : 'stale-or-unknown',
+                incompleteReasons,
+            },
+            current: {
+                commit: currentCommit,
+                runnerIdentity: currentRunnerIdentity,
+            },
+            status: isUpToDate ? 'up-to-date' : 'stale',
+        }));
+        return;
+    }
+    console.log(`${(0, index_js_1.t)('status.repository')}: ${repo.repoPath}`);
+    console.log(`${(0, index_js_1.t)('status.branch')}: ${currentBranch ?? (0, index_js_1.t)('status.detached')}`);
+    if (workspaceLagsBranch) {
+        console.log((0, index_js_1.t)('status.workspaceIndexLabel', { primary: repo.meta.branch ?? '' }));
+    }
+    console.log(`${(0, index_js_1.t)('status.indexed')}: ${new Date(activeMeta.indexedAt).toLocaleString()}`);
+    console.log(`${(0, index_js_1.t)('status.indexedCommit')}: ${activeMeta.lastCommit?.slice(0, 7)}`);
+    console.log(`${(0, index_js_1.t)('status.currentCommit')}: ${currentCommit?.slice(0, 7)}`);
+    // Emit the complete, versioned receipt as JSON so humans can inspect it and
+    // automation can compare it without reverse-engineering a display string.
+    // `null` is the backward-compatible signal for pre-receipt metadata.
+    console.log(`${(0, index_js_1.t)('status.indexRunnerIdentity')}: ${JSON.stringify(activeMeta.runnerIdentity ?? null)}`);
+    if (incompleteReasons.length > 0) {
+        console.log(`Index incomplete reasons: ${JSON.stringify(incompleteReasons)}`);
+    }
+    console.log(`${(0, index_js_1.t)('status.currentRunnerIdentity')}: ${JSON.stringify(currentRunnerIdentity)}`);
+    console.log(`${(0, index_js_1.t)('status.status')}: ${isUpToDate ? (0, index_js_1.t)('status.upToDate') : (0, index_js_1.t)('status.stale')}`);
+};
+exports.statusCommand = statusCommand;