Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(links): reconcile-links links the pages of the source you pick
garrytan4d41ea7b736c
diff --git a/src/cli/top-help.ts b/src/cli/top-help.tsindex ff715a5447..c9b365089c 100644--- a/src/cli/top-help.ts+++ b/src/cli/top-help.ts@@ -172,7 +172,7 @@ CODE INDEXING (v0.19.0 / v0.20.0 Cathedral II)code-callees <symbol> What does this symbol call? (v0.20.0 A1)query <q> --lang <l> Filter hybrid search to one language (v0.20.0)query <q> --symbol-kind <k> Filter to symbol type (function|class|method|...) (v0.20.0)- reconcile-links [--dry-run] Batch-recompute doc↔impl edges (v0.20.0)+ reconcile-links [--source id] [--dry-run] Batch-recompute doc↔impl edges in one sourcereindex-code [--source id] [--yes] [--force] Explicit code-page reindex (v0.20.0; --force re-chunks unchanged pages)reindex-search-vector [--dry-run] [--yes] [--json]Recreate FTS triggers + backfill underdiff --git a/src/commands/reconcile-links.ts b/src/commands/reconcile-links.tsindex 1ff95a9e2e..31a5d6e70c 100644--- a/src/commands/reconcile-links.ts+++ b/src/commands/reconcile-links.ts@@ -30,12 +30,14 @@ import type { BrainEngine } from '../core/engine.ts';import { PageMissingError } from '../core/engine-errors.ts';import type { Page } from '../core/types.ts';import { extractCodeRefs, type CodeRef } from '../core/link-extraction.ts';-import { OperationError } from '../core/ops/contract.ts';+import { OperationError, opError } from '../core/ops/contract.ts';import { isSegmentedPage } from '../core/page-body/page-shape.ts';import { bodyLines } from '../core/page-body/segment-lines.ts';import { slugifyCodePath } from '../core/sync.ts';import { createProgress } from '../core/progress.ts';import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';+import { ALL_SOURCES, resolveSourceId } from '../core/source-resolver.ts';+import { flagValueError } from '../cli/flag-values.ts';export interface ReconcileLinksResult {status: 'ok' | 'auto_link_disabled';@@ -69,12 +71,13 @@ async function pageCodeRefs(engine: BrainEngine, page: Page): Promise<CodeRef[]>}export interface ReconcileLinksOpts {+ /** The one source whose pages are scanned and linked; defaults to `default`, where addLink writes when none is named. */sourceId?: string;dryRun?: boolean;}/**- * Scan every markdown page for code-path references (e.g.+ * Scan one source's markdown pages for code-path references (e.g.* `src/core/sync.ts`, `lib/foo.py:42`) and create bidirectional* doc↔impl edges (`documents` + `documented_by`) for each hit* that resolves to a code page. Idempotent via ON CONFLICT DO@@ -89,6 +92,12 @@ export async function runReconcileLinks(engine: BrainEngine,opts: ReconcileLinksOpts = {},): Promise<ReconcileLinksResult> {+ const sourceId = opts.sourceId ?? 'default';+ if (sourceId === ALL_SOURCES) {+ throw opError('invalid_params', `reconcile-links links pages inside one source; ${ALL_SOURCES} is not a source.`,+ 'Name one source with --source (gbrain sources list shows the ids).');+ }+// Respect auto_link config (same gate put_page uses). A user that// explicitly turned off auto-link doesn't want reconcile-links// writing edges back either.@@ -105,11 +114,12 @@ export async function runReconcileLinks(const progress = createProgress(cliOptsToProgressOptions(getCliOptions()));- // Walk all markdown slugs. listPages(markdown-only filter) isn't exposed,+ // Walk the source's markdown slugs. listPages(markdown-only filter) isn't exposed,// so filter at call time via page_kind. Not using getAllSlugs because we// also need compiled_truth + timeline for extractCodeRefs.const mdSlugs = (await engine.executeRaw<{ slug: string }>(- `SELECT slug FROM pages WHERE page_kind = 'markdown' ORDER BY slug`,+ `SELECT slug FROM pages WHERE page_kind = 'markdown' AND source_id = $1 ORDER BY slug`,+ [sourceId],)).map(r => r.slug);progress.start('reconcile_links.scan', mdSlugs.length);@@ -126,10 +136,8 @@ export async function runReconcileLinks(// intended-source row for `default`-vs-`<source>` ambiguity. The link// edges below also propagate the same sourceId (Data R1 MED 1: opt was// declared on ReconcileLinksOpts but ignored end-to-end).- const getPageOpts = opts.sourceId ? { sourceId: opts.sourceId } : undefined;- const linkOpts = opts.sourceId- ? { fromSourceId: opts.sourceId, toSourceId: opts.sourceId, originSourceId: opts.sourceId }- : undefined;+ const getPageOpts = { sourceId };+ const linkOpts = { fromSourceId: sourceId, toSourceId: sourceId, originSourceId: sourceId };for (const mdSlug of mdSlugs) {const page = await engine.getPage(mdSlug, getPageOpts);if (!page) {@@ -168,13 +176,12 @@ export async function runReconcileLinks(await engine.addLink(mdSlug, codeSlug, ctx, 'documents', 'markdown', mdSlug, 'compiled_truth', linkOpts); // gbrain-allow-direct-insert: gbrain reconcile-links command — code-graph reconciliation from markdown referencesawait engine.addLink(codeSlug, mdSlug, ref.path, 'documented_by', 'markdown', mdSlug, 'compiled_truth', linkOpts); // gbrain-allow-direct-insert: gbrain reconcile-links command — reverse documented_by edge} catch (e: unknown) {- // Per-link errors don't abort the batch. Track them for the summary.- if (e instanceof PageMissingError) {- edgesTargetsMissing++;- } else {- // Real error — log but keep going. Agents can inspect progress events.- console.warn(`[reconcile-links] ${mdSlug} → ${codeSlug}: ${e instanceof Error ? e.message : String(e)}`);+ // A missing code page is expected and counted; any other write failure fails the run.+ if (!(e instanceof PageMissingError)) {+ progress.finish();+ throw e;}+ edgesTargetsMissing++;}}progress.tick(1, `${mdSlug} (+${refs.length} refs)`);@@ -194,13 +201,20 @@ export async function runReconcileLinks(/*** CLI entry. Parses argv, runs runReconcileLinks, prints a summary.- * --dry-run reports counts without writing. --json emits machine output.+ * --source <id> picks the source (else the usual chain: GBRAIN_SOURCE,+ * .gbrain-source, registered path, brain default). --dry-run reports counts+ * without writing. --json emits machine output.*/export async function runReconcileLinksCli(engine: BrainEngine, args: string[]): Promise<void> {const dryRun = args.includes('--dry-run');const jsonOut = args.includes('--json');- const result = await runReconcileLinks(engine, { dryRun });+ const sourceAt = args.indexOf('--source');+ const explicit = sourceAt === -1 ? null : args[sourceAt + 1];+ if (explicit !== null && (!explicit || explicit.startsWith('-'))) throw flagValueError('--source', explicit, 'a source id', 'default');+ const sourceId = await resolveSourceId(engine, explicit);++ const result = await runReconcileLinks(engine, { dryRun, sourceId });if (jsonOut) {console.log(JSON.stringify(result));diff --git a/test/fixtures/goldens/cli/help-and-errors.json b/test/fixtures/goldens/cli/help-and-errors.jsonindex dc17e605c3..d8e81b0be3 100644--- a/test/fixtures/goldens/cli/help-and-errors.json+++ b/test/fixtures/goldens/cli/help-and-errors.json@@ -171,7 +171,7 @@" code-callees <symbol> What does this symbol call? (v0.20.0 A1)"," query <q> --lang <l> Filter hybrid search to one language (v0.20.0)"," query <q> --symbol-kind <k> Filter to symbol type (function|class|method|...) (v0.20.0)",- " reconcile-links [--dry-run] Batch-recompute doc↔impl edges (v0.20.0)",+ " reconcile-links [--source id] [--dry-run] Batch-recompute doc↔impl edges in one source"," reindex-code [--source id] [--yes] [--force] Explicit code-page reindex (v0.20.0; --force re-chunks unchanged pages)"," reindex-search-vector [--dry-run] [--yes] [--json]"," Recreate FTS triggers + backfill under",@@ -403,7 +403,7 @@" code-callees <symbol> What does this symbol call? (v0.20.0 A1)"," query <q> --lang <l> Filter hybrid search to one language (v0.20.0)"," query <q> --symbol-kind <k> Filter to symbol type (function|class|method|...) (v0.20.0)",- " reconcile-links [--dry-run] Batch-recompute doc↔impl edges (v0.20.0)",+ " reconcile-links [--source id] [--dry-run] Batch-recompute doc↔impl edges in one source"," reindex-code [--source id] [--yes] [--force] Explicit code-page reindex (v0.20.0; --force re-chunks unchanged pages)"," reindex-search-vector [--dry-run] [--yes] [--json]"," Recreate FTS triggers + backfill under",@@ -635,7 +635,7 @@" code-callees <symbol> What does this symbol call? (v0.20.0 A1)"," query <q> --lang <l> Filter hybrid search to one language (v0.20.0)"," query <q> --symbol-kind <k> Filter to symbol type (function|class|method|...) (v0.20.0)",- " reconcile-links [--dry-run] Batch-recompute doc↔impl edges (v0.20.0)",+ " reconcile-links [--source id] [--dry-run] Batch-recompute doc↔impl edges in one source"," reindex-code [--source id] [--yes] [--force] Explicit code-page reindex (v0.20.0; --force re-chunks unchanged pages)"," reindex-search-vector [--dry-run] [--yes] [--json]"," Recreate FTS triggers + backfill under",diff --git a/test/reconcile-links-source-scope.test.ts b/test/reconcile-links-source-scope.test.tsnew file mode 100644index 0000000000..fe8d5e67ff--- /dev/null+++ b/test/reconcile-links-source-scope.test.ts@@ -0,0 +1,77 @@+/**+ * reconcile-links reconciles one selected source and fails on a real write error.+ *+ * Protects: `gbrain reconcile-links --source <id>` scans, reads and links only+ * that source's pages (both edge directions inside it), refuses `__all__`,+ * and a link write that fails for any reason other than a missing target+ * fails the run instead of reporting `ok`.+ * Fails when: the CLI drops --source, the markdown scan reads every source+ * while edges default to `default` (zero edges, status ok), or the catch+ * goes back to warning and continuing.+ * Seams: `engine.addLink` is wrapped on this test's own engine instance for+ * the write-failure case; everything else is real PGLite.+ */+import { afterAll, beforeAll, expect, test } from 'bun:test';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { runReconcileLinks, runReconcileLinksCli } from '../src/commands/reconcile-links.ts';++let engine: PGLiteEngine;++beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+ for (const sourceId of ['source-a', 'source-b']) {+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1)', [sourceId]);+ await engine.putPage('guides/widget', { type: 'guide', title: 'Widget guide', compiled_truth: 'The widget lives at src/widget.ts:12.', timeline: '' }, { sourceId });+ await engine.putPage('src-widget-ts', { type: 'code', page_kind: 'code', title: 'src/widget.ts', compiled_truth: 'module', timeline: '' }, { sourceId });+ }+ await engine.putPage('guides/only-in-b', { type: 'guide', title: 'B only', compiled_truth: 'See src/widget.ts.', timeline: '' }, { sourceId: 'source-b' });+}, 120_000);++afterAll(async () => {+ await engine.disconnect();+});++async function edges(): Promise<string[]> {+ const rows = await engine.executeRaw<{ edge: string }>(+ `SELECT f.source_id || ':' || f.slug || ' ' || l.link_type || ' ' || t.source_id || ':' || t.slug AS edge+ FROM links l JOIN pages f ON f.id = l.from_page_id JOIN pages t ON t.id = l.to_page_id`);+ return rows.map(r => r.edge).sort();+}++test('--source reconciles only that source and links its pages', async () => {+ const lines: string[] = [];+ const log = console.log;+ console.log = (...a: unknown[]) => { lines.push(a.join(' ')); };+ try {+ await runReconcileLinksCli(engine, ['--source', 'source-a', '--json']);+ } finally {+ console.log = log;+ }+ expect(JSON.parse(lines.join('\n'))).toMatchObject({ status: 'ok', markdownPagesScanned: 1, edgesAttempted: 1, edgesTargetsMissing: 0 });+ expect(await edges()).toEqual([+ 'source-a:guides/widget documents source-a:src-widget-ts',+ 'source-a:src-widget-ts documented_by source-a:guides/widget',+ ]);+});++test('a sourceId scopes the scan to that source', async () => {+ const result = await runReconcileLinks(engine, { sourceId: 'source-b', dryRun: true });+ expect(result).toMatchObject({ status: 'ok', markdownPagesScanned: 2, codeRefsFound: 2 });+});++test('__all__ is refused before anything is read or written', async () => {+ await expect(runReconcileLinks(engine, { sourceId: '__all__' })).rejects.toMatchObject({ code: 'invalid_params' });+});++test('a link write that fails for a reason other than a missing target fails the run', async () => {+ const before = await edges();+ (engine as unknown as { addLink: unknown }).addLink = async () => { throw new Error('connection reset'); };+ try {+ await expect(runReconcileLinks(engine, { sourceId: 'source-b' })).rejects.toThrow('connection reset');+ } finally {+ delete (engine as unknown as { addLink?: unknown }).addLink;+ }+ expect(await edges()).toEqual(before);+});