@am_shork/attest 0.9.3 → 0.10.0

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. */
@@ -237,9 +252,18 @@ export function spliceModifications(file, source, changes) {
     const edits = [];
     const wanted = new Map(changes.map((change) => [change.id, change]));
     // Ids the file does not hold, first and in code-unit order: they have no
-    // position to be reported at, and the walk below is driven by positions.
+    // position to be reported at, and the walk below is driven by positions. An
+    // entry the reader refused to describe is reported as *why* rather than as
+    // absent — a file that writes one key twice does hold the entry, and
+    // `entry-not-found` would send its reader looking for something that is
+    // there. Both are decided before a single edit is pushed, because a refusal
+    // arriving mid-walk would leave `edits` half-built for an entry whose offsets
+    // are exactly the ones not to be trusted.
     for (const id of [...wanted.keys()].sort(byCodeUnit)) {
-        if (!layouts.has(id))
+        const twice = layouts.repeated.get(id);
+        if (twice)
+            refusals.push({ reqId: id, ...twice, reason: 'duplicate-key' });
+        else if (!layouts.byId.has(id))
             refusals.push({ reqId: id, reason: 'entry-not-found' });
     }
     // **The file front to back, not the delta.** Driving the walk from the layout
@@ -253,7 +277,7 @@ export function spliceModifications(file, source, changes) {
     // It is also why the layout is `Map`s rather than objects at every level; the
     // container is what carries the order, and `registryEntryLayouts` says why an
     // object cannot.
-    for (const [id, layout] of layouts) {
+    for (const [id, layout] of layouts.byId) {
         const change = wanted.get(id);
         if (!change)
             continue;
@@ -290,14 +314,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 +345,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/static-registry.d.ts

@@ -135,6 +135,31 @@ export interface RegistryEntryLayout {
     /** Where a new field goes, inside the entry's own body. */
     fieldInsertion: RegistryInsertion;
 }
+/**
+ * The key an entry wrote twice, as the path the author would say it —
+ * `statement`, `params.limit`.
+ *
+ * Absent when what repeats is the entry's **own id**, which no field path
+ * names: `params.limit` is a place inside a requirement, and a second entry
+ * under one id is not inside anything.
+ */
+export interface RepeatedKey {
+    field?: string;
+}
+/** Every entry's layout, and the entries this reader refuses to describe. */
+export interface RegistryLayouts {
+    /**
+     * Value spans per requirement id, in the order the file writes them.
+     *
+     * Named `byId` rather than `entries` so nothing reads `layouts.entries` as
+     * the `Map` method of that name — the order this carries is the contract,
+     * and a reader who thinks they are calling `Map.prototype.entries` is a
+     * reader who has stopped seeing it.
+     */
+    byId: Map<string, RegistryEntryLayout>;
+    /** Ids left out of {@link RegistryLayouts.byId} because a key repeats. */
+    repeated: Map<string, RepeatedKey>;
+}
 /**
  * The layout of every entry in a registry file, by requirement id.
  *
@@ -154,6 +179,26 @@ export interface RegistryEntryLayout {
  * schema's `z.record(z.string(), …)` accepts the result. A `Map` keeps insertion
  * order for every key type, so the property holds by construction rather than by
  * the keys happening not to be numbers.
+ *
+ * **A key written twice defeats that pairing, which is why it is refused rather
+ * than described.** `Map.set` on a key it already holds keeps the *first*
+ * insertion's position and takes the *last* call's value — so an entry writing
+ * `params: { limit: 1, other: 'x', limit: 1 }` yields `limit` at position one
+ * carrying the span of the occurrence that sits after `other`, and the walk's
+ * offsets stop ascending — so an earlier edit moves the bytes under a later one
+ * and the replacement lands outside the value it was addressing.
+ *
+ * Nothing upstream refuses such a file, which is why the guard is here: a
+ * duplicate key is a TypeScript *semantic* error and `parseSource` asks only
+ * the syntactic question, so both readers take the file and hand back the last
+ * occurrence, and `--apply` is the one command that writes.
+ *
+ * Refused at every level for one reason, and the id level is not the mild one:
+ * two entries under a single id put a *later* entry's spans at an *earlier*
+ * entry's position, so the disorder is between entries rather than inside one.
+ * Nothing narrower is worth the reach — an entry whose keys are ambiguous is
+ * one no verdict describes, and the file is a defect to fix rather than one to
+ * edit around.
  */
-export declare function registryEntryLayouts(file: string, source: string): Map<string, RegistryEntryLayout> | undefined;
+export declare function registryEntryLayouts(file: string, source: string): RegistryLayouts | undefined;
 //# sourceMappingURL=static-registry.d.ts.map

package/dist/core/static-registry.js

@@ -295,11 +295,23 @@ function constInitializer(sf, name) {
  * The callee is matched against the local name the import bound — an alias or a
  * namespace import is the same call — rather than against any single-argument
  * call, so `buildRegistry({…})` is not mistaken for a registry.
+ *
+ * **Unwrapped here, once, rather than by each caller.** `as const`, `satisfies`
+ * and a bare pair of parentheses do not change the value, so `literalValue`
+ * strips them before it reads — while the write side asks
+ * `ts.isObjectLiteralExpression` of whatever this hands back. A wrapper returned
+ * from here is therefore a registry the readers accept and the writers cannot
+ * locate, on the one command that edits a `*.reqs.ts`. Both sides come through
+ * this function precisely so they cannot disagree about which literal is the
+ * registry; leaving the unwrap to each caller is what puts the disagreement
+ * inside it.
  */
 function authoringCall(expr, sf, fn) {
     if (!ts.isCallExpression(expr) || expr.arguments.length !== 1)
         return undefined;
-    return callsAuthoringFn(expr, localNames(sf, fn), fn) ? expr.arguments[0] : undefined;
+    if (!callsAuthoringFn(expr, localNames(sf, fn), fn))
+        return undefined;
+    return unwrap(expr.arguments[0]);
 }
 /**
  * Whether a call is a call of `fn`, by the local names the imports bound to it.
@@ -520,31 +532,66 @@ function objectInsertion(sf, source, obj) {
  * schema's `z.record(z.string(), …)` accepts the result. A `Map` keeps insertion
  * order for every key type, so the property holds by construction rather than by
  * the keys happening not to be numbers.
+ *
+ * **A key written twice defeats that pairing, which is why it is refused rather
+ * than described.** `Map.set` on a key it already holds keeps the *first*
+ * insertion's position and takes the *last* call's value — so an entry writing
+ * `params: { limit: 1, other: 'x', limit: 1 }` yields `limit` at position one
+ * carrying the span of the occurrence that sits after `other`, and the walk's
+ * offsets stop ascending — so an earlier edit moves the bytes under a later one
+ * and the replacement lands outside the value it was addressing.
+ *
+ * Nothing upstream refuses such a file, which is why the guard is here: a
+ * duplicate key is a TypeScript *semantic* error and `parseSource` asks only
+ * the syntactic question, so both readers take the file and hand back the last
+ * occurrence, and `--apply` is the one command that writes.
+ *
+ * Refused at every level for one reason, and the id level is not the mild one:
+ * two entries under a single id put a *later* entry's spans at an *earlier*
+ * entry's position, so the disorder is between entries rather than inside one.
+ * Nothing narrower is worth the reach — an entry whose keys are ambiguous is
+ * one no verdict describes, and the file is a defect to fix rather than one to
+ * edit around.
  */
 export function registryEntryLayouts(file, source) {
     const found = registryLiteral(file, source);
     if (!found)
         return undefined;
     const { sf, literal } = found;
-    const layouts = new Map();
+    const byId = new Map();
+    const repeated = new Map();
     for (const entry of literal.properties) {
         if (!ts.isPropertyAssignment(entry))
             continue;
         const id = staticName(entry.name);
         if (id === undefined || id === '__proto__')
             continue;
+        if (byId.has(id) || repeated.has(id)) {
+            // Deleted, not left as the first occurrence: both readers take the *last*
+            // one, so describing the first would hand the writer a span whose value
+            // nothing evaluates.
+            byId.delete(id);
+            repeated.set(id, {});
+            continue;
+        }
         const body = unwrap(entry.initializer);
         if (!ts.isObjectLiteralExpression(body))
             continue;
         const fields = new Map();
         const paramKeys = new Map();
         let params;
+        /** The first repeated key seen, as the path the refusal names. */
+        let twice;
         for (const field of body.properties) {
             if (!ts.isPropertyAssignment(field))
                 continue;
             const name = staticName(field.name);
             if (name === undefined || name === '__proto__')
                 continue;
+            if (fields.has(name)) {
+                twice ??= name;
+                continue;
+            }
             // The unwrapped value, so an `as const` or a parenthesis stays outside the
             // span and survives the replacement it wraps.
             const value = unwrap(field.initializer);
@@ -559,18 +606,26 @@ export function registryEntryLayouts(file, source) {
                 const key = staticName(param.name);
                 if (key === undefined || key === '__proto__')
                     continue;
+                if (paramKeys.has(key)) {
+                    twice ??= `params.${key}`;
+                    continue;
+                }
                 const value = unwrap(param.initializer);
                 paramKeys.set(key, { start: value.getStart(sf), end: value.getEnd() });
             }
         }
-        layouts.set(id, {
+        if (twice !== undefined) {
+            repeated.set(id, { field: twice });
+            continue;
+        }
+        byId.set(id, {
             fields,
             paramKeys,
             ...(params ? { paramsInsertion: objectInsertion(sf, source, params) } : {}),
             fieldInsertion: objectInsertion(sf, source, body),
         });
     }
-    return layouts;
+    return { byId, repeated };
 }
 /**
  * The `defineRequirements({ … })` literal of a registry file, with the source

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/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "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"
+    }
   }
-}
+}