@esneiderbravo/speclaw 0.3.13 → 1.0.0

package/dist/modules/foundation/integrity.js

@@ -0,0 +1,307 @@
+/**
+ * Rule-file integrity verification (digests + injection scan).
+ * Distinct from {@link verifyLaws} (deps/graph engines).
+ */
+// Covers: req~integrity-verify~1, req~laws-accept-human~1
+import fs from "node:fs";
+import path from "node:path";
+import { digestText, discoverIntegrityPaths, integrityPolicy, isRegenerableIdeMirror, lockfilePath, prepareIntegrityText, readLockfile, refreshLockfile, rootDigest, writeLockfile, } from "./lock.js";
+import { loadScanSuppressions, scanPaths } from "./scan.js";
+/**
+ * Verify digests and/or scan rule files. Missing lockfile is soft (ok=true)
+ * with guidance to run `speclaw laws lock`.
+ */
+export function verifyIntegrity(opts) {
+    const projectPath = opts.projectPath;
+    const checks = opts.checks ?? "both";
+    const doIntegrity = checks === "integrity" || checks === "both";
+    const doScan = checks === "scan" || checks === "both";
+    let lock;
+    try {
+        lock = readLockfile(projectPath);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            lockPresent: fs.existsSync(lockfilePath(projectPath)),
+            rootMatches: false,
+            guidance: err.message,
+            files: [],
+            symlinks: [],
+            findings: [],
+            verifyFindings: [
+                {
+                    lawId: "integrity~lockfile~1",
+                    severity: "error",
+                    engine: "integrity",
+                    file: "speclaw.lock",
+                    message: err.message,
+                },
+            ],
+        };
+    }
+    if (!lock && doIntegrity) {
+        const scanned = doScan ? scanAll(projectPath) : [];
+        const scanErrors = scanned.filter((f) => f.severity === "error");
+        return {
+            ok: scanErrors.length === 0,
+            lockPresent: false,
+            rootMatches: false,
+            guidance: "No speclaw.lock — run `speclaw laws lock` to create the baseline.",
+            files: [],
+            symlinks: [],
+            findings: scanned,
+            verifyFindings: scanned
+                .filter((f) => f.severity === "error" || f.severity === "warn")
+                .map(scanToFinding),
+        };
+    }
+    const files = [];
+    const symlinks = [];
+    const verifyFindings = [];
+    let ok = true;
+    if (lock && doIntegrity) {
+        const accepted = new Map(lock.accepted.map((a) => [a.path, a.digest]));
+        for (const [rel, entry] of Object.entries(lock.files)) {
+            const abs = path.join(projectPath, rel);
+            if (!fs.existsSync(abs)) {
+                // Stale lock entries for regenerable IDE mirrors (ai-specs gitignored) —
+                // warn only; never fail CI on a clean clone.
+                if (isRegenerableIdeMirror(rel)) {
+                    files.push({
+                        path: rel,
+                        ownership: entry.ownership,
+                        status: "missing",
+                        expected: entry.digest,
+                    });
+                    verifyFindings.push({
+                        lawId: "integrity~missing~1",
+                        severity: "warn",
+                        engine: "integrity",
+                        file: rel,
+                        message: "Regenerable IDE rule mirror missing — run `speclaw update` or `speclaw laws lock` to drop stale entries",
+                    });
+                    continue;
+                }
+                const severity = entry.ownership === "strict" ? "error" : "warn";
+                if (entry.ownership === "strict")
+                    ok = false;
+                files.push({
+                    path: rel,
+                    ownership: entry.ownership,
+                    status: "missing",
+                    expected: entry.digest,
+                });
+                verifyFindings.push({
+                    lawId: "integrity~missing~1",
+                    severity,
+                    engine: "integrity",
+                    file: rel,
+                    message: entry.ownership === "strict"
+                        ? `Managed rule file missing (expected ${entry.digest})`
+                        : `Advisory rule/source file missing (expected ${entry.digest})`,
+                });
+                continue;
+            }
+            const raw = prepareIntegrityText(rel, fs.readFileSync(abs, "utf8"));
+            const actual = digestText(raw);
+            if (actual === entry.digest) {
+                files.push({
+                    path: rel,
+                    ownership: entry.ownership,
+                    status: "ok",
+                    expected: entry.digest,
+                    actual,
+                });
+                continue;
+            }
+            if (accepted.get(rel) === actual) {
+                files.push({
+                    path: rel,
+                    ownership: entry.ownership,
+                    status: "accepted",
+                    expected: entry.digest,
+                    actual,
+                });
+                continue;
+            }
+            const unified = `--- speclaw.lock (${entry.digest})\n+++ ${rel} (${actual})\n`;
+            const isStrict = entry.ownership === "strict";
+            if (isStrict)
+                ok = false;
+            files.push({
+                path: rel,
+                ownership: entry.ownership,
+                status: isStrict ? "modified" : "advisory-modified",
+                expected: entry.digest,
+                actual,
+                diff: unified,
+            });
+            verifyFindings.push({
+                lawId: isStrict ? "integrity~digest-mismatch~1" : "integrity~advisory-mismatch~1",
+                severity: isStrict ? "error" : "warn",
+                engine: "integrity",
+                file: rel,
+                message: isStrict
+                    ? `Digest mismatch for strict rule file`
+                    : `Advisory rule/source file changed`,
+                detail: `expected ${entry.digest} found ${actual}`,
+            });
+        }
+        const { files: discovered } = discoverIntegrityPaths(projectPath);
+        for (const rel of discovered) {
+            if (lock.files[rel])
+                continue;
+            const ownership = integrityPolicy(rel);
+            if (ownership === "scan-only")
+                continue;
+            files.push({ path: rel, ownership, status: "untracked-by-lock" });
+            verifyFindings.push({
+                lawId: "integrity~untracked~1",
+                severity: "warn",
+                engine: "integrity",
+                file: rel,
+                message: `Rule file not listed in speclaw.lock`,
+            });
+        }
+        for (const [rel, entry] of Object.entries(lock.symlinks)) {
+            const abs = path.join(projectPath, rel);
+            let actual = null;
+            try {
+                if (fs.lstatSync(abs).isSymbolicLink())
+                    actual = fs.readlinkSync(abs);
+            }
+            catch {
+                actual = null;
+            }
+            if (actual === null) {
+                symlinks.push({
+                    path: rel,
+                    expectedTarget: entry.target,
+                    actualTarget: null,
+                    status: "missing",
+                });
+                ok = false;
+                verifyFindings.push({
+                    lawId: "integrity~symlink~1",
+                    severity: "error",
+                    engine: "integrity",
+                    file: rel,
+                    message: `Managed symlink missing (expected → ${entry.target})`,
+                });
+            }
+            else if (normalizeLink(actual) !== normalizeLink(entry.target)) {
+                symlinks.push({
+                    path: rel,
+                    expectedTarget: entry.target,
+                    actualTarget: actual,
+                    status: "mismatch",
+                });
+                ok = false;
+                verifyFindings.push({
+                    lawId: "integrity~symlink~1",
+                    severity: "error",
+                    engine: "integrity",
+                    file: rel,
+                    message: `Managed symlink retargeted`,
+                    detail: `expected ${entry.target} found ${actual}`,
+                });
+            }
+            else {
+                symlinks.push({
+                    path: rel,
+                    expectedTarget: entry.target,
+                    actualTarget: actual,
+                    status: "ok",
+                });
+            }
+        }
+    }
+    const findings = doScan ? scanAll(projectPath) : [];
+    for (const f of findings.filter((x) => x.severity === "error")) {
+        ok = false;
+        verifyFindings.push(scanToFinding(f));
+    }
+    for (const f of findings.filter((x) => x.severity === "warn")) {
+        verifyFindings.push(scanToFinding(f));
+    }
+    return {
+        ok,
+        lockPresent: lock !== null,
+        rootMatches: lock ? rootDigest(lock.files) === lock.root : false,
+        guidance: !lock && doIntegrity
+            ? "No speclaw.lock — run `speclaw laws lock` to create the baseline."
+            : undefined,
+        files,
+        symlinks,
+        findings,
+        verifyFindings,
+    };
+}
+/**
+ * Fold integrity findings into a batch {@link VerifyReport} (SARIF / exit codes).
+ * Error-severity findings increment `summary.failed`.
+ */
+export function foldIntegrityIntoReport(report, integrity) {
+    for (const f of integrity.verifyFindings) {
+        report.findings.push(f);
+        if (f.severity === "error")
+            report.summary.failed += 1;
+    }
+}
+function normalizeLink(t) {
+    return t.split("\\").join("/").replace(/\/+$/, "");
+}
+function scanAll(projectPath) {
+    const { files } = discoverIntegrityPaths(projectPath);
+    return scanPaths(projectPath, files, {
+        suppressions: loadScanSuppressions(projectPath),
+    });
+}
+function scanToFinding(f) {
+    return {
+        lawId: f.detector.replace(/\//g, "~"),
+        severity: f.severity,
+        engine: "integrity",
+        file: f.path,
+        line: f.line,
+        message: f.message,
+        detail: f.excerpt,
+    };
+}
+/**
+ * Accept a changed file's current digest into the lock (caller must ensure TTY).
+ * Updates digest, root, and accepted[].
+ */
+export function acceptLockPath(projectPath, relPath, meta) {
+    const lock = readLockfile(projectPath);
+    if (!lock)
+        throw new Error("No speclaw.lock — run `speclaw laws lock` first.");
+    const abs = path.join(projectPath, relPath);
+    if (!fs.existsSync(abs))
+        throw new Error(`File not found: ${relPath}`);
+    const raw = prepareIntegrityText(relPath, fs.readFileSync(abs, "utf8"));
+    const dig = digestText(raw);
+    const ownership = lock.files[relPath]?.ownership ?? integrityPolicy(relPath);
+    if (ownership === "scan-only") {
+        throw new Error(`${relPath} is scan-only — digests are not locked for this path.`);
+    }
+    lock.files[relPath] = { digest: dig, ownership };
+    lock.root = rootDigest(lock.files);
+    const entry = {
+        path: relPath,
+        digest: dig,
+        at: meta.at ?? new Date().toISOString(),
+        by: meta.by,
+        note: meta.note,
+    };
+    lock.accepted = [...lock.accepted.filter((a) => a.path !== relPath), entry];
+    writeLockfile(projectPath, lock);
+    return lock;
+}
+/** Re-export refresh for CLI `laws lock`. */
+export { refreshLockfile };
+/** True when stdin is a TTY (accept requires this). */
+export function isInteractiveTty() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}

package/dist/modules/foundation/laws-parse.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Parse laws declared in markdown via HTML comment blocks:
+ *
+ * ```html
+ * <!-- speclaw:law
+ * id: law~example~1
+ * title: Example
+ * severity: warn
+ * scope: src/**\/*.ts
+ * enforcement: feedback
+ * verification: semantic
+ * -->
+ * Prose that follows until the next heading or comment.
+ * ```
+ */
+const BLOCK_RE = /<!--\s*speclaw:law\b([\s\S]*?)-->/gi;
+function parseMeta(raw) {
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const m = /^\s*([a-zA-Z_][\w-]*)\s*:\s*(.*?)\s*$/.exec(line);
+        if (m)
+            out[m[1].toLowerCase()] = m[2];
+    }
+    return out;
+}
+function verificationOf(kind) {
+    switch (kind) {
+        case "path":
+            return { kind: "path" };
+        case "ast":
+            return { kind: "ast" };
+        case "deps":
+            return { kind: "deps", rule: { from: "^", to: "^", type: "forbidden" } };
+        case "graph":
+            return { kind: "graph", rule: { circular: true } };
+        case "process":
+            return { kind: "process" };
+        case "traceability":
+            return { kind: "traceability" };
+        case "none":
+            return { kind: "none" };
+        case "semantic":
+        default:
+            return { kind: "semantic" };
+    }
+}
+function proseAfter(content, endIndex) {
+    const rest = content.slice(endIndex);
+    const next = rest.search(/\n#{1,3}\s|\n<!--\s*speclaw:law\b/i);
+    const chunk = (next === -1 ? rest : rest.slice(0, next)).trim();
+    return chunk.replace(/^#+\s*.*$/m, "").trim() || "(no prose)";
+}
+/**
+ * Parse one markdown file for `speclaw:law` blocks.
+ *
+ * @param fileRel - Project-relative path recorded on each law's `source`.
+ * @param content - File contents.
+ */
+export function parseLawsFromMarkdown(fileRel, content) {
+    const laws = [];
+    let m;
+    const re = new RegExp(BLOCK_RE.source, "gi");
+    while ((m = re.exec(content)) !== null) {
+        const meta = parseMeta(m[1] ?? "");
+        const id = meta.id?.trim();
+        if (!id)
+            continue;
+        const line = content.slice(0, m.index).split(/\r?\n/).length;
+        const scope = (meta.scope ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const severity = (meta.severity ?? "warn");
+        const enforcement = (meta.enforcement ?? "feedback");
+        const title = meta.title?.trim() || id;
+        const prose = proseAfter(content, m.index + m[0].length);
+        laws.push({
+            id,
+            title,
+            severity: ["error", "warn", "info"].includes(severity) ? severity : "warn",
+            scope,
+            prose,
+            verification: verificationOf(meta.verification),
+            enforcement: ["bloqueo", "feedback", "gate"].includes(enforcement) ? enforcement : "feedback",
+            source: { file: fileRel, line },
+            status: meta.status === "draft" ? "draft" : "active",
+        });
+    }
+    return laws;
+}
+/**
+ * Walk `docs/standards/**\/*.md` under the project and parse law blocks.
+ * Collects duplicate ids across files into {@link ParseLawsResult.duplicates}.
+ */
+export function parseLawsFromStandards(projectPath) {
+    const root = path.join(projectPath, "docs", "standards");
+    const laws = [];
+    const seen = new Map();
+    if (!fs.existsSync(root))
+        return { laws, duplicates: seen };
+    const walk = (dir) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!ent.name.endsWith(".md"))
+                continue;
+            const rel = path.relative(projectPath, abs).split(path.sep).join("/");
+            const content = fs.readFileSync(abs, "utf8");
+            for (const law of parseLawsFromMarkdown(rel, content)) {
+                const locs = seen.get(law.id) ?? [];
+                locs.push(`${law.source.file}:${law.source.line ?? "?"}`);
+                seen.set(law.id, locs);
+                laws.push(law);
+            }
+        }
+    };
+    walk(root);
+    const duplicates = new Map();
+    for (const [id, locs] of seen) {
+        if (locs.length > 1)
+            duplicates.set(id, locs);
+    }
+    // Keep first occurrence of each id in `laws` when reporting merge later;
+    // callers must fail if duplicates.size > 0.
+    return { laws, duplicates };
+}

package/dist/modules/foundation/laws.js

@@ -44,7 +44,12 @@ const lawSchema = z.object({
     verification: verificationSchema,
     enforcement: z.enum(["bloqueo", "feedback", "gate"]),
     source: z.object({ file: z.string(), line: z.number().optional() }),
+    status: z.enum(["active", "draft"]).optional(),
 });
+/** True when a law participates in enforcement (default active). */
+export function isActiveLaw(law) {
+    return (law.status ?? "active") !== "draft";
+}
 // Reject a malformed `from`/`to` regex when the manifest is validated — naming
 // the law id, not a bare array index — rather than letting it explode at verify
 // time. Mirrors the generation-time treatment of malformed globs.