Sync fork to upstream v1.6.0

CLAUDE.md

@@ -217,6 +217,7 @@ Formatting rules for any entry (anywhere — `[Unreleased]` or otherwise):
 3. **Strip the internals.** No internal file paths (`src/...`), no internal symbol / function / class names, no benchmark numbers / percentages / node-or-edge counts. **Keep:** language & framework names (Go, Spring, NestJS, …), things a user types or sets (`codegraph install`, `codegraph_explore`, the `CODEGRAPH_*` env vars), agent / IDE names (Claude Code, Cursor, opencode, Kiro, …), and a brief `Thanks @user` when a contributor is credited.
 4. Issue / PR references in entries are by number (`(#403)` etc.); the GitHub renderer auto-links them in the published release notes.
 5. **Don't add a `[X.Y.Z]: https://...` link reference yourself** — `prepare-release.mjs` appends it automatically when it promotes the version (idempotent: a re-run is a no-op if it already exists).
+6. **Every release opens with a `### Highlights` block — the only part most people read.** At most ~8 one-line bullets, in plain language for someone who doesn't read code, ordered by what a typical user notices first (new agent/IDE support and setup changes, then answer quality, then reliability), plus a one-sentence upgrade note when a re-index is needed. Write or refresh it in `[Unreleased]` when a release is being prepared — not per PR — and keep the detailed `### New Features` / `### Fixes` entries below it. When `### Fixes` grows past ~15 entries, group them under `####` sub-headings (`Better answers from codegraph_explore`, `Finding your project, live updates, and the CLI`, `Indexing reliability and disk usage`, `Language and framework accuracy`) so a skimmer can find their area.
 
 Multi-word headings like `### New Features` are safe on the normal release path: `prepare-release.mjs` **Case A** moves the whole `[Unreleased]` body verbatim into `[X.Y.Z]`. (Only its rarely-used **Case B** *merge* splits sub-sections with a single-word `^### (\w+)$` regex that wouldn't match them — and Case B fires only if a `[X.Y.Z]` block was pre-created, which rule above already forbids.)
 

FORK.md

@@ -3,13 +3,15 @@
 FM-Agent's maintenance fork of
 [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph).
 
-**Pinned base:** upstream `main` at `c6aaa20358cd6adcd04b87bdef8e5803ad146f3a`
-(2026-08-07). That is *past* `v1.5.0` and before whatever upstream tags next:
-`v1.5.0` was 104 commits behind, and the incremental-sync convergence work, the
-first-class `union` nodes and the WAL growth fix in between all matter to how
-FM-Agent reads the graph. The version marker keeps saying `1.5.0-fmagent.N`
-because it is the last upstream *release* this descends from — the exact base is
-this commit.
+**Pinned base:** upstream `v1.6.0` (2026-08-26) — a tagged release, as the policy
+below prefers. It carries fixes for the three issues reported upstream from this
+project since the previous base: Rust field-receiver resolution
+([#1585](https://github.com/colbymchenry/codegraph/issues/1585)), generic `impl`
+ownership ([#1588](https://github.com/colbymchenry/codegraph/issues/1588)) and
+Erlang per-arity identity
+([#1610](https://github.com/colbymchenry/codegraph/issues/1610)). The previous
+base was `c6aaa20` (upstream `main`, 2026-08-07), 27 commits behind this tag; see
+issue #10 for the full rationale of this sync.
 
 Upstream shipped the C macro-attribute extraction fix (issue #1211, PR #1311) in
 v1.5.0, so the base carries it natively; the fork no longer needs its own patch
@@ -31,9 +33,9 @@ tree or changing how the runner discovers it: our file would stay where it is, q
 stop being collected, and nothing would fail. Check the suite's file count after a
 sync, not just that it is green.
 
-**Version marker:** `codegraph --version` → `1.5.0-fmagent.N` identifies a build
-from this fork. Note this is a SemVer pre-release of `1.5.0`, so it sorts *below*
-plain `1.5.0`; the updater must therefore point at this fork (see below), never
+**Version marker:** `codegraph --version` → `1.6.0-fmagent.N` identifies a build
+from this fork. Note this is a SemVer pre-release of `1.6.0`, so it sorts *below*
+plain `1.6.0`; the updater must therefore point at this fork (see below), never
 upstream, or it would advertise a "downgrade to upstream" as an upgrade.
 
 **All install/upgrade entry points point at this fork,** so a fork install never

README.md

@@ -388,6 +388,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
@@ -400,6 +401,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 | — |
 
@@ -414,7 +416,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.
 
@@ -669,6 +671,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

__tests__/cli-context-command.test.ts

@@ -0,0 +1,114 @@
+/**
+ * `codegraph context` CLI command (#1611).
+ *
+ * The usage header has advertised `codegraph context <task>  Build context for
+ * a task` since the first release, and the ContextBuilder behind the public
+ * `buildContext` API has always shipped in the package — but the command was
+ * never registered with commander, so external integrations built against the
+ * documented contract (`codegraph context --path <root> --format json
+ * --max-nodes 8 --no-code <task>`, e.g. Memorix) got `unknown command
+ * 'context'` and fell back to their own heuristics.
+ *
+ * Exercised end-to-end against the built binary, mirroring
+ * cli-query-command.test.ts.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CodeGraph } from '../src';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+
+const ENV = { ...process.env, CODEGRAPH_NO_DAEMON: '1', CODEGRAPH_WASM_RELAUNCHED: '1' };
+
+function runContext(cwd: string, extraArgs: string[], taskParts: string[] = ['parseToken', 'expiry', 'handling']): string {
+  return execFileSync(process.execPath, [BIN, 'context', ...extraArgs, '-p', cwd, ...taskParts], {
+    encoding: 'utf-8',
+    env: ENV,
+    stdio: ['ignore', 'pipe', 'ignore'], // drop stderr (SQLite experimental warning)
+  });
+}
+
+describe('codegraph context — registered CLI command (#1611)', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-context-cmd-'));
+    fs.mkdirSync(path.join(tempDir, 'src'));
+    fs.writeFileSync(
+      path.join(tempDir, 'src/auth.ts'),
+      'export function parseToken(t: string){ return parseTokenExpiry(t) + t.trim().length; }\n' +
+        'export function parseTokenExpiry(t: string){ return Date.parse(t); }\n',
+    );
+    const cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.close();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('--format json emits clean machine-parseable JSON on stdout', () => {
+    const parsed = JSON.parse(runContext(tempDir, ['--format', 'json']));
+    expect(parsed.query).toBe('parseToken expiry handling');
+    expect(Array.isArray(parsed.nodes)).toBe(true);
+    expect(parsed.nodes.length).toBeGreaterThan(0);
+    expect(Array.isArray(parsed.codeBlocks)).toBe(true);
+    expect(parsed.codeBlocks.length).toBeGreaterThan(0);
+  });
+
+  it('--max-nodes bounds the returned symbol set', () => {
+    const parsed = JSON.parse(runContext(tempDir, ['--format', 'json', '--max-nodes', '1']));
+    expect(parsed.nodes.length).toBeLessThanOrEqual(1);
+  });
+
+  it('--no-code omits code blocks (the Memorix contract shape)', () => {
+    // The exact documented invocation: --format json --max-nodes 8 --no-code
+    const parsed = JSON.parse(
+      runContext(tempDir, ['--format', 'json', '--max-nodes', '8', '--no-code']),
+    );
+    expect(parsed.codeBlocks).toEqual([]);
+    expect(parsed.nodes.length).toBeGreaterThan(0);
+  });
+
+  it('defaults to markdown output', () => {
+    const out = runContext(tempDir, []);
+    expect(out).toContain('## Code Context');
+    expect(out).toContain('**Query:** parseToken expiry handling');
+  });
+
+  it('fails cleanly on an uninitialized project', () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-context-empty-'));
+    try {
+      execFileSync(process.execPath, [BIN, 'context', '-p', empty, 'some', 'task'], {
+        encoding: 'utf-8',
+        env: ENV,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      throw new Error('expected non-zero exit');
+    } catch (err: any) {
+      expect(err.status).toBe(1);
+      expect(String(err.stderr)).toContain('not initialized');
+    } finally {
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects an unknown --format value', () => {
+    try {
+      execFileSync(process.execPath, [BIN, 'context', '--format', 'yaml', '-p', tempDir, 'task'], {
+        encoding: 'utf-8',
+        env: ENV,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      throw new Error('expected non-zero exit');
+    } catch (err: any) {
+      expect(err.status).toBe(1);
+      expect(String(err.stderr)).toContain('Unknown format');
+    }
+  });
+});

__tests__/cli-install-init.test.ts

@@ -0,0 +1,108 @@
+/**
+ * `codegraph install --init` and `codegraph init --yes` (#1578): the one-shot,
+ * non-interactive "wire agents + build this project's index" bootstrap a fresh
+ * container / CI job needs.
+ *
+ * Exercised end-to-end against the built binary so the CLI wiring (the shared
+ * `runInit` flow, the flag plumbing, exit codes) is what's covered. Every run
+ * uses `--target none`, so the installer touches no agent config on the
+ * machine running the suite; the only side effect is the temp project's
+ * `.codegraph/`.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+
+interface RunResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Run the CLI with stdin closed — a prompt that blocks would hang / fail here. */
+function runCodegraph(args: string[], cwd: string): RunResult {
+  try {
+    const stdout = execFileSync(process.execPath, [BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      env: {
+        ...process.env,
+        CODEGRAPH_NO_DAEMON: '1',
+        CODEGRAPH_TELEMETRY: '0',
+        DO_NOT_TRACK: '1',
+        NO_COLOR: '1',
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 120_000,
+    });
+    return { status: 0, stdout, stderr: '' };
+  } catch (err) {
+    const e = err as { status?: number | null; stdout?: string | Buffer; stderr?: string | Buffer };
+    return {
+      status: e.status ?? -1,
+      stdout: String(e.stdout ?? ''),
+      stderr: String(e.stderr ?? ''),
+    };
+  }
+}
+
+describe('codegraph install --init / init --yes (#1578)', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-install-init-'));
+    fs.writeFileSync(
+      path.join(tempDir, 'a.ts'),
+      `export function greet(name: string) { return hello(name); }\n` +
+        `export function hello(n: string) { return 'hi ' + n; }\n`,
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('install --yes --target none --init builds the current project\'s index in one command', () => {
+    const r = runCodegraph(['install', '--yes', '--target', 'none', '--init'], tempDir);
+    expect(r.status, r.stdout + r.stderr).toBe(0);
+    // The installer ran (and had nothing to wire) …
+    expect(r.stdout).toContain('No agent targets selected');
+    // … and the init ran afterwards, in cwd.
+    expect(r.stdout).toContain(`Initialized in ${fs.realpathSync(tempDir)}`);
+    expect(fs.existsSync(path.join(tempDir, '.codegraph', 'codegraph.db'))).toBe(true);
+  });
+
+  it('install --init on an already-initialized project reports that and still exits 0', () => {
+    expect(runCodegraph(['init', '--yes'], tempDir).status).toBe(0);
+    const r = runCodegraph(['install', '--yes', '--target', 'none', '--init'], tempDir);
+    expect(r.status, r.stdout + r.stderr).toBe(0);
+    expect(r.stdout).toContain('Already initialized');
+  });
+
+  it('install --init refuses an unsafe root (filesystem root) with exit code 1, like init does', () => {
+    // `/` (or the drive root on Windows) is the canonical unsafe root: the
+    // refusal fires before anything is created, so nothing is written there.
+    const root = path.parse(process.cwd()).root;
+    const r = runCodegraph(['install', '--yes', '--target', 'none', '--init'], root);
+    expect(r.status).toBe(1);
+    expect(r.stdout).toContain('Refusing to initialize');
+    expect(fs.existsSync(path.join(root, '.codegraph'))).toBe(false);
+  });
+
+  it('init --yes runs non-interactively with stdin closed and builds the index', () => {
+    const r = runCodegraph(['init', '--yes'], tempDir);
+    expect(r.status, r.stdout + r.stderr).toBe(0);
+    expect(r.stdout).toContain('Initialized in');
+    expect(fs.existsSync(path.join(tempDir, '.codegraph', 'codegraph.db'))).toBe(true);
+  });
+
+  it('documents the new flags in --help', () => {
+    expect(runCodegraph(['init', '--help'], tempDir).stdout).toMatch(/-y, --yes\b/);
+    expect(runCodegraph(['install', '--help'], tempDir).stdout).toMatch(/-i, --init\b/);
+  });
+});