fix(error-lookup): simplify isUsefulSemanticChunk — shape-only check

Codex review feedback. Two related issues:

1. Sourceish set used `match.source` and `match.title` to detect a
   rendered file-path heading line. But `/api/search` rewrites
   `source` to a public URL (`_aztec_source_url` produces e.g.
   `https://github.com/.../foo.nr`), so the bare-path heading
   `aztec-nr/.../foo.nr` never matched the URL — the heading was
   never stripped, the chunk fell through to the path-shape check
   which also missed because `# foo/bar.nr` contains whitespace
   from the markdown marker. Result: a class of empty chunks
   slipping through both gates.

2. The mitigation — strip a leading `#+ ` from each line before
   the path-shape predicate — makes the metadata coupling
   unnecessary. Drop the sourceish comparison entirely. New
   helper `lineIsPathShaped` strips heading markers, then checks
   "contains `/` and no whitespace". Real signature lines always
   have whitespace (`pub fn ...`, `struct ...`, `pub use a::b;`),
   so they never trip the predicate.

Equivalent fix on the docsgpt side: AztecProtocol/honk-ai#66
gets the same shape-only simplification.

New regression test: chunk with `#`-prefixed heading body and a
URL-rewritten source field — the exact failure mode codex
described — is correctly identified as "no useful results".

283/283 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: critesjosh

src/tools/error-lookup.ts

@@ -31,6 +31,20 @@ import { checkVersionGate, formatMismatchMessage } from "../utils/version-check.
  */
 const STRONG_MATCH_THRESHOLD = 70;
 
+/**
+ * A line is "path-shaped" if it looks like a filesystem path rather
+ * than a code/docs line. Strips a leading markdown heading marker so
+ * ``# aztec-nr/.../foo.nr`` is recognized as path-shaped just like
+ * the bare ``aztec-nr/.../foo.nr``. Path-shaped means: contains ``/``
+ * and has no whitespace. Real signature lines (``pub fn foo(...)``,
+ * ``struct Bar { ... }``, ``pub use a::b;``) always have whitespace,
+ * so they never trip this predicate.
+ */
+function lineIsPathShaped(line: string): boolean {
+  const cleaned = line.replace(/^#+\s*/, "").trim();
+  return cleaned.length > 0 && cleaned.includes("/") && !/\s/.test(cleaned);
+}
+
 /**
  * Drop semantic chunks whose body is empty or just the file path.
  *
@@ -43,6 +57,14 @@ const STRONG_MATCH_THRESHOLD = 70;
  *
  * Mirrors the Python helper in ``application/api/answer/routes/search.py``
  * (``_is_empty_apiref_chunk``) — same content-shape predicate.
+ *
+ * The predicate is deliberately metadata-free. An earlier draft used
+ * ``match.source`` / ``match.title`` as a "heading-equivalent" set
+ * to strip a rendered file heading before checking the rest, but
+ * docsgpt's ``/api/search`` rewrites ``source`` to a public URL via
+ * ``_aztec_source_url`` — so the heading string never matches the
+ * post-rewrite source field. The shape-only check below works
+ * regardless of metadata transformations.
  */
 function isUsefulSemanticChunk(match: SemanticSearchResult): boolean {
   const text = (match.text ?? "").trim();
@@ -54,29 +76,8 @@ function isUsefulSemanticChunk(match: SemanticSearchResult): boolean {
     .filter((l) => l.length > 0);
   if (lines.length === 0) return false;
 
-  // Sourceish: any of the strings the rendered file-heading might have
-  // matched (source path / filename-equivalent title). Strip a leading
-  // "#" / "##" markdown heading marker before comparing. Deliberately
-  // does NOT include match.text — that would create a fixed point
-  // (text === sourceish[0]) that filters single-line legitimate
-  // chunks that happen to be one line long.
-  const sourceish = new Set(
-    [match.source, match.title]
-      .map((s) => (s ?? "").trim())
-      .filter(Boolean)
-  );
-  const firstStripped = lines[0].replace(/^#+\s*/, "").trim();
-  let body = lines;
-  if (sourceish.has(firstStripped) || sourceish.has(lines[0])) {
-    body = body.slice(1);
-  }
-
-  if (body.length === 0) return false;
-
-  // Body still looks like a file path: every remaining line is path-
-  // shaped (contains "/" and no whitespace). A real signature line
-  // ("pub fn ..., struct Foo, ...") always has whitespace.
-  if (body.every((l) => l.includes("/") && !/\s/.test(l))) return false;
+  // All non-empty lines are path-shaped → no real API content.
+  if (lines.every(lineIsPathShaped)) return false;
 
   return true;
 }

tests/tools/error-lookup.test.ts

@@ -304,6 +304,30 @@ describe("lookupAztecError — content-thin chunk filter", () => {
     return { text, title: "foo.nr", source };
   }
 
+  it("drops chunks with `#`-prefixed path heading even when source field is a public URL", async () => {
+    /**
+     * Regression for codex review: `/api/search` rewrites the chunk's
+     * `source` field to a public URL via `_aztec_source_url`. A chunk
+     * whose body is `# aztec-nr/.../foo.nr` (path heading only) won't
+     * match the URL-rewritten source field by string equality. The
+     * earlier filter would fail to strip the heading, then fall through
+     * to the path-shape check — which also failed because `# ...` has
+     * whitespace from the markdown marker. The new shape-only filter
+     * catches this directly.
+     */
+    const client = makeClient({
+      search: vi.fn().mockResolvedValue([
+        {
+          text: "# aztec-nr/aztec/src/context/foo.nr\n",
+          title: "foo.nr",
+          source: "https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0/noir-projects/aztec-nr/aztec/src/context/foo.nr",
+        },
+      ]),
+    });
+    const result = await lookupAztecError({ query: "obscure" }, client);
+    expect(result.semanticHealth).toBe("no_results");
+  });
+
   it("treats raw output of all path-only chunks as 'no_results'", async () => {
     const client = makeClient({
       search: vi.fn().mockResolvedValue([