CLI-Reference DB overlay: lossless ETL, inspect crosswalks, export (#124)

[mobileskyfi]

Implements the CLI-Reference DB overlay from #124 (design: briefings/B-0016-cli-reference-overlay-design.md). DB / ETL / export only — no MCP/TUI/query-behavior changes (those stay in #25). Every number below was reproduced against the v0.11.1 release DB during development.

What's here

1. DB schema (v11) — cliref_pages/entries/fields/flags source tables (occurrence identity, byte-exact source Markdown + SHA-256, no path on fields), cliref_entry_schema_links stored crosswalk, cliref_field_inspect_links view, and schema_nodes.inspect_type (preserves raw path/dir/cmd/arg; type still normalizes path→dir).
2. extract-schema.ts — stores inspect_type; roundtrip test proves the path→dir divergence.
3. src/extract-cliref.ts — source-faithful extractor. 228 pages → 1,051 entries → 10,118 fields → 948 flags; asserts parsed == source markers, fails loud on unknown labels, guards fenced-code false headings, keeps verbatim descriptions (no whitespace flattening).
4. src/link-cliref.ts + fast view — resolves entries exact / single-internal-segment alias / manual-only: 907 exact, 24 alias, 120 manual-only (matches the experiment exactly). View rewritten as a UNION with a (parent_path, name) index: ~200ms (was >14s).
5. rosetta export — six cli-reference/*.tsv + byte-exact source/<slug>.md. fields.tsv uses entry_source_path, never field_path; zero-to-many lives in field-inspect-links.tsv.
6. Tests + fixture + build wiring + docs — make extract-cliref/link-cliref targets added; extract-full orders the link pass after schema_nodes population; CHANGELOG, VALIDATION, MANUAL, DESIGN updated.

Key modeling decisions (from the second-pass review)

• Entries have paths; fields don't. A settable field maps to zero-to-many inspect coordinates (5,124 of 6,171 settable fields link in the audited 7.23.2 tree; certificate.name → 7). cliref_fields has a name + entry FK. Read-only fields are excluded from the inspect-input view because a same-name input is not proof of an output-field identity.
• Store the entry link, compute the field links. The entry link carries the non-derivable exact/alias decision; field links are a view so the version-less overlay never pins to a versioned schema_nodes snapshot.
• Auditable aliasing. Only one of the 19 documented internal module segments may be dropped (never root/leaf); match_detail records it; unknown or ambiguous shapes → manual-only. Source paths are never rewritten.

Verification

• Review pass: 1032 tests passed; the stdio integration also passes when pointed at the current schema-v11 test DB. Biome, tsc, markdownlint, and cspell are clean.
• Export validated on a full build: 228/1051/10118/948 rows, entry-links 931 (907+24), field-links 13,036 for settable fields and 0 for read-only fields, all 228 source md sha256-exact, every TSV round-trips through parseTsv.

Known GAPs (honest debt, in VALIDATION.md, tracked by #127)

• V-cliref-link-drift — the linker now allowlists the 19 known internal segments, so a new alias-shaped mismatch stays manual-only; CLI-Reference overlay: CI publish wiring + close V-cliref-link-drift / V-cliref-db-integrity gaps #127 still needs the committed 907/24/120 baseline gate.
• V-cliref-db-integrity — full-DB FK/integrity/enum/orphan checks validated manually during development, not yet a committed CI gate (CLI-Reference overlay: CI publish wiring + close V-cliref-link-drift / V-cliref-db-integrity gaps #127).
• CI wiring — Makefile targets are added and extract-full has the correct ordering; CLI-Reference overlay: CI publish wiring + close V-cliref-link-drift / V-cliref-db-integrity gaps #127 tracks placing extract-cliref + link-cliref in release.yml/qa.yml. Until then, released DBs do not carry the overlay.
• Out of scope by design: raw_type structured parsing; the CLI-Reference argument-type glossary landing page (prose, no command entries) — both noted as follow-ups.

Closes #124.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a CLI Reference overlay with parsed pages, entries, fields, flags, and byte-exact source markdown for deterministic exports.
  • Exports can now include a new cli-reference/ subtree and corresponding manifest disclosures when the overlay is present.
  • Added build steps to extract and link CLI Reference overlay data.
  • Preserves original CLI classification alongside normalized schema typing for lossless matching.
• Documentation
  • Updated guides for overlay parsing, identity rules, and export/link semantics.
• Validation / Tests
  • Added CLI Reference validation invariants and export/link integration tests.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 51a7a7cd-9449-49fe-b310-ecdb53ecb705

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Changes

The PR adds a lossless CLI-Reference overlay, preserves raw inspect node classes, links entries to schema nodes, extends extraction and export pipelines, and adds parser, linking, schema, and export validation.

CLI-Reference overlay

Layer / File(s)	Summary
Schema and inspect-type contracts src/db.ts, src/extract-schema.ts, src/paths.ts, src/schema-roundtrip.test.ts, DESIGN.md, briefings/...	Adds overlay tables, a field-link view, schema version 11, and schema_nodes.inspect_type preservation alongside normalized types.
CLI-Reference extraction and parsing src/extract-cliref.ts, src/extract-cliref.test.ts, Makefile, MANUAL.md, VALIDATION.md, project-words.txt	Discovers or loads cached Markdown, parses and stores entries, fields, flags, metadata, ancestry, and source hashes with reconciliation checks.
Entry and field inspect linking src/link-cliref.ts, src/link-cliref.test.ts, src/db.ts, VALIDATION.md	Resolves exact or unambiguous aliases into stored entry links and computes field-to-inspect mappings through the SQLite view.
Overlay export and pipeline wiring src/export.ts, src/export.test.ts, Makefile, MANUAL.md, CHANGELOG.md	Adds conditional CLI-Reference TSV and byte-exact Markdown exports, manifest disclosures, pruning ownership, and extraction pipeline prerequisites.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Build as Makefile
  participant Extractor as extract-cliref
  participant Database as SQLite
  participant Linker as link-cliref
  participant Exporter as export
  Build->>Extractor: fetch or read cached Markdown
  Extractor->>Database: store pages, entries, fields, and flags
  Linker->>Database: resolve and store entry schema links
  Exporter->>Database: read overlay datasets and field-inspect view
  Exporter->>Build: publish TSV and source Markdown

Loading

Possibly related issues

• CLI-Reference overlay: CI publish wiring + close V-cliref-link-drift / V-cliref-db-integrity gaps #127 — Covers deferred CI wiring and integrity/drift gates for the CLI-Reference overlay introduced here.

Possibly related PRs

• tikoci/rosetta#103 — Provides the DB-only export pipeline extended here with CLI-Reference datasets.
• tikoci/rosetta#110 — Shares the export manifest ownership and pruning logic extended for overlay artifacts.

Suggested labels: area:docusaurus

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.73% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main CLI-Reference overlay, lossless ETL, and export work.
Linked Issues check	✅ Passed	The changes cover the overlay schema, inspect_type preservation, crosswalks, computed field links, export, validation, and docs required by #124.
Out of Scope Changes check	✅ Passed	No out-of-scope MCP, TUI, or query changes are present; the added dictionary terms support the new CLI-Reference content.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cliref-overlay-124

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Implements the CLI-Reference DB overlay (issue #124) as a DB/ETL/export-only addition: new cliref_* source-faithful tables, a stored entry→inspect crosswalk, a computed field→inspect view, export artifacts, and associated tests/docs. This extends Rosetta’s SQLite corpus without changing MCP/TUI/query behavior (those remain scoped to #25).

Changes:

• Adds schema v11: cliref_pages/cliref_entries/cliref_fields/cliref_flags, stored cliref_entry_schema_links, computed cliref_field_inspect_links view, and new schema_nodes.inspect_type.
• Adds new extract/link pipelines (src/extract-cliref.ts, src/link-cliref.ts) plus fixtures/tests proving source fidelity, link policy, and inspect_type roundtrip behavior.
• Extends rosetta export to emit cli-reference/*.tsv plus byte-exact cli-reference/source/<slug>.md, and updates docs/validation/changelog accordingly.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
VALIDATION.md	Adds V-* rows for CLI-Reference parse reconciliation, source roundtrip/export contract, and inspect_type preservation; records known gaps.
src/schema-roundtrip.test.ts	Updates test schema and adds coverage for inspect_type vs normalized type behavior.
src/paths.ts	Bumps SCHEMA_VERSION to 11 and documents the v11 schema intent.
src/link-cliref.ts	Adds entry-level linker that populates cliref_entry_schema_links using exact/alias/manual-only rules.
src/link-cliref.test.ts	Tests alias policy and validates the field-link view behavior against a minimal schema tree.
src/extract-schema.ts	Plumbs raw inspect node class into inspectType and stores it as schema_nodes.inspect_type.
src/extract-cliref.ts	Adds CLI-Reference extractor that caches/fetches Markdown, parses entries/fields/flags losslessly, and stores into cliref_* tables.
src/extract-cliref.test.ts	Adds fixture-driven tests for slug filtering, parsing correctness, fence-guard behavior, and fail-loud parsing.
src/export.ts	Adds conditional CLI-Reference export datasets and raw source page emission + disclosures.
src/export.test.ts	Adds export test ensuring six TSVs + source md are emitted and contract details (e.g., entry_source_path not field_path).
src/db.ts	Adds schema v11 tables/view and indexes; adds inspect_type column migration logic and view indexes.
project-words.txt	Adds new tokens used in tests/fixtures (e.g., vcmd, ztname).
MANUAL.md	Documents CLI-Reference overlay tables, link pass, and export outputs.
Makefile	Adds extract-cliref/link-cliref targets and wires them into extract / extract-full.
fixtures/cli-reference/sample.md	Adds a representative CLI-Reference MD fixture to validate parsing and preservation behavior.
DESIGN.md	Documents the CLI-Reference identity model, stored vs computed crosswalk, aliasing policy, and inspect_type rationale.
CHANGELOG.md	Adds [Unreleased] entries describing the overlay and schema version bump.
briefings/B-0016-cli-reference-overlay-design.md	Updates design briefing to reflect accepted schema (stored entry link + computed field view).

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Makefile`:
- Around line 136-138: The extract target must run the schema_nodes-producing
step before link-cliref. Update the extract dependency list to include
extract-all-versions, or otherwise place link-cliref after the schema import
dependency, while preserving the existing extract-full behavior and target
ordering.

In `@src/extract-cliref.ts`:
- Around line 319-339: Guard both field-marker matching and `<ArgTable>` block
detection with `!inFence`, so fenced transcript content remains prose. Update
the checks around the field regex and `<ArgTable ` branch, while preserving
their existing parsing behavior outside fenced sections.
- Around line 92-110: Update loadTocNames so FROM_CACHE never enters the
network-fetch branch when the cached _llms.txt file is absent; return the
appropriate empty/no-data result instead, matching fetchPage’s existing
FROM_CACHE behavior while preserving normal fetching when caching is not
requested.

In `@src/link-cliref.test.ts`:
- Around line 59-98: Update the test’s seed setup to initialize the in-memory
database through the project’s real initDb/schema-setup path instead of manually
creating cliref_field_inspect_links and duplicating its SQL. Retain only the
minimal seed data required for the assertions, including any FK-adjacent tables,
and ensure the test continues exercising the shipped view definition.

In `@src/link-cliref.ts`:
- Around line 52-55: Update pickNode to return no candidate when nodes does not
contain a node matching preferredType(sourceType), rather than falling back to
nodes[0]. Adjust resolveEntry to treat that null result like no candidate at the
path: continue alias search or remain manual-only for the exact branch,
preventing links to nodes whose type conflicts with the entry source type.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a5fe72fe-93d1-4561-a678-a3b15d8b9e1c

📥 Commits

Reviewing files that changed from the base of the PR and between ce97791 and 7c72eab.

⛔ Files ignored due to path filters (1)

• fixtures/cli-reference/sample.md is excluded by !fixtures/**

📒 Files selected for processing (17)

• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• Makefile
• VALIDATION.md
• briefings/B-0016-cli-reference-overlay-design.md
• project-words.txt
• src/db.ts
• src/export.test.ts
• src/export.ts
• src/extract-cliref.test.ts
• src/extract-cliref.ts
• src/extract-schema.ts
• src/link-cliref.test.ts
• src/link-cliref.ts
• src/paths.ts
• src/schema-roundtrip.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: copilot-pull-request-reviewer
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (12)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use Bun and TypeScript, including Bun-native runtime APIs such as bun:sqlite, Bun.serve, and bunx.

Rosetta uses Bun and TypeScript; prefer bun, bun test, and make verify where applicable, rather than Node/npm-oriented substitutes.

Files:

• src/link-cliref.test.ts
• src/paths.ts
• src/extract-cliref.test.ts
• src/export.test.ts
• src/link-cliref.ts
• src/extract-schema.ts
• src/db.ts
• src/schema-roundtrip.test.ts
• src/extract-cliref.ts
• src/export.ts

src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Rosetta is read-only documentation/schema context and must not connect to or modify a user's router.

Files:

• src/link-cliref.test.ts
• src/paths.ts
• src/extract-cliref.test.ts
• src/export.test.ts
• src/link-cliref.ts
• src/extract-schema.ts
• src/db.ts
• src/schema-roundtrip.test.ts
• src/extract-cliref.ts
• src/export.ts

**/*.{ts,tsx,md}

📄 CodeRabbit inference engine (AGENTS.md)

Keep the attribution boundary visible when community RouterOS skills surface, because they are supplemental rather than official MikroTik documentation.

Files:

• src/link-cliref.test.ts
• src/paths.ts
• VALIDATION.md
• src/extract-cliref.test.ts
• src/export.test.ts
• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• src/link-cliref.ts
• src/extract-schema.ts
• src/db.ts
• briefings/B-0016-cli-reference-overlay-design.md
• src/schema-roundtrip.test.ts
• src/extract-cliref.ts
• src/export.ts

*

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Keep this Copilot instructions file short; put substantive rules in narrow instruction files under .github/instructions/*.instructions.md.

Files:

• project-words.txt
• VALIDATION.md
• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• Makefile

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Keep each project documentation file limited to its canonical role; prefer the documented canonical home instead of creating a new top-level Markdown file.
Do not duplicate content from this routing index; move operational detail, schema blocks, or long rule lists to their canonical documentation or instruction files.
Apply the repository's Markdown linting and fenced-code conventions, while excluding LLM instruction files where the repository explicitly requires that exclusion.

Files:

• VALIDATION.md
• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• briefings/B-0016-cli-reference-overlay-design.md

VALIDATION.md

📄 CodeRabbit inference engine (CLAUDE.md)

Document load-bearing invariants and how CI proves them in VALIDATION.md.

Files:

• VALIDATION.md

CHANGELOG.md

📄 CodeRabbit inference engine (CLAUDE.md)

Record user-visible shipped changes in CHANGELOG.md under [Unreleased] or release sections.

Files:

• CHANGELOG.md

DESIGN.md

📄 CodeRabbit inference engine (CLAUDE.md)

Store durable project rationale, data-source provenance, and architecture tradeoffs in DESIGN.md.

Read DESIGN.md when changing retrieval, MCP/TUI behavior, data sources, extraction, skills, command validation, or Docusaurus migration work.

Files:

• DESIGN.md

MANUAL.md

📄 CodeRabbit inference engine (CLAUDE.md)

Store installation, operations, release or re-extraction procedures, and schema reference material in MANUAL.md.

Files:

• MANUAL.md

{README.md,MANUAL.md,src/setup.ts}

📄 CodeRabbit inference engine (AGENTS.md)

Keep public client setup snippets aligned across README.md, src/setup.ts, and MANUAL.md, including codex mcp add rosetta -- bunx @tikoci/rosetta``.

Files:

• MANUAL.md

src/db.ts

📄 CodeRabbit inference engine (CLAUDE.md)

When touching src/db.ts, follow both the Bun/runtime conventions and the database-specific instructions.

Files:

• src/db.ts

briefings/B-*.md

📄 CodeRabbit inference engine (CLAUDE.md)

Store grounded research and decision support in briefings/B-*.md.

Files:

• briefings/B-0016-cli-reference-overlay-design.md

🪛 ast-grep (0.44.1)

src/extract-cliref.ts

[warning] 224-224: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(\\b${n}="([\\s\\S]*?)")
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)

🪛 GitHub Check: CodeQL

src/extract-cliref.ts

[failure] 120-120: Potential file system race condition
The file may have changed since it was checked.

---

[warning] 102-102: Network data written to file
Write to file system depends on Untrusted data.

---

[warning] 120-120: Network data written to file
Write to file system depends on Untrusted data.

🪛 LanguageTool

DESIGN.md

[style] ~213-~213: To elevate your writing, try using more formal phrasing here.
Context: ...h/dir/cmd/argclass whiletype` keeps normalizing, so the crosswalk can reason about the ...

(CONTINUE_TO_VB)

🔇 Additional comments (16)

src/export.ts (1)

448-603: LGTM!

Also applies to: 733-749, 789-790, 819-823, 837-837, 850-854

src/export.test.ts (1)

552-600: LGTM!

src/db.ts (1)

465-502: LGTM!

Also applies to: 512-621

src/extract-schema.ts (1)

53-54: LGTM!

Also applies to: 105-105, 378-382, 396-396

src/paths.ts (1)

135-141: LGTM!

src/schema-roundtrip.test.ts (1)

34-53: LGTM!

Also applies to: 195-207, 284-292

CHANGELOG.md (1)

25-33: LGTM!

project-words.txt (1)

135-135: LGTM!

Also applies to: 444-444, 480-481

DESIGN.md (1)

201-216: 📐 Maintainability & Code Quality | ⚡ Quick win

Figure mismatch: "4,161" vs the briefing's own table ("4,164").

Line 205 states 4,161 of 6,171 settable fields match 2–4 inspect nodes. briefings/B-0016-cli-reference-overlay-design.md's pre-existing table for the same metric says 4,164 (and the sum 1,177+822+4,164+8=6,171 checks out against that table). Pick one number and reconcile the other; see the consolidated comment for the paired site.

briefings/B-0016-cli-reference-overlay-design.md (2)

201-203: LGTM!

Also applies to: 272-273, 302-307, 351-372

---

225-254: 📐 Maintainability & Code Quality | ⚡ Quick win

Numeric discrepancy carried into DESIGN.md — see consolidated comment.

Line 245-246 says 4,161 of 6,171 settable fields match 2–4 inspect nodes; the file's own unchanged table (~line 176) puts that same bucket at 4,164. DESIGN.md line 205 then repeats the "4,161" figure. Reconcile the source-of-truth number.

src/extract-cliref.ts (1)

1-91: LGTM!

Also applies to: 112-317, 340-508

src/extract-cliref.test.ts (1)

1-116: LGTM!

MANUAL.md (2)

100-102: 📐 Maintainability & Code Quality | ⚡ Quick win

Stale "not yet ingested" claim left elsewhere in this file.

Line 118 (unchanged by this PR) still reads: CLI Reference "...not yet ingested — see B-0012's proposed follow-up tasks." That directly contradicts the new overlay description just added here. Update or remove line 118's parenthetical now that extract-cliref.ts/link-cliref.ts ingest it.

---

328-329: LGTM!

VALIDATION.md (1)

56-60: LGTM!

[mobileskyfi]

Independent DB/data-quality review complete. I do not see a need for structural rework after the follow-up commit ba067a0.

The source model is the right boundary for future consumers: occurrence-based pages/entries/fields/flags, exact source Markdown + hash, a stored non-derivable entry decision, and a computed field view that follows the current inspect snapshot. I ran a full cached extract → link → DB audit → export against the 7.23.2 release tree: 228 pages / 1,051 entries / 10,118 fields / 948 flags; 907 exact / 24 alias / 120 manual-only; clean SQLite integrity/FKs; all 228 source pages round-trip through export.

The review found and fixed four data-quality risks:

• The view previously emitted 108 links for 96 Read-only Argument rows merely because their names collided with inspect inputs. It now only maps settable Argument rows: 13,036 link rows across 5,124 fields, and zero read-only links.
• Alias discovery previously accepted any uniquely droppable internal segment. It now allowlists the 19 observed source artifacts, so an unknown future mismatch stays manual-only and is visible to the drift gate.
• A missing per-entry Type could be masked by a duplicate marker elsewhere, and cached discovery could silently omit a missing page. Both full live/offline runs now fail closed from the cached sitemap inventory; fenced examples are excluded from marker reconciliation.
• SQLite now enforces the raw inspect-type enum, source-order/line bounds, and exact-vs-alias match_detail consistency. I simulated the v10→v11 migration and verified invalid rows are rejected.

Tests cover the new read-only, unknown-alias, duplicate/missing-Type, and fenced-marker semantics. TypeScript/Biome/Markdown/cspell are clean; the full run passed 1,032 tests, and the stdio test passes when the isolated worktree is explicitly pointed at the schema-v11 test DB.

The remaining work is appropriately separate and now sharpened in #127: release/QA publish wiring, a committed 907/24/120 drift baseline, and full-artifact DB integrity checks (including the read-only=zero view invariant). Until that issue lands, released DBs still will not contain this overlay.

[mobileskyfi]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/extract-cliref.ts`:
- Around line 256-295: Update parseArgTable so each ArgTableRow requires
non-empty arg and typ attributes instead of converting missing values to empty
strings. Validate these attributes before pushing to entry.flags or
entry.fields, and throw a descriptive error including slug and rowLine when
either is absent; preserve the existing decoding and row-processing behavior for
valid rows.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 613acb95-aa3d-4ba6-859a-69e5a3382ec2

📥 Commits

Reviewing files that changed from the base of the PR and between ce97791 and 5704fcf.

⛔ Files ignored due to path filters (1)

• fixtures/cli-reference/sample.md is excluded by !fixtures/**

📒 Files selected for processing (17)

• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• Makefile
• VALIDATION.md
• briefings/B-0016-cli-reference-overlay-design.md
• project-words.txt
• src/db.ts
• src/export.test.ts
• src/export.ts
• src/extract-cliref.test.ts
• src/extract-cliref.ts
• src/extract-schema.ts
• src/link-cliref.test.ts
• src/link-cliref.ts
• src/paths.ts
• src/schema-roundtrip.test.ts

📜 Review details

🧰 Additional context used

📓 Path-based instructions (12)

*

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Keep this Copilot instructions file short; put substantive rules in narrow instruction files under .github/instructions/*.instructions.md.

Files:

• project-words.txt
• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• Makefile
• VALIDATION.md

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use Bun and TypeScript, including Bun-native runtime APIs such as bun:sqlite, Bun.serve, and bunx.

Rosetta uses Bun and TypeScript; prefer bun, bun test, and make verify where applicable, rather than Node/npm-oriented substitutes.

Files:

• src/paths.ts
• src/link-cliref.test.ts
• src/schema-roundtrip.test.ts
• src/export.test.ts
• src/extract-schema.ts
• src/link-cliref.ts
• src/export.ts
• src/extract-cliref.test.ts
• src/db.ts
• src/extract-cliref.ts

src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Rosetta is read-only documentation/schema context and must not connect to or modify a user's router.

Files:

• src/paths.ts
• src/link-cliref.test.ts
• src/schema-roundtrip.test.ts
• src/export.test.ts
• src/extract-schema.ts
• src/link-cliref.ts
• src/export.ts
• src/extract-cliref.test.ts
• src/db.ts
• src/extract-cliref.ts

**/*.{ts,tsx,md}

📄 CodeRabbit inference engine (AGENTS.md)

Keep the attribution boundary visible when community RouterOS skills surface, because they are supplemental rather than official MikroTik documentation.

Files:

• src/paths.ts
• src/link-cliref.test.ts
• src/schema-roundtrip.test.ts
• CHANGELOG.md
• DESIGN.md
• src/export.test.ts
• MANUAL.md
• VALIDATION.md
• src/extract-schema.ts
• src/link-cliref.ts
• src/export.ts
• src/extract-cliref.test.ts
• src/db.ts
• src/extract-cliref.ts
• briefings/B-0016-cli-reference-overlay-design.md

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Keep each project documentation file limited to its canonical role; prefer the documented canonical home instead of creating a new top-level Markdown file.
Do not duplicate content from this routing index; move operational detail, schema blocks, or long rule lists to their canonical documentation or instruction files.
Apply the repository's Markdown linting and fenced-code conventions, while excluding LLM instruction files where the repository explicitly requires that exclusion.

Files:

• CHANGELOG.md
• DESIGN.md
• MANUAL.md
• VALIDATION.md
• briefings/B-0016-cli-reference-overlay-design.md

CHANGELOG.md

📄 CodeRabbit inference engine (CLAUDE.md)

Record user-visible shipped changes in CHANGELOG.md under [Unreleased] or release sections.

Files:

• CHANGELOG.md

DESIGN.md

📄 CodeRabbit inference engine (CLAUDE.md)

Store durable project rationale, data-source provenance, and architecture tradeoffs in DESIGN.md.

Read DESIGN.md when changing retrieval, MCP/TUI behavior, data sources, extraction, skills, command validation, or Docusaurus migration work.

Files:

• DESIGN.md

MANUAL.md

📄 CodeRabbit inference engine (CLAUDE.md)

Store installation, operations, release or re-extraction procedures, and schema reference material in MANUAL.md.

Files:

• MANUAL.md

{README.md,MANUAL.md,src/setup.ts}

📄 CodeRabbit inference engine (AGENTS.md)

Keep public client setup snippets aligned across README.md, src/setup.ts, and MANUAL.md, including codex mcp add rosetta -- bunx @tikoci/rosetta``.

Files:

• MANUAL.md

VALIDATION.md

📄 CodeRabbit inference engine (CLAUDE.md)

Document load-bearing invariants and how CI proves them in VALIDATION.md.

Files:

• VALIDATION.md

src/db.ts

📄 CodeRabbit inference engine (CLAUDE.md)

When touching src/db.ts, follow both the Bun/runtime conventions and the database-specific instructions.

Files:

• src/db.ts

briefings/B-*.md

📄 CodeRabbit inference engine (CLAUDE.md)

Store grounded research and decision support in briefings/B-*.md.

Files:

• briefings/B-0016-cli-reference-overlay-design.md

🪛 ast-grep (0.44.1)

src/extract-cliref.ts

[warning] 264-264: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(\\b${n}="([\\s\\S]*?)")
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)

🪛 GitHub Check: CodeQL

src/extract-cliref.ts

[warning] 112-112: Network data written to file
Write to file system depends on Untrusted data.

---

[warning] 136-136: Network data written to file
Write to file system depends on Untrusted data.

---

[warning] 160-160: Network data written to file
Write to file system depends on Untrusted data.

🪛 LanguageTool

DESIGN.md

[style] ~213-~213: To elevate your writing, try using more formal phrasing here.
Context: ...h/dir/cmd/argclass whiletype` keeps normalizing, so the crosswalk can reason about the ...

(CONTINUE_TO_VB)

🔇 Additional comments (22)

src/db.ts (4)

52-71: LGTM!

---

497-497: 🩺 Stability & Availability

Confirm the inspect_type CHECK is meant to hard-fail on a new inspect class.

inspect_type is constrained to path|dir|cmd|arg, but the normalized type column (extract-schema.ts) is unconstrained. walk() sets inspectType = nodeType (raw _type). If RouterOS ever emits a new class, type stores it silently while this INSERT fails the CHECK, aborting extraction. If that crash-early asymmetry is intended, ignore; otherwise widen or drop the constraint.

---

519-532: LGTM!

---

542-637: LGTM!

src/extract-schema.ts (1)

53-54: LGTM!

Also applies to: 105-105, 378-382, 396-396

src/paths.ts (1)

135-141: LGTM!

src/schema-roundtrip.test.ts (1)

34-55: LGTM!

Also applies to: 195-206, 284-291

src/link-cliref.ts (2)

87-133: LGTM!

---

135-188: LGTM!

src/link-cliref.test.ts (1)

16-118: LGTM!

src/export.ts (2)

448-602: LGTM!

---

733-748: LGTM!

Also applies to: 789-790, 819-823, 837-837, 850-854

src/export.test.ts (1)

552-600: LGTM!

DESIGN.md (1)

201-216: LGTM!

briefings/B-0016-cli-reference-overlay-design.md (1)

201-374: LGTM!

CHANGELOG.md (1)

25-33: LGTM!

src/extract-cliref.ts (1)

1-255: LGTM!

Also applies to: 296-583

src/extract-cliref.test.ts (1)

1-139: LGTM!

VALIDATION.md (1)

56-60: LGTM!

Makefile (1)

6-6: LGTM!

Also applies to: 136-144, 160-174

project-words.txt (1)

135-135: LGTM!

Also applies to: 444-444, 480-481

MANUAL.md (1)

100-102: LGTM!

Also applies to: 118-118, 328-329

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.