eval-quality 3.1.0 → 3.2.0

package/dist/gates/package-boundary.js

@@ -1,22 +1,46 @@
-import { lstat, readdir, readFile } from 'node:fs/promises';
+// A published gate: everything a package ships, held against forbidden patterns
+// the consumer declares.
+//
+// Both halves are the consumer's. The scanned set is a list of paths, each with
+// a recursion flag and an extension filter, plus the manifest fields a registry
+// publishes verbatim. What a consumer leaves out of that list is exempt, and
+// omission is the only exemption the gate has. The rules are an ordered array of
+// named regular expressions carrying a reason apiece.
+//
+// `scanPackageBoundary` is pure and synchronous over a file map, so one function
+// backs both the real scan and a synthetic test map. It matches text line by
+// line rather than tokenizing, because the references this class of rule forbids
+// live in comments and in string literals, which a token scan reports by kind
+// and not by content. Nothing here loads `typescript`.
+//
+// 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 { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { z } from 'zod';
+import { PatternFlags, PatternSource, refinePattern, } from './consumer-pattern.js';
+import { discoverEntries, RelativePath, SCAN_PATH_ERROR, ScannedPathList, } from './scanned-paths.js';
 /**
  * The bound on a consumer-supplied regular expression, and what it does not
  * cover.
  *
  * A pattern arrives as text from a file this package did not write, so the work
  * one pattern can do is the consumer's to choose. JavaScript's `RegExp` exposes
- * no step counter and no timeout, and `check-doc-claims.ts:943` records the same
+ * no step counter and no timeout, and `doc-claim-sources.ts` records the same
  * limit from the other side: `REGEX_STEP_BUDGET` is a number that exists because
- * a step count is the bound you would want and nothing offers one.
+ * a step count is the bound you would want and nothing offers one. A line
+ * citation is deliberately not used here: the doc-claims gate resolves citations
+ * on published pages, so one rotting inside `scripts/` is held by nothing.
  *
  * So the bound is on the two things that are measurable. The pattern side:
  * `MAX_PATTERN_LENGTH` on the source, `MAX_PATTERNS` on the array, a flag set
  * that excludes `g` and `y`, and a refusal of backreferences, which is the
- * construct that turns a linear scan of one line into an exponential one. The
- * input side: `MAX_SCANNED_LINE` on the text a pattern is matched against, so a
- * minified bundle or an embedded data URI cannot hand a pattern a megabyte.
+ * construct that turns a linear scan of one line into an exponential one. Those
+ * four live in `consumer-pattern.ts`, shared with every gate that takes a
+ * pattern. The input side is this scanner's own: `MAX_SCANNED_LINE` bounds the
+ * text a pattern is matched against, so a minified bundle or an embedded data
+ * URI cannot hand a pattern a megabyte.
  *
  * 64 KiB, not the single kilobyte a first draft of this bound used. This
  * package's own `corpus/` is a legitimate long-line source: an unminified
@@ -34,7 +58,6 @@ import { z } from 'zod';
  * more than the surface is worth.
  */
 export const MAX_PATTERNS = 64;
-export const MAX_PATTERN_LENGTH = 200;
 export const MAX_SCANNED_LINE = 65_536;
 /**
  * The name an over-long line is reported under. Reserved, so a consumer pattern
@@ -42,46 +65,9 @@ export const MAX_SCANNED_LINE = 65_536;
  * line the gate declined to match.
  */
 export const OVERLONG_LINE = 'line-exceeds-scan-bound';
-/** A path or manifest field the configuration named and the tree does not have. */
-export const SCAN_PATH_ERROR = 'EVAL_QUALITY_SCAN_PATH';
-/** A tree the gate could not read to the end, so the scan proves nothing. */
-export const SCAN_UNREADABLE = 'EVAL_QUALITY_SCAN_UNREADABLE';
 const codedError = (code, message) => Object.assign(new Error(message), { code });
 const detail = (error) => error instanceof Error ? error.message : String(error);
 const NonEmpty = z.string().min(1);
-const isSafeRelative = (value) => !value.startsWith('/') &&
-    !/^[A-Za-z]:/.test(value) &&
-    !value.includes('\\') &&
-    value.split('/').every((segment) => segment !== '' && segment !== '..');
-const RELATIVE_PATH_MESSAGE = 'is not a repository-relative path: write it with forward slashes, no leading slash, no drive letter, and no ".." segment, so a configuration can only name files beneath itself';
-/** Shared with `lineage-ownership.ts`; see the note on `ScannedPathList`. */
-export const RelativePath = NonEmpty.max(400).refine(isSafeRelative, RELATIVE_PATH_MESSAGE);
-/** The same shape with a trailing slash allowed, for a directory prefix. */
-export const RelativePrefix = NonEmpty.max(400).refine((value) => isSafeRelative(value.endsWith('/') ? value.slice(0, -1) : value), RELATIVE_PATH_MESSAGE);
-const ScannedPath = z.strictObject({
-    path: RelativePath.describe('A directory to walk, or a single file to read, relative to this configuration file.'),
-    recursive: z
-        .boolean()
-        .default(true)
-        .describe('Whether a directory is walked to the bottom. Ignored when the path names a file.'),
-    extensions: z
-        .array(z
-        .string()
-        .regex(/^\.[A-Za-z0-9][A-Za-z0-9.]*$/, 'is not a file extension; write it with its leading dot, as ".ts"'))
-        .min(1)
-        .optional()
-        .describe('Which files under this path are read. Leave it out and every file is read whatever its name, which is what a tree of generated data needs.'),
-    optional: z
-        .boolean()
-        .default(false)
-        .describe('Whether this path may contribute nothing. False, the default, fails when the path is absent or holds no matching file, so a generated tree nobody built cannot read as a clean scan.'),
-});
-/**
- * The scanned-set declaration, shared with the field-ownership gate. It sits
- * here because this is the gate whose headline is the scanned set; a third gate
- * that needs it is the point at which it earns a module of its own.
- */
-export const ScannedPathList = z.array(ScannedPath).min(1);
 const ManifestField = NonEmpty.regex(/^[A-Za-z_$][A-Za-z0-9_$-]*(?:\.[A-Za-z_$][A-Za-z0-9_$-]*)*$/, 'is not a manifest field path; write one key, or several joined by dots');
 const ManifestScan = z
     .strictObject({
@@ -92,25 +78,11 @@ const ManifestScan = z
         .describe('Which fields are scanned. A string is one entry, an array joins into one, and an object becomes one entry per key, so "scripts" covers every script by name. A field named here and absent from the manifest is refused, so a typo cannot read as a field with nothing in it.'),
 })
     .describe('The manifest fields scanned as synthetic entries. A JSON value has no line of its own, so every one of them reports at line 1.');
-/**
- * `\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 boundary pattern anyway.
- */
-const BACKREFERENCE = /\\[1-9]|\\k</;
 const ForbiddenPattern = z
     .strictObject({
     name: NonEmpty.describe('What a violation is reported under. Unique across the array.'),
-    match: z
-        .string()
-        .min(1)
-        .max(MAX_PATTERN_LENGTH)
-        .describe('The regular expression, as source text. It is matched against one logical line at a time.'),
-    flags: z
-        .string()
-        .regex(/^[imsuv]*$/, '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 line it should have matched')
-        .default('')
-        .describe('Regular-expression flags. Empty by default.'),
+    match: PatternSource.describe('The regular expression, as source text. It is matched against one logical line at a time.'),
+    flags: PatternFlags.describe('Regular-expression flags. Empty by default.'),
     reason: NonEmpty.describe('Why the package may not carry it. Printed beside every violation, so the report says what to do rather than only what fired.'),
 })
     .superRefine((pattern, ctx) => {
@@ -121,23 +93,7 @@ const ForbiddenPattern = z
             message: `is reserved: the gate reports a line past its own matching bound under "${OVERLONG_LINE}"`,
         });
     }
-    if (BACKREFERENCE.test(pattern.match)) {
-        ctx.addIssue({
-            code: 'custom',
-            path: ['match'],
-            message: 'carries a backreference, which is the construct that turns a scan of one line into an exponential one; write the pattern without one',
-        });
-    }
-    try {
-        new RegExp(pattern.match, pattern.flags);
-    }
-    catch (error) {
-        ctx.addIssue({
-            code: 'custom',
-            path: ['match'],
-            message: `is not a regular expression: ${detail(error)}`,
-        });
-    }
+    refinePattern(pattern.match, pattern.flags, ctx, ['match']);
 });
 export const PackageBoundarySection = z
     .strictObject({
@@ -251,73 +207,6 @@ export function scanPackageBoundary(files, patterns) {
     }
     return violations;
 }
-const matchesExtension = (declared, name) => declared.extensions === undefined ||
-    declared.extensions.some((extension) => name.endsWith(extension));
-async function walk(root, posix, declared, entries) {
-    let dirents;
-    try {
-        dirents = await readdir(resolve(root, posix), { withFileTypes: true });
-    }
-    catch (error) {
-        throw codedError(SCAN_UNREADABLE, `${posix} could not be read: ${detail(error)}`);
-    }
-    let count = 0;
-    for (const entry of dirents) {
-        const child = `${posix}/${entry.name}`;
-        if (entry.isSymbolicLink()) {
-            throw codedError(SCAN_UNREADABLE, `${child} is a symbolic link; this scan does not follow links, and skipping one would leave a file unscanned while the run reported a clean tree`);
-        }
-        if (entry.isDirectory()) {
-            if (!declared.recursive)
-                continue;
-            count += await walk(root, child, declared, entries);
-        }
-        else if (entry.isFile() && matchesExtension(declared, entry.name)) {
-            entries.set(child, await readFile(resolve(root, child), 'utf8'));
-            count += 1;
-        }
-    }
-    return count;
-}
-/**
- * Everything the declared paths hold, keyed by the path a report prints. Fails
- * closed on the three ways a walk under-reports: a path that is not there, a
- * path that matched no file, and a link whose target could sit anywhere.
- */
-export async function discoverEntries(root, paths, gate) {
-    const entries = new Map();
-    const counts = [];
-    for (const declared of paths) {
-        let info;
-        try {
-            info = await lstat(resolve(root, declared.path));
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT') {
-                throw codedError(SCAN_UNREADABLE, `${declared.path} could not be read: ${detail(error)}`);
-            }
-            if (declared.optional) {
-                counts.push({ path: declared.path, files: 0 });
-                continue;
-            }
-            throw codedError(SCAN_PATH_ERROR, `${declared.path} does not exist, and the "${gate}" section names it under paths; mark it optional if it may be absent`);
-        }
-        if (info.isSymbolicLink()) {
-            throw codedError(SCAN_UNREADABLE, `${declared.path} is a symbolic link, and this scan does not follow links`);
-        }
-        if (info.isFile()) {
-            entries.set(declared.path, await readFile(resolve(root, declared.path), 'utf8'));
-            counts.push({ path: declared.path, files: 1 });
-            continue;
-        }
-        const found = await walk(root, declared.path, declared, entries);
-        if (found === 0 && !declared.optional) {
-            throw codedError(SCAN_PATH_ERROR, `${declared.path} holds no file the "${gate}" section asked for, so a scan of nothing would report zero violations for the wrong reason; mark it optional if it may be empty`);
-        }
-        counts.push({ path: declared.path, files: found });
-    }
-    return { entries, counts };
-}
 function flattenField(key, value, into) {
     if (typeof value === 'string') {
         into.set(key, value);

package/dist/gates/scanned-paths.js

@@ -0,0 +1,110 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+/** A path or manifest field the configuration named and the tree does not have. */
+export const SCAN_PATH_ERROR = 'EVAL_QUALITY_SCAN_PATH';
+/** A tree the gate could not read to the end, so the scan proves nothing. */
+export const SCAN_UNREADABLE = 'EVAL_QUALITY_SCAN_UNREADABLE';
+const codedError = (code, message) => Object.assign(new Error(message), { code });
+const detail = (error) => error instanceof Error ? error.message : String(error);
+const NonEmpty = z.string().min(1);
+const isSafeRelative = (value) => !value.startsWith('/') &&
+    !/^[A-Za-z]:/.test(value) &&
+    !value.includes('\\') &&
+    value.split('/').every((segment) => segment !== '' && segment !== '..');
+const RELATIVE_PATH_MESSAGE = 'is not a repository-relative path: write it with forward slashes, no leading slash, no drive letter, and no ".." segment, so a configuration can only name files beneath itself';
+/** Shared with `lineage-ownership.ts`; see the note on `ScannedPathList`. */
+export const RelativePath = NonEmpty.max(400).refine(isSafeRelative, RELATIVE_PATH_MESSAGE);
+/** The same shape with a trailing slash allowed, for a directory prefix. */
+export const RelativePrefix = NonEmpty.max(400).refine((value) => isSafeRelative(value.endsWith('/') ? value.slice(0, -1) : value), RELATIVE_PATH_MESSAGE);
+const ScannedPath = z.strictObject({
+    path: RelativePath.describe('A directory to walk, or a single file to read, relative to this configuration file.'),
+    recursive: z
+        .boolean()
+        .default(true)
+        .describe('Whether a directory is walked to the bottom. Ignored when the path names a file.'),
+    extensions: z
+        .array(z
+        .string()
+        .regex(/^\.[A-Za-z0-9][A-Za-z0-9.]*$/, 'is not a file extension; write it with its leading dot, as ".ts"'))
+        .min(1)
+        .optional()
+        .describe('Which files under this path are read. Leave it out and every file is read whatever its name, which is what a tree of generated data needs.'),
+    optional: z
+        .boolean()
+        .default(false)
+        .describe('Whether this path may contribute nothing. False, the default, fails when the path is absent or holds no matching file, so a generated tree nobody built cannot read as a clean scan.'),
+});
+/**
+ * The scanned-set declaration. It lived in `package-boundary.ts` while that gate
+ * was its only owner, on a note saying a third gate needing it was the point at
+ * which it earned a module of its own. The two documentation gates made three.
+ */
+export const ScannedPathList = z.array(ScannedPath).min(1);
+const matchesExtension = (declared, name) => declared.extensions === undefined ||
+    declared.extensions.some((extension) => name.endsWith(extension));
+async function walk(root, posix, declared, entries) {
+    let dirents;
+    try {
+        dirents = await readdir(resolve(root, posix), { withFileTypes: true });
+    }
+    catch (error) {
+        throw codedError(SCAN_UNREADABLE, `${posix} could not be read: ${detail(error)}`);
+    }
+    let count = 0;
+    for (const entry of dirents) {
+        const child = `${posix}/${entry.name}`;
+        if (entry.isSymbolicLink()) {
+            throw codedError(SCAN_UNREADABLE, `${child} is a symbolic link; this scan does not follow links, and skipping one would leave a file unscanned while the run reported a clean tree`);
+        }
+        if (entry.isDirectory()) {
+            if (!declared.recursive)
+                continue;
+            count += await walk(root, child, declared, entries);
+        }
+        else if (entry.isFile() && matchesExtension(declared, entry.name)) {
+            entries.set(child, await readFile(resolve(root, child), 'utf8'));
+            count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * Everything the declared paths hold, keyed by the path a report prints. Fails
+ * closed on the three ways a walk under-reports: a path that is not there, a
+ * path that matched no file, and a link whose target could sit anywhere.
+ */
+export async function discoverEntries(root, paths, gate) {
+    const entries = new Map();
+    const counts = [];
+    for (const declared of paths) {
+        let info;
+        try {
+            info = await lstat(resolve(root, declared.path));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw codedError(SCAN_UNREADABLE, `${declared.path} could not be read: ${detail(error)}`);
+            }
+            if (declared.optional) {
+                counts.push({ path: declared.path, files: 0 });
+                continue;
+            }
+            throw codedError(SCAN_PATH_ERROR, `${declared.path} does not exist, and the "${gate}" section names it under paths; mark it optional if it may be absent`);
+        }
+        if (info.isSymbolicLink()) {
+            throw codedError(SCAN_UNREADABLE, `${declared.path} is a symbolic link, and this scan does not follow links`);
+        }
+        if (info.isFile()) {
+            entries.set(declared.path, await readFile(resolve(root, declared.path), 'utf8'));
+            counts.push({ path: declared.path, files: 1 });
+            continue;
+        }
+        const found = await walk(root, declared.path, declared, entries);
+        if (found === 0 && !declared.optional) {
+            throw codedError(SCAN_PATH_ERROR, `${declared.path} holds no file the "${gate}" section asked for, so a scan of nothing would report zero violations for the wrong reason; mark it optional if it may be empty`);
+        }
+        counts.push({ path: declared.path, files: found });
+    }
+    return { entries, counts };
+}

package/dist/index.d.ts

@@ -22,4 +22,4 @@ export { SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION } from './core/schemas/sealed-eva
 export type { SealedRunRecord } from './core/schemas/sealed-run-record.ts';
 export { SEALED_RUN_RECORD_SCHEMA_VERSION } from './core/schemas/sealed-run-record.ts';
 export type { FixtureReset, ManifestationWitness, SensitivityWitness, SensitivityWitnessLeg, WitnessChannel, WitnessInputs, } from './core/schemas/sensitivity-witness.ts';
-export declare const VERSION = "3.1.0";
+export declare const VERSION = "3.2.0";

package/dist/index.js

@@ -38,4 +38,4 @@ export { PROBE_SCHEMA_VERSION } from './core/schemas/probe.js';
 export { SCORING_POLICY_SCHEMA_VERSION } from './core/schemas/scoring-policy.js';
 export { SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION } from './core/schemas/sealed-evaluator-brief.js';
 export { SEALED_RUN_RECORD_SCHEMA_VERSION } from './core/schemas/sealed-run-record.js';
-export const VERSION = '3.1.0';
+export const VERSION = '3.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eval-quality",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Compile disciplined Behavioral Evaluation Contracts and score their ability to catch known defects.",
   "author": "Murat Ozcan",
   "license": "Apache-2.0",
@@ -73,9 +73,9 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "check:docs": "node scripts/check-docs.mjs",
-    "check:doc-invocations": "node scripts/check-doc-invocations.mjs",
-    "check:doc-counts": "node scripts/check-doc-counts.ts",
-    "check:doc-claims": "node scripts/check-doc-claims.ts",
+    "check:doc-invocations": "node scripts/gates-cli.ts doc-invocations",
+    "check:doc-counts": "node scripts/gates-cli.ts doc-counts",
+    "check:doc-claims": "node scripts/gates-cli.ts doc-claims",
     "lint:spine": "python3 scripts/spine-lint/lint_spine.py --registry-ad 5 --workspace-root . --fail-on high",
     "test:spine-lint": "uv run --with pytest pytest scripts/spine-lint/tests -q",
     "build:shareable": "node scripts/build-shareable.mjs",
@@ -103,6 +103,7 @@
     "check:worked-example": "node scripts/check-worked-example.ts",
     "generate:version": "node scripts/generate-version.ts",
     "check:version": "node scripts/check-version.ts",
+    "generate:lockfile-age-cache": "node scripts/generate-lockfile-age-cache.ts",
     "check:lockfile-age": "node dist/gates/gates-cli.js lockfile-age",
     "check:licences": "node scripts/gates-cli.ts licences",
     "check:shareable": "node scripts/check-shareable.mjs",