@am_shork/attest 0.7.0 → 0.7.2

package/dist/core/status.js

@@ -31,16 +31,11 @@ import { hasRecordedRed, recordedOutcome } from './red-record.js';
 export function statusRows(addedIds, plan, firstRun) {
     // Index the scenarios once, the way `validator.ts`'s `detectPotentialDrift`
     // does and for the reason recorded there: filtering the whole plan per
-    // requirement is O(requirements x scenarios). The plan here is the *merged*
-    // one, so the inner term is the whole repository's scenario count while the
-    // outer is only what this change adds.
+    // requirement is O(requirements x scenarios), and the plan here is the
+    // *merged* one, so the inner term is the whole repository's scenario count.
     //
-    // The cost is invisible today — 20 added ids against 2000 scenarios is 40k
-    // comparisons, well under a millisecond — so this is filed as the
-    // inconsistency it is rather than as a slow path. Two functions over one
-    // shape held two beliefs about whether it is worth indexing; they hold one
-    // now. Insertion order is plan order, which is file then line, so the
-    // scenarios a row carries are still in the order their author reads them.
+    // Insertion order is plan order, which is file then line, so the scenarios a
+    // row carries stay in the order their author reads them.
     const byReqId = new Map();
     for (const s of plan.scenarios) {
         const group = byReqId.get(s.reqId);

package/dist/core/terminal.d.ts

@@ -16,32 +16,18 @@ export declare function inline(text: string): string;
 /**
  * Every C0 control except the newline, plus DEL and the C1 range, as a space.
  *
- * A space rather than deletion: removing the byte would silently splice
- * `atte` + `st` into a word that was never in the file, and a diagnostic that
- * quietly rewrites what it quotes is its own kind of wrong.
+ * A space rather than deletion, and the newline exempt by not being in the
+ * class: both are design §9.1, stated there because they hold for every artifact
+ * Attest writes rather than only for this one.
  *
- * The class is written out rather than computed per character. The previous
- * spelling spread the string into a per-code-point array, mapped and rejoined —
- * three allocations proportional to the input, where the engine's own scan needs
- * none when nothing matches, which is the case every real registry is. Measured
- * over 120,000 characters: **27x** faster on plain ASCII, **54x** with
- * newlines, **84x** on CJK. A payload that is *entirely* control bytes is a
- * wash (0.9x), because then there is nothing to fast-path and both spellings
- * build a new string; both are linear either way, so this is a constant factor
- * rather than a second ATX-59.
+ * The one thing §9.1 does not reach: surrogates `D800`–`DFFF` fall outside every
+ * range below, so a pair is never touched and never split — the case that makes
+ * a per-code-point rewrite look necessary when it is not.
  *
- * It is worth the change because the count scales with the registry while the
- * length scales with whatever the registry chose: `render`'s `sanitised` calls
+ * Written out rather than computed per character so the scan allocates nothing
+ * when nothing matches, which is what every real registry is; `render` calls
  * this once per statement, rationale, param key, param value and out-of-scope
- * entry, on the same reachable `render --check` path ATX-59 came off.
- *
- * **Byte-identical to the spelling it replaces**, which is the only thing that
- * mattered: checked exhaustively over every code unit in the BMP, and over
- * 200,000 randomised strings mixing control bytes, CJK, astral characters and
- * lone surrogates. Surrogates are the case the spread existed to get right —
- * `D800`–`DFFF` fall outside every range below, so neither spelling touches a
- * pair or splits one — and newlines survive here as they always did, by not
- * being in the class.
+ * entry, on the `render --check` path ATX-59 came off. Measured in `[0.7.0]`.
  */
 export declare function control(text: string): string;
 //# sourceMappingURL=terminal.d.ts.map

package/dist/core/terminal.js

@@ -41,32 +41,18 @@ export function inline(text) {
 /**
  * Every C0 control except the newline, plus DEL and the C1 range, as a space.
  *
- * A space rather than deletion: removing the byte would silently splice
- * `atte` + `st` into a word that was never in the file, and a diagnostic that
- * quietly rewrites what it quotes is its own kind of wrong.
+ * A space rather than deletion, and the newline exempt by not being in the
+ * class: both are design §9.1, stated there because they hold for every artifact
+ * Attest writes rather than only for this one.
  *
- * The class is written out rather than computed per character. The previous
- * spelling spread the string into a per-code-point array, mapped and rejoined —
- * three allocations proportional to the input, where the engine's own scan needs
- * none when nothing matches, which is the case every real registry is. Measured
- * over 120,000 characters: **27x** faster on plain ASCII, **54x** with
- * newlines, **84x** on CJK. A payload that is *entirely* control bytes is a
- * wash (0.9x), because then there is nothing to fast-path and both spellings
- * build a new string; both are linear either way, so this is a constant factor
- * rather than a second ATX-59.
+ * The one thing §9.1 does not reach: surrogates `D800`–`DFFF` fall outside every
+ * range below, so a pair is never touched and never split — the case that makes
+ * a per-code-point rewrite look necessary when it is not.
  *
- * It is worth the change because the count scales with the registry while the
- * length scales with whatever the registry chose: `render`'s `sanitised` calls
+ * Written out rather than computed per character so the scan allocates nothing
+ * when nothing matches, which is what every real registry is; `render` calls
  * this once per statement, rationale, param key, param value and out-of-scope
- * entry, on the same reachable `render --check` path ATX-59 came off.
- *
- * **Byte-identical to the spelling it replaces**, which is the only thing that
- * mattered: checked exhaustively over every code unit in the BMP, and over
- * 200,000 randomised strings mixing control bytes, CJK, astral characters and
- * lone surrogates. Surrogates are the case the spread existed to get right —
- * `D800`–`DFFF` fall outside every range below, so neither spelling touches a
- * pair or splits one — and newlines survive here as they always did, by not
- * being in the class.
+ * entry, on the `render --check` path ATX-59 came off. Measured in `[0.7.0]`.
  */
 export function control(text) {
     // eslint-disable-next-line no-control-regex -- matching control characters is the whole function.

package/dist/core/types.d.ts

@@ -1,4 +1,4 @@
-export type { Requirement, Registry } from './schema.js';
+export type { Requirement, Registry, ParamValue } from './schema.js';
 export type { IssueCode } from './docs.js';
 import type { IssueCode } from './docs.js';
 /** A scenario extracted statically from a spec file (design §5.2). */

package/dist/core/validator.d.ts

@@ -15,6 +15,7 @@ export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): I
  * - orphan-test: a scenario covers an unknown requirement id
  * - uncovered-requirement: a requirement has no scenario
  * - unbound-param: a statement placeholder has no matching param
+ * - non-scalar-interpolation: a statement placeholder names a structured param
  *
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated

package/dist/core/validator.js

@@ -30,6 +30,7 @@ export function uncoveredIssues(registry, plan) {
  * - orphan-test: a scenario covers an unknown requirement id
  * - uncovered-requirement: a requirement has no scenario
  * - unbound-param: a statement placeholder has no matching param
+ * - non-scalar-interpolation: a statement placeholder names a structured param
  *
  * and one WARNING:
  * - rationale-placeholder: a `{name}` in a rationale, which is never interpolated
@@ -78,6 +79,14 @@ export function validateStructure(registry, plan, registryIncomplete = false) {
     // `Object.hasOwn`, never `in`: `'toString' in {}` is true, so an `in` probe
     // silently accepts placeholders no author declared — and render.ts would then
     // interpolate the prototype method into the document.
+    //
+    // non-scalar-interpolation: the placeholder resolves, but to a value that has
+    // no reading as a sentence. This is what the schema's old scalar-or-list union
+    // was actually defending — `[object Object]` in the rendered requirement
+    // document — and it is stated here because that is where the damage is. A
+    // param the statement never names can be any shape it likes: a kind -> payload
+    // table the scenario reads is not a rendering problem, and refusing it in the
+    // schema refused the drift-prone value along with the display bug.
     for (const [id, req] of Object.entries(registry)) {
         for (const m of req.statement.matchAll(/\{(\w+)\}/g)) {
             const name = m[1];
@@ -88,6 +97,16 @@ export function validateStructure(registry, plan, registryIncomplete = false) {
                     reqId: id,
                     message: `Requirement "${id}" uses {${name}} in its statement, but params does not define it.`,
                 });
+                continue;
+            }
+            if (!interpolatable(req.params[name])) {
+                issues.push({
+                    level: 'ERROR',
+                    code: 'non-scalar-interpolation',
+                    reqId: id,
+                    message: `Requirement "${id}" uses {${name}} in its statement, but that param is ${shapeOf(req.params[name])}. ` +
+                        `A statement placeholder must be a scalar or a list of scalars.`,
+                });
             }
         }
     }
@@ -156,4 +175,22 @@ export function detectPotentialDrift(registry, plan, refs) {
     }
     return issues;
 }
+/**
+ * Whether a param has a reading as a run of words inside a sentence.
+ *
+ * A scalar does; a list of scalars does, as a comma-separated series. Anything
+ * deeper does not — `render` would have to choose a punctuation for structure,
+ * and every choice is a way for the document to say something the registry did
+ * not. `null` is a scalar here: it renders as `null`, which is the value.
+ */
+function interpolatable(value) {
+    const isScalar = (v) => v === null || typeof v !== 'object';
+    return Array.isArray(value) ? value.every(isScalar) : isScalar(value);
+}
+/** How to name the offending shape in the diagnostic, in the author's terms. */
+function shapeOf(value) {
+    if (Array.isArray(value))
+        return 'a list with a structured element';
+    return 'an object';
+}
 //# sourceMappingURL=validator.js.map

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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"
   },
@@ -36,6 +37,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",
@@ -62,20 +81,13 @@
     "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"
+    }
   }
-}
+}