@esneiderbravo/speclaw 0.4.0 → 1.0.0

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

package/dist/modules/foundation/verify.js

@@ -1,6 +1,6 @@
 import { performance } from "node:perf_hooks";
 import { openDb, indexExists } from "../compass/db.js";
-import { hasBatchBackend, loadManifestForVerify } from "./laws.js";
+import { hasBatchBackend, isActiveLaw, loadManifestForVerify } from "./laws.js";
 import { runDepsLaw } from "./deps.js";
 import { runGraphLaw } from "./graph.js";
 export { underPaths } from "./verify-model.js";
@@ -50,6 +50,14 @@ export function verifyLaws(args) {
     const manifest = loadManifestForVerify(args.projectPath);
     const engines = args.engines;
     const selected = manifest.laws.filter((law) => {
+        if (!isActiveLaw(law)) {
+            skipped.push({
+                lawId: law.id,
+                reason: "draft",
+                detail: "status=draft — pending human activation; does not gate",
+            });
+            return false;
+        }
         if (!hasBatchBackend(law))
             return false;
         if (args.lawIds && !args.lawIds.includes(law.id))

package/dist/modules/lawbook/coverage.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { openDb, indexExists } from "../compass/db.js";
+import { detectPropertyRunnerInWindow, loadPropertyRunners } from "./ears.js";
 import { formatItemId, loadSpecItems, parseItemId, parseSpecItems, } from "./spec-items.js";
 export const DEFAULT_COVERAGE_CONFIG = {
     defaultNeeds: ["impl", "utest"],
@@ -10,8 +11,10 @@ export const DEFAULT_COVERAGE_CONFIG = {
         impl: ["src/**"],
         utest: ["test/unit/**", "test/**/*.test.ts", "test/**/*.test.js"],
         itest: ["test/integration/**"],
+        ptest: ["test/property/**"],
     },
     exclude: ["**/node_modules/**", "**/dist/**", "**/.speclaw/**"],
+    propertyRunners: [],
 };
 /**
  * Load coverage config from lawbook/config.yaml when present; otherwise defaults.
@@ -20,8 +23,10 @@ export const DEFAULT_COVERAGE_CONFIG = {
 export function loadCoverageConfig(projectPath) {
     const cfg = structuredClone(DEFAULT_COVERAGE_CONFIG);
     const cfgPath = path.join(projectPath, "lawbook", "config.yaml");
-    if (!fs.existsSync(cfgPath))
+    if (!fs.existsSync(cfgPath)) {
+        cfg.propertyRunners = loadPropertyRunners(projectPath);
         return cfg;
+    }
     const text = fs.readFileSync(cfgPath, "utf8");
     const gate = /^\s*gateArchive\s*:\s*(true|false)\s*$/im.exec(text);
     if (gate)
@@ -43,8 +48,21 @@ export function loadCoverageConfig(projectPath) {
             .toLowerCase())
             .filter(Boolean);
     }
+    cfg.propertyRunners = loadPropertyRunners(projectPath);
     return cfg;
 }
+/**
+ * Effective coverage needs for an item: explicit `Needs:` or defaults, plus
+ * `ptest` when `Verification: property` is declared.
+ */
+// Covers: req~ptest-need~1, req~ptest-archive-gate~1
+export function effectiveNeeds(item, cfg) {
+    const needs = item.needs.length > 0 ? [...item.needs] : [...cfg.defaultNeeds];
+    if (item.verification === "property" && !needs.includes("ptest")) {
+        needs.push("ptest");
+    }
+    return needs;
+}
 /** Glob match supporting `**`, `*`, and path separators. */
 export function matchGlob(relPath, pattern) {
     const norm = relPath.split("\\").join("/");
@@ -78,13 +96,33 @@ export function inferArtifactType(relPath, cfg) {
     const norm = relPath.split("\\").join("/");
     if (cfg.exclude.some((g) => matchGlob(norm, g)))
         return null;
-    for (const type of ["itest", "utest", "impl"]) {
+    for (const type of ["ptest", "itest", "utest", "impl"]) {
         const globs = cfg.sources[type] ?? [];
         if (globs.some((g) => matchGlob(norm, g)))
             return type;
     }
     return null;
 }
+/**
+ * Prefer `ptest` when a property-runner invocation sits near the link line.
+ */
+// Covers: req~ptest-need~1
+export function refineSourceType(projectPath, filePath, line, current, runners) {
+    if (runners.length === 0)
+        return current;
+    const abs = path.isAbsolute(filePath) ? filePath : path.join(projectPath, filePath);
+    if (!fs.existsSync(abs))
+        return current;
+    let source;
+    try {
+        source = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return current;
+    }
+    const hit = detectPropertyRunnerInWindow(source, line, runners);
+    return hit ? "ptest" : current;
+}
 function readIndexLinks(projectPath) {
     if (!indexExists(projectPath))
         return [];
@@ -135,7 +173,7 @@ function inlineLinksAsRaw(projectPath, items, cfg) {
     }
     return out;
 }
-function classifyLink(link, item, idCounts, cfg) {
+function classifyLink(link, item, idCounts, cfg, projectPath) {
     const base = {
         artifactType: link.artifactType,
         name: link.name,
@@ -172,6 +210,7 @@ function classifyLink(link, item, idCounts, cfg) {
     const inferred = inferArtifactType(link.filePath, cfg);
     if (inferred)
         base.sourceType = inferred;
+    base.sourceType = refineSourceType(projectPath, link.filePath, link.line, base.sourceType, cfg.propertyRunners);
     return base;
 }
 /**
@@ -198,12 +237,12 @@ export function buildCoverageReport(projectPath, opts = {}) {
     const matchedKeys = new Set();
     for (const item of identified) {
         const idText = item.idText;
-        const needs = item.needs.length > 0 ? item.needs : [...cfg.defaultNeeds];
+        const needs = effectiveNeeds(item, cfg);
         const itemLinks = rawLinks
             .filter((l) => l.artifactType === item.id.artifactType && l.name === item.id.name)
             .map((l) => {
             matchedKeys.add(`${l.filePath}:${l.line}:${l.revision}:${l.kind}`);
-            return classifyLink(l, item, idCounts, cfg);
+            return classifyLink(l, item, idCounts, cfg, projectPath);
         });
         const covering = itemLinks.filter((l) => l.status === "Covers");
         const coveredTypes = [...new Set(covering.map((l) => l.sourceType))];
@@ -282,7 +321,7 @@ export function buildCoverageReport(projectPath, opts = {}) {
         const key = `${l.filePath}:${l.line}:${l.revision}:${l.kind}`;
         if (matchedKeys.has(key))
             continue;
-        orphans.push(classifyLink(l, undefined, idCounts, cfg));
+        orphans.push(classifyLink(l, undefined, idCounts, cfg, projectPath));
     }
     const gated = results.filter((r) => cfg.gateStatuses.includes(r.status));
     const directDefects = gated.reduce((n, r) => n + r.directDefects.length, 0);