@esneiderbravo/speclaw 0.4.0 → 1.0.1

package/dist/modules/foundation/lock.js

@@ -0,0 +1,283 @@
+/**
+ * speclaw.lock — committed digests for rule files (never under `.speclaw/`).
+ * A gitignored lock would be invisible in PR diffs and would not detect
+ * Rules File Backdoor edits. Like package-lock.json / go.sum.
+ */
+// Covers: req~speclaw-lock~1
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pkgName, pkgVersion } from "../../shared/version.js";
+export const LOCKFILE_NAME = "speclaw.lock";
+export const LOCKFILE_VERSION = 1;
+/** Delimited provenance block excluded from digests (self-reference). */
+export const PROVENANCE_START = "<!-- speclaw:begin-provenance";
+export const PROVENANCE_END = "speclaw:end-provenance -->";
+/** Project-relative path of the committed lockfile. */
+export function lockfilePath(projectPath) {
+    return path.join(projectPath, LOCKFILE_NAME);
+}
+/**
+ * Canonical bytes for hashing: LF endings, strip provenance, trim EOL spaces,
+ * ensure a single trailing newline.
+ */
+export function canonicalize(raw) {
+    let text = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    text = stripProvenanceBlock(text);
+    text = text
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/g, ""))
+        .join("\n");
+    if (!text.endsWith("\n"))
+        text += "\n";
+    else if (text.endsWith("\n\n")) {
+        // collapse to exactly one trailing newline
+        text = text.replace(/\n+$/g, "\n");
+    }
+    return text;
+}
+/** Remove speclaw provenance HTML comment blocks. */
+export function stripProvenanceBlock(text) {
+    const re = new RegExp(`${escapeRegExp(PROVENANCE_START)}[\\s\\S]*?${escapeRegExp(PROVENANCE_END)}\\n?`, "g");
+    return text.replace(re, "");
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** sha256 digest with `sha256:` prefix. */
+export function digestOf(canonical) {
+    const hex = crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
+    return `sha256:${hex}`;
+}
+/** Digest raw file text after canonicalization. */
+export function digestText(raw) {
+    return digestOf(canonicalize(raw));
+}
+/** Root hash over sorted path → digest pairs. */
+export function rootDigest(files) {
+    const paths = Object.keys(files).sort();
+    let acc = "";
+    for (const p of paths) {
+        acc += `${p}\0${files[p].digest}\n`;
+    }
+    return digestOf(acc);
+}
+/** Read lockfile or null if missing. Throws on unknown version / parse error. */
+export function readLockfile(projectPath) {
+    const abs = lockfilePath(projectPath);
+    if (!fs.existsSync(abs))
+        return null;
+    const raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    if (typeof raw.lockfileVersion !== "number") {
+        throw new Error("speclaw.lock: missing lockfileVersion");
+    }
+    if (raw.lockfileVersion > LOCKFILE_VERSION) {
+        throw new Error(`speclaw.lock: unsupported lockfileVersion ${raw.lockfileVersion} (max ${LOCKFILE_VERSION})`);
+    }
+    return {
+        lockfileVersion: raw.lockfileVersion,
+        generator: String(raw.generator ?? ""),
+        algorithm: "sha256",
+        root: String(raw.root ?? ""),
+        files: raw.files && typeof raw.files === "object" ? raw.files : {},
+        symlinks: raw.symlinks && typeof raw.symlinks === "object" ? raw.symlinks : {},
+        accepted: Array.isArray(raw.accepted) ? raw.accepted : [],
+    };
+}
+/** Write lockfile with stable JSON formatting. */
+export function writeLockfile(projectPath, lock) {
+    const abs = lockfilePath(projectPath);
+    const body = JSON.stringify(lock, null, 2) + "\n";
+    fs.writeFileSync(abs, body);
+}
+/** Build a fresh lock object from file digests + symlinks. */
+export function buildLock(opts) {
+    const files = { ...opts.files };
+    return {
+        lockfileVersion: LOCKFILE_VERSION,
+        generator: `${pkgName()}@${pkgVersion()}`,
+        algorithm: "sha256",
+        root: rootDigest(files),
+        files,
+        symlinks: { ...(opts.symlinks ?? {}) },
+        accepted: [...(opts.accepted ?? [])],
+    };
+}
+/** Integrity severity policy for a project-relative path. */
+export function integrityPolicy(relPath) {
+    const n = relPath.split("\\").join("/");
+    // `.cursor/rules/` mirrors regenerable `ai-specs/` (gitignored) — lock/CI must
+    // not treat them as strict committed files; scan when present, never pin.
+    if (n === "AGENTS.md" ||
+        n === "CLAUDE.md" ||
+        n.startsWith(".github/instructions/") ||
+        n === ".coderabbit.yaml" ||
+        n === ".claude/rules/speclaw") {
+        return "strict";
+    }
+    if (n === "LAWS.md" || n === "docs/compass.md" || n.startsWith("docs/standards/")) {
+        return "advisory";
+    }
+    return "scan-only";
+}
+/** True when a path is an IDE mirror of regenerable (typically gitignored) content. */
+export function isRegenerableIdeMirror(relPath) {
+    const n = relPath.split("\\").join("/");
+    return (n.startsWith(".cursor/rules/") ||
+        n.startsWith(".cursor/skills/") ||
+        n.startsWith(".cursor/commands/") ||
+        n.startsWith(".claude/skills/") ||
+        n.startsWith(".claude/commands/") ||
+        n.startsWith("ai-specs/"));
+}
+/** Discover candidate paths under the project for locking / scanning. */
+export function discoverIntegrityPaths(projectPath) {
+    const files = [];
+    const symlinks = [];
+    const addFile = (rel) => {
+        const abs = path.join(projectPath, rel);
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile())
+            files.push(rel.split("\\").join("/"));
+    };
+    for (const f of ["AGENTS.md", "CLAUDE.md", "LAWS.md", "docs/compass.md", ".coderabbit.yaml"]) {
+        addFile(f);
+    }
+    walkFiles(path.join(projectPath, "docs", "standards"), projectPath, files, (p) => p.endsWith(".md"));
+    walkFiles(path.join(projectPath, ".cursor", "rules"), projectPath, files, () => true);
+    walkFiles(path.join(projectPath, ".github", "instructions"), projectPath, files, () => true);
+    // Outside-pipeline / skills (scan-only)
+    for (const f of [".clinerules", ".windsurfrules", "BUGBOT.md", ".cursorrules"])
+        addFile(f);
+    walkFiles(path.join(projectPath, "ai-specs", "skills"), projectPath, files, (p) => p.endsWith("SKILL.md") || p.endsWith(".md"));
+    walkFiles(path.join(projectPath, "ai-specs", "agents"), projectPath, files, (p) => p.endsWith(".md"));
+    walkFiles(path.join(projectPath, ".claude", "skills"), projectPath, files, (p) => p.endsWith("SKILL.md") || p.endsWith(".md"));
+    const linkRel = ".claude/rules/speclaw";
+    const linkAbs = path.join(projectPath, linkRel);
+    try {
+        const st = fs.lstatSync(linkAbs);
+        if (st.isSymbolicLink()) {
+            symlinks.push({ path: linkRel, target: fs.readlinkSync(linkAbs) });
+        }
+    }
+    catch {
+        /* missing */
+    }
+    return { files: [...new Set(files)].sort(), symlinks };
+}
+function walkFiles(dir, projectPath, out, pred) {
+    if (!fs.existsSync(dir))
+        return;
+    const stack = [dir];
+    while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(cur, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile()) {
+                const rel = path.relative(projectPath, full).split(path.sep).join("/");
+                if (pred(rel))
+                    out.push(rel);
+            }
+        }
+    }
+}
+/** Markers for the regenerable map block inside `docs/compass.md` (see compass/map.ts). */
+export const COMPASS_MAP_START = "<!-- speclaw:map:start -->";
+export const COMPASS_MAP_END = "<!-- speclaw:map:end -->";
+/**
+ * Strip the regenerable map body between markers so integrity digests stay stable
+ * across `speclaw index` (which rewrites the map in CI before verify).
+ *
+ * @param text - Full docs/compass.md contents.
+ * @returns The same text with an empty map body, or `text` if markers are missing.
+ */
+export function stripCompassMapBlock(text) {
+    const start = text.indexOf(COMPASS_MAP_START);
+    const end = text.indexOf(COMPASS_MAP_END);
+    if (start < 0 || end < 0 || end < start)
+        return text;
+    return text.slice(0, start + COMPASS_MAP_START.length) + "\n" + text.slice(end);
+}
+/**
+ * Path-specific bytes that feed {@link digestText}: speclaw-owned coderabbit
+ * region, regenerable Compass map body stripped, otherwise the file as-is.
+ *
+ * @param relPath - Project-relative path.
+ * @param raw - File contents.
+ * @returns Text to canonicalize and hash for this path.
+ */
+export function prepareIntegrityText(relPath, raw) {
+    const n = relPath.split("\\").join("/");
+    if (n === ".coderabbit.yaml")
+        return extractSpeclawYamlBlock(raw) ?? raw;
+    if (n === "docs/compass.md")
+        return stripCompassMapBlock(raw);
+    return raw;
+}
+/**
+ * Snapshot digests for discovered files with ownership policy.
+ * For `.coderabbit.yaml`, digests only the speclaw delimited block when present.
+ * For `docs/compass.md`, digests with the regenerable map body stripped.
+ */
+export function snapshotLockEntries(projectPath) {
+    const { files: paths, symlinks } = discoverIntegrityPaths(projectPath);
+    const files = {};
+    for (const rel of paths) {
+        const ownership = integrityPolicy(rel);
+        if (ownership === "scan-only")
+            continue; // locked only when previously accepted / explicit
+        const abs = path.join(projectPath, rel);
+        const raw = prepareIntegrityText(rel, fs.readFileSync(abs, "utf8"));
+        files[rel] = { digest: digestText(raw), ownership };
+    }
+    const symlinkMap = {};
+    for (const s of symlinks)
+        symlinkMap[s.path] = { target: s.target };
+    return { files, symlinks: symlinkMap };
+}
+/** Extract a speclaw-marked region from coderabbit yaml if present. */
+export function extractSpeclawYamlBlock(raw) {
+    const m = /# speclaw:begin[\s\S]*?# speclaw:end/.exec(raw);
+    if (m)
+        return m[0];
+    const m2 = /<!-- speclaw:laws:start -->[\s\S]*?<!-- speclaw:laws:end -->/.exec(raw) ??
+        /<!-- speclaw:begin-provenance[\s\S]*?speclaw:end-provenance -->/.exec(raw);
+    return m2 ? m2[0] : null;
+}
+/** Create or refresh speclaw.lock from the current tree. */
+export function refreshLockfile(projectPath) {
+    const prev = (() => {
+        try {
+            return readLockfile(projectPath);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const { files, symlinks } = snapshotLockEntries(projectPath);
+    const lock = buildLock({
+        files,
+        symlinks,
+        accepted: prev?.accepted ?? [],
+    });
+    writeLockfile(projectPath, lock);
+    return lock;
+}
+/** Render a data-only provenance HTML comment (no imperatives). */
+export function provenanceBlock(opts) {
+    const laws = (opts.lawIds ?? []).map((l) => `  law: ${l}`).join("\n");
+    return (`${PROVENANCE_START}\n` +
+        (laws ? laws + "\n" : "") +
+        (opts.source ? `  source: ${opts.source}\n` : "") +
+        `  digest: ${opts.digest}\n` +
+        `  generator: ${pkgName()}@${pkgVersion()}\n` +
+        `speclaw:end-provenance -->\n`);
+}

package/dist/modules/foundation/ownership.js

@@ -1,6 +1,10 @@
 // Which scaffolded files speclaw owns vs the user owns. `speclaw update` uses
 // this split to decide what it may overwrite automatically (managed) and what it
 // must leave to the user's agent via a prompt (personalized).
+//
+// Integrity severity (`strict` / `advisory` / `scan-only` in lock.ts) is a
+// separate axis: CLAUDE.md / AGENTS.md stay PERSONALIZED for update, but are
+// `strict` for `verifyIntegrity` digest mismatches.
 /**
  * Project-relative trees that hold speclaw's workflow machinery. The user is not
  * meant to edit these, so `speclaw update` overwrites them with the current

package/dist/modules/foundation/scaffold.js

@@ -8,8 +8,11 @@ import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
 import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
-import { mergeSeedLaws, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
+import { mergeSeedLaws, readLawManifest, seedManifestFor, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
+import { compileLaws } from "./compile-laws.js";
+import { refreshLockfile } from "./lock.js";
+import { refreshOwnersIfConfigured } from "../team/owners.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
 // provide default to empty so a bare `scaffold` never leaves a raw {{tag}}.
@@ -25,19 +28,22 @@ const FOUNDATION_DEFAULTS = {
     documentation_extra: "",
 };
 /**
- * Ensure the project has a law manifest. Missing → seed. Present → append any
- * shipped seed law whose `id` is absent (never overwrite a curated entry).
+ * Ensure the project has a law manifest. Missing → adapted seed for this tree.
+ * Present → merge the adapted catalog (never overwrite a curated entry; prune
+ * unmodified dogfood laws whose required paths are absent).
  */
 function ensureLawManifest(projectPath, report) {
     const existing = readLawManifest(projectPath);
     if (!existing) {
-        const seed = seedManifest();
+        const seed = seedManifestFor(projectPath);
         writeLawManifest(projectPath, seed);
         report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
         return seed;
     }
-    const { manifest, added } = mergeSeedLaws(existing);
-    if (added.length > 0) {
+    const { manifest, added, removed } = mergeSeedLaws(existing, projectPath);
+    if (added.length > 0 ||
+        removed.length > 0 ||
+        JSON.stringify(manifest.laws) !== JSON.stringify(existing.laws)) {
         writeLawManifest(projectPath, manifest);
         report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
     }
@@ -150,12 +156,34 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // configured. The seam is the manifest: check-dispatcher enforces `path` laws;
     // executable-laws will extend the same manifest with more backends.
     const lawManifest = ensureLawManifest(projectPath, report);
+    try {
+        compileLaws({ projectPath, agents, writeManifest: false });
+    }
+    catch {
+        // Compilation must not fail scaffold; `speclaw laws compile` surfaces errors.
+    }
+    // Covers: req~lock-refresh-update~1
+    try {
+        refreshLockfile(projectPath);
+    }
+    catch {
+        // Lock refresh must not fail scaffold; `speclaw laws lock` surfaces errors.
+    }
     ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {
         baselines: managedOpts.baselines,
         backup: managedOpts.backup,
         record,
     });
+    // Refresh CODEOWNERS managed block when the project declared team.owners —
+    // never invent owners when the key is absent.
+    try {
+        refreshOwnersIfConfigured(projectPath);
+    }
+    catch (err) {
+        // Surface as a soft note — invalid tokens should not abort scaffold/update.
+        report.skipped.push(`owners refresh skipped: ${err.message}`);
+    }
     // Record what was installed so `speclaw update` can re-apply these packs and
     // gate feature migrations by version, plus the managed-file baselines that let
     // a later update tell user edits from stale files.

package/dist/modules/foundation/scan.js

@@ -0,0 +1,227 @@
+/**
+ * Prompt-injection scanners for rule / skill files.
+ * Complements digests: hashes catch any edit; scanners catch known payloads.
+ */
+// Covers: req~injection-scan~1
+import fs from "node:fs";
+import path from "node:path";
+const OVERRIDE = /\b(ignore\s+previous\s+instructions|disregard\s+the\s+above|you\s+are\s+now|new\s+system\s+prompt|ignora\s+las\s+instrucciones\s+anteriores)\b/i;
+const SHELL = /\b(curl\s+[^\n|]*\|\s*(ba)?sh|bash\s+-c|Invoke-Expression|iex\b|eval\s*\(|npm\s+run\s+[^\s]+.*\|\s*sh)\b/i;
+const EXFIL = /\b(send\s+(this|the)\s+(repo|code|contents?)\s+to|exfiltrat|upload\s+to\s+https?:\/\/|read\s+(\.env|~\/\.ssh|~\/\.aws|\.npmrc)|exfiltra)\b/i;
+const URL_RE = /https?:\/\/[^\s)>\]]+/gi;
+const ZERO_WIDTH = /[\u200B-\u200D\uFEFF\u202A-\u202E]/;
+const IMPERATIVE_HTML = /<!--[\s\S]{0,200}\b(run|execute|ignore|disregard|curl|bash|send)\b[\s\S]{0,200}-->/i;
+/**
+ * Normalize text before detection (NFKC, strip zero-width/bidi, fold common
+ * Cyrillic lookalikes, collapse whitespace).
+ */
+export function normalizeForScan(text) {
+    let t = text.normalize("NFKC");
+    t = t.replace(ZERO_WIDTH, "");
+    t = t.replace(/[\u0400-\u04FF]/g, (ch) => CYRILLIC_FOLD[ch] ?? ch);
+    t = t.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+    t = t.replace(/\\\*|\\_|\\`/g, (m) => m.slice(1));
+    t = t.replace(/\s+/g, " ").trim();
+    return t;
+}
+const CYRILLIC_FOLD = {
+    а: "a",
+    е: "e",
+    о: "o",
+    р: "p",
+    с: "c",
+    у: "y",
+    х: "x",
+    А: "A",
+    Е: "E",
+    О: "O",
+    Р: "P",
+    С: "C",
+    У: "Y",
+    Х: "X",
+};
+/** Scan one file's raw contents; returns findings with original line numbers. */
+export function scanText(relPath, raw, opts = {}) {
+    const suppressions = opts.suppressions ?? [];
+    const allow = new Set((opts.allowHosts ?? []).map((h) => h.toLowerCase()));
+    const out = [];
+    const lines = raw.split(/\r?\n/);
+    const push = (f) => {
+        if (suppressions.some((s) => s.detector === f.detector && matchPath(s.path, f.path) && s.note.trim().length > 0)) {
+            return;
+        }
+        out.push(f);
+    };
+    if (ZERO_WIDTH.test(raw)) {
+        push({
+            detector: "injection/hidden-text",
+            severity: "error",
+            path: relPath,
+            line: 1,
+            excerpt: "zero-width or bidi control characters",
+            message: "Hidden / bidi control characters in a rule file.",
+        });
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const norm = normalizeForScan(line);
+        const ln = i + 1;
+        if (OVERRIDE.test(norm) || OVERRIDE.test(line)) {
+            push({
+                detector: "injection/instruction-override",
+                severity: "error",
+                path: relPath,
+                line: ln,
+                excerpt: clip(line),
+                message: "Instruction-override phrasing in a rule file.",
+            });
+        }
+        if (SHELL.test(norm) || SHELL.test(line)) {
+            push({
+                detector: "injection/shell-execution",
+                severity: "error",
+                path: relPath,
+                line: ln,
+                excerpt: clip(line),
+                message: "Shell-execution instruction in a rule file.",
+            });
+        }
+        if (EXFIL.test(norm) || EXFIL.test(line)) {
+            push({
+                detector: "injection/exfiltration",
+                severity: "error",
+                path: relPath,
+                line: ln,
+                excerpt: clip(line),
+                message: "Possible exfiltration instruction in a rule file.",
+            });
+        }
+        for (const m of line.matchAll(URL_RE)) {
+            try {
+                const host = new URL(m[0]).hostname.toLowerCase();
+                if (allow.size > 0 && !allow.has(host) && !host.endsWith(".github.com")) {
+                    push({
+                        detector: "injection/unallowlisted-url",
+                        severity: "warn",
+                        path: relPath,
+                        line: ln,
+                        excerpt: clip(m[0]),
+                        message: `URL host not on allowlist: ${host}`,
+                    });
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    if (IMPERATIVE_HTML.test(raw)) {
+        const idx = raw.search(IMPERATIVE_HTML);
+        const snippet = raw.slice(Math.max(0, idx), idx + 220);
+        // Data-only speclaw markers (map/laws/provenance) are not agent instructions.
+        if (!/<!--\s*speclaw:/.test(snippet)) {
+            const line = lineOf(raw, idx);
+            push({
+                detector: "injection/imperative-html-comment",
+                severity: "warn",
+                path: relPath,
+                line,
+                excerpt: clip(raw.slice(idx, idx + 120)),
+                message: "HTML comment contains imperative language (visible to some agents).",
+            });
+        }
+    }
+    // External @import / @~/ / @C:\…
+    // External @import / @~/ / @C:\…
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = /@([~/][^\s)\]>"']+)/.exec(line) ??
+            /@([A-Za-z]:[^\s)\]>"']+)/.exec(line) ??
+            /@import\s+["']([^"']+)["']/.exec(line);
+        if (!m)
+            continue;
+        const target = m[1];
+        push({
+            detector: "injection/external-import",
+            severity: "warn",
+            path: relPath,
+            line: i + 1,
+            excerpt: clip(line),
+            message: `Import may resolve outside the working directory: ${target}`,
+        });
+    }
+    // Frontmatter ↔ body mismatch (skills)
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(raw);
+    if (fm) {
+        const front = fm[1];
+        const body = fm[2];
+        const frontDesc = /(?:^|\n)description:\s*["']?([^\n"']+)/i.exec(front)?.[1] ?? "";
+        if (frontDesc && SHELL.test(body) && !SHELL.test(frontDesc)) {
+            push({
+                detector: "injection/manifest-prose-mismatch",
+                severity: "warn",
+                path: relPath,
+                line: 1,
+                excerpt: clip(frontDesc),
+                message: "Skill frontmatter description and body disagree on shell risk.",
+            });
+        }
+    }
+    return out;
+}
+function matchPath(pattern, file) {
+    if (pattern === file)
+        return true;
+    if (pattern.endsWith("/**")) {
+        const prefix = pattern.slice(0, -3);
+        return file === prefix || file.startsWith(prefix + "/");
+    }
+    if (pattern.includes("*")) {
+        const re = new RegExp("^" + pattern.split("*").map(escapeRegExp).join(".*") + "$");
+        return re.test(file);
+    }
+    return false;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function clip(s, n = 120) {
+    const t = s.trim();
+    return t.length <= n ? t : t.slice(0, n - 1) + "…";
+}
+function lineOf(text, index) {
+    if (index <= 0)
+        return 1;
+    return text.slice(0, index).split(/\r?\n/).length;
+}
+/** Load optional scan suppressions from lawbook/config.yaml (line-oriented). */
+export function loadScanSuppressions(projectPath) {
+    const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
+    if (!fs.existsSync(cfgPath))
+        return [];
+    const text = fs.readFileSync(cfgPath, "utf8");
+    // Very small subset: repeated blocks under scanSuppressions are not fully
+    // parsed; support a flat JSON-ish list in a comment-free line for v1:
+    // scanSuppressions: [{"detector":"…","path":"…","note":"…"}]
+    const m = /^\s*scanSuppressions\s*:\s*(\[[\s\S]*?\])\s*$/m.exec(text);
+    if (!m)
+        return [];
+    try {
+        const arr = JSON.parse(m[1]);
+        return arr.filter((s) => s.detector && s.path && s.note);
+    }
+    catch {
+        return [];
+    }
+}
+/** Scan a list of project-relative files that exist. */
+export function scanPaths(projectPath, relPaths, opts = {}) {
+    const out = [];
+    for (const rel of relPaths) {
+        const abs = path.join(projectPath, rel);
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isFile())
+            continue;
+        out.push(...scanText(rel, fs.readFileSync(abs, "utf8"), opts));
+    }
+    return out;
+}