@nielspeter/eess-crossvalidate 0.1.1 → 0.2.0

package/README.md

@@ -34,10 +34,50 @@ AST-grounded: cited titles are resolved against actual `it()` call expressions
 (via eess-ts's public API — no ts-morph here, per ADR-007), so it also catches
 no-substitution template titles the text-level check misses.
 
+## Markdown ↔ Gherkin
+
+```typescript
+import { scenarioCitationsResolve } from '@nielspeter/eess-crossvalidate/md-gherkin'
+import { corpus } from '@nielspeter/eess-md'
+import { features } from '@nielspeter/eess-gherkin'
+
+// every scenario a story cites — `checkout.feature` · 'Apply a valid code' —
+// resolves to a real scenario in the feature set
+scenarioCitationsResolve(
+  corpus({ roots: ['docs/**'] }),
+  features({ roots: ['features/**/*.feature'] }),
+)
+```
+
+Spec↔spec: a markdown story cites a behavior — a backticked `.feature` path plus
+an optional quoted scenario title — and the citation is resolved against the
+loaded feature set. Three failure modes fail the build: the feature file is
+missing, the path is ambiguous, or the scenario title doesn't exist. The
+`gherkin-ts` preset below is its code↔spec mirror.
+
+## Gherkin ↔ TypeScript
+
+```typescript
+import { scenarioTestsResolve } from '@nielspeter/eess-crossvalidate/gherkin-ts'
+import { features } from '@nielspeter/eess-gherkin'
+import { project } from '@nielspeter/eess-ts'
+
+// every scenario a test cites — it('checkout.feature › Apply a valid code') —
+// resolves to a real scenario in the feature set
+scenarioTestsResolve(project('tsconfig.json'), features({ roots: ['features/**/*.feature'] }))
+```
+
+The mirror image of md↔gherkin's story citations: here the citing side is the
+**test AST** (`it('…')` titles, read via eess-ts's public API — no ts-morph, per
+ADR-007). A scenario renamed or deleted out from under the test that cites it
+fails the build. It resolves the citation; it does not claim the test exercises
+the scenario's steps (Tier 2, still open).
+
 ## Peers
 
 The dialects are optional peer dependencies — install the ones your presets use
-(`@nielspeter/eess-ts`, `@nielspeter/eess-mermaid`, `@nielspeter/eess-md`).
+(`@nielspeter/eess-ts`, `@nielspeter/eess-mermaid`, `@nielspeter/eess-md`,
+`@nielspeter/eess-gherkin`).
 
 ## License
 

package/dist/gherkin-ts.d.ts

@@ -0,0 +1,68 @@
+import { type ArchViolation, type PresetReportOptions } from '@nielspeter/eess';
+import { type ArchProject } from '@nielspeter/eess-ts';
+import type { FeatureSet, GherkinScenario } from '@nielspeter/eess-gherkin';
+export interface ScenarioTestsResolveOptions extends PresetReportOptions {
+    /**
+     * Custom citation extractor for transition periods — receives one `it('…')`
+     * title and returns the scenario it cites, or `undefined` if the title is not
+     * a citation. Default: the frozen convention adapted to a single string —
+     * `` it('<path>.feature › <Scenario title>') `` (plan 0080).
+     */
+    readonly extract?: (itTitle: string) => ExtractedTestCitation | undefined;
+}
+export interface ScenariosCoveredOptions extends PresetReportOptions {
+    /** Custom citation extractor — same contract as {@link ScenarioTestsResolveOptions.extract}. */
+    readonly extract?: (itTitle: string) => ExtractedTestCitation | undefined;
+    /**
+     * Require coverage only for scenarios matching this predicate — the opt-in
+     * scope. Default: every scenario. Use it to exclude un-implemented flows,
+     * e.g. `(s) => !s.tags.includes('wip')`.
+     */
+    readonly include?: (scenario: GherkinScenario) => boolean;
+}
+export interface ExtractedTestCitation {
+    /** The cited feature path, as written (may be a unique suffix). */
+    readonly path: string;
+    /** The cited scenario title. */
+    readonly title: string;
+}
+/** The default `it()`-title convention: `<path>.feature › <title>`. */
+declare function defaultExtract(itTitle: string): ExtractedTestCitation | undefined;
+/**
+ * Cross-validate that every scenario citation in the *test* AST resolves against
+ * the loaded feature set — the mirror image of `scenarioCitationsResolve`, whose
+ * left side is the markdown corpus; here it is the project's `it('…')` titles.
+ * This is the code↔spec half plan 0069 deferred ("this one is spec↔spec only").
+ *
+ * A citation is an `it()` whose title matches the convention `<path>.feature ›
+ * <Scenario title>` (overridable via `extract`). Three failure modes are gated:
+ * the cited feature file doesn't exist in the set, the path is ambiguous
+ * (matches several files), or the cited scenario title doesn't exist in that
+ * file. A test whose title is not a citation is ignored.
+ *
+ * Resolves a citation; it does NOT claim the test exercises the scenario's
+ * steps — that is Tier 2, still open (plan 0079).
+ */
+export declare function scenarioTestsResolve(project: ArchProject, set: FeatureSet, options?: ScenarioTestsResolveOptions): ArchViolation[];
+/**
+ * Cross-validate that every in-scope scenario is cited by at least one test —
+ * the coverage (right→left) direction, the complement of `scenarioTestsResolve`.
+ * A scenario shipped with no citing test fails; `include` narrows the scope so
+ * `@wip` / un-implemented flows do not force a red build.
+ *
+ * Assumes scenario titles are unique within a file — coverage keys on
+ * `relPath + title`, so two identically-titled scenarios share one key and
+ * citing one marks its twin covered. Pair with eess-gherkin's `haveUniqueTitles`
+ * to close that gap.
+ *
+ * Coverage means "a test cites this scenario", not "a test exercises its steps"
+ * (Tier 2, still open — plan 0079).
+ */
+export declare function scenariosCovered(project: ArchProject, set: FeatureSet, options?: ScenariosCoveredOptions): ArchViolation[];
+/** Count citing tests / scenarios for a caller's non-vacuity summary line. */
+export declare function scenarioTestStats(project: ArchProject, set: FeatureSet, options?: ScenarioTestsResolveOptions): {
+    citations: number;
+    scenarios: number;
+};
+export { defaultExtract };
+//# sourceMappingURL=gherkin-ts.d.ts.map

package/dist/gherkin-ts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin-ts.d.ts","sourceRoot":"","sources":["../src/gherkin-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAG3E,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACtE;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,qBAAqB,GAAG,SAAS,CAAA;CAC1E;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,qBAAqB,GAAG,SAAS,CAAA;IACzE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAA;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAcD,uEAAuE;AACvE,iBAAS,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAM1E;AA+CD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,2BAAgC,GACxC,aAAa,EAAE,CA0CjB;AA+BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,uBAA4B,GACpC,aAAa,EAAE,CAgBjB;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,2BAAgC,GACxC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAM1C;AAGD,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/gherkin-ts.js

@@ -0,0 +1,161 @@
+import { finishPreset } from '@nielspeter/eess';
+import { calls } from '@nielspeter/eess-ts';
+import { itOrTestTitleOf } from './it-title.js';
+// The gherkin↔ts citation convention (plan 0080): a test names the scenario it
+// proves in its `it()` title — a feature path (unique `/`-boundary suffix, like
+// md↔gherkin) then the scenario title, separated by `›` or `·`.
+const IT_CITE_RE = /^(?<path>.*\.feature)\s*[›·]\s*(?<title>.+)$/;
+const RULE = 'tests that cite a scenario should cite one that exists';
+/** The default `it()`-title convention: `<path>.feature › <title>`. */
+function defaultExtract(itTitle) {
+    const m = IT_CITE_RE.exec(itTitle);
+    const path = m?.groups?.path;
+    const title = m?.groups?.title;
+    if (path === undefined || title === undefined)
+        return undefined;
+    return { path, title };
+}
+/**
+ * Read every `it('…')` title from the project via eess-ts's public call API —
+ * no ts-morph here, per ADR-007, exactly as `adrCitationsResolve` does. Sees
+ * `` it(`no-substitution template`) `` titles a source regex would miss. The
+ * title grammar itself lives in `it-title.ts`, shared with md↔ts (bug 0104).
+ */
+function itTitles(project) {
+    const allCalls = calls(project).select({
+        label: 'call',
+        identify: (c) => ({ name: c.getName() ?? '' }),
+    }).elements;
+    const out = [];
+    for (const call of allCalls) {
+        // Accept `it(...)` / `test(...)` and their modifier forms (`it.only`,
+        // `it.skip`, `test.concurrent`, …) — the root callee is what matters, not
+        // the modifier. The gate binds a citation, it does not run the test, so a
+        // skipped test's citation is still checked (consistent with "cites, not
+        // exercises"). `it.each(table)(...)` is a call-of-a-call with a templated
+        // `%s` title — no static citation — so `root` is undefined and it is skipped.
+        const root = call.getObjectName() ?? call.getMethodName();
+        if (root !== 'it' && root !== 'test')
+            continue;
+        const title = itOrTestTitleOf(call.getName({ withArgument: 0 }) ?? '');
+        if (title === undefined)
+            continue;
+        out.push({ title, file: call.getSourceFile().getFilePath(), line: call.getStartLineNumber() });
+    }
+    return out;
+}
+/** Resolve a cited path against the set: exact relPath, or unique `/`-boundary suffix. */
+function resolveFeature(path, set) {
+    const all = set.features().map((f) => f.relPath);
+    if (all.includes(path))
+        return [path];
+    return all.filter((rel) => rel.endsWith(`/${path}`));
+}
+const v = (site, message, because) => ({
+    rule: RULE,
+    ruleId: 'crossval/scenario-tests-resolve',
+    element: `${site.file}:${site.line}`,
+    file: site.file,
+    line: site.line,
+    message,
+    because,
+});
+/**
+ * Cross-validate that every scenario citation in the *test* AST resolves against
+ * the loaded feature set — the mirror image of `scenarioCitationsResolve`, whose
+ * left side is the markdown corpus; here it is the project's `it('…')` titles.
+ * This is the code↔spec half plan 0069 deferred ("this one is spec↔spec only").
+ *
+ * A citation is an `it()` whose title matches the convention `<path>.feature ›
+ * <Scenario title>` (overridable via `extract`). Three failure modes are gated:
+ * the cited feature file doesn't exist in the set, the path is ambiguous
+ * (matches several files), or the cited scenario title doesn't exist in that
+ * file. A test whose title is not a citation is ignored.
+ *
+ * Resolves a citation; it does NOT claim the test exercises the scenario's
+ * steps — that is Tier 2, still open (plan 0079).
+ */
+export function scenarioTestsResolve(project, set, options = {}) {
+    const extract = options.extract ?? defaultExtract;
+    const scenarioKeys = new Set(set.scenarios().map((s) => `${s.relPath} ${s.title}`));
+    const violations = [];
+    for (const site of itTitles(project)) {
+        const cite = extract(site.title);
+        if (cite === undefined)
+            continue; // not a scenario-citing test
+        const resolved = resolveFeature(cite.path, set);
+        if (resolved.length === 0) {
+            violations.push(v(site, `cites \`${cite.path}\` — no such feature file in the set`, 'a test citing a missing behavior spec is a dangling reference'));
+            continue;
+        }
+        if (resolved.length > 1) {
+            violations.push(v(site, `cites \`${cite.path}\` — ambiguous, matches ${resolved.length} feature files (${resolved.join(', ')})`, 'an ambiguous citation cannot be mechanically resolved; cite a longer suffix'));
+            continue;
+        }
+        const rel = resolved[0];
+        if (rel !== undefined && !scenarioKeys.has(`${rel} ${cite.title}`)) {
+            violations.push(v(site, `cites '${cite.title}' in \`${rel}\` — no such scenario in that feature file`, 'a renamed or deleted scenario must not silently orphan the test that proves it'));
+        }
+    }
+    return finishPreset(violations, options);
+}
+const COVER_RULE = 'every scenario should be proven by a citing test';
+const sv = (scenario, message, because) => ({
+    rule: COVER_RULE,
+    ruleId: 'crossval/scenarios-covered',
+    element: `${scenario.relPath} › ${scenario.title}`,
+    file: scenario.file,
+    line: scenario.line,
+    message,
+    because,
+});
+/** The set of `relPath title` keys a test unambiguously cites in the project. */
+function citedScenarioKeys(project, set, extract) {
+    const covered = new Set();
+    for (const site of itTitles(project)) {
+        const cite = extract(site.title);
+        if (cite === undefined)
+            continue;
+        const resolved = resolveFeature(cite.path, set);
+        const rel = resolved.length === 1 ? resolved[0] : undefined;
+        if (rel !== undefined)
+            covered.add(`${rel} ${cite.title}`);
+    }
+    return covered;
+}
+/**
+ * Cross-validate that every in-scope scenario is cited by at least one test —
+ * the coverage (right→left) direction, the complement of `scenarioTestsResolve`.
+ * A scenario shipped with no citing test fails; `include` narrows the scope so
+ * `@wip` / un-implemented flows do not force a red build.
+ *
+ * Assumes scenario titles are unique within a file — coverage keys on
+ * `relPath + title`, so two identically-titled scenarios share one key and
+ * citing one marks its twin covered. Pair with eess-gherkin's `haveUniqueTitles`
+ * to close that gap.
+ *
+ * Coverage means "a test cites this scenario", not "a test exercises its steps"
+ * (Tier 2, still open — plan 0079).
+ */
+export function scenariosCovered(project, set, options = {}) {
+    const extract = options.extract ?? defaultExtract;
+    const include = options.include ?? (() => true);
+    const covered = citedScenarioKeys(project, set, extract);
+    const violations = set
+        .scenarios()
+        .filter(include)
+        .filter((s) => !covered.has(`${s.relPath} ${s.title}`))
+        .map((s) => sv(s, 'no test cites this scenario', 'an unproven use-case flow is a spec with no gate behind it'));
+    return finishPreset(violations, options);
+}
+/** Count citing tests / scenarios for a caller's non-vacuity summary line. */
+export function scenarioTestStats(project, set, options = {}) {
+    const extract = options.extract ?? defaultExtract;
+    return {
+        citations: itTitles(project).filter((s) => extract(s.title) !== undefined).length,
+        scenarios: set.scenarios().length,
+    };
+}
+// Referenced by tests to keep the default convention itself under test.
+export { defaultExtract };
+//# sourceMappingURL=gherkin-ts.js.map

package/dist/gherkin-ts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin-ts.js","sourceRoot":"","sources":["../src/gherkin-ts.ts"],"names":[],"mappings":"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"}

package/dist/it-title.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The `it('…')` title grammar for this package — one definition, because both of
+ * its presets read it. Not the family's only copy: `eess-md`'s `adr.ts` carries a
+ * third, on the same ADR-citation contract, and cannot import this one (the
+ * dependency runs crossvalidate → md, and `eess/md-isolated` forbids the
+ * reverse). See bug 0111 for that, and 0114 for why the grammar arguably belongs
+ * behind eess-ts's engine boundary rather than here at all.
+ *
+ * `md-ts` (ADR citations) and `gherkin-ts` (scenario citations) both have to
+ * recover the title a test declares from source text, and both got it wrong the
+ * same way: `['"`]([^'"`]+)['"`]` ends the capture at **any** quote character,
+ * not at the one that opened the string. A character class cannot express "up to
+ * the *matching* delimiter" — the opening quote is matched but never captured,
+ * so the closing side has no way to require the same character.
+ *
+ * The cost is bug 0104, a false green: a single-quoted title containing a
+ * backtick — the ordinary way to name a symbol in prose, and this repo's own
+ * house style — truncated at that backtick, so
+ *
+ *     it('catches `HACK` inside a body')     ─┐
+ *     it('catches `any` in a return position') ┴─→ both key on `catches `
+ *
+ * collapsed onto one key. Because the markdown side truncated identically, a
+ * citation to a test that had been renamed away still resolved — against a
+ * *different* test that happened to share the truncated prefix. The gate passed
+ * over exactly the drift it exists to catch.
+ *
+ * Capturing the delimiter as `q` and back-referencing it fixes both halves at
+ * once; the `\\.` alternative keeps an escaped delimiter inside the title.
+ *
+ * Titles are compared as **raw source text**, so `it('it\'s fine')` keys on
+ * `it\'s fine`, backslash included. That is a deliberate consequence of reading
+ * one grammar on both sides: an ADR cites what is written in the test file, not
+ * what the string evaluates to, and both sides read it identically.
+ *
+ * That has a cost worth knowing before you write a citation: a title's raw text
+ * is **prettier's to change**. `it("say 'hi' to \"them\"")` is reformatted to
+ * `it('say \'hi\' to "them"')` — same string, different source, different key —
+ * while the ADR's citation sits in a markdown code span prettier will not touch.
+ * A correct citation can go red after a routine `npm run format`. It fails loud
+ * rather than silent, which is the right direction, but prefer a title that
+ * needs no escaping at all.
+ *
+ * ## Two input classes, two grammars
+ *
+ * The anchored readers are handed an enriched call name built from ts-morph's
+ * `getText()` — guaranteed-valid TypeScript, where a `\` is always an escape and
+ * the delimiters always balance. `citedItTitles` reads **arbitrary prose** from
+ * a table cell, where neither holds. Sharing one permissive grammar across both
+ * cost a real regression, caught in review before this shipped: given a cell
+ * holding a malformed citation followed by a good one,
+ *
+ *     `it('first` and `it('second')`
+ *
+ * the permissive body ran past the second citation's opening quote and closed
+ * there — yielding one bogus key and **dropping a real citation from the check
+ * entirely**. A citation nobody checks is the same false green this module was
+ * written to remove. So the prose variant is tempered: it cannot cross a line,
+ * and it cannot swallow the start of another citation.
+ */
+/**
+ * The title in an enriched call name like `it('does a thing')`, or `undefined`
+ * if the argument is not a literal string. Accepts modifier forms (`it.skip`,
+ * `it.only`) — whether a *definition* in one of those forms counts is the
+ * caller's call, made by the callee filter above this.
+ */
+export declare function itTitleOf(enriched: string): string | undefined;
+/** As {@link itTitleOf}, also accepting the `test` alias — gherkin↔ts's convention. */
+export declare function itOrTestTitleOf(enriched: string): string | undefined;
+/** Every `it('…')` title cited inside a fragment of prose, in order. */
+export declare function citedItTitles(text: string): string[];
+//# sourceMappingURL=it-title.d.ts.map

package/dist/it-title.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"it-title.d.ts","sourceRoot":"","sources":["../src/it-title.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAwCH;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9D;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOpD"}

package/dist/it-title.js

@@ -0,0 +1,115 @@
+/**
+ * The `it('…')` title grammar for this package — one definition, because both of
+ * its presets read it. Not the family's only copy: `eess-md`'s `adr.ts` carries a
+ * third, on the same ADR-citation contract, and cannot import this one (the
+ * dependency runs crossvalidate → md, and `eess/md-isolated` forbids the
+ * reverse). See bug 0111 for that, and 0114 for why the grammar arguably belongs
+ * behind eess-ts's engine boundary rather than here at all.
+ *
+ * `md-ts` (ADR citations) and `gherkin-ts` (scenario citations) both have to
+ * recover the title a test declares from source text, and both got it wrong the
+ * same way: `['"`]([^'"`]+)['"`]` ends the capture at **any** quote character,
+ * not at the one that opened the string. A character class cannot express "up to
+ * the *matching* delimiter" — the opening quote is matched but never captured,
+ * so the closing side has no way to require the same character.
+ *
+ * The cost is bug 0104, a false green: a single-quoted title containing a
+ * backtick — the ordinary way to name a symbol in prose, and this repo's own
+ * house style — truncated at that backtick, so
+ *
+ *     it('catches `HACK` inside a body')     ─┐
+ *     it('catches `any` in a return position') ┴─→ both key on `catches `
+ *
+ * collapsed onto one key. Because the markdown side truncated identically, a
+ * citation to a test that had been renamed away still resolved — against a
+ * *different* test that happened to share the truncated prefix. The gate passed
+ * over exactly the drift it exists to catch.
+ *
+ * Capturing the delimiter as `q` and back-referencing it fixes both halves at
+ * once; the `\\.` alternative keeps an escaped delimiter inside the title.
+ *
+ * Titles are compared as **raw source text**, so `it('it\'s fine')` keys on
+ * `it\'s fine`, backslash included. That is a deliberate consequence of reading
+ * one grammar on both sides: an ADR cites what is written in the test file, not
+ * what the string evaluates to, and both sides read it identically.
+ *
+ * That has a cost worth knowing before you write a citation: a title's raw text
+ * is **prettier's to change**. `it("say 'hi' to \"them\"")` is reformatted to
+ * `it('say \'hi\' to "them"')` — same string, different source, different key —
+ * while the ADR's citation sits in a markdown code span prettier will not touch.
+ * A correct citation can go red after a routine `npm run format`. It fails loud
+ * rather than silent, which is the right direction, but prefer a title that
+ * needs no escaping at all.
+ *
+ * ## Two input classes, two grammars
+ *
+ * The anchored readers are handed an enriched call name built from ts-morph's
+ * `getText()` — guaranteed-valid TypeScript, where a `\` is always an escape and
+ * the delimiters always balance. `citedItTitles` reads **arbitrary prose** from
+ * a table cell, where neither holds. Sharing one permissive grammar across both
+ * cost a real regression, caught in review before this shipped: given a cell
+ * holding a malformed citation followed by a good one,
+ *
+ *     `it('first` and `it('second')`
+ *
+ * the permissive body ran past the second citation's opening quote and closed
+ * there — yielding one bogus key and **dropping a real citation from the check
+ * entirely**. A citation nobody checks is the same false green this module was
+ * written to remove. So the prose variant is tempered: it cannot cross a line,
+ * and it cannot swallow the start of another citation.
+ */
+/** The opening of a citation: `it(`, `it.skip(`, … up to and including its quote. */
+const IT_OPEN = `it(?:\\.\\w+)?\\(\\s*['"\`]`;
+/**
+ * A quoted string whose closing delimiter must match its opening one — group `q`
+ * is the delimiter, group `title` the payload. `body` is what may sit between
+ * them; the two alternatives have disjoint first characters (`\\.` starts with a
+ * backslash, the other excludes it), so the alternation is deterministic and the
+ * `+` cannot fork — no backtracking blowup on a long unterminated title.
+ */
+const quoted = (body) => `(?<q>['"\`])(?<title>(?:\\\\.|${body})+)\\k<q>`;
+/** Valid TypeScript source: anything but the delimiter that opened the string. */
+const SOURCE_BODY = `(?!\\k<q>)[^\\\\]`;
+/**
+ * Arbitrary prose: additionally refuses to cross a newline (a Mechanism cell is
+ * one line) or to consume the start of another citation, so one malformed
+ * citation cannot eat its neighbour. Tempering on the full opening — callee,
+ * paren *and* quote — keeps a title that merely mentions `it(x)` intact.
+ */
+const PROSE_BODY = `(?!\\k<q>)(?!${IT_OPEN})[^\\\\\\n]`;
+/**
+ * `<callee>(` with an optional modifier — `it(`, `it.skip(`, `test.concurrent(`.
+ * The lookbehind is what keeps `submit('save')`, `emit('drift')` and `audit('x')`
+ * from reading as citations; it is redundant under `^` and load-bearing in prose.
+ */
+const CALL = (callee) => `(?<![\\w$.])(?:${callee})(?:\\.\\w+)?\\(\\s*`;
+// Anchored: the input is an enriched call name produced by eess-ts's
+// `getName({ withArgument: 0 })`, e.g. `it('does a thing')`.
+const IT_TITLE = new RegExp(`^${CALL('it')}${quoted(SOURCE_BODY)}`);
+const IT_OR_TEST_TITLE = new RegExp(`^${CALL('it|test')}${quoted(SOURCE_BODY)}`);
+// Unanchored + global: citations are embedded in prose (an ADR's Mechanism cell).
+const IT_CITATION = new RegExp(`${CALL('it')}${quoted(PROSE_BODY)}`, 'g');
+/**
+ * The title in an enriched call name like `it('does a thing')`, or `undefined`
+ * if the argument is not a literal string. Accepts modifier forms (`it.skip`,
+ * `it.only`) — whether a *definition* in one of those forms counts is the
+ * caller's call, made by the callee filter above this.
+ */
+export function itTitleOf(enriched) {
+    return IT_TITLE.exec(enriched)?.groups?.title;
+}
+/** As {@link itTitleOf}, also accepting the `test` alias — gherkin↔ts's convention. */
+export function itOrTestTitleOf(enriched) {
+    return IT_OR_TEST_TITLE.exec(enriched)?.groups?.title;
+}
+/** Every `it('…')` title cited inside a fragment of prose, in order. */
+export function citedItTitles(text) {
+    const out = [];
+    for (const m of text.matchAll(IT_CITATION)) {
+        const title = m.groups?.title;
+        if (title !== undefined)
+            out.push(title);
+    }
+    return out;
+}
+//# sourceMappingURL=it-title.js.map

package/dist/it-title.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"it-title.js","sourceRoot":"","sources":["../src/it-title.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,qFAAqF;AACrF,MAAM,OAAO,GAAG,6BAA6B,CAAA;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,iCAAiC,IAAI,WAAW,CAAA;AAEzF,kFAAkF;AAClF,MAAM,WAAW,GAAG,mBAAmB,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,GAAG,gBAAgB,OAAO,aAAa,CAAA;AAEvD;;;;GAIG;AACH,MAAM,IAAI,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,kBAAkB,MAAM,sBAAsB,CAAA;AAEvF,qEAAqE;AACrE,6DAA6D;AAC7D,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAA;AACnE,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAA;AAEhF,kFAAkF;AAClF,MAAM,WAAW,GAAG,IAAI,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;AAEzE;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,OAAO,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAA;AAC/C,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,CAAA;AACvD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,CAAA;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/md-ts.d.ts

@@ -8,6 +8,16 @@ export interface AdrCitationsResolveOptions {
     /** Header pattern locating the mechanism column. Default `/mechanism/i` — non-English corpora pass their own (e.g. `/mekanisme/i`). */
     readonly mechanismColumn?: RegExp;
 }
+/**
+ * Count what this preset would actually scan — the caller's non-vacuity guard.
+ * `adrCitationsResolve` reports OK when it resolves zero citations, so a drifted
+ * `dir` or `roots` reads exactly like a clean pass; a gate that prints this
+ * number can tell the two apart. Mirrors `scenarioTestStats` in gherkin↔ts.
+ */
+export declare function adrCitationStats(corpus: Corpus, options?: AdrCitationsResolveOptions): {
+    citations: number;
+    adrs: number;
+};
 /**
  * Cross-validate that every `it('…')` cited in an ADR's enforcement table
  * actually exists as a test in the project. The AST-grounded upgrade of the

package/dist/md-ts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"md-ts.d.ts","sourceRoot":"","sources":["../src/md-ts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAE7D,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAClC,uIAAuI;IACvI,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAoED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,0BAA+B,GACvC,IAAI,CA+BN"}
+{"version":3,"file":"md-ts.d.ts","sourceRoot":"","sources":["../src/md-ts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAG7D,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAClC,uIAAuI;IACvI,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AA6CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,0BAA+B,GACvC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAYrC;AAqCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,0BAA+B,GACvC,IAAI,CA8CN"}

package/dist/md-ts.js

@@ -1,9 +1,7 @@
 import picomatch from 'picomatch';
 import { correspondence } from '@nielspeter/eess';
 import { calls } from '@nielspeter/eess-ts';
-const IT_CITE_RE = /it(?:\.\w+)?\(\s*['"`]([^'"`]+)['"`]/g;
-// Parse a title out of an enriched call name like `it('does a thing')`.
-const IT_NAME_RE = /^it(?:\.\w+)?\(\s*['"`]([^'"`]+)['"`]/;
+import { citedItTitles, itTitleOf } from './it-title.js';
 function matchName(value, name) {
     return typeof name === 'string' ? value === name : name.test(value);
 }
@@ -23,15 +21,32 @@ function extractCitations(opts) {
             continue;
         for (const row of table.rows) {
             const mech = row[mechIdx] ?? '';
-            for (const m of mech.matchAll(IT_CITE_RE)) {
-                const title = m[1];
-                if (title !== undefined)
-                    out.push({ title, adr: doc.relPath, line: table.line });
+            for (const title of citedItTitles(mech)) {
+                out.push({ title, adr: doc.relPath, line: table.line });
             }
         }
     }
     return out;
 }
+/**
+ * Count what this preset would actually scan — the caller's non-vacuity guard.
+ * `adrCitationsResolve` reports OK when it resolves zero citations, so a drifted
+ * `dir` or `roots` reads exactly like a clean pass; a gate that prints this
+ * number can tell the two apart. Mirrors `scenarioTestStats` in gherkin↔ts.
+ */
+export function adrCitationStats(corpus, options = {}) {
+    const dir = options.dir ?? 'docs/adr/**';
+    const inDir = picomatch(dir);
+    return {
+        citations: extractCitations({
+            corpus,
+            dir,
+            section: options.section ?? /^enforcement$/i,
+            mechanismColumn: options.mechanismColumn ?? /mechanism/i,
+        }).length,
+        adrs: corpus.documents().filter((d) => inDir(d.relPath)).length,
+    };
+}
 /** Collect actual `it('…')` definitions from the project via eess-ts's public call API. */
 function extractTestDefs(project) {
     const allCalls = calls(project).select({
@@ -40,12 +55,29 @@ function extractTestDefs(project) {
     }).elements;
     const out = [];
     for (const call of allCalls) {
-        if (call.getName() !== 'it')
+        // The ROOT callee, not the full name. eess-ts names a modifier call by its
+        // whole member expression, so `it.skip(…)` is `'it.skip'` and comparing the
+        // full name dropped every skipped, focused or concurrent test before its
+        // title was read — while the citation side had always accepted those forms
+        // (bug 0105). The gate binds a citation; it does not run the test, so a
+        // skipped test's citation is still checked. Same reasoning, same shape as
+        // `gherkin-ts.ts` — which is where it was already written down.
+        //
+        // **This guard is not what decides.** `itTitleOf` is anchored on the literal
+        // callee (`^` + `(?:it)(?:\.\w+)?\(`), so the grammar alone already rejects
+        // `describe(…)`, `test(…)`, `suite.it(…)`, `it.a.b(…)` and the outer
+        // `it.each([…])(…)`. Review measured it: delete these two lines and the whole
+        // suite stays green. What the guard buys is a cheap pre-filter — it skips
+        // `getArguments()` + `getText()` for every call expression in the project —
+        // and defence in depth: widening what counts as a test takes BOTH this line
+        // and the grammar, so neither can smuggle one in alone. Keep it for those
+        // reasons, not for a rejection it does not perform.
+        const root = call.getObjectName() ?? call.getMethodName();
+        if (root !== 'it')
             continue;
-        const enriched = call.getName({ withArgument: 0 }) ?? '';
-        const m = IT_NAME_RE.exec(enriched);
-        if (m?.[1] !== undefined) {
-            out.push({ title: m[1], file: call.getSourceFile().getFilePath() });
+        const title = itTitleOf(call.getName({ withArgument: 0 }) ?? '');
+        if (title !== undefined) {
+            out.push({ title, file: call.getSourceFile().getFilePath() });
         }
     }
     return out;
@@ -78,6 +110,20 @@ export function adrCitationsResolve(corpus, project, options = {}) {
         left,
         right,
         keyBy: (e) => e.title,
+        // `suggest.left`, not `.rule({ suggestion })`, and now for the right reason.
+        // The original comment here said rule-level suggestions never render on a
+        // correspondence (true until bug 0122 fixed it) and that appending to the
+        // message "does" render — which was never true: the terminal formatter
+        // dropped `message` entirely, so this remedy was invisible in the one format
+        // an agent reads. Both halves are fixed. `suggest` stays because the remedy
+        // is per-branch: a rule-level `suggestion` is stamped onto every branch of
+        // the correspondence, and "match the citation character for character" is
+        // advice for a *dangling* citation, not for an ambiguous or an uncited one.
+        suggest: {
+            left: () => 'Fix: the cited title is compared as raw source text — if the test was renamed, ' +
+                'match the citation to it character for character (escapes included); ' +
+                'if it was deleted, restore it or retire the clause it enforced.',
+        },
     })
         .should()
         .beComplete({ direction: 'left-to-right' })

package/dist/md-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"md-ts.js","sourceRoot":"","sources":["../src/md-ts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"md-ts.js","sourceRoot":"","sources":["../src/md-ts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nielspeter/eess-crossvalidate",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Cross-validation presets for the eess family — bind two dialects' artifacts and fail when they drift.",
   "type": "module",
   "exports": {
@@ -24,6 +24,10 @@
       "types": "./dist/md-gherkin.d.ts",
       "import": "./dist/md-gherkin.js"
     },
+    "./gherkin-ts": {
+      "types": "./dist/gherkin-ts.d.ts",
+      "import": "./dist/gherkin-ts.js"
+    },
     "./md-mermaid-er": {
       "types": "./dist/md-mermaid-er.d.ts",
       "import": "./dist/md-mermaid-er.js"
@@ -58,14 +62,14 @@
     "markdown"
   ],
   "dependencies": {
-    "@nielspeter/eess": "^0.1.1",
+    "@nielspeter/eess": "^0.2.2",
     "picomatch": "^4.0.4"
   },
   "peerDependencies": {
-    "@nielspeter/eess-ts": "^0.1.1",
-    "@nielspeter/eess-mermaid": "^0.1.1",
-    "@nielspeter/eess-md": "^0.1.1",
-    "@nielspeter/eess-gherkin": "^0.1.1"
+    "@nielspeter/eess-ts": ">=0.1.1",
+    "@nielspeter/eess-mermaid": ">=0.1.1",
+    "@nielspeter/eess-md": ">=0.1.1",
+    "@nielspeter/eess-gherkin": ">=0.1.1"
   },
   "peerDependenciesMeta": {
     "@nielspeter/eess-ts": {