@colbymchenry/codegraph-darwin-x64 0.9.9 → 1.0.0

package/lib/dist/bin/codegraph.d.ts

@@ -20,6 +20,7 @@
  *   codegraph callees <symbol>   Find what a function/method calls
  *   codegraph impact <symbol>    Analyze what code is affected by changing a symbol
  *   codegraph affected [files]   Find test files affected by changes
+ *   codegraph upgrade [version]  Update CodeGraph to the latest release
  */
 export {};
 //# sourceMappingURL=codegraph.d.ts.map

package/lib/dist/bin/codegraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;GAqBG"}
+{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../src/bin/codegraph.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/lib/dist/bin/codegraph.js

@@ -21,6 +21,7 @@
  *   codegraph callees <symbol>   Find what a function/method calls
  *   codegraph impact <symbol>    Analyze what code is affected by changing a symbol
  *   codegraph affected [files]   Find test files affected by changes
+ *   codegraph upgrade [version]  Update CodeGraph to the latest release
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -65,6 +66,8 @@ const shimmer_progress_1 = require("../ui/shimmer-progress");
 const glyphs_1 = require("../ui/glyphs");
 const node_version_check_1 = require("./node-version-check");
 const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
+const extraction_version_1 = require("../extraction/extraction-version");
+const telemetry_1 = require("../telemetry");
 // Lazy-load heavy modules (CodeGraph, runInstaller) to keep CLI startup fast.
 async function loadCodeGraph() {
     try {
@@ -166,6 +169,30 @@ function main() {
         .name('codegraph')
         .description('Code intelligence and knowledge graph for any codebase')
         .version(packageJson.version);
+    // Anonymous usage telemetry (see TELEMETRY.md): record the invoked subcommand
+    // NAME only — never arguments or paths. Counts buffer locally; network sends
+    // piggyback on commands that run long anyway (quick commands only append to
+    // the local buffer at exit, costing nothing).
+    // install/uninstall are absent on purpose: the installer flushes at its own
+    // end, AFTER its consent prompt — a flush here would fire the first-run
+    // notice before the user ever sees the toggle.
+    const TELEMETRY_FLUSH_COMMANDS = new Set(['init', 'uninit', 'index', 'sync', 'upgrade']);
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        try {
+            // The detached daemon re-invokes `serve --mcp` internally — not a user action.
+            if (process.env.CODEGRAPH_DAEMON_INTERNAL)
+                return;
+            const name = actionCommand.name();
+            if (name === 'telemetry')
+                return; // managing telemetry is not usage
+            (0, telemetry_1.getTelemetry)().recordUsage('cli_command', name, true);
+            if (TELEMETRY_FLUSH_COMMANDS.has(name))
+                (0, telemetry_1.getTelemetry)().maybeFlush();
+        }
+        catch {
+            /* telemetry must never break the CLI */
+        }
+    });
     // =============================================================================
     // Helper Functions
     // =============================================================================
@@ -339,7 +366,7 @@ function main() {
             }
         }
         else if (projectPath) {
-            const logPath = path.join(projectPath, '.codegraph', 'errors.log');
+            const logPath = path.join((0, directory_1.getCodeGraphDir)(projectPath), 'errors.log');
             if (fs.existsSync(logPath)) {
                 fs.unlinkSync(logPath);
             }
@@ -349,7 +376,7 @@ function main() {
      * Write detailed error log to .codegraph/errors.log
      */
     function writeErrorLog(projectPath, errors) {
-        const cgDir = path.join(projectPath, '.codegraph');
+        const cgDir = (0, directory_1.getCodeGraphDir)(projectPath);
         if (!fs.existsSync(cgDir))
             return;
         const logPath = path.join(cgDir, 'errors.log');
@@ -386,6 +413,15 @@ function main() {
         }
         fs.writeFileSync(logPath, lines.join('\n') + '\n');
     }
+    /**
+     * Telemetry for a completed full index (see TELEMETRY.md). The bounded flush
+     * keeps init/index responsive (these commands just ran for seconds anyway)
+     * while delivering the event promptly.
+     */
+    async function recordIndexTelemetry(cg, result) {
+        (0, telemetry_1.recordIndexEvent)(cg, result);
+        await (0, telemetry_1.getTelemetry)().flushNow();
+    }
     // =============================================================================
     // Commands
     // =============================================================================
@@ -435,6 +471,7 @@ function main() {
                 await progress.stop();
             }
             printIndexResult(clack, result, projectPath);
+            await recordIndexTelemetry(cg, result);
             try {
                 const { offerWatchFallback } = await Promise.resolve().then(() => __importStar(require('../installer')));
                 await offerWatchFallback(clack, projectPath);
@@ -488,6 +525,13 @@ function main() {
             }
             catch { /* non-fatal */ }
             success(`Removed CodeGraph from ${projectPath}`);
+            // Churn signal — and flush now, since after an uninit there may be no
+            // "next run" to deliver it.
+            try {
+                (0, telemetry_1.getTelemetry)().recordLifecycle('uninstall', {});
+                await (0, telemetry_1.getTelemetry)().flushNow();
+            }
+            catch { /* non-fatal */ }
         }
         catch (err) {
             error(`Failed to uninitialize: ${err instanceof Error ? err.message : String(err)}`);
@@ -545,6 +589,7 @@ function main() {
                 await progress.stop();
             }
             printIndexResult(clack, result, projectPath);
+            await recordIndexTelemetry(cg, result);
             if (!result.success) {
                 process.exit(1);
             }
@@ -629,7 +674,13 @@ function main() {
         try {
             if (!(0, directory_1.isInitialized)(projectPath)) {
                 if (options.json) {
-                    console.log(JSON.stringify({ initialized: false, projectPath }));
+                    console.log(JSON.stringify({
+                        initialized: false,
+                        version: packageJson.version,
+                        projectPath,
+                        indexPath: (0, directory_1.getCodeGraphDir)(projectPath),
+                        lastIndexed: null,
+                    }));
                     return;
                 }
                 console.log(chalk.bold('\nCodeGraph Status\n'));
@@ -644,11 +695,17 @@ function main() {
             const changes = cg.getChangedFiles();
             const backend = cg.getBackend();
             const journalMode = cg.getJournalMode();
+            const buildInfo = cg.getIndexBuildInfo();
+            const reindexRecommended = cg.isIndexStale();
             // JSON output mode
             if (options.json) {
+                const lastIndexedMs = cg.getLastIndexedAt();
                 console.log(JSON.stringify({
                     initialized: true,
+                    version: packageJson.version,
                     projectPath,
+                    indexPath: (0, directory_1.getCodeGraphDir)(projectPath),
+                    lastIndexed: lastIndexedMs != null ? new Date(lastIndexedMs).toISOString() : null,
                     fileCount: stats.fileCount,
                     nodeCount: stats.nodeCount,
                     edgeCount: stats.edgeCount,
@@ -665,6 +722,12 @@ function main() {
                     worktreeMismatch: worktreeMismatch
                         ? { worktreeRoot: worktreeMismatch.worktreeRoot, indexRoot: worktreeMismatch.indexRoot }
                         : null,
+                    index: {
+                        builtWithVersion: buildInfo.version,
+                        builtWithExtractionVersion: buildInfo.extractionVersion,
+                        currentExtractionVersion: extraction_version_1.EXTRACTION_VERSION,
+                        reindexRecommended,
+                    },
                 }));
                 cg.destroy();
                 return;
@@ -732,6 +795,14 @@ function main() {
                 success('Index is up to date');
             }
             console.log();
+            // Re-index hint: the index was built by an older engine than the one now
+            // running, so a rebuild would add data a migration can't backfill.
+            if (reindexRecommended) {
+                const builtWith = buildInfo.version ? `v${buildInfo.version.replace(/^v/, '')}` : 'an earlier version';
+                warn(`Index was built by ${builtWith}; re-index to pick up this engine's improvements.`);
+                info('Run "codegraph index -f" (full rebuild) or "codegraph sync"');
+                console.log();
+            }
             cg.destroy();
         }
         catch (err) {
@@ -803,6 +874,106 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * codegraph explore <query...>
+     *
+     * The CLI face of the MCP codegraph_explore tool — same handler, same
+     * output (source of the relevant symbols grouped by file + the call path
+     * among them). Exists so agents WITHOUT the MCP tools — Task-tool
+     * subagents (which don't inherit MCP tools, #704) and non-MCP harnesses —
+     * can reach the graph through a plain shell command.
+     */
+    program
+        .command('explore <query...>')
+        .description('Explore an area: relevant symbols\' source + call paths in one shot (same output as the codegraph_explore MCP tool)')
+        .option('-p, --path <path>', 'Project path')
+        .option('--max-files <number>', 'Maximum number of files to include source from')
+        .action(async (queryParts, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`CodeGraph isn't available here — no .codegraph/ index exists in ${projectPath}. If you are an AI agent: continue with your usual tools; indexing is the user's decision, do not run it yourself. (The project owner can enable CodeGraph with 'codegraph init'.)`);
+                process.exit(1);
+            }
+            const { default: CodeGraph } = await loadCodeGraph();
+            const cg = await CodeGraph.open(projectPath);
+            const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
+            const handler = new ToolHandler(cg);
+            const args = { query: queryParts.join(' ') };
+            if (options.maxFiles)
+                args.maxFiles = parseInt(options.maxFiles, 10);
+            const result = await handler.execute('codegraph_explore', args);
+            console.log(result.content[0]?.text ?? '');
+            cg.destroy();
+            if (result.isError)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`Explore failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
+    /**
+     * codegraph node <name>
+     *
+     * The CLI face of the MCP codegraph_node tool: one symbol's source +
+     * caller/callee trail, or a whole file with line numbers + dependents
+     * (Read-parity). Same subagent/non-MCP rationale as `explore`.
+     */
+    program
+        .command('node <name>')
+        .description('One symbol\'s source + caller/callee trail, or read a file with line numbers + dependents (same output as the codegraph_node MCP tool)')
+        .option('-p, --path <path>', 'Project path')
+        .option('-f, --file <file>', 'Treat as file mode (or disambiguate a symbol to this file)')
+        .option('--offset <number>', 'File mode: 1-based start line')
+        .option('--limit <number>', 'File mode: maximum lines')
+        .option('--symbols-only', 'File mode: just the symbol map + dependents')
+        .action(async (name, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`CodeGraph isn't available here — no .codegraph/ index exists in ${projectPath}. If you are an AI agent: continue with your usual tools; indexing is the user's decision, do not run it yourself. (The project owner can enable CodeGraph with 'codegraph init'.)`);
+                process.exit(1);
+            }
+            const { default: CodeGraph } = await loadCodeGraph();
+            const cg = await CodeGraph.open(projectPath);
+            const { ToolHandler } = await Promise.resolve().then(() => __importStar(require('../mcp/tools')));
+            const handler = new ToolHandler(cg);
+            // A name with a path separator is a file read; otherwise a symbol
+            // (use --file for basename-only file reads or to pin an overload).
+            // Both separators: Windows users type src\auth\session.ts. Symbols
+            // never contain either ('/' isn't an identifier char anywhere we
+            // index; C++ scope is '::', JS members '.').
+            const args = {};
+            if (options.file) {
+                args.file = options.file;
+                if (name && name !== options.file)
+                    args.symbol = name;
+            }
+            else if (name.includes('/') || name.includes('\\')) {
+                args.file = name.replace(/\\/g, '/');
+            }
+            else {
+                args.symbol = name;
+                args.includeCode = true;
+            }
+            if (options.offset)
+                args.offset = parseInt(options.offset, 10);
+            if (options.limit)
+                args.limit = parseInt(options.limit, 10);
+            if (options.symbolsOnly)
+                args.symbolsOnly = true;
+            const result = await handler.execute('codegraph_node', args);
+            console.log(result.content[0]?.text ?? '');
+            cg.destroy();
+            if (result.isError)
+                process.exit(1);
+        }
+        catch (err) {
+            error(`Node lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * codegraph files [path]
      */
@@ -1505,6 +1676,78 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * codegraph telemetry [on|off|status]
+     */
+    program
+        .command('telemetry [action]')
+        .description('Show or change anonymous usage telemetry (status, on, off)')
+        .action((action) => {
+        const t = (0, telemetry_1.getTelemetry)();
+        if (action === 'on' || action === 'off') {
+            t.setEnabled(action === 'on', 'cli');
+            if (action === 'on') {
+                success('Telemetry enabled — anonymous usage stats only (no code, paths, or names).');
+            }
+            else {
+                success('Telemetry disabled. Buffered, unsent data was deleted.');
+            }
+            const effective = t.getStatus();
+            if (effective.decidedBy === 'DO_NOT_TRACK' || effective.decidedBy === 'CODEGRAPH_TELEMETRY') {
+                warn(`The ${effective.decidedBy} environment variable overrides this choice — ` +
+                    `effective state right now: ${effective.enabled ? 'enabled' : 'disabled'}.`);
+            }
+            return;
+        }
+        if (action !== undefined && action !== 'status') {
+            error(`Unknown action: ${action} (expected status, on, or off)`);
+            process.exit(1);
+        }
+        const s = t.getStatus();
+        const decidedBy = {
+            DO_NOT_TRACK: 'DO_NOT_TRACK environment variable',
+            CODEGRAPH_TELEMETRY: 'CODEGRAPH_TELEMETRY environment variable',
+            config: 'your saved choice',
+            default: 'default',
+        };
+        console.log(`\nTelemetry: ${s.enabled ? chalk.green('enabled') : chalk.yellow('disabled')} ${chalk.dim(`(${decidedBy[s.decidedBy]})`)}`);
+        console.log(`Machine ID: ${s.machineId ?? chalk.dim('(random UUID, created on first use)')}`);
+        console.log(`Config:     ${s.configPath}`);
+        console.log(chalk.dim(`\nExactly what is collected (and never collected): ${telemetry_1.TELEMETRY_DOCS}\n`));
+    });
+    /**
+     * codegraph upgrade [version]
+     *
+     * Self-update, however CodeGraph was installed (bundle via install.sh/.ps1,
+     * npm-global, npx, or a source checkout). See ../upgrade for the detection and
+     * per-method upgrade logic.
+     */
+    program
+        .command('upgrade [version]')
+        .description('Update CodeGraph to the latest release (or a specific version)')
+        .option('--check', 'Check whether an update is available without installing')
+        .option('-f, --force', 'Reinstall even if already on the target version')
+        .action(async (versionArg, options) => {
+        const up = await Promise.resolve().then(() => __importStar(require('../upgrade')));
+        const method = up.detectInstallMethod({
+            filename: __filename,
+            platform: process.platform,
+            cwd: process.cwd(),
+        });
+        const pin = versionArg || process.env.CODEGRAPH_VERSION || undefined;
+        const code = await up.runUpgrade({ version: pin, check: options.check, force: options.force }, {
+            currentVersion: packageJson.version,
+            method,
+            resolveLatest: () => up.resolveLatestVersion(),
+            run: up.defaultRun,
+            hasCommand: up.hasCommand,
+            log: (m) => console.log(m),
+            warn: (m) => warn(m),
+            error: (m) => error(m),
+            platform: process.platform,
+        });
+        process.exit(code);
+    });
     // Parse and run
     program.parse();
 } // end main()