@esneiderbravo/speclaw 0.4.0 → 1.0.0

package/dist/modules/foundation/doctor.js

@@ -5,14 +5,18 @@ import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
 import { isGitRepo } from "../../shared/git.js";
 import { readManifest } from "../../shared/manifest.js";
 import { pkgName, pkgVersion } from "../../shared/version.js";
-import { indexExists, openDb } from "../compass/db.js";
+import { indexExists, openDb, probeFts5Support } from "../compass/db.js";
+import { getEmbedder } from "../compass/embedder.js";
 import { specList } from "../lawbook/engine.js";
 import { doctorDriftCheck } from "../lawbook/drift.js";
 import { loadCeremonyConfig } from "../lawbook/levels.js";
+import { doctorOwnersChecks } from "../team/owners.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
+import { estimateAlwaysOnTokens } from "./compile-laws.js";
 import { redactValue } from "../../shared/redact.js";
 import { readDeprecatedCallCounts, scanRetiredToolReferences } from "../../shared/deprecation.js";
 import { CANONICAL_TOOLS, ALIAS_TARGETS, isCanonicalTool } from "../../shared/tool-catalog.js";
+import { discoverIntegrityPaths, lockfilePath, readLockfile, rootDigest } from "./lock.js";
 const STATUS_RANK = {
     skip: 0,
     ok: 1,
@@ -48,18 +52,29 @@ function detectInstallKind() {
 function enginesRequirement() {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
-        return pkg.engines?.node ?? ">=22";
+        return pkg.engines?.node ?? ">=22.16";
     }
     catch {
-        return ">=22";
+        return ">=22.16";
     }
 }
 function nodeSatisfies(required, version) {
-    const m = /^>=\s*(\d+)/.exec(required.trim());
+    const m = /^>=\s*(\d+)(?:\.(\d+))?/.exec(required.trim());
     if (!m)
         return true;
-    const major = parseInt(version.replace(/^v/, "").split(".")[0], 10);
-    return major >= parseInt(m[1], 10);
+    const parts = version
+        .replace(/^v/, "")
+        .split(".")
+        .map((x) => parseInt(x, 10));
+    const major = parts[0] ?? 0;
+    const minor = parts[1] ?? 0;
+    const needMajor = parseInt(m[1], 10);
+    const needMinor = m[2] !== undefined ? parseInt(m[2], 10) : 0;
+    if (major > needMajor)
+        return true;
+    if (major < needMajor)
+        return false;
+    return minor >= needMinor;
 }
 function libcLabel() {
     if (process.platform !== "linux")
@@ -179,6 +194,25 @@ function buildEnvironment(projectPath) {
         detail: git ? "repository" : "not a git repository",
         remedy: git ? undefined : "git init",
     });
+    const ftsOk = probeFts5Support();
+    addCheck(checks, {
+        id: "env.fts5",
+        title: "fts5",
+        status: ftsOk ? "ok" : "warn",
+        value: ftsOk,
+        detail: ftsOk
+            ? "node:sqlite FTS5 available"
+            : "FTS5 unavailable — hybrid search degrades to vector+name (need Node >=22.16)",
+        remedy: ftsOk ? undefined : "Upgrade to Node.js >=22.16",
+    });
+    const embedderId = getEmbedder().id;
+    addCheck(checks, {
+        id: "env.embedder",
+        title: "embedder",
+        status: "ok",
+        value: embedderId,
+        detail: `active embedder: ${embedderId}`,
+    });
     addCheck(checks, {
         id: "env.ast-engine",
         title: "ast engine",
@@ -369,12 +403,23 @@ function lawsCheck(projectPath) {
     }
     const withPath = manifest.laws.filter(hasBackend).length;
     const withBatch = manifest.laws.filter(hasBatchBackend).length;
+    const budget = estimateAlwaysOnTokens(manifest.laws);
+    if (budget.total > 2000) {
+        const top = budget.top.map((t) => `${t.id}(~${t.tokens})`).join(", ");
+        return {
+            id: "cfg.laws",
+            title: "laws",
+            status: "warn",
+            detail: `always-on laws ~${budget.total} tokens (budget 2000); top: ${top || "n/a"}`,
+            remedy: "Add scope globs to the largest always-on laws, then speclaw laws compile",
+        };
+    }
     return {
         id: "cfg.laws",
         title: "laws",
         status: "ok",
         value: manifest.laws.length,
-        detail: `${manifest.laws.length} declared · ${withPath} path · ${withBatch} deps/graph · 0 invalid`,
+        detail: `${manifest.laws.length} declared · ${withPath} path · ${withBatch} deps/graph · always-on ~${budget.total} tokens`,
     };
 }
 async function budgetCheck(projectPath) {
@@ -512,6 +557,154 @@ function specsOrphansCheck(projectPath) {
         remedy: `speclaw lawbook archive ${active[0]}`,
     };
 }
+function integrityChecks(projectPath) {
+    // Covers: req~doctor-integrity~1
+    const out = [];
+    const abs = lockfilePath(projectPath);
+    if (!fs.existsSync(abs)) {
+        out.push({
+            id: "cfg.integrity.lock",
+            title: "rule lockfile",
+            status: "warn",
+            detail: "no speclaw.lock — rule digests are not pinned",
+            remedy: "speclaw laws lock",
+        });
+    }
+    else {
+        try {
+            const lock = readLockfile(projectPath);
+            const matches = rootDigest(lock.files) === lock.root;
+            out.push({
+                id: "cfg.integrity.lock",
+                title: "rule lockfile",
+                status: matches ? "ok" : "warn",
+                value: matches,
+                detail: matches
+                    ? `speclaw.lock root matches (${Object.keys(lock.files).length} files)`
+                    : "speclaw.lock root does not match recomputed digests",
+                remedy: matches ? undefined : "speclaw laws lock",
+            });
+        }
+        catch (err) {
+            out.push({
+                id: "cfg.integrity.lock",
+                title: "rule lockfile",
+                status: "error",
+                detail: err.message,
+                remedy: "speclaw laws lock",
+            });
+        }
+    }
+    const imports = findExternalImports(projectPath, 4);
+    out.push({
+        id: "cfg.integrity.imports",
+        title: "external rule imports",
+        status: imports.length ? "warn" : "ok",
+        value: imports.length ? imports.slice(0, 8).join("; ") : null,
+        detail: imports.length
+            ? `${imports.length} external @import hop(s) (≤4): ${imports.slice(0, 5).join("; ")}`
+            : "no external @import / @~/ paths detected in rule files",
+        remedy: imports.length
+            ? "review imports that resolve outside the working directory"
+            : undefined,
+    });
+    const { files } = discoverIntegrityPaths(projectPath);
+    const outside = files.filter((f) => {
+        const n = f.split("\\").join("/");
+        return (n === ".clinerules" ||
+            n === ".windsurfrules" ||
+            n === "BUGBOT.md" ||
+            n === ".cursorrules" ||
+            n.startsWith("ai-specs/skills/") ||
+            n.startsWith(".claude/skills/"));
+    });
+    out.push({
+        id: "cfg.integrity.outside-pipeline",
+        title: "outside-pipeline rules",
+        status: "ok",
+        value: outside.length,
+        detail: outside.length > 0
+            ? `${outside.length} scan-only / outside-pipeline path(s): ${outside.slice(0, 6).join(", ")}`
+            : "no outside-pipeline rule files discovered",
+    });
+    return out;
+}
+/**
+ * Follow `@~/…`, absolute `@/…`, and `@import "…"` targets outside the project,
+ * transitively up to `maxHops`.
+ */
+/* node:coverage disable */
+function findExternalImports(projectPath, maxHops) {
+    const roots = [
+        "CLAUDE.md",
+        "AGENTS.md",
+        "LAWS.md",
+        ".cursorrules",
+        ".clinerules",
+        ".windsurfrules",
+    ];
+    const seen = new Set();
+    const out = [];
+    const queue = [];
+    for (const r of roots) {
+        const abs = path.join(projectPath, r);
+        if (fs.existsSync(abs))
+            queue.push({ file: abs, hop: 0 });
+    }
+    while (queue.length) {
+        const { file, hop } = queue.shift();
+        if (hop > maxHops || seen.has(file))
+            continue;
+        seen.add(file);
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split(/\r?\n/)) {
+            const m = /@([~/][^\s)\]>"']+)/.exec(line) ??
+                /@import\s+["']([^"']+)["']/.exec(line) ??
+                /@([A-Za-z]:[^\s)\]>"']+)/.exec(line);
+            if (!m)
+                continue;
+            const target = m[1];
+            const resolved = resolveImportTarget(file, target);
+            if (!resolved)
+                continue;
+            const projectRoot = path.resolve(projectPath);
+            const outside = target.startsWith("~/") ||
+                path.isAbsolute(target) ||
+                !resolved.startsWith(projectRoot + path.sep);
+            if (outside) {
+                const label = `${path.relative(projectPath, file) || path.basename(file)} → ${target}`;
+                out.push(label);
+                if (hop < maxHops && fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+                    queue.push({ file: resolved, hop: hop + 1 });
+                }
+            }
+        }
+    }
+    return out;
+}
+function resolveImportTarget(fromFile, target) {
+    if (target.startsWith("~/")) {
+        const home = process.env.HOME || process.env.USERPROFILE || "";
+        if (!home)
+            return null;
+        return path.resolve(home, target.slice(2));
+    }
+    if (target.startsWith("/") || /^[A-Za-z]:/.test(target))
+        return path.resolve(target);
+    if (target.startsWith("./") || target.startsWith("../")) {
+        return path.resolve(path.dirname(fromFile), target);
+    }
+    if (!target.includes("://"))
+        return path.resolve(path.dirname(fromFile), target);
+    return null;
+}
+/* node:coverage enable */
 /** Ceremony config validity + archived level histogram. */
 function ceremonyChecks(projectPath) {
     const out = [];
@@ -617,13 +810,16 @@ function configurationChecks(projectPath, initialised) {
             "cfg.index.freshness",
             "cfg.specs.orphans",
         ];
-        return ids.map((id) => ({
-            id,
-            title: id.replace(/^cfg\./, ""),
-            status: "skip",
-            detail: "project not initialised",
-            remedy: "speclaw init",
-        }));
+        return [
+            ...ids.map((id) => ({
+                id,
+                title: id.replace(/^cfg\./, ""),
+                status: "skip",
+                detail: "project not initialised",
+                remedy: "speclaw init",
+            })),
+            ...integrityChecks(projectPath),
+        ];
     }
     const checks = [];
     const manifest = readManifest(projectPath);
@@ -650,6 +846,7 @@ function configurationChecks(projectPath, initialised) {
         remedy: "speclaw update",
     });
     checks.push(lawsCheck(projectPath));
+    checks.push(...integrityChecks(projectPath));
     // budget + mcp + freshness + specs filled async by caller
     return checks;
 }
@@ -709,6 +906,15 @@ export async function doctor(projectPath, opts = {}) {
                 remedy: d.remedy,
             });
         }
+        for (const o of doctorOwnersChecks(projectPath)) {
+            addCheck(configuration, {
+                id: o.id,
+                title: o.title,
+                status: o.status,
+                detail: o.detail,
+                remedy: o.remedy,
+            });
+        }
         const configured = detectConfiguredAgents(projectPath);
         const mcpAgents = AGENTS.filter((a) => a.mcpFile && configured.includes(a.id));
         if (mcpAgents.length === 0) {

package/dist/modules/foundation/import-rules.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readLawManifest, writeLawManifest } from "./laws.js";
+/**
+ * Import rulesync-style markdown rules under `.rulesync/` or `rulesync/` into
+ * draft semantic laws and append them to the manifest.
+ */
+export function importRulesFrom(projectPath, from) {
+    if (from !== "rulesync") {
+        throw new Error(`unsupported import source "${from}" — try rulesync`);
+    }
+    const candidates = [".rulesync", "rulesync", ".rulesync/rules", "rulesync/rules"];
+    let root = null;
+    for (const c of candidates) {
+        const abs = path.join(projectPath, c);
+        if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+            root = abs;
+            break;
+        }
+    }
+    if (!root) {
+        throw new Error("no rulesync rules directory found (.rulesync/ or rulesync/)");
+    }
+    const report = { imported: [], skipped: [] };
+    const existing = readLawManifest(projectPath) ?? { version: 1, laws: [] };
+    const have = new Set(existing.laws.map((l) => l.id));
+    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 (!/\.(md|mdc)$/i.test(ent.name))
+                continue;
+            const rel = path.relative(projectPath, abs).split(path.sep).join("/");
+            const prose = fs.readFileSync(abs, "utf8").trim() || "(empty rule)";
+            const slug = ent.name
+                .replace(/\.(md|mdc)$/i, "")
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "");
+            const id = `law~import-rulesync-${slug}~1`;
+            if (have.has(id)) {
+                report.skipped.push(id);
+                continue;
+            }
+            const law = {
+                id,
+                title: `Imported: ${ent.name}`,
+                severity: "warn",
+                scope: [],
+                prose,
+                verification: { kind: "semantic" },
+                enforcement: "feedback",
+                source: { file: rel, line: 1 },
+                status: "draft",
+            };
+            existing.laws.push(law);
+            have.add(id);
+            report.imported.push(id);
+        }
+    };
+    walk(root);
+    writeLawManifest(projectPath, existing);
+    return report;
+}

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);
+}