@tikoci/rosetta 0.10.0 → 0.11.0-alpha.87

package/README.md

@@ -121,6 +121,21 @@ Need to force a database reload later? Use:
 bunx @tikoci/rosetta@latest --refresh
 ```
 
+### Prerelease channels (optional)
+
+New corpus builds sometimes ship first under a non-default npm dist-tag so testers can opt in without moving what everyone else gets by default:
+
+```sh
+bunx @tikoci/rosetta@next     # newest prerelease of any stage (alpha/beta/rc)
+bunx @tikoci/rosetta@alpha    # pinned to the alpha stage's latest
+bunx @tikoci/rosetta@beta     # pinned to the beta stage's latest
+bunx @tikoci/rosetta@rc       # pinned to the rc stage's latest
+```
+
+`bunx @tikoci/rosetta` (no tag) and `bunx @tikoci/rosetta@latest` always resolve to the default, non-prerelease channel — publishing a prerelease never moves `latest`.
+
+> **Dist-tags, not semver ranges.** A version range like `^0.11.0-alpha` is **not** equivalent to a dist-tag. npm's prerelease range matching only spans the exact `[major,minor,patch]` tuple written in the range, so it stops tracking new prereleases the moment a patch/minor bump happens. `@next`/`@alpha`/`@beta`/`@rc` are the actual "follow forever" mechanism — use those, not a range, to stay on a moving prerelease channel.
+
 ### Configure your MCP client
 
 <details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/rosetta",
-  "version": "0.10.0",
+  "version": "0.11.0-alpha.87",
   "description": "RouterOS documentation as SQLite FTS5 — RAG search + command glossary via MCP",
   "type": "module",
   "license": "MIT",

package/src/db.ts

@@ -81,6 +81,16 @@ export function initDb() {
     html_file    TEXT NOT NULL
   );`);
 
+  // Migration: add rosetta_id (H7 Option 2 — see briefings/B-0012, "Identity / rosetta-id
+  // design"). NULL for legacy Confluence-sourced rows (they keep their numeric `id` as the
+  // only identifier); populated for Docusaurus-sourced rows extracted by extract-docusaurus.ts.
+  // A UNIQUE index (not a column constraint) so multiple NULLs are allowed side by side.
+  const pageCols = db.prepare("PRAGMA table_info(pages)").all() as Array<{ name: string }>;
+  if (!pageCols.some((c) => c.name === "rosetta_id")) {
+    db.run("ALTER TABLE pages ADD COLUMN rosetta_id TEXT;");
+  }
+  db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_pages_rosetta_id ON pages(rosetta_id) WHERE rosetta_id IS NOT NULL;");
+
   db.run(`CREATE VIRTUAL TABLE IF NOT EXISTS pages_fts USING fts5(
     title, path, text, code,
     content=pages,

package/src/eval/retrieval.ts

@@ -25,6 +25,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { searchAll } from "../query.ts";
+import { deriveRosettaId } from "../rosetta-id.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -49,7 +50,10 @@ type GoldenQuery = {
   id: string;
   query: string;
   shape: Shape;
-  expected_pages?: number[];
+  /** Stable identity for Docusaurus-sourced pages — see src/rosetta-id.ts. `pages.id` is NOT
+   * stable across extraction runs (extract-docusaurus.ts re-mints it as a fresh rowid every
+   * time), so golden-set expectations must pin to rosetta_id, not the numeric id. */
+  expected_rosetta_ids?: string[];
   /** "any" (default): top-k contains ≥1 expected page → recall=1. "all": classical subset recall. */
   match_mode?: MatchMode;
   expected_classified?: ExpectedClassified;
@@ -85,7 +89,7 @@ type QueryResult = {
   topics_ok: boolean;
   skipped: boolean;
   skip_reason?: string;
-  top_pages: { id: number; title: string }[];
+  top_pages: { id: number; title: string; rosetta_id: string }[];
   classified_actual: Record<string, unknown>;
   notes: string[];
 };
@@ -152,15 +156,15 @@ function evalQuery(q: GoldenQuery, commandsCount: number, k = 5): QueryResult {
   }
 
   const resp = searchAll(q.query, k * 2);
-  const topIds = resp.pages.slice(0, k).map((p) => p.id);
-  const top3Ids = resp.pages.slice(0, 3).map((p) => p.id);
+  const topRosettaIds = resp.pages.slice(0, k).map((p) => deriveRosettaId(p.url));
+  const top3RosettaIds = resp.pages.slice(0, 3).map((p) => deriveRosettaId(p.url));
 
   // Recall semantics — default "any" (≥1 expected page in top-k counts as full recall).
   // For QA-style retrieval we usually only need ONE good answer; classical subset recall
   // ("all" mode) is opt-in for cases where coverage actually matters.
-  const expected = q.expected_pages ?? [];
+  const expected = q.expected_rosetta_ids ?? [];
   const mode: MatchMode = q.match_mode ?? "any";
-  const recallFor = (ids: number[]): number => {
+  const recallFor = (ids: string[]): number => {
     if (expected.length === 0) return 1;
     if (mode === "any") {
       return expected.some((id) => ids.includes(id)) ? 1 : 0;
@@ -168,14 +172,14 @@ function evalQuery(q: GoldenQuery, commandsCount: number, k = 5): QueryResult {
     // "all" mode: classical subset recall
     return expected.filter((id) => ids.includes(id)).length / expected.length;
   };
-  const recall_at_5 = recallFor(topIds);
-  const recall_at_3 = recallFor(top3Ids);
+  const recall_at_5 = recallFor(topRosettaIds);
+  const recall_at_3 = recallFor(top3RosettaIds);
 
   // Reciprocal rank: 1/rank of first expected page in top-k. 0 if none found.
   let rr = 0;
   if (expected.length > 0) {
-    for (let i = 0; i < topIds.length; i++) {
-      if (expected.includes(topIds[i] as number)) {
+    for (let i = 0; i < topRosettaIds.length; i++) {
+      if (expected.includes(topRosettaIds[i] as string)) {
         rr = 1 / (i + 1);
         break;
       }
@@ -220,7 +224,7 @@ function evalQuery(q: GoldenQuery, commandsCount: number, k = 5): QueryResult {
   }
 
   if (expected.length > 0 && recall_at_5 === 0) {
-    notes.push(`top-${k} pages: ${topIds.join(", ")} (none of expected ${expected.join(", ")})`);
+    notes.push(`top-${k} pages: ${topRosettaIds.join(", ")} (none of expected ${expected.join(", ")})`);
   }
 
   return {
@@ -234,7 +238,7 @@ function evalQuery(q: GoldenQuery, commandsCount: number, k = 5): QueryResult {
     related_ok,
     topics_ok,
     skipped: false,
-    top_pages: resp.pages.slice(0, 5).map((p) => ({ id: p.id, title: p.title })),
+    top_pages: resp.pages.slice(0, 5).map((p) => ({ id: p.id, title: p.title, rosetta_id: deriveRosettaId(p.url) })),
     classified_actual: { ...resp.classified },
     notes,
   };

package/src/extract-docusaurus.test.ts

@@ -0,0 +1,251 @@
+// Force in-memory DB before importing extract-docusaurus.ts (which transitively imports
+// db.ts) — same guard as extract-dude.test.ts. See BACKLOG.md "Test DB-leak guards".
+process.env.DB_PATH = ":memory:";
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const {
+  isInScopeDocsUrl,
+  parseProperties,
+  parseCallouts,
+  parseSections,
+  parsePage,
+  resolveDescriptionLinks,
+  extractCodeBlocks,
+  slugify,
+  parseLlmsTxtInScopeCount,
+  markdownUrlFor,
+} = await import("./extract-docusaurus.ts");
+
+const FIXTURES_DIR = join(import.meta.dirname, "..", "fixtures", "docusaurus");
+const read = (name: string) => readFileSync(join(FIXTURES_DIR, name), "utf-8");
+
+const dhcpMd = read("dhcp.md");
+const smsMd = read("sms.md");
+const dot1xMd = read("dot1x.md");
+const addressListsMd = read("address-lists.md");
+
+const DHCP_URL = "https://manual.mikrotik.com/docs/network-management/dhcp";
+const SMS_URL = "https://manual.mikrotik.com/docs/mobile-networking/sms";
+const ADDRESS_LISTS_URL = "https://manual.mikrotik.com/docs/firewall-and-quality-of-service/firewall/address-lists";
+
+describe("isInScopeDocsUrl", () => {
+  test("accepts ordinary /docs prose pages", () => {
+    expect(isInScopeDocsUrl(DHCP_URL)).toBeTrue();
+    expect(isInScopeDocsUrl("/docs/network-management/dhcp")).toBeTrue();
+  });
+
+  test("rejects CLI Reference pages", () => {
+    expect(isInScopeDocsUrl("https://manual.mikrotik.com/docs/cli-reference/ip/address")).toBeFalse();
+  });
+
+  test("rejects tag-index pages, including the bare tags root (no trailing slash — real 404 live)", () => {
+    expect(isInScopeDocsUrl("https://manual.mikrotik.com/docs/tags/dhcp")).toBeFalse();
+    expect(isInScopeDocsUrl("https://manual.mikrotik.com/docs/tags")).toBeFalse();
+  });
+
+  test("rejects non-/docs sections (hardware, changelog, blog)", () => {
+    expect(isInScopeDocsUrl("https://manual.mikrotik.com/hardware/rb5009")).toBeFalse();
+    expect(isInScopeDocsUrl("https://manual.mikrotik.com/changelog/changelog-2026-05-25")).toBeFalse();
+    expect(isInScopeDocsUrl("https://manual.mikrotik.com/blog/news130")).toBeFalse();
+  });
+});
+
+describe("markdownUrlFor", () => {
+  test("appends .md to an ordinary leaf page URL", () => {
+    expect(markdownUrlFor(DHCP_URL)).toBe(`${DHCP_URL}.md`);
+  });
+
+  test("appends index.md (not .md) to a category/index page URL — real 404 otherwise", () => {
+    // Confirmed live 2026-07-07: .../accounting.md 404s, .../accounting/index.md is 200.
+    const categoryUrl = "https://manual.mikrotik.com/docs/authentication-authorization-accounting/";
+    expect(markdownUrlFor(categoryUrl)).toBe(`${categoryUrl}index.md`);
+  });
+});
+
+describe("slugify", () => {
+  test("produces a github-slugger-style anchor", () => {
+    expect(slugify("DHCP Client")).toBe("dhcp-client");
+    expect(slugify("Read-only properties")).toBe("read-only-properties");
+  });
+});
+
+describe("parseProperties — dhcp.md (real malformed-emphasis case, B-0012 H4)", () => {
+  const properties = parseProperties(dhcpMd);
+
+  test("finds a realistic number of properties across the whole page", () => {
+    // dhcp.md has multiple "### Properties"/"#### Read-only properties" tables
+    // (client + server + DHCPv6). Anchor on a floor, not an exact count, so a future
+    // MikroTik doc edit doesn't spuriously fail this test the way an exact-count
+    // assertion would — matching the "durable, trend toward catching real drift" goal.
+    expect(properties.length).toBeGreaterThan(50);
+  });
+
+  test("flags check-gateway's malformed bold/italic collision, not just any property", () => {
+    const checkGateway = properties.find((p) => p.name === "check-gateway");
+    expect(checkGateway).toBeDefined();
+    expect(checkGateway?.malformedEmphasis).toBeTrue();
+    expect(checkGateway?.defaultVal).toBe("none");
+  });
+
+  test("parses a well-formed property cleanly (not flagged malformed)", () => {
+    const disabled = properties.find((p) => p.name === "disabled" && p.section === "Properties");
+    expect(disabled).toBeDefined();
+    expect(disabled?.malformedEmphasis).toBeFalse();
+    expect(disabled?.defaultVal).toBe("yes");
+    expect(disabled?.rawType).toContain("yes");
+  });
+
+  test("attributes properties to the nearest preceding heading as section", () => {
+    const readOnly = properties.find((p) => p.section === "Read-only properties");
+    expect(readOnly).toBeDefined();
+  });
+
+  test("leaves the relative link target as-is at the parseProperties layer (resolution happens in parsePage)", () => {
+    const useDns = properties.find((p) => p.name === "use-peer-dns");
+    expect(useDns?.description).toContain("./dhcp.md#dhcp-server");
+  });
+});
+
+describe("parseProperties — sms.md (real 'Parameter' header spelling, not 'Property')", () => {
+  test("recognizes the 'Parameter' header spelling used on sms.md", () => {
+    const properties = parseProperties(smsMd);
+    expect(properties.length).toBeGreaterThan(5);
+    expect(properties.some((p) => p.name === "phone-number")).toBeTrue();
+  });
+
+  test("handles an empty Default value without crashing or eating the next cell", () => {
+    const properties = parseProperties(smsMd);
+    const smsc = properties.find((p) => p.name === "smsc");
+    expect(smsc).toBeDefined();
+    expect(smsc?.defaultVal).toBeNull();
+  });
+});
+
+describe("parseProperties — address-lists.md (no property table at all)", () => {
+  test("returns an empty array rather than a false-positive match", () => {
+    expect(parseProperties(addressListsMd)).toEqual([]);
+  });
+});
+
+describe("parseCallouts — dot1x.md (real live :::: fenced admonitions)", () => {
+  const callouts = parseCallouts(dot1xMd);
+
+  test("finds every :::: warning block on the page", () => {
+    expect(callouts.length).toBe(4);
+    expect(callouts.every((c) => c.type === "warning")).toBeTrue();
+  });
+
+  test("captures real callout content, not an empty fence", () => {
+    expect(callouts[0].content).toContain("not supported on SMIPS devices");
+  });
+});
+
+describe("parseCallouts — address-lists.md (no admonitions)", () => {
+  test("returns an empty array", () => {
+    expect(parseCallouts(addressListsMd)).toEqual([]);
+  });
+});
+
+describe("parseSections", () => {
+  test("skips the duplicated title H1 (real quirk: raw .md repeats '# Title' after the summary blockquote)", () => {
+    const sections = parseSections(dot1xMd, "Dot1X");
+    const topLevel = sections.filter((s) => s.level === 1);
+    expect(topLevel.length).toBe(0); // both H1 occurrences are the title; neither should mint a section
+  });
+
+  test("splits on h1-h3 but folds deeper headings into the enclosing section's text", () => {
+    const sections = parseSections(dhcpMd, "DHCP");
+    const summary = sections.find((s) => s.heading === "Summary");
+    expect(summary).toBeDefined();
+    expect(summary?.level).toBe(3);
+  });
+
+  test("de-duplicates colliding anchor ids within a page", () => {
+    // dhcp.md has more than one "Example"-style heading across its DHCP Client /
+    // DHCPv6 Client / DHCP Server subsections at different heading levels.
+    const sections = parseSections(dhcpMd, "DHCP");
+    const anchors = sections.map((s) => s.anchorId);
+    expect(new Set(anchors).size).toBe(anchors.length);
+  });
+
+  test("a page whose only headings are the duplicated title yields zero sections (content stays in page text)", () => {
+    // address-lists.md has no h2/h3 at all — both its headings are the "Address-lists"
+    // title duplicate, so both get dropped. Matches extract-html.ts's own behavior for
+    // Confluence pages with no id-bearing headings: sections == [], full text elsewhere.
+    const sections = parseSections(addressListsMd, "Address-lists");
+    expect(sections).toEqual([]);
+  });
+});
+
+describe("extractCodeBlocks", () => {
+  test("extracts fenced ```ros blocks and records the language", () => {
+    const { code, codeLang } = extractCodeBlocks(addressListsMd);
+    expect(code).toContain("/ip/firewall/address-list/add");
+    expect(codeLang).toBe("ros");
+  });
+});
+
+describe("resolveDescriptionLinks", () => {
+  test("leaves absolute links and same-page anchors untouched", () => {
+    const desc = "See [external](https://example.com/x) and [here](#section).";
+    expect(resolveDescriptionLinks(desc, DHCP_URL)).toBe(desc);
+  });
+
+  test("rewrites a relative .md link to a live manual.mikrotik.com URL", () => {
+    const desc = "See [gateway reachability](../user-guides/routing-and-networking-protocols/routing-decision.md).";
+    const resolved = resolveDescriptionLinks(desc, DHCP_URL);
+    expect(resolved).toBe(
+      "See [gateway reachability](https://manual.mikrotik.com/docs/user-guides/routing-and-networking-protocols/routing-decision).",
+    );
+  });
+});
+
+describe("parsePage — end-to-end shape", () => {
+  test("derives rosetta_id, slug, path, and depth from the page URL", () => {
+    const page = parsePage(dhcpMd, DHCP_URL);
+    expect(page.rosettaId).toBe("docs/network-management/dhcp");
+    expect(page.slug).toBe("dhcp");
+    expect(page.path).toBe("docs > network-management > dhcp");
+    expect(page.depth).toBe(3);
+  });
+
+  test("every property on a real page round-trips through parsePage with resolved links", () => {
+    const page = parsePage(dhcpMd, DHCP_URL);
+    expect(page.properties.length).toBeGreaterThan(50);
+    expect(page.properties.filter((p) => p.malformedEmphasis).length).toBeGreaterThanOrEqual(1);
+
+    const useDns = page.properties.find((p) => p.name === "use-peer-dns");
+    expect(useDns?.description).toContain("https://manual.mikrotik.com/docs/network-management/dhcp#dhcp-server");
+    expect(useDns?.description).not.toContain(".md");
+  });
+
+  test("a short page with no properties/callouts still produces a valid page shape", () => {
+    const page = parsePage(addressListsMd, ADDRESS_LISTS_URL);
+    expect(page.title).toBe("Address-lists");
+    expect(page.properties).toEqual([]);
+    expect(page.callouts).toEqual([]);
+    expect(page.sections).toEqual([]); // see parseSections' dedicated test for why
+    expect(page.wordCount).toBeGreaterThan(0);
+    expect(page.text).toContain("dynamic address list");
+  });
+
+  test("sms.md's 'Parameter'-spelled table still surfaces via parsePage", () => {
+    const page = parsePage(smsMd, SMS_URL);
+    expect(page.properties.some((p) => p.name === "phone-number")).toBeTrue();
+  });
+});
+
+describe("parseLlmsTxtInScopeCount (B-0012 H8, V-docusaurus-docs-count)", () => {
+  test("counts only in-scope /docs entries, excluding CLI Reference and tags", () => {
+    const llmsTxt = [
+      "- [DHCP](https://manual.mikrotik.com/docs/network-management/dhcp.md): desc",
+      "- [ip/address](https://manual.mikrotik.com/docs/cli-reference/ip/address.md): desc",
+      "- [tag](https://manual.mikrotik.com/docs/tags/dhcp.md): desc",
+      "- [Dot1X](https://manual.mikrotik.com/docs/authentication-authorization-accounting/dot1x.md): desc",
+    ].join("\n");
+    expect(parseLlmsTxtInScopeCount(llmsTxt)).toBe(2);
+  });
+});