@am_shork/attest 0.8.0 → 0.9.0

package/dist/core/splice.js

@@ -14,6 +14,19 @@
 // and the only edit made to the file is text inserted at it. Every other byte is
 // the byte that was already there, which is a property a test can state.
 //
+// **MODIFIED is the second shape, and it is not an insertion — so it is bounded
+// instead.** `spliceModifications` writes a changed value over the value that was
+// there, and the clause above does not cover it: a re-read verifies the values
+// and is blind to what was *lost*, so a replacement that ate a comment would pass
+// one cleanly. What stands in for the pure-insertion property is the **size of
+// the span**. Nothing here replaces an entry; it replaces the source span of one
+// value inside an entry, which is why `statement` and `rationale` are free —
+// their span is a single string literal and a comment does not fit inside a
+// token — and why a `params` key or an `outOfScope` list is checked for one
+// before it is written over, and refused if it carries it. That is the whole of
+// the difference from REMOVED, which is still refused: deleting an entry has no
+// smaller span to fall back to, so its comments have nowhere to go.
+//
 // The generated text is therefore the one thing here that has to be right on its
 // own, and it is generated conservatively: strings are escaped rather than
 // interpolated, params are emitted in code-unit key order so the same delta
@@ -21,7 +34,7 @@
 // reach this file because the gate validated the delta before `--apply` ran.
 import ts from 'typescript';
 import { dirname, relative, resolve } from 'node:path';
-import { registryInsertionPoint } from './static-registry.js';
+import { registryEntryLayouts, registryInsertionPoint } from './static-registry.js';
 import { toPosixPath } from './paths.js';
 import { byCodeUnit, sortDeep } from './order.js';
 /**
@@ -155,15 +168,23 @@ export function requirementSource(id, req, indent) {
     // are as much of the emitted text as the outer ones.
     const params = Object.entries(sortDeep(req.params));
     if (params.length > 0) {
-        const body = params.map(([k, v]) => `${keySource(k)}: ${paramSource(v)}`).join(', ');
+        const body = params.map(([k, v]) => paramEntrySource(k, v)).join(', ');
         lines.push(`${inner}params: { ${body} },`);
     }
     if (req.outOfScope.length > 0) {
-        lines.push(`${inner}outOfScope: [${req.outOfScope.map((s) => tsString(s)).join(', ')}],`);
+        lines.push(`${inner}outOfScope: ${outOfScopeSource(req.outOfScope)},`);
     }
     lines.push(`${indent}}`);
     return lines.join('\n');
 }
+/** One `outOfScope` list as source. Shared with the modification writer below. */
+function outOfScopeSource(entries) {
+    return `[${entries.map((s) => tsString(s)).join(', ')}]`;
+}
+/** One `params` key as source, at the key order the emitter writes everywhere. */
+function paramEntrySource(key, value) {
+    return `${keySource(key)}: ${paramSource(sortDeep(value))}`;
+}
 /**
  * `source` with `additions` inserted into its registry literal.
  *
@@ -187,6 +208,215 @@ export function spliceRequirements(file, source, additions) {
     const text = point.leadingComma ? `,\n${entries}` : `\n${entries},\n`;
     return source.slice(0, point.offset) + text + source.slice(point.offset);
 }
+/**
+ * `source` with each modified requirement's **changed values** written over.
+ *
+ * The other half of `--apply`'s write-back, and the one the design refused for
+ * five releases. What makes it allowable is stated at the top of this file and
+ * is a property of *granularity*: this never replaces an entry, only the span of
+ * a value inside one. A `statement` is a single string literal, so a comment
+ * cannot be inside what it overwrites; a `params` key or an `outOfScope` list
+ * can be, and that span is the only place this has to ask. Everything else in
+ * the file — the keys, the commas, the layout, every comment attached to a field
+ * that did not move — is bytes this does not address.
+ *
+ * A refusal is per value and the caller's response is whole-merge: the list is
+ * returned complete rather than at the first one, so an author fixing them by
+ * hand sees the whole of what stopped it.
+ *
+ * `undefined` under the same condition `spliceRequirements` returns it, through
+ * the same reader.
+ */
+export function spliceModifications(file, source, changes) {
+    if (changes.length === 0)
+        return { ok: true, source };
+    const layouts = registryEntryLayouts(file, source);
+    if (!layouts)
+        return undefined;
+    const refusals = [];
+    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.
+    for (const id of [...wanted.keys()].sort(byCodeUnit)) {
+        if (!layouts[id])
+            refusals.push({ reqId: id, reason: 'entry-not-found' });
+    }
+    // **The file front to back, not the delta.** Driving the walk from the layout
+    // rather than from `changes` is what makes every edit below land at a higher
+    // offset than the one before it — entries in the order the file writes them,
+    // fields in the order the entry writes them, params in the order the entry
+    // writes those. That ordering is not cosmetic: it is what lets the pass at the
+    // bottom be a `reverse()` rather than a numeric sort, which ATX-15 does not
+    // allow in `src/` and would be the wrong shape anyway — an ordering that holds
+    // by construction beats one restored after the fact.
+    for (const [id, layout] of Object.entries(layouts)) {
+        const change = wanted.get(id);
+        if (!change)
+            continue;
+        const { before, after } = change;
+        // Everything this entry writes goes through one of these three, which is
+        // what lets `editParams` be a function rather than a fourth copy of them.
+        const out = {
+            at: (field, span, text) => {
+                // The one question a replacement has that an insertion does not. Run over
+                // every span rather than only the two that can fail it, so the rule is
+                // "nothing is written over a comment" rather than a list of fields somebody
+                // has to keep in step with the schema — on `statement` and `rationale` it
+                // is a scan of one token and can never fire.
+                if (spanHasComment(source.slice(span.start, span.end))) {
+                    refusals.push({ reqId: id, field, reason: 'comment' });
+                    return;
+                }
+                edits.push({ start: span.start, end: span.end, text });
+            },
+            insert: (offset, text) => edits.push({ start: offset, end: offset, text }),
+            refuse: (field, reason) => refusals.push({ reqId: id, field, reason }),
+        };
+        // Fields the entry does not write yet. Collected rather than emitted, since
+        // they share one offset — the end of the entry's body — and several edits at
+        // one position is the one thing the back-to-front pass cannot order.
+        const opened = [];
+        const openField = (name, value) => {
+            opened.push(`${layout.fieldInsertion.indent}${name}: ${value}`);
+        };
+        for (const [name, span] of Object.entries(layout.fields)) {
+            if (name === 'statement' || name === 'rationale') {
+                if (before[name] !== after[name])
+                    out.at(name, span, tsString(after[name]));
+            }
+            else if (name === 'outOfScope') {
+                if (!sameValue(before.outOfScope, after.outOfScope)) {
+                    out.at(name, span, outOfScopeSource(after.outOfScope));
+                }
+            }
+            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.
+        }
+        if (!layout.fields['statement'] && before.statement !== after.statement) {
+            openField('statement', tsString(after.statement));
+        }
+        if (!layout.fields['rationale'] && before.rationale !== after.rationale) {
+            openField('rationale', tsString(after.rationale));
+        }
+        if (!layout.fields['params']) {
+            const fresh = freshParams(before, after);
+            if (fresh.length > 0)
+                openField('params', `{ ${fresh.join(', ')} }`);
+        }
+        if (!layout.fields['outOfScope'] && !sameValue(before.outOfScope, after.outOfScope)) {
+            openField('outOfScope', outOfScopeSource(after.outOfScope));
+        }
+        if (opened.length > 0) {
+            const point = layout.fieldInsertion;
+            const body = opened.join(',\n');
+            // The comma leads rather than trails, for the reason the registry splice's
+            // does: the offset sits *before* whatever trailing comma the entry already
+            // carries, so writing one here would produce two.
+            edits.push({
+                start: point.offset,
+                end: point.offset,
+                text: point.leadingComma ? `,\n${body}` : `\n${body},\n`,
+            });
+        }
+    }
+    if (refusals.length > 0)
+        return { ok: false, refusals };
+    // Back to front, for the reason `repointImport` applies its edits that way: an
+    // edit cannot move an offset that lies before it, so every span stays valid as
+    // the string is rewritten under them. A `reverse()` and not a sort, because
+    // the walk above produced them in source order.
+    let out = source;
+    for (const edit of [...edits].reverse()) {
+        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    }
+    return { ok: true, source: out };
+}
+/**
+ * The `params` half of one entry: a value per changed key, and one insertion for
+ * the keys the entry does not have.
+ *
+ * Split out because it is the only field with structure of its own, and inlining
+ * it put three loops inside a loop inside a loop. Its edits are emitted in the
+ * order the file writes the keys, then the insertion at the end of the object —
+ * which is what keeps the caller's ascending-offset property true through it.
+ */
+function editParams(layout, before, after, out) {
+    // A key the end state has lost. Unreachable through the command — `applyDelta`
+    // merges `params` key by key and a patch has no spelling for a deletion — and
+    // refused rather than ignored, for the reason `keySource` refuses `__proto__`:
+    // this is the module that *writes*, and silently keeping a value the proved
+    // end state does not have is the one outcome worse than stopping.
+    for (const key of Object.keys(before.params).sort(byCodeUnit)) {
+        if (!Object.hasOwn(after.params, key)) {
+            out.refuse(`params.${key}`, 'param-dropped');
+        }
+    }
+    // A key the file holds and this cannot locate: its value is not written as a
+    // literal, which the registry reader refuses before a merge can reach here.
+    // Named rather than skipped, so the guard does not depend on something
+    // upstream holding.
+    for (const key of Object.keys(before.params).sort(byCodeUnit)) {
+        if (!layout.paramKeys[key] && !sameValue(before.params[key], after.params[key])) {
+            out.refuse(`params.${key}`, 'not-a-literal');
+        }
+    }
+    for (const [key, span] of Object.entries(layout.paramKeys)) {
+        if (!Object.hasOwn(after.params, key))
+            continue;
+        const value = after.params[key];
+        if (sameValue(before.params[key], value))
+            continue;
+        // The value alone: the span is the value's, and the key in front of it is a
+        // byte this does not address — the same rule that keeps the comma, the
+        // comment and the layout where they are.
+        out.at(`params.${key}`, span, paramSource(sortDeep(value)));
+    }
+    const fresh = freshParams(before, after);
+    if (fresh.length === 0)
+        return;
+    if (!layout.paramsInsertion) {
+        // A `params` that is not an object literal, so there is no inside to write
+        // into. Same guard as the keys above, one level out.
+        out.refuse('params', 'not-a-literal');
+        return;
+    }
+    const point = layout.paramsInsertion;
+    out.insert(point.offset, point.leadingComma ? `, ${fresh.join(', ')}` : ` ${fresh.join(', ')} `);
+}
+/** The params the end state has and the file does not, as source, in key order. */
+function freshParams(before, after) {
+    return Object.keys(after.params)
+        .sort(byCodeUnit)
+        .filter((key) => !Object.hasOwn(before.params, key))
+        .map((key) => paramEntrySource(key, after.params[key]));
+}
+/**
+ * Whether a span of source carries a comment.
+ *
+ * Scanned rather than matched, and that is the whole of why it is correct: `//`
+ * inside a string is not a comment, and a registry's statements are prose full
+ * of URLs. The scanner is the same one the reader's parser is built on, so the
+ * two agree about what a comment is by construction.
+ */
+function spanHasComment(text) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, /* skipTrivia */ false);
+    scanner.setText(text);
+    for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+        if (token === ts.SyntaxKind.SingleLineCommentTrivia ||
+            token === ts.SyntaxKind.MultiLineCommentTrivia) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Content equality for one value, by the canonical form the engine compares on. */
+function sameValue(a, b) {
+    return JSON.stringify(sortDeep(a)) === JSON.stringify(sortDeep(b));
+}
 /**
  * `source` with every import of `from` repointed at `to`.
  *
@@ -196,9 +426,10 @@ export function spliceRequirements(file, source, additions) {
  * discipline as the splice, for the same reason.
  *
  * The extension is taken from the specifier being replaced rather than chosen
- * here. Whether a project writes `./x.reqs.js` or `./x.reqs.ts` is a property of
- * its module resolution, uniform across the project, and already answered by the
- * specifier sitting in front of us.
+ * here. Whether a project writes `./x.reqs.js`, `./x.reqs.ts` or `./x.reqs` is a
+ * property of its module resolution, uniform across the project, and already
+ * answered by the specifier sitting in front of us — the third spelling
+ * included, where the answer is "none".
  */
 export function repointImport(file, source, from, to) {
     const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, /* setParentNodes */ true);
@@ -212,10 +443,13 @@ export function repointImport(file, source, from, to) {
             continue;
         if (!resolvesTo(dir, spec.text, from))
             continue;
+        // Unconditional, because "no extension" is an answer and not a missing one:
+        // a bundler-resolution project writes every specifier that way, so the empty
+        // case has to strip what `to` carries rather than leave it. Guarding this on
+        // a non-empty `ext` is only safe while `resolvesTo` rejects an extensionless
+        // specifier — the two move together.
         const ext = spec.text.endsWith('.js') ? '.js' : spec.text.endsWith('.ts') ? '.ts' : '';
-        let target = toPosixPath(relative(dir, to));
-        if (ext)
-            target = target.replace(/\.[^./]+$/, ext);
+        let target = toPosixPath(relative(dir, to)).replace(/\.[^./]+$/, ext);
         // A bare `x.reqs.js` is a package specifier, not a sibling file.
         if (!target.startsWith('.'))
             target = `./${target}`;
@@ -248,14 +482,19 @@ export function repointImport(file, source, from, to) {
 /**
  * Whether `specifier`, written in a file under `dir`, names `target`.
  *
- * The `.js`-for-`.ts` spelling is accepted because NodeNext resolution requires
- * it, and a project using it writes every specifier that way — including the one
- * this is looking for.
+ * Three spellings of one import, because module resolution decides which a
+ * project writes and it writes that one everywhere — including here. The
+ * `.js`-for-`.ts` spelling is what NodeNext requires; the extensionless one is
+ * what bundler resolution produces, and matching it is the whole reason a
+ * specifier can be repointed at all in such a project.
  */
 function resolvesTo(dir, specifier, target) {
     if (!specifier.startsWith('.'))
         return false;
     const resolved = resolve(dir, specifier);
-    return resolved === target || resolved.replace(/\.js$/, '.ts') === target;
+    // Only `.ts` is appended, not `.js` as well: `target` is the delta, whose name
+    // is the constant `requirements.delta.ts`, so the symmetrical clause would be
+    // unreachable — a hypothetical seam rather than a real one.
+    return (resolved === target || resolved.replace(/\.js$/, '.ts') === target || `${resolved}.ts` === target);
 }
 //# sourceMappingURL=splice.js.map

package/dist/core/static-registry.d.ts

@@ -101,4 +101,46 @@ export interface RegistryInsertion {
     leadingComma: boolean;
 }
 export declare function registryInsertionPoint(file: string, source: string): RegistryInsertion | undefined;
+/** The source span of a value, as offsets into the file it was read from. */
+export interface ValueSpan {
+    start: number;
+    end: number;
+}
+/**
+ * Where each part of one requirement's entry sits in the file, for a merge that
+ * has to **replace** a value rather than add one (design §7).
+ *
+ * This is the reading half of writing MODIFIED back. A splice is a pure
+ * insertion and is safe by construction; a modification is not, and the property
+ * that replaces "every other byte is the byte that was there" is the *size of
+ * what it overwrites*. So nothing here describes an entry — it describes the
+ * spans of its individual values, and the writer replaces one value at a time.
+ * Note what that buys at the top of `splice.ts`: a `statement` is one string
+ * literal, and a comment does not fit inside a token.
+ *
+ * The spans are of the values, never of the properties that hold them: the key,
+ * the colon, the comma and every comment around them are outside every span
+ * this hands back, so they cannot be written over by anything using it.
+ */
+export interface RegistryEntryLayout {
+    /** Value span of each field the entry writes, by field name. */
+    fields: Record<string, ValueSpan>;
+    /** Value span of each key of `params`, when the entry writes one as a literal. */
+    paramKeys: Record<string, ValueSpan>;
+    /** Where a new `params` key goes — absent when the entry writes no `params`. */
+    paramsInsertion?: RegistryInsertion;
+    /** Where a new field goes, inside the entry's own body. */
+    fieldInsertion: RegistryInsertion;
+}
+/**
+ * The layout of every entry in a registry file, by requirement id.
+ *
+ * `undefined` under exactly the condition `registryInsertionPoint` returns it —
+ * one walker answers "where is this registry's literal" for both, so a file the
+ * splice refuses cannot be one the modification accepts. Entries whose *shape*
+ * this cannot describe (a computed key, a value built by a call) are absent from
+ * the result rather than partially described, which the caller reads as a
+ * refusal for that id: an entry nothing can locate is not one to edit.
+ */
+export declare function registryEntryLayouts(file: string, source: string): Record<string, RegistryEntryLayout> | undefined;
 //# sourceMappingURL=static-registry.d.ts.map

package/dist/core/static-registry.js

@@ -425,12 +425,32 @@ function objectValue(expr) {
     return out;
 }
 function propertyName(name) {
+    const key = staticName(name);
+    if (key !== undefined)
+        return key;
+    // The reason is re-derived here rather than carried out of `staticName`,
+    // which has no diagnostics to give: the extraction refuses a whole file over
+    // this, so the sentence has to name which of the two it met.
+    throw new NotStatic(name, ts.isNumericLiteral(name) ? 'a number this reader cannot spell out' : 'a computed key');
+}
+/**
+ * A property's key when the source text alone fixes it, `undefined` when it does
+ * not.
+ *
+ * The total half of `propertyName`, which is the form the layout reader needs:
+ * that one promises a result for a whole file and cannot throw over one entry it
+ * merely fails to describe. One function for both so a key the extractor reads
+ * and a key the writer locates can never be two different strings.
+ */
+function staticName(name) {
     if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) {
         return name.text;
     }
-    if (ts.isNumericLiteral(name))
-        return String(numericValue(name));
-    throw new NotStatic(name, 'a computed key');
+    if (ts.isNumericLiteral(name)) {
+        const value = numericText(name);
+        return value === undefined ? undefined : String(value);
+    }
+    return undefined;
 }
 /**
  * The value of a numeric literal, read from its source spelling.
@@ -441,12 +461,117 @@ function propertyName(name) {
  * first, since `Number('1_000')` is NaN.
  */
 function numericValue(node) {
-    const value = Number(node.getText().replace(/_/g, ''));
-    if (Number.isNaN(value))
+    const value = numericText(node);
+    if (value === undefined)
         throw new NotStatic(node, 'a number this reader cannot spell out');
     return value;
 }
+/** The same reading, without the refusal — see `staticName`. */
+function numericText(node) {
+    const value = Number(node.getText().replace(/_/g, ''));
+    return Number.isNaN(value) ? undefined : value;
+}
 export function registryInsertionPoint(file, source) {
+    const found = registryLiteral(file, source);
+    return found && objectInsertion(found.sf, source, found.literal);
+}
+/**
+ * Where a new member goes in an object literal.
+ *
+ * Three sites ask, at three depths — the registry's own body, a requirement's
+ * body, and its `params` — and the answer is the same question each time. One
+ * function because the interesting half is a rule about *commas*, and a second
+ * copy of it is a second trailing-comma policy the moment one is edited.
+ */
+function objectInsertion(sf, source, obj) {
+    const last = obj.properties[obj.properties.length - 1];
+    if (!last) {
+        // An empty body: open it rather than continue it. What separates the new
+        // member from the braces is the caller's, since a registry opens a line for
+        // its entry and a `params` writes one on the line it is already on.
+        return {
+            offset: obj.getStart(sf) + 1,
+            indent: indentOf(sf, source, obj) + '  ',
+            leadingComma: false,
+        };
+    }
+    // Deliberately the *end of the last property*, not the end of the literal:
+    // inserting here sits before any trailing comma the file already has, so one
+    // leading comma is correct whether or not that comma is present, and the
+    // file's own trailing-comma style is left exactly as it was.
+    return { offset: last.getEnd(), indent: indentOf(sf, source, last), leadingComma: true };
+}
+/**
+ * The layout of every entry in a registry file, by requirement id.
+ *
+ * `undefined` under exactly the condition `registryInsertionPoint` returns it —
+ * one walker answers "where is this registry's literal" for both, so a file the
+ * splice refuses cannot be one the modification accepts. Entries whose *shape*
+ * this cannot describe (a computed key, a value built by a call) are absent from
+ * the result rather than partially described, which the caller reads as a
+ * refusal for that id: an entry nothing can locate is not one to edit.
+ */
+export function registryEntryLayouts(file, source) {
+    const found = registryLiteral(file, source);
+    if (!found)
+        return undefined;
+    const { sf, literal } = found;
+    const layouts = {};
+    for (const entry of literal.properties) {
+        if (!ts.isPropertyAssignment(entry))
+            continue;
+        const id = staticName(entry.name);
+        if (id === undefined || id === '__proto__')
+            continue;
+        const body = unwrap(entry.initializer);
+        if (!ts.isObjectLiteralExpression(body))
+            continue;
+        const fields = {};
+        const paramKeys = {};
+        let params;
+        for (const field of body.properties) {
+            if (!ts.isPropertyAssignment(field))
+                continue;
+            const name = staticName(field.name);
+            if (name === undefined || name === '__proto__')
+                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);
+            fields[name] = { start: value.getStart(sf), end: value.getEnd() };
+            if (name === 'params' && ts.isObjectLiteralExpression(value))
+                params = value;
+        }
+        if (params) {
+            for (const param of params.properties) {
+                if (!ts.isPropertyAssignment(param))
+                    continue;
+                const key = staticName(param.name);
+                if (key === undefined || key === '__proto__')
+                    continue;
+                const value = unwrap(param.initializer);
+                paramKeys[key] = { start: value.getStart(sf), end: value.getEnd() };
+            }
+        }
+        layouts[id] = {
+            fields,
+            paramKeys,
+            ...(params ? { paramsInsertion: objectInsertion(sf, source, params) } : {}),
+            fieldInsertion: objectInsertion(sf, source, body),
+        };
+    }
+    return layouts;
+}
+/**
+ * The `defineRequirements({ … })` literal of a registry file, with the source
+ * file it was parsed from.
+ *
+ * Both write-side readers go through it, for the reason there is one reader:
+ * "which literal is the registry" must have one answer, and a second walk that
+ * accepted a file the first refuses would let a modification edit a file the
+ * splice would not touch.
+ */
+function registryLiteral(file, source) {
     // The write site, and the one where a recovered AST does damage rather than
     // merely misreports: an offset taken from a file that does not compile would
     // splice a new requirement into it. `undefined` is this function's documented
@@ -462,18 +587,7 @@ export function registryInsertionPoint(file, source) {
     const arg = authoringCall(exported, sf, 'defineRequirements');
     if (!arg || !ts.isObjectLiteralExpression(arg))
         return undefined;
-    const last = arg.properties[arg.properties.length - 1];
-    if (!last) {
-        // An empty registry: open the body rather than continue it. The trailing
-        // newline is written by the caller, so `{` does not end up sharing a line
-        // with the entry and the closing `}`.
-        return { offset: arg.getStart(sf) + 1, indent: indentOf(sf, source, arg) + '  ', leadingComma: false };
-    }
-    // Deliberately the *end of the last property*, not the end of the literal:
-    // inserting here sits before any trailing comma the file already has, so one
-    // leading comma is correct whether or not that comma is present, and the
-    // file's own trailing-comma style is left exactly as it was.
-    return { offset: last.getEnd(), indent: indentOf(sf, source, last), leadingComma: true };
+    return { sf, literal: arg };
 }
 /**
  * The whitespace a node's line opens with.

package/dist/core/validator.d.ts

@@ -13,6 +13,7 @@ import type { AttestPlan, Issue, ParamRef, Registry } from './types.js';
 export declare function uncoveredIssues(registry: Registry, plan: AttestPlan): Issue[];
 /**
  * Static structural validation (design §5.3). Emits ERROR-level issues for:
+ * - empty-spec: the root declares no requirements at all
  * - 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

package/dist/core/validator.js

@@ -28,6 +28,7 @@ export function uncoveredIssues(registry, plan) {
 }
 /**
  * Static structural validation (design §5.3). Emits ERROR-level issues for:
+ * - empty-spec: the root declares no requirements at all
  * - 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
@@ -47,6 +48,27 @@ export function uncoveredIssues(registry, plan) {
 export function validateStructure(registry, plan, unreadable = []) {
     const issues = [];
     const knownIds = new Set(Object.keys(registry));
+    // empty-spec: nothing under this root declares intent, so no finding below is
+    // about a requirement — and the report has no line saying why. It is stated
+    // first because everything else this function can emit against an empty
+    // registry is fallout from it: every scenario in the project is an orphan, and
+    // the diagnosis after 135 of them is a diagnosis nobody reaches.
+    //
+    // Guarded on `unreadable`, which is the same withdrawal the orphan advice
+    // makes below and for the same reason. "Point attest at the directory holding
+    // your *.reqs.ts files" is right for a root that has none, and **wrong** for
+    // one whose registry is sitting right there and failed to load: the files were
+    // found, the fix is the load error already in the report, and following the
+    // hint would move a working path. A registry that could not be read is not an
+    // absent one, and the two take different repairs.
+    if (knownIds.size === 0 && unreadable.length === 0) {
+        issues.push({
+            level: 'ERROR',
+            code: 'empty-spec',
+            message: `No requirements found under this root, so there is no intent here to attest. ` +
+                `Point attest at the directory holding your *.reqs.ts files, or add one.`,
+        });
+    }
     // orphan-test: covers a requirement that does not exist.
     //
     // "Add it to the registry, or fix the id" is the right advice for an id that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.8.0",
+  "version": "0.9.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",
   "engines": {