From 43987a37dffecfadfc435aba5c6920884a3dc733 Mon Sep 17 00:00:00 2001 From: Breno Oliveira Date: Tue, 20 Oct 2026 11:27:39 -0300 Subject: [PATCH] check-kb: normalize path separators for Windows walk() produced OS-native paths (backslashes on Windows) that never matched the '/'-based definition tables (FILE_ID_DIRS, the rules/ prefix, evidence/index.csv), so on Windows every nested E-/R- definition went unregistered and valid knowledge bases failed check-kb. Normalize to POSIX in walk() via an exported toPosix helper; add an entry guard so the module is importable, and a unit test. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 4 ++++ skills/reverse-engineering-saas/scripts/check-kb.mjs | 10 ++++++++-- tests/kb-scripts.test.mjs | 12 ++++++++++++ 3 files changed, 24 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 62b47e6..e8715ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased + +- `check-kb.mjs`: normalize path separators to POSIX so a knowledge base validates on Windows. `walk()` used `relative()`, which returns backslashes on Windows, but definitions are keyed to `/`-based tables (`FILE_ID_DIRS` such as `data-model/entities`, the `rules/` prefix, `evidence/index.csv`). Without normalization every nested heading/filename definition went unregistered on Windows, so every `E-`/`R-` reference was reported as "referenced but not defined" and `evidence/index.csv` drew a spurious naming warning. Added an importable `toPosix` helper (with an entry guard matching `build-report.mjs`) and a unit test. + ## 0.4.0 (2026-10-17) - `REPORT.html` redesigned as a UX study a person can read and navigate: IBM Plex type, a light and a dark theme with a toggle, a one-line answer with the key findings, stat tiles, section chips, and screenshots in framed figures that enlarge on click. diff --git a/skills/reverse-engineering-saas/scripts/check-kb.mjs b/skills/reverse-engineering-saas/scripts/check-kb.mjs index 4d00f7e..4078ba0 100644 --- a/skills/reverse-engineering-saas/scripts/check-kb.mjs +++ b/skills/reverse-engineering-saas/scripts/check-kb.mjs @@ -4,6 +4,7 @@ // Exit code 1 when there are errors, 2 on bad usage. import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'; import { dirname, join, relative, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; const USAGE = 'Usage: node check-kb.mjs [--closing] [--next] [--help]'; const ID_PATTERN = /\b(FL|SRC|EV|BR|F|S|C|R|E|B|Q|L)-(\d{3})\b/g; @@ -40,13 +41,18 @@ let closingRun = false; const warnings = []; const definitions = new Map(); +// Normalize path separators to POSIX so comparisons against the '/'-based tables +// (FILE_ID_DIRS, HEADING_ID_FILES, EVIDENCE_INDEX and the 'rules/' prefix) also +// hold on Windows, where relative() returns backslashes. +export const toPosix = (p) => p.replaceAll('\\', '/'); + function walk(dir, root = dir) { const files = []; for (const entry of readdirSync(dir)) { if (SKIP_DIRS.has(entry)) continue; const full = join(dir, entry); if (statSync(full).isDirectory()) files.push(...walk(full, root)); - else files.push(relative(root, full)); + else files.push(toPosix(relative(root, full))); } return files; } @@ -372,4 +378,4 @@ function main() { process.exitCode = errors.length ? 1 : 0; } -main(); +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(); diff --git a/tests/kb-scripts.test.mjs b/tests/kb-scripts.test.mjs index 3b912eb..31d39b6 100644 --- a/tests/kb-scripts.test.mjs +++ b/tests/kb-scripts.test.mjs @@ -6,6 +6,7 @@ import { tmpdir } from 'node:os'; import { dirname, join } from 'node:path'; import { afterEach, beforeEach, test } from 'node:test'; import { fileURLToPath } from 'node:url'; +import { toPosix } from '../skills/reverse-engineering-saas/scripts/check-kb.mjs'; const scripts = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'reverse-engineering-saas', 'scripts'); const run = (name, ...args) => spawnSync(process.execPath, [join(scripts, name), ...args], { encoding: 'utf8' }); @@ -25,6 +26,17 @@ afterEach(() => rmSync(dir, { recursive: true, force: true })); const write = (path, text) => writeFileSync(join(kb, path), text); const check = (...args) => run('check-kb.mjs', kb, ...args); +// Regression for the Windows path-separator bug: walk() used relative(), which +// yields backslashes on Windows, but definitions are keyed to '/'-based tables +// (FILE_ID_DIRS like 'data-model/entities', the 'rules/' prefix, EVIDENCE_INDEX). +// Without normalization every nested heading/filename definition went unregistered +// on Windows, so every E-/R- reference was flagged "referenced but not defined". +test('toPosix normalizes separators so nested IDs resolve on every platform', () => { + assert.equal(toPosix('data-model\\entities\\E-002-x.md'), 'data-model/entities/E-002-x.md'); + assert.equal(toPosix('rules\\atendimento.md'), 'rules/atendimento.md'); + assert.equal(toPosix('evidence/index.csv'), 'evidence/index.csv'); +}); + test('init creates the tree, fills product and date, copies artifact templates', () => { for (const path of ['STATUS.md', 'sandbox/ledger.csv', 'inventory/coverage.md', '_templates/screen.md', 'evidence/index.csv']) { assert.ok(existsSync(join(kb, path)), `${path} missing`);