Enforce static db.ts-import guard + control-char scan (#98); point MANUAL schema rows at Docusaurus

[mobileskyfi]

Closes #98.

Two 0.11.0 cleanups, per the triage split on #98: the cheap durable guard (suggested-work item 1 + the "Related" NUL-byte note), plus the requested MANUAL/README docs pass toward manual.mikrotik.com.

#98 — make the rule enforced, not remembered

The live bug (a hoisted static db.ts-reaching import in extract-docusaurus.test.ts, and a stray NUL byte) was already fixed in PR #97; what was left was enforcement so it can't silently come back. New src/source-hygiene.test.ts — two DB-less structural scans, no runtime cost:

• V-test-db-import-static-guard — scans every *.test.ts that sets process.env.DB_PATH and fails if any statically **value-**imports a module transitively reaching db.ts. That's the hoisting hazard: the static import runs db.ts's module-scope new sqlite(DB_PATH) before :memory: is assigned, opening the real ros-help.db. query.test.ts's V-db-wipe-guard only trips on it when the offending file loads db.ts first, and bun's file order isn't stable — so it presents as a flake. This blocks it at author time regardless of order. Statement-level import type … from is erased and stays allowed (e.g. extract-hardware-catalog.test.ts).
• V-source-no-control-chars — no source .ts may carry a NUL or other disallowed C0/DEL control byte (tab/newline/CR allowed). The class where a stray NUL makes file report the source as data and grep silently match nothing while tests/typecheck/biome all pass.

Both verified to fire on a planted violation (a static ./query.ts import in a DB_PATH test; a NUL byte in a temp source file) with a one-read diagnostic, then pass on the real tree. extractor-import-side-effects.instructions.md and VALIDATION.md updated.

Deferred per the triage split (not in this PR): item 2 (name the offender in V-db-wipe-guard) and item 3 (bun test --isolate investigation).

Docs — point at Docusaurus, not Confluence

README and DESIGN already frame the live manual.mikrotik.com Docusaurus corpus as current with Confluence as frozen/legacy (issue #77); a full sweep found nothing still presenting Confluence as the live source. The one honest touch-up: MANUAL's schema-reference pages/callouts row descriptions still described the Confluence source shape under the frozen-counts caveat — refreshed to name the current Docusaurus source (manual.mikrotik.com URL; ::: admonitions), counts still flagged frozen.

Validation

• bun test — 985 pass / 0 fail (32 files); source-hygiene.test.ts 87 pass.
• bunx @biomejs/biome check clean; bun run lint:md / lint:spell clean (nul added to project-words.txt).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Prevented intermittent test failures caused by database connections being initialized before test configuration was applied.
  • Added safeguards to detect invalid imports that could trigger unintended database access.

• Tests

  • Added automated checks to prevent disallowed control characters in source files.
  • Strengthened validation for database-related test setup and source hygiene.

• Documentation

  • Updated the changelog and validation documentation with the new safeguards.

[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: bdb04180-d816-429e-ba2c-d243f914e2e1

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

Adds repo-wide tests that detect DB-reaching static imports in DB_PATH tests and disallowed control bytes in TypeScript sources. Updates validation documentation, authoring guidance, changelog, and spelling data.

Changes

Source hygiene enforcement

Layer / File(s)	Summary
Static import graph analysis src/source-hygiene.test.ts	Enumerates source files, resolves local imports, excludes type and dynamic imports, and computes transitive reachability to db.ts.
DB import and byte guards src/source-hygiene.test.ts	Rejects DB_PATH-setting tests with statically reachable DB imports and reports disallowed control bytes with file and position details.
Validation and repository guidance .github/instructions/..., VALIDATION.md, CHANGELOG.md, project-words.txt	Documents the new invariants, records the fix, and adds nul to the spelling dictionary.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• tikoci/rosetta#81: Addresses deferred db.ts initialization and related static-import hygiene.
• tikoci/rosetta#103: Covers DB_PATH-setting tests that can statically reach database modules.

Suggested labels: area:docusaurus

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: a static db.ts-import guard plus a control-character scan.
Linked Issues check	✅ Passed	The PR implements both #98 requirements: a structural DB_PATH/static-import guard and a source scan for disallowed control characters.
Out of Scope Changes check	✅ Passed	No clear out-of-scope code changes are evident; the docs and dictionary updates support the two source-hygiene checks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/98-static-db-import-guard

---

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

Adds structural “source hygiene” checks to prevent a known Bun test-order hazard from silently opening the on-disk DB, and documents the new validation rules while refreshing MANUAL schema-row wording to reflect the live Docusaurus corpus.

Changes:

• Add src/source-hygiene.test.ts with two DB-less structural scans: a static db.ts-reaching import guard for DB_PATH tests, and a control-character (NUL/C0/DEL) source scan.
• Document the new validation IDs (V-test-db-import-static-guard, V-source-no-control-chars) and reinforce the dynamic-import discipline in the extractor side-effects instruction.
• Update MANUAL schema table descriptions to point to manual.mikrotik.com (Docusaurus) while keeping legacy Confluence rows acknowledged; add nul to the spelling dictionary; add a changelog entry.

Reviewed changes

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

Show a summary per file

File	Description
src/source-hygiene.test.ts	New structural tests: db.ts-reaching static import guard for DB_PATH-setting tests, plus control-character scan.
VALIDATION.md	Adds two new V-* rows describing the new structural guards and where CI runs them.
.github/instructions/extractor-import-side-effects.instructions.md	Updates the documented rule to note the new structural enforcement test.
MANUAL.md	Updates schema-row descriptions to reference the live Docusaurus corpus and manual.mikrotik.com.
CHANGELOG.md	Adds an Unreleased “Fixed” bullet describing the new enforcement and control-char scan.
project-words.txt	Adds nul to the project dictionary to keep spellcheck clean.

[mobileskyfi]

Update — Copilot review + main merge resolved

• Copilot threads (3): all three flagged the same thing — the control-char scan wording said "source .ts" but only walked src/. Broadened the scan to cover both source roots the repo ships (src/ + scripts/, via SOURCE_DIRS); diagnostics now print repo-relative paths. Wording in the header comment, VALIDATION.md, and CHANGELOG.md tightened to "under src/ or scripts/". All three threads replied to + resolved.
• Merge conflict with main: resolved. CHANGELOG.md kept all entries from both sides (Test-suite hazard: a static db.ts-reaching import silently opens the real ros-help.db; V-db-wipe-guard only catches it on unlucky file order #98 + the Video search buries changelog-title videos: dotted versions shredded, title text unindexed #89/Shared version comparator ignores prerelease number (7.24beta1 == beta2) #107/Refresh legacy Confluence-era counts in MANUAL.md Tables + src/mcp.ts schema text #88 entries from main). MANUAL.md — my schema-table edit is now fully superseded by Refresh legacy Confluence-era counts in MANUAL.md Tables + src/mcp.ts schema text #88 (merged to main), which did a more complete order-of-magnitude refresh of the same Tables block with the same Docusaurus-source / legacy-Confluence framing; took main's version, so this branch no longer changes MANUAL.md. The docs-review goal is satisfied on main via Refresh legacy Confluence-era counts in MANUAL.md Tables + src/mcp.ts schema text #88.
• Net remaining scope of this PR: the Test-suite hazard: a static db.ts-reaching import silently opens the real ros-help.db; V-db-wipe-guard only catches it on unlucky file order #98 structural guard (src/source-hygiene.test.ts + VALIDATION.md + instruction + changelog + nul dict word). No product-code change.
• Local verification post-merge: bun test 998 pass / 0 fail (1018 incl. skip/todo, 33 files); biome + markdownlint + cspell all clean.

[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/source-hygiene.test.ts`:
- Around line 81-83: Update the fromRe regular expression in
source-hygiene.test.ts to match both import declarations and re-export
declarations by replacing the import-only prefix with an import-or-export
alternative. Preserve the existing multiline specifier and module-source capture
behavior so export * from and export { ... } from contribute to the transitive
dependency closure.

🪄 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: e77a6e49-8fcf-4673-9cc1-39c6a065f125

📥 Commits

Reviewing files that changed from the base of the PR and between 75f2587 and 84f579a.

📒 Files selected for processing (5)

• .github/instructions/extractor-import-side-effects.instructions.md
• CHANGELOG.md
• VALIDATION.md
• project-words.txt
• src/source-hygiene.test.ts

📜 Review details

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

• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (actions)
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (8)

*

📄 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

.github/instructions/*.instructions.md

📄 CodeRabbit inference engine (AGENTS.md)

Manually read matching .github/instructions/*.instructions.md files because Codex does not automatically apply Copilot applyTo selection.

Files:

• .github/instructions/extractor-import-side-effects.instructions.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:

• VALIDATION.md
• CHANGELOG.md

VALIDATION.md

📄 CodeRabbit inference engine (CLAUDE.md)

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

Files:

• VALIDATION.md

**/*.{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:

• VALIDATION.md
• CHANGELOG.md
• src/source-hygiene.test.ts

CHANGELOG.md

📄 CodeRabbit inference engine (CLAUDE.md)

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

Files:

• CHANGELOG.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/source-hygiene.test.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/source-hygiene.test.ts

🪛 LanguageTool

VALIDATION.md

[uncategorized] ~29-~29: The official name of this software platform is spelled with a capital “H”.
Context: ...db.ts import guard) via bun test in .github/workflows/test.yml | blocking | #98 | ...

(GITHUB)

---

[uncategorized] ~30-~30: The official name of this software platform is spelled with a capital “H”.
Context: ...haracters in source) via bun testin.github/workflows/test.yml| blocking |#98` | ...

(GITHUB)