@jjchill/probity-rules 0.1.0

package/dist/rules/scoping.js

@@ -0,0 +1,93 @@
+import picomatch from 'picomatch';
+/**
+ * Replica of Probity's glob-scoping internals, for the tooling in
+ * this template set — the workflow eval and `scripts/scope-report.ts`
+ * — which must resolve `{ files, rules }` blocks exactly the way the
+ * real engine does. Hand-mirrored scoping predicates were the eval's
+ * main blind spot: a template glob edit could silently diverge from
+ * what the eval exercised.
+ *
+ * Probity implements these in `src/rules/utils/match-paths.ts`
+ * (`buildMatcher`, `actionMatchesFilesScope`) and `src/config.ts`
+ * (`anchorGlob` inside `loadConfig`), but its package `exports` map
+ * (".", "./types", "./rules") does not expose them, so they are
+ * ported here verbatim — same picomatch options, same anchoring
+ * convention. Pinned against @nizos/probity 1.10.0: on a Probity
+ * upgrade, diff this file against those two sources; if upstream
+ * starts exporting them, delete this file and import instead.
+ *
+ * picomatch is Probity's own matcher dependency, so the same version
+ * resolves here in any project with @nizos/probity installed; if your
+ * package manager doesn't hoist it, add it: `npm install -D picomatch`.
+ */
+/** A `Config.rules` entry that carries a `files` scope. */
+export function isRuleBlock(entry) {
+    return typeof entry !== 'function';
+}
+/**
+ * Builds a path matcher from include/exclude patterns. Patterns
+ * prefixed with `!` are negations (picomatch's `ignore` option);
+ * everything else is an include. An all-negations list gets `**` as
+ * the default include. `dot: true` so `*`/`**` traverse dot-prefixed
+ * segments — without it a scoped rule silently skips dotfiles.
+ *
+ * Port of @nizos/probity `src/rules/utils/match-paths.ts#buildMatcher`.
+ */
+export function buildMatcher(patterns) {
+    if (patterns.length === 0)
+        return () => false;
+    const includes = patterns.filter((p) => !p.startsWith('!'));
+    const ignore = patterns
+        .filter((p) => p.startsWith('!'))
+        .map((p) => p.slice(1));
+    const matcher = picomatch(includes.length ? [...includes] : '**', {
+        dot: true,
+        ignore,
+    });
+    return (path) => matcher(path);
+}
+/**
+ * Whether a `{ files, rules }` block applies to an action. Empty
+ * `files` matches nothing; non-write actions (commands) pass the
+ * block-level filter and rules self-filter by action kind; write
+ * actions are matched against `files`.
+ *
+ * Port of @nizos/probity
+ * `src/rules/utils/match-paths.ts#actionMatchesFilesScope`.
+ */
+export function actionMatchesFilesScope(files, action) {
+    if (files.length === 0)
+        return false;
+    if (action.kind !== 'write')
+        return true;
+    return buildMatcher(files)(action.path);
+}
+/**
+ * `**`-prefixed globs are intentional "match anywhere" patterns;
+ * anchoring them at the config dir would defeat the user's intent.
+ * Negations carry the same convention through the `!` prefix.
+ *
+ * Port of @nizos/probity `src/config.ts#anchorGlob`.
+ */
+export function anchorGlob(glob, root) {
+    if (glob.startsWith('!'))
+        return '!' + anchorGlob(glob.slice(1), root);
+    if (glob.startsWith('**'))
+        return glob;
+    return `${root.replace(/\\/g, '/').replace(/\/$/, '')}/${glob}`;
+}
+/**
+ * Anchors every block's relative globs against `root`, the way
+ * Probity's `loadConfig` anchors them against the config file's
+ * directory — so paths in `Action.path` (absolute POSIX) match
+ * regardless of where the session is rooted. Flat rules pass through.
+ */
+export function anchorEntries(entries, root) {
+    return entries.map((entry) => {
+        if (!isRuleBlock(entry) || !entry.files)
+            return entry;
+        const [first, ...rest] = entry.files.map((glob) => anchorGlob(glob, root));
+        return { ...entry, files: [first, ...rest] };
+    });
+}
+//# sourceMappingURL=scoping.js.map

package/dist/rules/scoping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoping.js","sourceRoot":"","sources":["../../rules/scoping.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,WAAW,CAAA;AAIjC;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,KAAgB;IAC1C,OAAO,OAAO,KAAK,KAAK,UAAU,CAAA;AACpC,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,QAA2B;IAE3B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,KAAK,CAAA;IAC7C,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;IAC3D,MAAM,MAAM,GAAG,QAAQ;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACzB,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;QAChE,GAAG,EAAE,IAAI;QACT,MAAM;KACP,CAAC,CAAA;IACF,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAwB,EACxB,MAAc;IAEd,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACpC,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAA;IACxC,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAY;IACnD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;IACtE,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACtC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAA;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,OAA6B,EAC7B,IAAY;IAEZ,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC3B,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,KAAK,CAAA;QACrD,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;QAC1E,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,KAAM,EAAE,GAAG,IAAI,CAAU,EAAE,CAAA;IACxD,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/rules/spec-test-parity.d.ts

@@ -0,0 +1,164 @@
+import type { Rule } from '@nizos/probity';
+type Scenario = {
+    key: string;
+    specFile: string;
+    title: string;
+    wip: boolean;
+    /** Driver scopes the heading declares, e.g. `[system]` → ['system']. */
+    scopes: string[];
+};
+type CoversRef = {
+    key: string;
+    testFile: string;
+    specFile: string;
+    title: string;
+};
+export declare function extractScenarios(specFile: string, content: string): Scenario[];
+export declare function extractCoversRefs(testFile: string, content: string): CoversRef[];
+/**
+ * A named driver scope: which test files count as coverage from a
+ * given driver suite. Scope names are the vocabulary scenario
+ * headings may use in `[scope, ...]` tags — lowercase by convention
+ * (tags are lowercased before matching).
+ */
+export type DriverScope = {
+    name: string;
+    filePattern: RegExp;
+};
+type ScanOptions = {
+    specsDir: string;
+    testRoots: string[];
+    testFilePattern?: RegExp;
+    /**
+     * Per-scenario driver mapping (optional). Each entry names a driver
+     * suite and the test files that belong to it (e.g.
+     * `{ name: 'system', filePattern: /AcceptanceTests[/\\]UITests[/\\]/ }`).
+     * A scenario tagged `## Scenario [system]:` must then be covered by
+     * at least one test matching that scope's pattern — **in addition
+     * to** the base requirement that some acceptance test covers it.
+     * Tags are floors, never ceilings: extra coverage in other scopes
+     * is always fine, and untagged scenarios only need `defaultScopes`
+     * (below) plus the base requirement. A tag naming a scope absent
+     * from this list is a violation (misspelling protection); with no
+     * `driverScopes` configured, any tag is unknown, so adopting tags
+     * requires configuring scopes first.
+     */
+    driverScopes?: DriverScope[];
+    /**
+     * Scope names every non-wip, non-baselined scenario must satisfy
+     * even without a tag — the project's standard driver set (e.g.
+     * `['view-model']`). Names must exist in `driverScopes`. Omit for
+     * the status-quo default: untagged scenarios need any one covering
+     * test, regardless of driver.
+     */
+    defaultScopes?: string[];
+    /**
+     * Incremental-adoption baseline (optional). Path to a text file of
+     * scenario keys — one `<spec>.feature.md :: <title>` per line, `#`
+     * comments allowed — that are exempt from the orphan check. Use it
+     * to adopt the parity gate on a brownfield spec suite: generate the
+     * baseline once (`spec-parity.mjs --baseline <path> --write-baseline`),
+     * commit it, and from then on only scenarios *not* in the baseline
+     * must carry a covering test — new specs are enforced from day one
+     * while the backlog burns down by deleting lines. A missing file
+     * means full enforcement (the greenfield default). Dangling Covers
+     * tags are never baselined: they are actively wrong, not legacy.
+     */
+    baselinePath?: string;
+};
+/** Parses a baseline file into normalized scenario keys. Missing file → empty set. */
+export declare function readBaseline(path: string | undefined): Set<string>;
+/** All spec files (either extension) under a directory. */
+export declare function findSpecFiles(specsDir: string): string[];
+export declare function scanSpecs(specsDir: string): Scenario[];
+export declare function scanCoversRefs(testRoots: string[], testFilePattern: RegExp): CoversRef[];
+/**
+ * Bidirectional parity gate on `git commit`: blocks when any
+ * non-wip `## Scenario:` heading in `specsDir` has no acceptance
+ * test claiming it via a `Covers:` tag, or when any `Covers:` tag
+ * points at a scenario that no longer exists (spec renamed or
+ * removed). Deterministic filesystem scan — no AI call; milliseconds
+ * at typical spec-suite scale.
+ *
+ * The test claiming a scenario may still be red or quarantined —
+ * parity requires the *link*, not a passing run; keeping in-progress
+ * specs out of the pipeline is the pipeline's job. Alternatively
+ * mark the scenario `## Scenario (wip):` to exempt it entirely.
+ *
+ * Applies to: command actions matching `git commit`.
+ *
+ * @param options.specsDir — absolute path to the specs directory
+ *   (e.g. `<root>/docs/specs`). A missing directory passes: no
+ *   specs, nothing to enforce.
+ * @param options.testRoots — absolute paths to scan for acceptance
+ *   tests (the repo root is fine; node_modules/build dirs are
+ *   skipped).
+ * @param options.testFilePattern — which files count as acceptance
+ *   tests (default: any file under an `acceptance/` directory).
+ * @param options.baselinePath — optional incremental-adoption
+ *   baseline; scenarios listed there are exempt from the orphan
+ *   check (see {@link readBaseline}). Missing file → full enforcement.
+ * @param options.driverScopes — optional per-scenario driver mapping;
+ *   see {@link DriverScope}. Scenarios tagged `[scope]` (and every
+ *   scenario, for `defaultScopes` entries) must be covered by a test
+ *   matching that scope's `filePattern`, on top of the base check.
+ * @param options.defaultScopes — scope names required of untagged
+ *   scenarios too (the project's standard driver set).
+ */
+export declare function enforceSpecTestParity(options: ScanOptions): Rule;
+/**
+ * Spec-first, made mechanical: a write that adds a new acceptance
+ * test case is blocked unless it also adds a `Covers:` tag pointing
+ * at a `## Scenario:` heading that ALREADY EXISTS in `specsDir`. The
+ * executable specification (`*.feature.md`) must be written before
+ * the test that claims it — an agent that codes the test first gets
+ * told exactly what to create and where.
+ *
+ * This is the write-time front half of the traceability story;
+ * {@link enforceSpecTestParity} is the commit-time back half (every
+ * scenario covered, every tag resolving). Together they close the
+ * gap where an agent authors a whole acceptance suite with no
+ * feature file and nothing objects until commit — or ever, if the
+ * tests carry no tags at all.
+ *
+ * Delta-based and deterministic (no AI call): only NEW test cases
+ * demand a NEW resolving tag, so edits inside an existing brownfield
+ * test file pass untouched, and a pre-existing dangling tag can't
+ * block unrelated work (the commit gate owns that). `(wip)` and
+ * `(planned)` scenarios count as existing — they are exactly the
+ * headings outside-in work drives against.
+ *
+ * Applies to: write actions — scope it via a `{ files, rules }`
+ * block to the acceptance test-case layer only (e.g.
+ * `**\/acceptance/**\/*Spec.kt`), never to drivers/DSL/infrastructure.
+ *
+ * @param options.specsDir — absolute path to the specs directory.
+ *   Missing directory ⇒ every new tag is unresolved ⇒ the deny
+ *   message says to create the first feature file (greenfield
+ *   enforcement, not a free pass).
+ * @param options.testDeclarationPattern — what counts as a test-case
+ *   declaration (default: Kotlin/Java `@Test` or Swift `func test…`).
+ */
+export declare function requireSpecBackedAcceptanceTest(options: {
+    specsDir: string;
+    testDeclarationPattern?: RegExp;
+}): Rule;
+/**
+ * Surfaces link breakage at the moment it is created: when a write
+ * to a `*.feature.md` file removes or renames a `## Scenario:`
+ * heading that acceptance tests still claim, the write is blocked
+ * with the list of affected tests — update their `Covers:` tags (or
+ * delete the tests) in the same change, then re-apply the spec edit.
+ * Removing a scenario nothing covers passes silently.
+ *
+ * Applies to: write actions to `*.feature.md` files (scope via a
+ * `{ files, rules }` block). Deterministic — no AI call.
+ *
+ * @param options.testRoots — absolute paths to scan for acceptance
+ *   tests.
+ * @param options.testFilePattern — which files count as acceptance
+ *   tests (default: any file under an `acceptance/` directory).
+ */
+export declare function surfaceScenarioLinkBreakage(options: Omit<ScanOptions, 'specsDir'>): Rule;
+export {};
+//# sourceMappingURL=spec-test-parity.d.ts.map

package/dist/rules/spec-test-parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-test-parity.d.ts","sourceRoot":"","sources":["../../rules/spec-test-parity.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAU,IAAI,EAA2B,MAAM,gBAAgB,CAAA;AAuE3E,KAAK,QAAQ,GAAG;IACd,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,OAAO,CAAA;IACZ,wEAAwE;IACxE,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AACD,KAAK,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAUnF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,EAAE,CA6C9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAahF;AAqBD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/D,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAA;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,CAelE;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAIxD;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAItD;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EAAE,EACnB,eAAe,EAAE,MAAM,GACtB,SAAS,EAAE,CAUb;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAyGhE;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAA;IAChB,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAChC,GAAG,IAAI,CAqDP;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,GACrC,IAAI,CAyCN"}