@vizalice/codegraph 1.5.0 → 1.6.0

package/README.md

@@ -389,6 +389,7 @@ The installer **wires up your agents only — it does not index your code.** Aft
 
 ```bash
 codegraph install --yes                              # auto-detect agents, install global
+codegraph install --yes --init                       # same, then build the current project's index (one-shot bootstrap)
 codegraph install --target=cursor,claude --yes       # explicit target list
 codegraph install --target=auto --location=local     # detected agents, project-local
 codegraph install --target=copilot-vscode,copilot-cli,copilot-jetbrains --yes  # GitHub Copilot everywhere
@@ -401,6 +402,7 @@ codegraph install --print-config copilot-vscode      # same, for Copilot in VS C
 | `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,...`) | prompt |
 | `--location` | `global`, `local` | prompt |
 | `--yes` | (boolean) | prompt every step |
+| `--init` | (boolean) run `codegraph init` in the current directory after wiring agents | — |
 | `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
 | `--print-config <id>` | dump snippet for one agent and exit | — |
 
@@ -415,7 +417,7 @@ cd your-project
 codegraph init
 ```
 
-Builds the per-project knowledge graph index, which then auto-syncs on every file change. A single global `codegraph install` works in every project you open — no need to re-run the installer per project.
+Builds the per-project knowledge graph index, which then auto-syncs on every file change. A single global `codegraph install` works in every project you open — no need to re-run the installer per project. Add `--yes` to skip every prompt (scripts / CI / container bootstraps).
 
 That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
 
@@ -670,6 +672,26 @@ CodeGraph discovers those files off disk, overriding `.gitignore`, on index,
 sync, and watch. An explicit `exclude` still wins, and built-in skips
 (`node_modules`, `dist`, `.git`) are never re-included.
 
+Sometimes a directory shouldn't leave the index — you still want to find things
+in it — it just shouldn't *outrank* your real code. A `scripts/` or
+`optional-skills/` tree whose helpers use generic names (`usage`, `status`,
+`run`) can win on an exact name match and crowd out the product code that
+actually answers the query. Name those trees under `deprioritize`:
+
+```json
+{
+  "deprioritize": ["optional-skills/", "scripts/"]
+}
+```
+
+This is the ranking counterpart to `exclude`: those paths stay indexed and
+findable — searching for them directly still works — they just stop winning
+against first-party code. It applies to `query` / `search` and to `explore`'s
+ranking. It is *not* a filter: unlike the built-in `example/`, `sample/`,
+`fixture/`, `benchmark/` and `demo/` handling — which also drops those files
+from some result sets outright — `deprioritize` only ever changes rank. Reach
+for `exclude` when you want something gone.
+
 ### Custom file extensions
 
 If your project uses a non-standard extension for a [supported
@@ -857,6 +879,8 @@ Framework routing is validated the same way, on a canonical app per framework: E
 
 **Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.
 
+**Very large repositories (hundreds of thousands of files), or a large `.codegraph/codegraph.db-wal` file** — The `-wal` file is SQLite's write-ahead log: writes waiting to be folded into `codegraph.db`. While a big index is being built, CodeGraph lets it grow in proportion to the index (soft threshold = the larger of 256 MB and a quarter of the index size, up to 2 GB) before folding it back, because folding too often is what made large indexes slow on ordinary disks. At rest it is trimmed to 64 MB, and a leftover from a killed session is folded and trimmed the next time the project opens — the index itself has no size limit. Two environment variables tune this: `CODEGRAPH_WAL_VALVE_MB` (the soft threshold during indexing) and `CODEGRAPH_WAL_HEAL_MB` (the resting size and the trim threshold). `CODEGRAPH_WAL_VALVE_DEBUG=1` prints every decision to stderr.
+
 ## License
 
 MIT

package/dist/bin/codegraph.js

@@ -393,6 +393,16 @@ function main() {
             for (const w of result.errors.filter((e) => e.code === 'index_partial')) {
                 clack.log.warn(w.message);
             }
+            // Files salvaged from comment-stripped source after repeated parser
+            // failures are indexed but possibly incomplete — say so here, or the run
+            // reads as fully clean and the index quietly disagrees with a later
+            // re-parse of the same bytes (#1565).
+            const salvaged = result.errors.filter((e) => e.code === 'salvaged_stripped');
+            if (salvaged.length > 0) {
+                const sample = salvaged.slice(0, 3).map((e) => e.filePath).filter(Boolean).join(', ');
+                const more = salvaged.length > 3 ? ', ...' : '';
+                clack.log.warn(`${formatNumber(salvaged.length)} file(s) indexed from comment-stripped source after repeated parse failures ${(0, glyphs_1.getGlyphs)().dash} symbols may be incomplete (${sample}${more})`);
+            }
         }
         else if (hasErrors) {
             clack.log.error(`Indexing failed ${(0, glyphs_1.getGlyphs)().dash} all ${formatNumber(result.filesErrored)} files had errors`);
@@ -429,9 +439,17 @@ function main() {
             }
         }
         else if (projectPath) {
-            const logPath = path.join((0, directory_1.getCodeGraphDir)(projectPath), 'errors.log');
-            if (fs.existsSync(logPath)) {
-                fs.unlinkSync(logPath);
+            // No hard errors. Salvaged-file warnings still belong in the log — it
+            // carries the per-file detail behind the one-line summary above.
+            if (result.errors.some((e) => e.code === 'salvaged_stripped')) {
+                writeErrorLog(projectPath, result.errors);
+                clack.log.info('See .codegraph/errors.log for details');
+            }
+            else {
+                const logPath = path.join((0, directory_1.getCodeGraphDir)(projectPath), 'errors.log');
+                if (fs.existsSync(logPath)) {
+                    fs.unlinkSync(logPath);
+                }
             }
         }
     }
@@ -551,16 +569,14 @@ function main() {
     // Commands
     // =============================================================================
     /**
-     * codegraph init [path]
+     * The `init` flow — shared by `codegraph init` and `codegraph install --init`
+     * (#1578): refuse an unsafe root, create `.codegraph/`, build the initial
+     * index under supervision, then the post-index offers. `yes` makes every
+     * offer non-interactive (defaults only), so a container / CI bootstrap never
+     * blocks on a prompt. An unsafe root sets `process.exitCode = 1` and returns
+     * (no `--force` is implied by any caller); an index failure exits 1.
      */
-    program
-        .command('init [path]')
-        .description('Initialize CodeGraph in a project directory and build the initial index')
-        .option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')
-        .option('-f, --force', 'Initialize even if the path looks like your home directory or a filesystem root')
-        .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
-        .action(async (pathArg, options) => {
-        const projectPath = path.resolve(pathArg || process.cwd());
+    async function runInit(projectPath, options) {
         const clack = await importESM('@clack/prompts');
         clack.intro('Initializing CodeGraph');
         try {
@@ -580,7 +596,7 @@ function main() {
                 clack.log.info('Use "codegraph index" to re-index or "codegraph sync" to update');
                 try {
                     const { offerWatchFallback } = await Promise.resolve().then(() => __importStar(require('../installer')));
-                    await offerWatchFallback(clack, projectPath);
+                    await offerWatchFallback(clack, projectPath, { yes: options.yes });
                 }
                 catch { /* non-fatal */ }
                 clack.outro('');
@@ -620,12 +636,14 @@ function main() {
             // An empty graph at a git super-repo usually means `.gitignore` excludes
             // the child repos that hold the code — surface them and offer to opt in
             // rather than leaving the user with a silent 0-node "Done". (#1156)
+            // Under --yes the offer prints its one-line opt-in snippet instead of
+            // prompting (same as a non-TTY run).
             if (result.nodesCreated === 0) {
-                await offerIndexIgnoredRepos(clack, projectPath, runIndex, { interactive: true });
+                await offerIndexIgnoredRepos(clack, projectPath, runIndex, { interactive: !options.yes });
             }
             try {
                 const { offerWatchFallback } = await Promise.resolve().then(() => __importStar(require('../installer')));
-                await offerWatchFallback(clack, projectPath);
+                await offerWatchFallback(clack, projectPath, { yes: options.yes });
             }
             catch { /* non-fatal */ }
             clack.outro('Done');
@@ -635,6 +653,19 @@ function main() {
             clack.log.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
             process.exit(1);
         }
+    }
+    /**
+     * codegraph init [path]
+     */
+    program
+        .command('init [path]')
+        .description('Initialize CodeGraph in a project directory and build the initial index')
+        .option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')
+        .option('-f, --force', 'Initialize even if the path looks like your home directory or a filesystem root')
+        .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
+        .option('-y, --yes', 'Non-interactive: skip every prompt and take the defaults (for scripts / CI / container bootstraps)')
+        .action(async (pathArg, options) => {
+        await runInit(path.resolve(pathArg || process.cwd()), options);
     });
     /**
      * codegraph uninit [path]
@@ -1130,6 +1161,60 @@ function main() {
             process.exit(1);
         }
     });
+    /**
+     * codegraph context <task...>
+     *
+     * The CLI face of the public `buildContext` API (ContextBuilder): FTS entry
+     * points + graph expansion + code blocks, formatted as markdown or JSON.
+     * Advertised in the usage header since the first release but never actually
+     * registered (#1611); external integrations (e.g. Memorix) invoke it as
+     * `codegraph context --path <root> --format json --max-nodes 8 --no-code <task>`.
+     */
+    program
+        .command('context <task...>')
+        .description('Build context for a task: relevant symbols, relationships, and code blocks')
+        .option('-p, --path <path>', 'Project path')
+        .option('-f, --format <format>', 'Output format: markdown or json', 'markdown')
+        .option('-n, --max-nodes <number>', 'Maximum number of symbols to include')
+        .option('--no-code', 'Omit code blocks (structure only)')
+        .action(async (taskParts, options) => {
+        const projectPath = resolveProjectPath(options.path);
+        const format = options.format ?? 'markdown';
+        if (format !== 'markdown' && format !== 'json') {
+            error(`Unknown format "${options.format}" — use "markdown" or "json".`);
+            process.exit(1);
+        }
+        let maxNodes;
+        if (options.maxNodes !== undefined) {
+            maxNodes = parseInt(options.maxNodes, 10);
+            if (Number.isNaN(maxNodes) || maxNodes < 1) {
+                error(`--max-nodes expects a positive integer, got "${options.maxNodes}".`);
+                process.exit(1);
+            }
+        }
+        try {
+            if (!(0, directory_1.isInitialized)(projectPath)) {
+                error(`CodeGraph not initialized in ${projectPath}`);
+                process.exit(1);
+            }
+            const { default: CodeGraph } = await loadCodeGraph();
+            const cg = await CodeGraph.open(projectPath);
+            const result = await cg.buildContext(taskParts.join(' '), {
+                format,
+                includeCode: options.code !== false,
+                ...(maxNodes !== undefined ? { maxNodes } : {}),
+            });
+            // Both supported formats return a formatted string; print it verbatim so
+            // `--format json` stays machine-parseable on stdout (error()/warnings go
+            // to stderr only).
+            console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+            cg.destroy();
+        }
+        catch (err) {
+            error(`Context build failed: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    });
     /**
      * codegraph prompt-hook  (hidden)
      *
@@ -1592,9 +1677,9 @@ function main() {
         .aliases(['daemons'])
         .description('Manage running CodeGraph background daemons — pick one and press enter to stop it')
         .action(async () => {
-        const { listDaemons, stopDaemonAt, stopAllDaemons } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
+        const { listVerifiedDaemons, stopDaemonAt, stopAllDaemons } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
         const { runDaemonPicker } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-manager')));
-        const daemons = listDaemons();
+        const daemons = await listVerifiedDaemons();
         if (daemons.length === 0) {
             info('No CodeGraph daemons running.');
             return;
@@ -1621,7 +1706,7 @@ function main() {
         const clack = await importESM('@clack/prompts');
         clack.intro('CodeGraph daemons');
         await runDaemonPicker({
-            list: listDaemons,
+            list: listVerifiedDaemons,
             stop: stopDaemonAt,
             stopAll: stopAllDaemons,
             cwdRoot,
@@ -1723,12 +1808,17 @@ function main() {
                 return;
             }
             const lockPath = path.join((0, directory_1.getCodeGraphDir)(projectPath), 'codegraph.lock');
-            if (!fs.existsSync(lockPath)) {
-                info(`No lock file found ${(0, glyphs_1.getGlyphs)().dash} nothing to do`);
-                return;
-            }
-            fs.unlinkSync(lockPath);
-            success('Removed lock file. You can now run indexing again.');
+            let removed = false;
+            if (fs.existsSync(lockPath)) {
+                fs.unlinkSync(lockPath);
+                removed = true;
+            }
+            const { clearStaleDaemonArtifacts } = await Promise.resolve().then(() => __importStar(require('../mcp/daemon-registry')));
+            removed = await clearStaleDaemonArtifacts(projectPath) || removed;
+            if (removed)
+                success('Removed stale lock artifacts. You can now run indexing again.');
+            else
+                info(`No stale lock files found ${(0, glyphs_1.getGlyphs)().dash} nothing to do`);
         }
         catch (err) {
             error(`Failed to remove lock: ${err instanceof Error ? err.message : String(err)}`);
@@ -2116,6 +2206,7 @@ function main() {
         .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt')
         .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
         .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
+        .option('-i, --init', 'After wiring agents, also run `codegraph init` in the current directory — builds this project’s index, so install + index is one command (combine with --yes for an unattended bootstrap)')
         .option('--no-permissions', 'Skip writing the auto-allow permissions list (Claude Code only)')
         .option('--print-config <id>', 'Print MCP config snippet for the named agent and exit (no file writes)')
         .option('--refresh', 'Rewrite what previous installs configured, for already-configured agents only (never adds new ones). Run automatically by `codegraph upgrade`')
@@ -2191,6 +2282,17 @@ function main() {
             error(err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
+        // --init: the one-shot "wire agents AND build this project's index"
+        // bootstrap (#1578). The installer itself never indexes implicitly (a
+        // surprise index of $HOME is the thing we refuse) — an explicit flag is
+        // the user choosing. Runs after a successful install, including the
+        // `--target none` / nothing-detected case (the installer returns normally
+        // there), and shares every guard with `codegraph init`: an unsafe root
+        // is refused (exit 1, no implied --force), an already-initialized
+        // project just says so. `--yes` flows through so no offer prompts.
+        if (opts.init) {
+            await runInit(process.cwd(), { yes: opts.yes });
+        }
     });
     /**
      * codegraph uninstall