@am_shork/attest 0.9.2 → 0.9.4

package/dist/core/splice.js

@@ -148,11 +148,11 @@ function paramSource(value) {
  * body needs one after, and putting that decision here would mean this function
  * had to be told which case it was in anyway.
  *
- * `params` and `outOfScope` are omitted when empty rather than written as `{}`
- * and `[]`. The schema defaults both, so the two spellings mean the same thing,
- * and the shorter one is what a person writing this entry by hand would have
- * produced — which is the standard for a file `--apply` is merging into rather
- * than generating.
+ * `params`, `outOfScope` and `open` are omitted when empty rather than written
+ * as `{}` and `[]`. The schema defaults all three, so the two spellings mean the
+ * same thing, and the shorter one is what a person writing this entry by hand
+ * would have produced — which is the standard for a file `--apply` is merging
+ * into rather than generating.
  */
 export function requirementSource(id, req, indent) {
     const inner = `${indent}  `;
@@ -172,13 +172,28 @@ export function requirementSource(id, req, indent) {
         lines.push(`${inner}params: { ${body} },`);
     }
     if (req.outOfScope.length > 0) {
-        lines.push(`${inner}outOfScope: ${outOfScopeSource(req.outOfScope)},`);
+        lines.push(`${inner}outOfScope: ${stringListSource(req.outOfScope)},`);
+    }
+    // Reachable only through a delta the gate never approves — `open-unresolved`
+    // blocks any end state that still carries one, so an ADDED entry written here
+    // has an empty list. Emitted anyway rather than left out: this function's
+    // contract is to write the requirement it is given, and a writer silently
+    // shorter than the schema is exactly the divergence the MODIFIED half below
+    // was found to have.
+    if (req.open.length > 0) {
+        lines.push(`${inner}open: ${stringListSource(req.open)},`);
     }
     lines.push(`${indent}}`);
     return lines.join('\n');
 }
-/** One `outOfScope` list as source. Shared with the modification writer below. */
-function outOfScopeSource(entries) {
+/**
+ * One list-of-strings field as source — `outOfScope` or `open`.
+ *
+ * One function for both, and named for the shape rather than for either field,
+ * so a third such field does not arrive with a third spelling of the same
+ * emitter. Shared with the modification writer below.
+ */
+function stringListSource(entries) {
     return `[${entries.map((s) => tsString(s)).join(', ')}]`;
 }
 /** One `params` key as source, at the key order the emitter writes everywhere. */
@@ -290,14 +305,24 @@ export function spliceModifications(file, source, changes) {
             }
             else if (name === 'outOfScope') {
                 if (!sameValue(before.outOfScope, after.outOfScope)) {
-                    out.at(name, span, outOfScopeSource(after.outOfScope));
+                    out.at(name, span, stringListSource(after.outOfScope));
+                }
+            }
+            else if (name === 'open') {
+                if (!sameValue(before.open, after.open)) {
+                    out.at(name, span, stringListSource(after.open));
                 }
             }
             else if (name === 'params') {
                 editParams(layout, before, after, out);
             }
             // Any other field is one the schema does not define, and not this
-            // module's to rewrite or to remove.
+            // module's to rewrite or to remove. `open` is above rather than here for
+            // exactly that reason: adding it to the schema without adding it to this
+            // loop would let the gate approve an end state where a question is closed
+            // while the file on disk still carries it — a divergence between the
+            // registry the verdict was reached on and the registry the merge commits,
+            // with nothing anywhere comparing the two.
         }
         if (!layout.fields.has('statement') && before.statement !== after.statement) {
             openField('statement', tsString(after.statement));
@@ -311,7 +336,10 @@ export function spliceModifications(file, source, changes) {
                 openField('params', `{ ${fresh.join(', ')} }`);
         }
         if (!layout.fields.has('outOfScope') && !sameValue(before.outOfScope, after.outOfScope)) {
-            openField('outOfScope', outOfScopeSource(after.outOfScope));
+            openField('outOfScope', stringListSource(after.outOfScope));
+        }
+        if (!layout.fields.has('open') && !sameValue(before.open, after.open)) {
+            openField('open', stringListSource(after.open));
         }
         if (opened.length > 0) {
             const point = layout.fieldInsertion;

package/dist/core/validator.d.ts

@@ -19,8 +19,9 @@ export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): I
  * - unbound-param: a statement placeholder has no matching param
  * - non-scalar-interpolation: a statement placeholder names a structured param
  *
- * and one WARNING:
+ * and two WARNINGs:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
+ * - requirement-open: the requirement names something still undecided about it
  *
  * and one more WARNING, which exists only when a registry file failed to load:
  * - orphan-from-failed-registry: the scenarios attesting ids that file declares

package/dist/core/validator.js

@@ -34,8 +34,9 @@ export function uncoveredIssues(registry, plan) {
  * - unbound-param: a statement placeholder has no matching param
  * - non-scalar-interpolation: a statement placeholder names a structured param
  *
- * and one WARNING:
+ * and two WARNINGs:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
+ * - requirement-open: the requirement names something still undecided about it
  *
  * and one more WARNING, which exists only when a registry file failed to load:
  * - orphan-from-failed-registry: the scenarios attesting ids that file declares
@@ -208,6 +209,24 @@ export function validateStructure(registry, plan, unreadable = []) {
             });
         }
     }
+    // requirement-open: the requirement says what is still undecided about it.
+    // WARNING and not an ERROR, because the four static commands are where an
+    // author works while a proposal legitimately still has questions in it —
+    // failing here would push them back to inventing a value, which is the
+    // behaviour the field exists to replace. What refuses to call such a registry
+    // done is the archive gate (`open-unresolved`), the same asymmetry `never-red`
+    // runs on. One issue per question rather than one per requirement: each is a
+    // separate thing to answer, and a reader resolving them wants them listed.
+    for (const [id, req] of Object.entries(registry)) {
+        for (const question of req.open) {
+            issues.push({
+                level: 'WARNING',
+                code: 'requirement-open',
+                reqId: id,
+                message: `Requirement "${id}" is still open: ${question} Answer it and remove the entry from open — the archive gate refuses a registry that still carries one.`,
+            });
+        }
+    }
     return issues;
 }
 /**

package/dist/inspect.d.ts

@@ -51,4 +51,96 @@ export interface Inspection {
  * not ours to choose.
  */
 export declare function inspectProject(root: string): Promise<Inspection>;
+/**
+ * What the archived first-run records say about one scenario a spec declares.
+ *
+ * Four values, not two, and the two absences are the reason. `'fail'` and
+ * `'pass'` are the record's own outcomes, spelled the same so a caller
+ * comparing against `'fail'` is comparing against the string the gate compares
+ * against. The other two are both "no observation", and folding them together
+ * would report a design working as intended as if it were a defect:
+ *
+ * - `'unarchived'` — this scenario's requirement appears in no archived change
+ *   at all. It was written straight into the registry, which is how existing
+ *   behaviour is described in a brownfield adoption, and it carries **no**
+ *   obligation to have been red. Nothing is wrong.
+ * - `'unobserved'` — the requirement *is* archived and this scenario is not in
+ *   the record. It was added after the change was archived, and nothing will
+ *   ever require it to have failed first: the gate raises `never-red` only for
+ *   ids a change is currently ADDing, and an archived id is ADDed by nothing
+ *   again. This is the one no gate can see.
+ *
+ * `'pass'` is a state the gate cannot produce — it blocks a change whose
+ * scenario passed on its first run — so an archived `'pass'` means the record
+ * was hand-edited or written by a format that has since moved. Reported rather
+ * than folded into the absences, because the fix is different.
+ *
+ * Attest computes which of the four holds and stops there. Whether an
+ * `'unobserved'` scenario matters is a judgement about that scenario, which is
+ * the caller's (design §0).
+ */
+export type ScenarioEvidence = 'fail' | 'pass' | 'unobserved' | 'unarchived';
+/** One declared scenario, and what the archive records about it. */
+export interface EvidenceRow {
+    readonly reqId: string;
+    /** The spec file, relative to the root and POSIX-spelled, as {@link ParsedScenario} spells it. */
+    readonly file: string;
+    readonly name: string;
+    readonly line: number;
+    readonly evidence: ScenarioEvidence;
+}
+/** An archived change folder the evidence was read from. */
+export interface ArchivedChangeRef {
+    /** The folder name, `<YYYY-MM-DD>-<change>`, as `archive --apply` spelled it. */
+    readonly name: string;
+    /** The folder relative to the root, POSIX-spelled. */
+    readonly path: string;
+}
+/** What {@link inspectRedEvidence} answers. */
+export interface RedEvidenceInspection {
+    /**
+     * One row per scenario declared under the root, in the order
+     * {@link Inspection.scenarios} lists them.
+     *
+     * Rows for *declared* scenarios rather than for recorded ones: the question is
+     * what today's suite can show about itself, so a record naming a scenario no
+     * spec declares any more contributes nothing here. It is not lost — the folder
+     * it came from is in {@link RedEvidenceInspection.archived} — but a row about
+     * a scenario that no longer exists is not something a caller can act on.
+     */
+    readonly scenarios: readonly EvidenceRow[];
+    /**
+     * Every archived change folder that was read, in folder-name order.
+     *
+     * Provenance, and it is load-bearing: an empty list means the project has
+     * archived nothing, in which case every row is `'unarchived'` and the report
+     * says nothing about the project rather than something bad about it.
+     */
+    readonly archived: readonly ArchivedChangeRef[];
+    /** Everything that stopped a file being read, exactly as {@link Inspection.issues}. */
+    readonly issues: readonly Issue[];
+}
+/**
+ * Join what a project declares against what its archive recorded, executing
+ * nothing.
+ *
+ * **Why this is not a field on {@link Inspection}.** It walks `archive/`, which
+ * most callers of {@link inspectProject} have no use for, and a reader should
+ * not pay a second tree walk to be told about requirements.
+ *
+ * **Why it returns rows rather than the records.** The record is a nested map
+ * keyed by requirement ids, paths and scenario names read off disk, and reading
+ * it correctly means never answering from an inherited key — the whole of the
+ * prototype argument `red-record.ts` carries. Handing that container to a caller
+ * would export the hazard along with the data. What is exported is the answer,
+ * at the granularity the question is asked.
+ *
+ * **What the granularity is, and why it is not the requirement.** The gate
+ * blocks a change unless *every* scenario of every id it ADDs was observed
+ * failing, so "did this requirement ever have red evidence" comes back yes for
+ * every archived id and answers nothing. Where the gate stops is one level down:
+ * a scenario grown onto a requirement after it archived, and a requirement whose
+ * statement a later change MODIFIED, which carries no such obligation at all.
+ */
+export declare function inspectRedEvidence(root: string): Promise<RedEvidenceInspection>;
 //# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.js

@@ -24,7 +24,9 @@
 // `tests/import-boundary.spec.ts` gates that rather than leaving it to review —
 // this module is on the short list of entry points whose closure is walked.
 import { resolve } from 'node:path';
+import { readArchivedEvidence } from './core/archive.js';
 import { loadRegistry, parseSpecs, scanProject, staticReader } from './core/locate.js';
+import { recordedOutcome } from './core/red-record.js';
 /**
  * Read the requirements and scenarios declared under `root`, executing nothing.
  *
@@ -65,4 +67,57 @@ export async function inspectProject(root) {
         issues: [...loaded.issues, ...parsed.issues],
     };
 }
+/**
+ * Join what a project declares against what its archive recorded, executing
+ * nothing.
+ *
+ * **Why this is not a field on {@link Inspection}.** It walks `archive/`, which
+ * most callers of {@link inspectProject} have no use for, and a reader should
+ * not pay a second tree walk to be told about requirements.
+ *
+ * **Why it returns rows rather than the records.** The record is a nested map
+ * keyed by requirement ids, paths and scenario names read off disk, and reading
+ * it correctly means never answering from an inherited key — the whole of the
+ * prototype argument `red-record.ts` carries. Handing that container to a caller
+ * would export the hazard along with the data. What is exported is the answer,
+ * at the granularity the question is asked.
+ *
+ * **What the granularity is, and why it is not the requirement.** The gate
+ * blocks a change unless *every* scenario of every id it ADDs was observed
+ * failing, so "did this requirement ever have red evidence" comes back yes for
+ * every archived id and answers nothing. Where the gate stops is one level down:
+ * a scenario grown onto a requirement after it archived, and a requirement whose
+ * statement a later change MODIFIED, which carries no such obligation at all.
+ */
+export async function inspectRedEvidence(root) {
+    const projectRoot = resolve(root);
+    // Sequential rather than concurrent, unlike the two reads inside
+    // `inspectProject`: this is one tree walk after another over the same disk,
+    // and the archive holds only the folders of changes already merged — so
+    // overlapping them buys nothing worth a second fan-out.
+    const inspection = await inspectProject(projectRoot);
+    const { changes, firstRun } = await readArchivedEvidence(projectRoot);
+    const scenarios = [];
+    for (const [reqId, declared] of inspection.scenarios) {
+        // Own property only, and the distinction the two absences rest on: an id
+        // the archive never mentions is a different fact from an id it mentions
+        // without this scenario.
+        const archived = Object.hasOwn(firstRun, reqId);
+        for (const s of declared) {
+            const outcome = recordedOutcome(firstRun, { reqId, file: s.file, name: s.name });
+            scenarios.push({
+                reqId,
+                file: s.file,
+                name: s.name,
+                line: s.line,
+                evidence: outcome ?? (archived ? 'unobserved' : 'unarchived'),
+            });
+        }
+    }
+    return {
+        scenarios,
+        archived: changes.map((c) => ({ name: c.name, path: c.path })),
+        issues: inspection.issues,
+    };
+}
 //# sourceMappingURL=inspect.js.map

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
+  "packageManager": "pnpm@10.28.0",
   "engines": {
     "node": ">=20.19"
   },
@@ -41,6 +42,24 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:all": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:consumer": "pnpm run build && vitest run --config vitest.consumer.config.ts",
+    "lint": "eslint .",
+    "prepack": "pnpm run build",
+    "prepublishOnly": "pnpm run test:consumer",
+    "attest": "node bin/attest.js",
+    "check:self": "node bin/attest.js check self",
+    "verify:self": "node bin/attest.js verify self",
+    "cover:self": "node bin/attest.js cover self",
+    "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
+    "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"
+  },
   "keywords": [
     "tdd",
     "spec",
@@ -67,20 +86,15 @@
     "vite": "^8.1.5",
     "vitest": "^4.1.10"
   },
-  "scripts": {
-    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
-    "build": "pnpm run clean && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "typecheck:all": "tsc -p tsconfig.typecheck.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:consumer": "pnpm run build && vitest run --config vitest.consumer.config.ts",
-    "lint": "eslint .",
-    "attest": "node bin/attest.js",
-    "check:self": "node bin/attest.js check self",
-    "verify:self": "node bin/attest.js verify self",
-    "cover:self": "node bin/attest.js cover self",
-    "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
-    "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ],
+    "overrides": {
+      "brace-expansion@<5.0.9": ">=5.0.9",
+      "js-yaml@<4.3.1": ">=4.3.1",
+      "nanoid@<3.3.17": ">=3.3.17",
+      "postcss@<8.5.23": ">=8.5.23"
+    }
   }
-}
+}