Skip to content

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.ts
index 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 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/src/commands/reconcile-links.ts b/src/commands/reconcile-links.ts
index 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 references
await 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.json
index 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.ts
new file mode 100644
index 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);
+});