eval-quality 3.1.0 → 3.3.0

package/dist/gates/check-licenses.mjs

@@ -218,6 +218,13 @@ function findDependencyPath(packages, edges, targetPath) {
  * fails every entry or silently permits every entry, and a gate that picks one
  * of those on the caller's behalf is the fallback this package does not have.
  *
+ * `options.undeclared` is the rows for entries whose manifest declares no
+ * licence, each a `prefix`, the one identifier the entry is read as under
+ * `readAs`, the `evidence` for that reading and a `reason`. The caller has
+ * already decided which rows apply to this lockfile. A row that reached no
+ * undeclared entry comes back by prefix in `unusedUndeclared`, so the caller
+ * can refuse a reading nothing is holding.
+ *
  * `options.source` is the path this lockfile was read from, named in the refusal
  * a document without a `packages` object earns.
  */
@@ -229,6 +236,7 @@ export function checkLicenses(lockfile, options = {}) {
     const allowlist = new Set(allowed);
     const label = typeof options.label === 'string' ? options.label : 'allowlist';
     const tolerances = options.tolerances ?? [];
+    const undeclared = options.undeclared ?? [];
     const source = typeof options.source === 'string' ? options.source : 'the lockfile';
     // Every entry is read from `packages`, which npm writes from lockfileVersion 2
     // onward. Defaulting it to {} turned an npm 6 lockfile, or a path naming
@@ -247,6 +255,8 @@ export function checkLicenses(lockfile, options = {}) {
     const entries = Object.entries(packages).filter(([pkgPath, meta]) => pkgPath !== '' && !meta.link);
     const violations = [];
     const tolerated = [];
+    const readByEvidence = [];
+    const usedPrefixes = new Set();
     const reasons = new Set();
     for (const [pkgPath, meta] of entries) {
         const name = meta.name ?? pkgPath.split('node_modules/').pop();
@@ -259,6 +269,21 @@ export function checkLicenses(lockfile, options = {}) {
         // of the artifact being installed. Requiring `resolved` to be the one tarball
         // URL the registry has for this entry's own name and version is what ties the
         // two together.
+        // "Declares nothing" is an absent, null or blank field. A field present in
+        // a shape `licenseStringOf` does not read, an array or an object with no
+        // `type`, declares something and fails below as it always has, rather than
+        // reading as nothing and taking a row's evidence.
+        const declaresNothing = meta.license === undefined ||
+            meta.license === null ||
+            (typeof meta.license === 'string' && meta.license.trim() === '');
+        const matching = declaresNothing
+            ? undeclared.filter((candidate) => name.startsWith(candidate.prefix))
+            : [];
+        // A row is held to have reached an entry before the resolved-URL check
+        // below, so a tampered entry the row documents reports the tampering and
+        // never a row that reaches nothing.
+        for (const row of matching)
+            usedPrefixes.add(row.prefix);
         const expected = registryTarballUrl(name, version);
         if (meta.resolved !== expected) {
             violations.push({
@@ -271,6 +296,48 @@ export function checkLicenses(lockfile, options = {}) {
             continue;
         }
         const license = licenseStringOf(meta);
+        // A manifest with no licence field declares nothing, so there is no
+        // expression to widen and no tolerance is consulted. A row under
+        // `undeclared` supplies the reading and its evidence, and the identifier is
+        // then held by `isAllowed` like a declared one, so a row cannot admit what
+        // the allowlist refuses.
+        if (declaresNothing) {
+            const blank = typeof meta.license === 'string';
+            const undeclaredAs = blank
+                ? 'declares no licence, the field is blank'
+                : 'declares no licence';
+            if (matching.length === 0) {
+                violations.push({
+                    path: pkgPath,
+                    name,
+                    version,
+                    license: meta.license ?? null,
+                    reason: undeclaredAs,
+                });
+                continue;
+            }
+            // The first row whose reading the allowlist admits, as a tolerance is
+            // the first that holds; the failure names every reading that was tried.
+            const row = matching.find((candidate) => isAllowed(candidate.readAs, allowlist));
+            if (row === undefined) {
+                const tried = [...new Set(matching.map((c) => c.readAs))].join(' or ');
+                violations.push({
+                    path: pkgPath,
+                    name,
+                    version,
+                    license: meta.license ?? null,
+                    reason: `read by evidence as ${tried}, which is outside ${label}`,
+                });
+                continue;
+            }
+            readByEvidence.push({
+                entry: `${name}@${version}`,
+                readAs: row.readAs,
+                evidence: row.evidence,
+                reason: row.reason,
+            });
+            continue;
+        }
         if (isAllowed(license, allowlist))
             continue;
         const tolerance = tolerances.find((candidate) => isTolerated(candidate, meta, name, license, allowlist));
@@ -279,27 +346,33 @@ export function checkLicenses(lockfile, options = {}) {
             reasons.add(tolerance.reason);
             continue;
         }
-        violations.push({ path: pkgPath, name, version, license });
+        // The raw field when the reader made nothing of it, so `["MIT"]` prints as
+        // what it is and never as the null that means "declares nothing".
+        violations.push({
+            path: pkgPath,
+            name,
+            version,
+            license: license ?? meta.license,
+        });
     }
     tolerated.sort();
-    const toleranceReasons = [...reasons].sort();
-    if (violations.length === 0)
-        return {
-            violations: [],
-            entryCount: entries.length,
-            tolerated,
-            toleranceReasons,
-            policy: label,
-        };
-    const edges = buildEdges(packages);
-    for (const violation of violations) {
-        violation.dependencyPath = findDependencyPath(packages, edges, violation.path);
-    }
-    return {
+    readByEvidence.sort((a, b) => a.entry < b.entry ? -1 : a.entry > b.entry ? 1 : 0);
+    const report = {
         violations,
         entryCount: entries.length,
         tolerated,
-        toleranceReasons,
+        toleranceReasons: [...reasons].sort(),
+        readByEvidence,
+        unusedUndeclared: undeclared
+            .map((row) => row.prefix)
+            .filter((prefix) => !usedPrefixes.has(prefix)),
         policy: label,
     };
+    if (violations.length === 0)
+        return report;
+    const edges = buildEdges(packages);
+    for (const violation of violations) {
+        violation.dependencyPath = findDependencyPath(packages, edges, violation.path);
+    }
+    return report;
 }

package/dist/gates/consumer-pattern.js

@@ -0,0 +1,104 @@
+// The bound on a regular expression a consumer writes, shared by every gate
+// that takes one.
+//
+// Four gates now accept a pattern out of `eval-quality.config.json`, and the
+// bound has to be the same in all four: a length cap on the source, a flag set
+// that excludes the two flags carrying a match position between calls, a
+// refusal of backreferences, and a compile check so a malformed pattern is a
+// configuration error rather than a crash at the first line it reads.
+//
+// `package-boundary.ts` states why these are the bounds and what they leave
+// uncovered. That note stays there, beside `MAX_SCANNED_LINE`, because the
+// input bound is the scanner's own and only the pattern half is shared.
+//
+// Run by `node` directly: Node's type stripping erases types only, so no
+// TypeScript enum, namespace, parameter property, or non-type re-export may
+// appear in this file or anything it imports.
+import { z } from 'zod';
+export const MAX_PATTERN_LENGTH = 200;
+/**
+ * The same bound for a pattern that describes a sentence.
+ *
+ * A boundary pattern names a construct, and 200 characters is more than any of
+ * them needs. A documentation pattern quotes prose: it carries the words either
+ * side of the number or the list it captures, because those words are what stop
+ * it matching a different sentence on the same page. Holding it to the shorter
+ * bound would push consumers towards loose patterns, which is the failure mode
+ * these gates exist to close.
+ *
+ * Length is the weaker half of the bound in both cases. What the work actually
+ * rests on is the backreference refusal and the size of the subject, and both
+ * are unchanged here.
+ */
+export const MAX_PROSE_PATTERN_LENGTH = 800;
+/**
+ * `\1` through `\9` and `\k<name>`. It over-refuses an escaped backslash
+ * followed by a digit, which is a literal backslash and not a backreference,
+ * and that spelling has no place in a configured pattern anyway.
+ */
+const BACKREFERENCE = /\\[1-9]|\\k</;
+const FLAG_MESSAGE = 'admits only i, m, s, u and v. A g or a y carries a match position between calls, so a pattern holding either would match every second thing it should have matched';
+export const PatternSource = z.string().min(1).max(MAX_PATTERN_LENGTH);
+export const ProsePatternSource = z
+    .string()
+    .min(1)
+    .max(MAX_PROSE_PATTERN_LENGTH);
+export const PatternFlags = z
+    .string()
+    .regex(/^[imsuv]*$/, FLAG_MESSAGE)
+    .default('');
+/**
+ * The two refusals a length bound and a flag set do not cover. Exported as a
+ * function so a gate composing its own object around a pattern reports them
+ * against its own key path.
+ */
+export function refinePattern(match, flags, ctx, path) {
+    if (BACKREFERENCE.test(match)) {
+        ctx.addIssue({
+            code: 'custom',
+            path,
+            message: 'carries a backreference, which is the construct that turns a linear scan into an exponential one; write the pattern without one',
+        });
+    }
+    try {
+        new RegExp(match, flags);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: 'custom',
+            path,
+            message: `is not a regular expression: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+/**
+ * A pattern on its own, for a gate with nothing to say about it beyond where it
+ * is matched. A gate that reports under a name or carries a reason composes
+ * `PatternSource`, `PatternFlags` and `refinePattern` into its own object
+ * instead.
+ */
+export const ConsumerPattern = z
+    .strictObject({
+    match: PatternSource.describe('The regular expression, as source text.'),
+    flags: PatternFlags.describe('Regular-expression flags. Empty by default.'),
+})
+    .superRefine((pattern, ctx) => {
+    refinePattern(pattern.match, pattern.flags, ctx, ['match']);
+});
+/** The same object at the prose bound, for the documentation gates. */
+export const ProsePattern = z
+    .strictObject({
+    match: ProsePatternSource.describe('The regular expression, as source text.'),
+    flags: PatternFlags.describe('Regular-expression flags. Empty by default.'),
+})
+    .superRefine((pattern, ctx) => {
+    refinePattern(pattern.match, pattern.flags, ctx, ['match']);
+});
+export const compilePattern = (pattern) => new RegExp(pattern.match, pattern.flags);
+/**
+ * The same pattern with `g` added, for a gate that counts every occurrence.
+ * `g` is outside the configured flag set because a consumer cannot be given a
+ * stateful `lastIndex`; a gate that needs it adds it at the point of use, where
+ * the regular expression is built fresh for each subject.
+ */
+export const compileGlobalPattern = (pattern) => new RegExp(pattern.match, `${pattern.flags}g`);

package/dist/gates/dependency-direction.js

@@ -473,6 +473,20 @@ function scanFile(file, source, files, graph, violations) {
             const openIndex = tokens[i + 1]?.kind === SyntaxKind.QuestionDotToken ? i + 2 : i + 1;
             if (tokens[openIndex]?.kind !== SyntaxKind.OpenParenToken)
                 continue;
+            // The site this arm exists for is the free identifier `require` called
+            // with a specifier. Two shapes share its tokens and are ordinary
+            // JavaScript: a member call, `sandbox.require('fs')`, where the token
+            // before is `.` or `?.`, and a method named require, `require(name) {`
+            // in an object literal or a class, where the token after the matching
+            // `)` is `{`. A call's own `)` is never followed by `{`, so
+            // `if (require('x')) {` still reads as the call it is. A consumer
+            // renaming a mock to get past this arm is a gate teaching the wrong lesson.
+            const before = tokens[i - 1]?.kind;
+            if (before === SyntaxKind.DotToken ||
+                before === SyntaxKind.QuestionDotToken ||
+                isMethodDefinition(tokens, i, openIndex)) {
+                continue;
+            }
             if (graph.commonjs === 'forbid') {
                 violations.push({
                     file,
@@ -545,6 +559,122 @@ function scanFile(file, source, files, graph, violations) {
  * against `graph` and returns every violation found, in no particular cross-file
  * order.
  */
+/**
+ * A modifier or generator marker that can sit between a declaration boundary
+ * and the member name it modifies: `async`, `static`, `get`, `set`,
+ * `readonly`, an access modifier, or `*`. Skipped when walking backward from
+ * `require` to find what actually introduces it.
+ */
+const MEMBER_MODIFIERS = new Set([
+    SyntaxKind.AsyncKeyword,
+    SyntaxKind.StaticKeyword,
+    SyntaxKind.GetKeyword,
+    SyntaxKind.SetKeyword,
+    SyntaxKind.ReadonlyKeyword,
+    SyntaxKind.PrivateKeyword,
+    SyntaxKind.PublicKeyword,
+    SyntaxKind.ProtectedKeyword,
+    SyntaxKind.AsteriskToken,
+]);
+/**
+ * Whether `require`, immediately followed by a parameter list and then `{`,
+ * actually sits where a name is declared rather than where a call's result is
+ * followed by an unrelated block statement: `const mod = require('x')` and a
+ * stray `{` on the next line tokenize exactly like a method body, and only
+ * what precedes `require` tells them apart. Skips the modifiers above, then
+ * requires the next token to be the opening brace of the object, class or
+ * interface `require` is the first member of, a `,` or `;` separating it from
+ * a prior member, a `case`/`default` label, `function` for a function
+ * declaration, or the start of the file. Anything else -- `=`, `return`, or
+ * any other token an expression puts before a call -- means this is a call.
+ *
+ * A `;` or `}` immediately before `require` stays undecidable this way: both
+ * a prior class member and a prior unrelated statement end on one, and
+ * telling them apart needs knowing what kind of block `require` sits in,
+ * which a token stream does not carry. Rare enough, and specific enough to
+ * write on purpose, that it is left as the one shape this arm still misses.
+ */
+function isDeclarationPosition(tokens, requireIndex) {
+    let j = requireIndex - 1;
+    while (j >= 0 && MEMBER_MODIFIERS.has(tokens[j]?.kind))
+        j -= 1;
+    if (j < 0)
+        return true;
+    const kind = tokens[j]?.kind;
+    return (kind === SyntaxKind.OpenBraceToken ||
+        kind === SyntaxKind.CommaToken ||
+        kind === SyntaxKind.SemicolonToken ||
+        kind === SyntaxKind.CaseKeyword ||
+        kind === SyntaxKind.DefaultKeyword ||
+        kind === SyntaxKind.FunctionKeyword);
+}
+/**
+ * Whether the parenthesised list opening at `openIndex` is a parameter list,
+ * which is to say `require` here is a method or a signature and never a call.
+ * A `{` straight after the matching `)` defers to `isDeclarationPosition`. A
+ * `:` after it is either a return-type annotation, a ternary's else, or a
+ * `case`/`default` label, and the three are told apart by looking back from
+ * `require` at bracket depth zero: a ternary has its `?` before the call and
+ * inside the same expression, a `case`/`default` label has the keyword
+ * immediately before the call and nothing between them, and a member
+ * declaration has none of those before its own `{`, `,` or `;` -- or before
+ * reaching an enclosing `(`, `[` or `{` with nothing still open inside it,
+ * which is the same boundary one level up. An unclosed list reads as a call,
+ * which is what this arm already did with a stream it could not place.
+ */
+function isMethodDefinition(tokens, requireIndex, openIndex) {
+    let depth = 0;
+    let closeIndex = -1;
+    for (let j = openIndex; j < tokens.length; j++) {
+        const kind = tokens[j]?.kind;
+        if (kind === SyntaxKind.OpenParenToken)
+            depth += 1;
+        else if (kind === SyntaxKind.CloseParenToken) {
+            depth -= 1;
+            if (depth === 0) {
+                closeIndex = j;
+                break;
+            }
+        }
+    }
+    if (closeIndex === -1)
+        return false;
+    const after = tokens[closeIndex + 1]?.kind;
+    if (after === SyntaxKind.OpenBraceToken) {
+        return isDeclarationPosition(tokens, requireIndex);
+    }
+    if (after !== SyntaxKind.ColonToken)
+        return false;
+    depth = 0;
+    for (let j = requireIndex - 1; j >= 0; j--) {
+        const kind = tokens[j]?.kind;
+        if (kind === SyntaxKind.CloseParenToken ||
+            kind === SyntaxKind.CloseBracketToken ||
+            kind === SyntaxKind.CloseBraceToken) {
+            depth += 1;
+            continue;
+        }
+        if (kind === SyntaxKind.OpenParenToken ||
+            kind === SyntaxKind.OpenBracketToken ||
+            kind === SyntaxKind.OpenBraceToken) {
+            if (depth === 0)
+                return true;
+            depth -= 1;
+            continue;
+        }
+        if (depth > 0)
+            continue;
+        if (kind === SyntaxKind.QuestionToken)
+            return false;
+        if (kind === SyntaxKind.CaseKeyword || kind === SyntaxKind.DefaultKeyword) {
+            return false;
+        }
+        if (kind === SyntaxKind.SemicolonToken || kind === SyntaxKind.CommaToken) {
+            return true;
+        }
+    }
+    return true;
+}
 export function scanSources(files, graph) {
     const fileSet = new Set(files.keys());
     const violations = [];

package/dist/gates/gate-config.js

@@ -25,17 +25,26 @@ import { readFile } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
 import { z } from 'zod';
 import { DependencyDirectionSection } from './check-dependency-direction.js';
+import { DocClaimsSection } from './check-doc-claims.js';
+import { DocCountsSection } from './check-doc-counts.js';
 import { FieldOwnershipSection } from './lineage-ownership.js';
 import { PackageBoundarySection } from './package-boundary.js';
+import { RelativePath } from './scanned-paths.js';
 /** The file a consumer writes, resolved against the directory the gate runs in. */
 export const DEFAULT_CONFIG_FILE = 'eval-quality.config.json';
 /**
  * The gates this build publishes, in the order the usage text lists them.
  *
- * Three of the five keep their schema in the gate module rather than here, so
- * that a module reachable only after `typescript` has been probed still declares
- * its own section. Importing those schemas is safe on any load path: each of the
- * three reaches `typescript` through a dynamic import and nothing else.
+ * Five of the eight keep their schema in the gate module rather than here. Three
+ * do so because they are reachable only after `typescript` has been probed and
+ * still have to declare their own section, and two because their schemas are
+ * large enough that carrying them here would make this file the place every gate
+ * is described. Importing any of those schemas is safe on any load path: each
+ * reaches `typescript` through a dynamic import and nothing else.
+ *
+ * The two `.mjs` gates and the invocation gate keep their schemas here, because
+ * a `.mjs` module cannot import `zod` without breaking the pre-install path PR 1
+ * records.
  */
 export const GATE_NAMES = [
     'lockfile-age',
@@ -43,6 +52,9 @@ export const GATE_NAMES = [
     'dependency-direction',
     'package-boundary',
     'field-ownership',
+    'doc-invocations',
+    'doc-counts',
+    'doc-claims',
 ];
 /**
  * The audit window when a configuration names none, in days.
@@ -63,6 +75,31 @@ const NonEmpty = z.string().min(1);
  * a hand maintains in step with the dependency graph.
  */
 const SpdxIdentifier = NonEmpty.regex(/^[A-Za-z0-9][A-Za-z0-9.+-]*$/, 'is not an SPDX short identifier: this setting takes identifiers such as MIT or Apache-2.0, and a package-and-version pin is not one');
+/**
+ * An npm package name, for an age exclusion: an optional `@scope/` and then the
+ * name, in the URL-safe charset npm admits. A second `@` is refused anywhere, so
+ * `left-pad@1.3.0` cannot be written here. Uppercase is admitted because a
+ * lockfile can carry a legacy name that has it, and this setting names what the
+ * lockfile has. The setting mirrors `.npmrc`'s `min-release-age-exclude`, which
+ * takes names for the reason the allowlist takes identifiers: a version here
+ * would be a value a hand maintains in step with the dependency graph.
+ */
+const PackageName = NonEmpty.regex(/^(?:@[A-Za-z0-9._~!*'()-]+\/)?[A-Za-z0-9._~!*'()-]+$/, 'is not a package name: this setting takes names such as left-pad or @scope/name, and a package-and-version pin is not one');
+/**
+ * One exemption from the age window. It names the package, the lockfiles it
+ * holds in, and why, so the run prints the reason beside the entry the way a
+ * policy and a tolerance do. A row that reaches no entry in any lockfile it
+ * names is refused at run time: the package left the lockfile, or the name is
+ * mistyped, and either way the row is a value nobody is holding.
+ */
+const AgeExclusion = z.strictObject({
+    name: PackageName.describe('The package the exemption covers, as the lockfile names the installed package, and every entry under that name in the lockfile, a nested duplicate at another version included. For an npm: alias that is the aliased package, so an entry installed at node_modules/foo from npm:bar@x is excluded by writing bar.'),
+    reason: NonEmpty.describe('Why this package may be adopted inside the window. It is printed on every run that uses it.'),
+    lockfiles: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('The lockfiles this exemption applies to, and no others.'),
+});
 const LockfileAgeSection = z
     .strictObject({
     lockfiles: z
@@ -74,6 +111,41 @@ const LockfileAgeSection = z
         .min(1)
         .default(LOCKFILE_WINDOW_DAYS_DEFAULT)
         .describe('How old an entry has to be, in days, and at least 1. A duration, so nothing here goes stale as time passes. Zero puts the cutoff at the instant of the run, admits a package published that same instant, and still reports that every entry was published before the cutoff.'),
+    cache: RelativePath.optional().describe('A JSON file mapping "name@version" to a publication timestamp. A publication time is fixed the moment it happens, so a reading taken once is correct forever and this cache carries no staleness bound. An entry it holds is used with no request; an entry it does not is fetched, and a fetch that fails still fails the gate. The gate only reads it.'),
+    exclude: z
+        .array(AgeExclusion)
+        .optional()
+        .describe("Packages exempt from the window and from the registry fetch, and never from the resolved-URL check, each row carrying its reason. The counterpart of .npmrc's min-release-age-exclude: names, so no version is pinned here. Every excluded entry is printed on every run, passing or failing."),
+})
+    // A row naming a lockfile the section does not declare would load clean and
+    // apply to nothing, for the reason the licences section refuses the same
+    // under `tolerances` and `undeclared`. Two rows exempting one name in one
+    // lockfile are one exemption written twice with two reasons, so the second
+    // is refused.
+    .superRefine((section, ctx) => {
+    const declared = new Set(section.lockfiles);
+    const seen = new Set();
+    section.exclude?.forEach((row, index) => {
+        row.lockfiles.forEach((named, position) => {
+            if (!declared.has(named)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['exclude', index, 'lockfiles', position],
+                    message: `names "${named}", which is not one of the lockfiles this section declares: ${section.lockfiles.join(', ')}`,
+                });
+                return;
+            }
+            const key = `${row.name}\u0000${named}`;
+            if (seen.has(key)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['exclude', index],
+                    message: `excludes "${row.name}" in ${named}, which an earlier row already excludes; one exemption carries one reason`,
+                });
+            }
+            seen.add(key);
+        });
+    });
 })
     .describe("Fails on a locked entry published inside the window, on metadata that could not be fetched, and on an entry whose resolved URL is not that entry's own tarball on the npm registry.");
 /**
@@ -112,6 +184,27 @@ const LicenceTolerance = z.strictObject({
         .optional()
         .describe('The exception holds only while this file carries this text. An absent or unreadable file withdraws it.'),
 });
+/**
+ * A reading for an entry whose manifest declares no licence. A tolerance widens
+ * the allowlist for a family that declares one, under a condition the gate can
+ * re-read; an undeclared entry declares nothing, so there is no expression to
+ * widen. The row supplies what the manifest would have said and the evidence
+ * for it, and the identifier is then held by the rule every other entry is held
+ * by, so a row cannot admit what the allowlist refuses. "Declares no licence"
+ * is an absent, null or blank `license` field: a field present in a shape the
+ * gate does not read, an array or an object with no `type`, declares something
+ * and fails as it always has.
+ */
+const UndeclaredLicence = z.strictObject({
+    reason: NonEmpty.describe('Why the manifest carries no licence field. It is printed on every run that uses it.'),
+    lockfiles: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('The lockfiles this reading applies to, and no others.'),
+    prefix: NonEmpty.describe('The package-name prefix the reading covers, matched as a plain string prefix with no boundary, so a whole name is the tightest prefix and zod-to-ts also reaches zod-to-ts-plugin the day one appears undeclared. A prefix, so no version is pinned here. It reaches only an entry that declares no licence; an entry under it that declares one is held to its declaration, and a row that reaches no such entry in any lockfile it names is refused at run time.'),
+    readAs: SpdxIdentifier.describe('The one identifier the entry is read as, held against the allowlist like any declared identifier. One identifier only: an expression, a marker or an optional flag has no meaning for an entry that declares nothing.'),
+    evidence: NonEmpty.describe('Where the reading comes from, such as the registry packument or a LICENSE file in the repository. It is printed on every run that uses it.'),
+});
 const LicencesSection = z
     .strictObject({
     lockfiles: z
@@ -130,13 +223,18 @@ const LicencesSection = z
         .array(LicenceTolerance)
         .optional()
         .describe('Scoped exceptions, each carrying its own reason.'),
+    undeclared: z
+        .array(UndeclaredLicence)
+        .optional()
+        .describe('Readings for entries whose manifest declares no licence, each carrying its evidence and its reason.'),
 })
-    // `policies` is keyed by lockfile path and every tolerance names the lockfiles
-    // it applies to, both by the same string `lockfiles` names them by. A value
-    // matching no declared lockfile loads clean and applies to nothing, so a typo
-    // like "pacakge-lock.json" reads as a policy that was written and never runs.
-    // Keeping those three lists in step by hand is the class of setting this format
-    // does not have, so a name matching nothing is refused here.
+    // `policies` is keyed by lockfile path, and every tolerance and every
+    // undeclared row names the lockfiles it applies to, all by the same string
+    // `lockfiles` names them by. A value matching no declared lockfile loads clean
+    // and applies to nothing, so a typo like "pacakge-lock.json" reads as a policy
+    // that was written and never runs. Keeping those lists in step by hand is the
+    // class of setting this format does not have, so a name matching nothing is
+    // refused here.
     .superRefine((section, ctx) => {
     const declared = new Set(section.lockfiles);
     const requireDeclared = (named, path) => {
@@ -156,13 +254,76 @@ const LicencesSection = z
             requireDeclared(named, ['tolerances', index, 'lockfiles', position]);
         });
     });
+    // Two rows reading one prefix in one lockfile would read one package as
+    // two licences, so the second is refused.
+    const seen = new Set();
+    section.undeclared?.forEach((row, index) => {
+        row.lockfiles.forEach((named, position) => {
+            requireDeclared(named, ['undeclared', index, 'lockfiles', position]);
+            const key = `${row.prefix}\u0000${named}`;
+            if (declared.has(named) && seen.has(key)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['undeclared', index],
+                    message: `reads "${row.prefix}" in ${named}, which an earlier row already reads; one package is read as one licence`,
+                });
+            }
+            seen.add(key);
+        });
+    });
 })
     .describe("Holds every locked entry's licence expression against an allowlist of SPDX identifiers, and fails on an entry whose resolved URL is not that entry's own tarball on the npm registry.");
+/**
+ * The invocation gate's section. It sits here rather than in its gate module,
+ * because that gate is `.mjs` and stays free of every import from
+ * `node_modules`, which is what keeps the pre-install path open for the two
+ * gates that run before `npm ci`.
+ */
+const DocumentedBinary = z
+    .strictObject({
+    entry: RelativePath.describe('The built entry point every documented command is run against. It is a precondition: a gate that skipped when it was absent would exit 0 having executed nothing.'),
+    spellings: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('How your documentation writes the command, as the literal text a reader types. Each is matched at the start of a fenced line, with whitespace or end of line after it, so a sample of your own diagnostic output is left alone.'),
+    installedPrefix: NonEmpty.optional().describe('The path prefix a page uses for a file inside the installed package, such as "node_modules/your-package/". Mapping it away is what lets those examples be checked against real bytes.'),
+})
+    .describe('One binary a documented command line runs.');
+const DocInvocationsSection = z
+    .strictObject({
+    pages: z
+        .array(RelativePath)
+        .min(1)
+        .describe("The pages whose fenced commands are run, as files or directories to walk. Naming the configuration's own directory is refused: every fenced command in a whole repository is more than this gate should run."),
+    binary: z
+        .union([DocumentedBinary, z.array(DocumentedBinary).min(1)])
+        .describe("What a documented command line runs. One object for a package that publishes one binary, or an array for a package that publishes several, each carrying its own entry, spellings and installedPrefix. Every spelling across every binary is matched against the same page and the longest one wins, so a short spelling belonging to one binary never claims a line that opens with a longer spelling belonging to another. Each binary's entry is its own precondition and the refusal names which one is missing. An empty array is refused, since a gate with no spelling to match extracts nothing and reports a pass over nothing."),
+    sampleInput: RelativePath.describe('A file that stands in for an input only a reader has, such as `<path>`. A run that needed one is judged for usage errors and crashes and no more.'),
+    usageExit: z
+        .int()
+        .min(1)
+        .max(255)
+        .default(64)
+        .describe('The code your command line returns when a command or a flag does not exist. Every documented invocation exiting with it fails, whatever inputs it named. 64 is sysexits.h EX_USAGE.'),
+    timeoutMs: z
+        .int()
+        .min(1000)
+        .default(30_000)
+        .describe('How long one documented invocation may run.'),
+    elisionLimit: z
+        .int()
+        .min(0)
+        .default(3)
+        .describe('How many "..." elisions one transcribed output line may carry. Matching them is polynomial in the count, so a line carrying many over a long repetitive diagnostic can run for minutes.'),
+})
+    .describe('Runs every fenced command in your documentation against your built binary and compares the exit code with what the page claims. A page that declares its exit may transcribe the diagnostic beside it, and that block is compared line for line.');
 /**
  * The whole document, as one schema. It is where the format states its own
- * incremental-adoption property, and its one consumer is `check-doc-claims.ts`,
+ * incremental-adoption property, and its one consumer is the `doc-claims` gate,
  * which parses the documented example through it so the page a consumer copies
- * is held to the format it describes.
+ * is held to the format it describes. The relation runs through the
+ * configuration rather than through an import: `eval-quality.config.json` names
+ * this export as the schema for that fence, and the gate imports it at run time.
  *
  * The loader never uses it. Validating the document whole would block a gate
  * the caller is running on a gate it is not, which is the opposite of the
@@ -175,6 +336,9 @@ export const GateConfiguration = z
     'dependency-direction': DependencyDirectionSection.optional(),
     'package-boundary': PackageBoundarySection.optional(),
     'field-ownership': FieldOwnershipSection.optional(),
+    'doc-invocations': DocInvocationsSection.optional(),
+    'doc-counts': DocCountsSection.optional(),
+    'doc-claims': DocClaimsSection.optional(),
 })
     .describe("The gates this repository has chosen to run, keyed by gate name. Incremental adoption is structural: the file carries only the gates you have adopted, and configuring a gate is what opts into it. A gate you invoke with no section here refuses by name; it falls back to nobody else's values.");
 const refuse = (message) => ({
@@ -249,3 +413,6 @@ export const loadLicencesConfig = (options = {}) => loadSection('licences', Lice
 export const loadDependencyDirectionConfig = (options = {}) => loadSection('dependency-direction', DependencyDirectionSection, options);
 export const loadPackageBoundaryConfig = (options = {}) => loadSection('package-boundary', PackageBoundarySection, options);
 export const loadFieldOwnershipConfig = (options = {}) => loadSection('field-ownership', FieldOwnershipSection, options);
+export const loadDocInvocationsConfig = (options = {}) => loadSection('doc-invocations', DocInvocationsSection, options);
+export const loadDocCountsConfig = (options = {}) => loadSection('doc-counts', DocCountsSection, options);
+export const loadDocClaimsConfig = (options = {}) => loadSection('doc-claims', DocClaimsSection, options);