@esneiderbravo/speclaw 0.4.0 → 1.0.1

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

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assetsDir } from "../../shared/paths.js";
+// Catalog adapter: the shipped JSON is speclaw's own architecture plus a few
+// portable laws. Consumer repos get only what their tree can actually host —
+// never compass/foundation/ATTRIBUTION rules copied from this package.
+//
+// Types are declared here (not imported from laws.ts) so the adapter and the
+// schema do not form a file-level import cycle.
+const ASSETS = assetsDir(import.meta.url);
+const CATALOG_PATH = path.join(ASSETS, "laws", "laws-manifest.json");
+/** Globs that drop test doubles from the cycle-law graph. */
+export const TEST_SCOPE_EXCLUSIONS = [
+    "!**/*.{spec,test}.{ts,tsx,js,jsx}",
+    "!**/test/**",
+    "!**/__tests__/**",
+];
+let cachedCatalog = null;
+/**
+ * Read the shipped law catalog (including adapter metadata). Cached for the
+ * process; tests that mutate the asset are not a supported path.
+ *
+ * @returns The parsed catalog.
+ * @throws If the asset is missing or not an object with a `laws` array.
+ */
+export function readLawCatalog() {
+    if (cachedCatalog)
+        return cachedCatalog;
+    const raw = JSON.parse(fs.readFileSync(CATALOG_PATH, "utf8"));
+    if (!raw || !Array.isArray(raw.laws)) {
+        throw new Error(`invalid law catalog at ${CATALOG_PATH}`);
+    }
+    cachedCatalog = raw;
+    return raw;
+}
+/** Drop adapter-only fields so the result is a persistable law. */
+export function asLaw(entry) {
+    const law = {
+        id: entry.id,
+        title: entry.title,
+        severity: entry.severity,
+        scope: [...entry.scope],
+        prose: entry.prose,
+        verification: structuredClone(entry.verification),
+        enforcement: entry.enforcement,
+        source: { ...entry.source },
+    };
+    if (entry.rationale !== undefined)
+        law.rationale = entry.rationale;
+    if (entry.status !== undefined)
+        law.status = entry.status;
+    return law;
+}
+/**
+ * Whether `req` names an existing file, directory, or glob under `projectPath`.
+ *
+ * @param projectPath - Project root.
+ * @param req - Relative path or glob (`*` / `**` in a segment).
+ */
+export function pathRequirementExists(projectPath, req) {
+    const trimmed = req.replace(/^!/, "").replace(/\/\*\*$/, "");
+    return globExists(projectPath, trimmed.split("/").filter(Boolean));
+}
+function globExists(dir, parts) {
+    if (parts.length === 0)
+        return fs.existsSync(dir);
+    if (!fs.existsSync(dir))
+        return false;
+    const head = parts[0];
+    const rest = parts.slice(1);
+    if (head === "**") {
+        if (globExists(dir, rest))
+            return true;
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isDirectory())
+            return false;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith("."))
+                continue;
+            if (globExists(path.join(dir, name), parts))
+                return true;
+        }
+        return false;
+    }
+    if (head === "*") {
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isDirectory())
+            return false;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith("."))
+                continue;
+            if (globExists(path.join(dir, name), rest))
+                return true;
+        }
+        return false;
+    }
+    return globExists(path.join(dir, head), rest);
+}
+function childSrcExists(projectPath, parent) {
+    const dir = path.join(projectPath, parent);
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    for (const name of fs.readdirSync(dir)) {
+        if (name.startsWith("."))
+            continue;
+        try {
+            if (fs.statSync(path.join(dir, name, "src")).isDirectory())
+                return true;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return false;
+}
+/**
+ * Source-root globs inferred from a repository layout.
+ *
+ * @param projectPath - Project root.
+ * @returns Globs covering app/package `src` trees, plus top-level `src/` or `lib/`, when they exist.
+ */
+export function detectSourceRootGlobs(projectPath) {
+    const out = [];
+    if (childSrcExists(projectPath, "apps"))
+        out.push("apps/*/src/**");
+    if (childSrcExists(projectPath, "packages"))
+        out.push("packages/*/src/**");
+    if (pathRequirementExists(projectPath, "src"))
+        out.push("src/**");
+    if (pathRequirementExists(projectPath, "lib"))
+        out.push("lib/**");
+    return out;
+}
+function positivesSatisfied(projectPath, scope) {
+    const positives = scope.filter((g) => !g.startsWith("!"));
+    if (positives.length === 0)
+        return true;
+    return positives.some((g) => pathRequirementExists(projectPath, g));
+}
+function withTestExclusions(scope) {
+    const have = new Set(scope);
+    const out = [...scope];
+    for (const g of TEST_SCOPE_EXCLUSIONS) {
+        if (!have.has(g))
+            out.push(g);
+    }
+    return out;
+}
+function adaptCycleLaw(projectPath, entry) {
+    const law = asLaw(entry);
+    const catalogHits = positivesSatisfied(projectPath, entry.scope);
+    const roots = catalogHits
+        ? entry.scope.filter((g) => !g.startsWith("!"))
+        : detectSourceRootGlobs(projectPath);
+    if (roots.length === 0)
+        return null;
+    law.scope = withTestExclusions(roots);
+    if (law.verification.kind === "graph") {
+        law.verification = {
+            kind: "graph",
+            rule: { ...(law.verification.rule ?? {}), circular: true, edgeKinds: ["import"] },
+        };
+    }
+    return law;
+}
+function isApplicable(projectPath, entry) {
+    const reqs = entry.requires ?? [];
+    return reqs.every((r) => pathRequirementExists(projectPath, r));
+}
+/**
+ * Catalog laws stripped of adapter metadata — the full shipped set, unfiltered.
+ *
+ * @returns Persistable laws in catalog order.
+ */
+export function catalogLaws() {
+    return readLawCatalog().laws.map(asLaw);
+}
+/**
+ * Laws from the catalog that apply to `projectPath`, with cycle-law scope
+ * rewritten to the repo's real source roots when needed.
+ *
+ * @param projectPath - Project root whose tree is inspected.
+ * @returns Persistable laws; adapter fields omitted.
+ */
+export function adaptedLaws(projectPath) {
+    // Covers: req~adapt-seed-to-repo~1
+    const out = [];
+    for (const entry of readLawCatalog().laws) {
+        if (!isApplicable(projectPath, entry))
+            continue;
+        if (entry.adaptScope === "source-roots") {
+            const adapted = adaptCycleLaw(projectPath, entry);
+            if (adapted)
+                out.push(adapted);
+            continue;
+        }
+        out.push(asLaw(entry));
+    }
+    return out;
+}
+/** True when `existing` is still the shipped catalog text (title + prose). */
+export function isUnmodifiedCatalogLaw(existing, catalog) {
+    return existing.title === catalog.title && existing.prose === catalog.prose;
+}
+/**
+ * Merge an on-disk manifest with the adapted catalog: append applicable ids,
+ * rewrite unmodified cycle-law scope, drop unmodified inapplicable dogfood.
+ *
+ * @param existing - The project's current manifest.
+ * @param projectPath - Project root used to adapt the catalog.
+ * @returns The merged manifest and the ids that were added or removed.
+ */
+export function mergeAdaptedSeed(existing, projectPath) {
+    const catalog = readLawCatalog();
+    const byId = new Map(catalog.laws.map((l) => [l.id, l]));
+    const adapted = adaptedLaws(projectPath);
+    const adaptedById = new Map(adapted.map((l) => [l.id, l]));
+    const added = [];
+    const removed = [];
+    const result = [];
+    const seen = new Set();
+    for (const law of existing.laws) {
+        const cat = byId.get(law.id);
+        if (!cat || !isUnmodifiedCatalogLaw(law, cat)) {
+            result.push(law);
+            seen.add(law.id);
+            continue;
+        }
+        const next = adaptedById.get(law.id);
+        if (next) {
+            result.push(next);
+            seen.add(law.id);
+        }
+        else {
+            removed.push(law.id);
+        }
+    }
+    for (const law of adapted) {
+        if (seen.has(law.id))
+            continue;
+        result.push(law);
+        added.push(law.id);
+        seen.add(law.id);
+    }
+    return { manifest: { ...existing, laws: result }, added, removed };
+}

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";
@@ -17,8 +17,8 @@ export { underPaths } from "./verify-model.js";
  *
  * When the project has no index, every selected batch law is reported as
  * `skipped` with reason `no-index` (never silently passed). When the gitignored
- * manifest file is missing, the shipped seed is used so a clean clone does not
- * report an empty pass. Each evaluated law lands in exactly one of `passed` /
+ * manifest file is missing, the adapted seed is used so a clean clone does not
+ * report an empty pass or inherit inapplicable dogfood laws. Each evaluated law lands in exactly one of `passed` /
  * `failed` / `unknown`: it fails when the engine produced a finding, is
  * `unknown` when it produced none but rests on unresolved edges (which could
  * hide a violation), and passes otherwise.
@@ -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);