eval-quality 3.1.0 → 3.3.0

package/README.md

@@ -134,7 +134,7 @@ Node.js 22.20.0 or newer. `zod` is the only production dependency.
 npm install eval-quality
 ```
 
-Every command runs through `npx`:
+Every command runs through `npx`. The four below are the grammar rather than a sequence to copy: they name files your own harness produces. [The full walkthrough](https://bmad-code-org.github.io/bmad-eval-quality/how-to/author-behavioral-contracts/) runs the same four end to end over files this repository commits, with no placeholder in the path.
 
 ```bash
 npx eval-quality compile --in contract.json --out ./eval-out

package/dist/application/index.d.ts

@@ -6,6 +6,11 @@
  * unamended.
  */
 export { digestArtifact, digestBytes, digestComposite, } from '../core/canonical/digest.ts';
+export { makePointerDenotesCollection, makeResolveOperand, referenceSetKeysOf, } from '../core/evaluate/evidence-resolution.ts';
+export type { PointerDenotesCollection, ReferenceSetKeys, ResolveOperand, } from '../core/evaluate/resolution.ts';
+export { resolveCheck } from '../core/evaluate/resolution.ts';
+export type { ResolvedValue } from '../core/evaluate/resolved-value.ts';
+export { ABSENT } from '../core/evaluate/resolved-value.ts';
 export type { FailureCode } from '../core/failure-codes.ts';
 export { FAILURE_CODES, StructuralFailure } from '../core/failure-codes.ts';
 export type { LineageChainReport, LineageFinding, } from '../core/lineage/chain.ts';
@@ -21,6 +26,7 @@ export type { QualificationFailure, QualificationFailureCode, QualificationResul
 export { QUALIFICATION_FAILURES } from '../core/score/qualification.ts';
 export type { ComparableResult, DominanceRelationValue, } from '../core/score/strength.ts';
 export { compareDominance, DOMINANCE_RELATIONS, } from '../core/score/strength.ts';
+export type { PlanIndex } from '../core/seal/plan-index.ts';
 export { compile } from './compile.ts';
 export type { Diagnostic, DiagnosticSink } from './diagnostics.ts';
 export type { PreflightFromObservationsOptions, RunPreflightOptions, } from './preflight.ts';

package/dist/application/index.js

@@ -6,6 +6,14 @@
  * unamended.
  */
 export { digestArtifact, digestBytes, digestComposite, } from '../core/canonical/digest.js';
+// The evaluator, for a consumer that resolves a check itself: the resolver,
+// the two factories that build its operand and collection predicates from a
+// contract and its observations, and the reference-set keys. `ABSENT` ships
+// beside them because a `ResolveOperand` a consumer writes has to return it,
+// and a sentinel the type names and the barrel withholds cannot be returned.
+export { makePointerDenotesCollection, makeResolveOperand, referenceSetKeysOf, } from '../core/evaluate/evidence-resolution.js';
+export { resolveCheck } from '../core/evaluate/resolution.js';
+export { ABSENT } from '../core/evaluate/resolved-value.js';
 export { FAILURE_CODES, StructuralFailure } from '../core/failure-codes.js';
 export { validateLineageChain } from '../core/lineage/chain.js';
 export { INTERCHANGE_ARTIFACT_KEYS } from '../core/schemas/artifact.js';

package/dist/gates/audit-lockfile-age.mjs

@@ -12,7 +12,8 @@
 // These flags are the pre-install path: `.github/actions/audit-lockfile-age`
 // runs this before `npm ci`, so nothing here may import from `node_modules`. A
 // consumer runs the same audit through `eval-quality-gates lockfile-age`, which
-// reads its lockfiles and its window out of a configuration file.
+// reads its lockfiles, its window and its exclusions out of a configuration
+// file.
 //
 // Usage:
 //   node scripts/audit-lockfile-age.mjs [--lockfile <path>] [--window-days <n>] [--now <RFC3339>]
@@ -59,6 +60,7 @@ function parseArgs(argv) {
         lockfile: 'package-lock.json',
         windowDays: WINDOW_DAYS_DEFAULT,
         now: null,
+        cache: null,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -68,6 +70,8 @@ function parseArgs(argv) {
             args.windowDays = Number(argv[++i]);
         else if (arg === '--now')
             args.now = argv[++i];
+        else if (arg === '--cache')
+            args.cache = argv[++i];
         else
             throw new Error(`Unknown argument: ${arg}`);
     }
@@ -117,8 +121,9 @@ async function fetchWithRetry(url, attempts = MAX_RETRIES) {
 }
 // One registry request per unique package NAME (not per lockfile entry): the response carries a
 // `time` map covering every published version, so every locked version of that package is checked
-// from a single fetch.
-async function fetchTimeMap(name) {
+// from a single fetch. Exported so the cache generator reads the registry the same way the gate
+// does, rather than carrying a second copy of the retry and URL rules.
+export async function fetchTimeMap(name) {
     const meta = await fetchWithRetry(registryUrlForName(name));
     return meta.time ?? {};
 }
@@ -164,13 +169,34 @@ function collectLockedEntries(lockfile, source) {
  * caller that wants the registry gets it by saying nothing, and a case that
  * wants a fixed answer runs offline.
  *
+ * `cache` is a map from "name@version" to a publication timestamp, and it is
+ * what keeps a gate that runs on every build off the network. Both of this
+ * audit's inputs make it sound with no staleness bound: a package's publication
+ * time is fixed the moment it is published, so a reading taken once is correct
+ * forever, and the predicate is monotone in time, so an entry that passes today
+ * passes every day after. The entries needing a live fetch are the ones the
+ * cache does not carry, which are exactly the dependencies a change added, and
+ * fail-closed holds unchanged for them.
+ *
+ * `exclude` is the package names exempt from the window and from the fetch,
+ * the counterpart of `.npmrc`'s `min-release-age-exclude`. Every entry under
+ * one of those names comes back in `excludedEntries` and still counts among
+ * `entries`; one that also fails the resolved-URL check comes back in both
+ * lists, because the exclusion never reached that check.
+ *
  * `source` is the path this lockfile was read from, named in the refusal a
  * document without a `packages` object earns.
  */
-export async function auditLockfileAge({ lockfile, now, windowDays, source = 'the lockfile', readTimeMap = fetchTimeMap, }) {
+export async function auditLockfileAge({ lockfile, now, windowDays, 
+// The cast is for the TypeScript caller: a bare `[]` default reads as never[].
+exclude = /** @type {readonly string[]} */ ([]), source = 'the lockfile', readTimeMap = fetchTimeMap, cache = {}, }) {
     if (!Number.isFinite(windowDays) || windowDays < 1) {
         throw new Error(`windowDays must be at least 1, got: ${windowDays}; a window of zero admits a package published this instant and still reports that every entry was published before the cutoff`);
     }
+    // `new Set('left-pad')` is a set of eight characters that excludes nothing.
+    if (!Array.isArray(exclude) || exclude.some((n) => typeof n !== 'string')) {
+        throw new Error(`exclude must be an array of package names, got: ${JSON.stringify(exclude)}`);
+    }
     const cutoff = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
     const entries = collectLockedEntries(lockfile, source);
     // An entry whose `resolved` is not the registry tarball for its own name and version did not come
@@ -189,7 +215,24 @@ export async function auditLockfileAge({ lockfile, now, windowDays, source = 'th
             offRegistryEntries.push(entry);
         }
     }
-    const uniqueNames = [...new Set(registryEntries.map((e) => e.name))];
+    const cachedAt = (entry) => cache[`${entry.name}@${entry.version}`];
+    // An exclusion exempts a name from the window and from the fetch, and from
+    // nothing else. `min-release-age-exclude` says a package's young releases are
+    // accepted and says nothing about which tarball the install fetches, so an
+    // excluded entry is still held by the resolved-URL check above: a substituted
+    // `resolved` under an excluded name is the defect that check exists for. The
+    // exclusion is read over every entry, so a run prints it beside that failure.
+    const excludedNames = new Set(exclude);
+    const excludedEntries = entries.filter((entry) => excludedNames.has(entry.name));
+    const auditedEntries = registryEntries.filter((entry) => !excludedNames.has(entry.name));
+    // One request per unique package name, and only for a name carrying at least
+    // one version the cache does not answer. A name whose every locked version is
+    // cached, or excluded, is never asked for.
+    const uniqueNames = [
+        ...new Set(auditedEntries
+            .filter((entry) => cachedAt(entry) === undefined)
+            .map((entry) => entry.name)),
+    ];
     const timeMaps = new Map();
     const fetchFailures = new Set();
     await mapWithConcurrency(uniqueNames, CONCURRENCY, async (name) => {
@@ -202,12 +245,13 @@ export async function auditLockfileAge({ lockfile, now, windowDays, source = 'th
     });
     const youngEntries = [];
     const unfetchableEntries = [];
-    for (const entry of registryEntries) {
-        if (fetchFailures.has(entry.name)) {
+    for (const entry of auditedEntries) {
+        const fromCache = cachedAt(entry);
+        if (fromCache === undefined && fetchFailures.has(entry.name)) {
             unfetchableEntries.push(entry);
             continue;
         }
-        const publishedAt = timeMaps.get(entry.name)?.[entry.version];
+        const publishedAt = fromCache ?? timeMaps.get(entry.name)?.[entry.version];
         if (!publishedAt) {
             unfetchableEntries.push(entry);
             continue;
@@ -230,8 +274,56 @@ export async function auditLockfileAge({ lockfile, now, windowDays, source = 'th
         youngEntries,
         unfetchableEntries,
         offRegistryEntries,
+        excludedEntries,
     };
 }
+/**
+ * The cache document, checked before a single timestamp is trusted. A malformed
+ * one is a refusal: a cache whose values are not timestamps would answer every
+ * lookup with something the audit reads as unparseable, and every entry would
+ * land in `unfetchableEntries` with no explanation of why.
+ */
+// `new Date(value)` alone accepts strings no publication record is ever written
+// in, "12" parses as the year 2001, so the shape is checked first: an RFC3339
+// date-time, which is what the npm registry's own `time` map writes and what
+// `fetchTimeMap` reads back into the cache.
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+export function readPublishCache(document, source) {
+    if (document === null ||
+        typeof document !== 'object' ||
+        Array.isArray(document)) {
+        throw refuseLockfileShape(`${source} is not a JSON object; a publication cache maps "name@version" to a timestamp`);
+    }
+    for (const [key, value] of Object.entries(document)) {
+        if (typeof value !== 'string' ||
+            !RFC3339.test(value) ||
+            Number.isNaN(new Date(value).getTime())) {
+            throw refuseLockfileShape(`${source} holds ${JSON.stringify(value)} for "${key}", which is not an RFC3339 timestamp`);
+        }
+        if (!key.includes('@', 1)) {
+            throw refuseLockfileShape(`${source} holds the key "${key}", which is not a "name@version"`);
+        }
+    }
+    return document;
+}
+/** The cache file, with the two ways reading it fails named rather than thrown raw. */
+async function readCacheFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw refuseLockfileShape(`${path} could not be read: ${error.message}; --cache names it`);
+    }
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch (error) {
+        throw refuseLockfileShape(`${path} is not valid JSON: ${error.message}`);
+    }
+    return readPublishCache(document, path);
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     const now = args.now ? new Date(args.now) : new Date();
@@ -240,11 +332,16 @@ async function main() {
     }
     console.log(`Effective clock: ${now.toISOString()}`);
     const lockfile = JSON.parse(await readFile(args.lockfile, 'utf8'));
+    // A cache the caller named and the tree does not have is a refusal rather
+    // than a silent full-fetch run: a mistyped path would read as a cache that
+    // happens to answer nothing, which is the shape a gate must never pass over.
+    const cache = args.cache === null ? {} : await readCacheFile(args.cache);
     const { cutoff, entries, youngEntries, unfetchableEntries, offRegistryEntries, } = await auditLockfileAge({
         lockfile,
         now,
         windowDays: args.windowDays,
         source: args.lockfile,
+        cache,
     });
     if (youngEntries.length === 0 &&
         unfetchableEntries.length === 0 &&

package/dist/gates/check-dependency-direction.js

@@ -18,6 +18,7 @@
 // appear in this file or anything it imports, or the gate fails at load.
 import { z } from 'zod';
 import { discoverSourceFiles } from './discover-source-files.js';
+import { isCode, loadTypeScriptScanner, TYPESCRIPT_UNAVAILABLE, } from './typescript-scanner.js';
 /** The gate's key in the configuration file, and the token the binary dispatches on. */
 export const DEPENDENCY_DIRECTION_GATE = 'dependency-direction';
 /**
@@ -26,7 +27,7 @@ export const DEPENDENCY_DIRECTION_GATE = 'dependency-direction';
  * description and asserted by `tests/architecture/dependency-direction.test.ts`,
  * so the ordering property below is a measured fact rather than a warning.
  */
-export const ORDERING_WITNESS_VIOLATIONS = 78;
+export const ORDERING_WITNESS_VIOLATIONS = 80;
 /** The optional peer is absent. The consumer repairs it by installing it, so it takes the usage code. */
 export const TYPESCRIPT_PEER_MISSING = 'EVAL_QUALITY_TYPESCRIPT_PEER_MISSING';
 /** A declared scan root could not be walked. Also a usage code: nothing was scanned, so nothing was answered. */
@@ -228,25 +229,24 @@ const refuse = (code, message) => ({
 /**
  * The scanner needs `typescript/unstable/ast`, and `typescript` is an optional
  * peer dependency so that a consumer running the other gates installs nothing.
- * Probing it by name is what turns a resolver stack trace into a sentence naming
- * the dependency and the gate that wanted it.
+ * `typescript-scanner.ts` is what turns a resolver stack trace into a sentence
+ * naming the dependency, the installed version and the gate that wanted it; a
+ * failure of any other shape is a bug in the scanner, not a missing peer, and
+ * is rethrown unchanged.
  *
  * `load` is injectable so a test can exercise the refusal without uninstalling
  * the package the test runner itself needs.
  */
-export async function probeTypeScript(load = () => import('typescript/unstable/ast')) {
+export async function probeTypeScript(load = () => loadTypeScriptScanner(DEPENDENCY_DIRECTION_GATE)) {
     try {
         await load();
         return { ok: true };
     }
     catch (error) {
-        if (error.code !== 'ERR_MODULE_NOT_FOUND') {
-            throw error;
+        if (isCode(error, TYPESCRIPT_UNAVAILABLE)) {
+            return { ok: false, message: error.message };
         }
-        return {
-            ok: false,
-            message: `the ${DEPENDENCY_DIRECTION_GATE} gate reads your source with the TypeScript scanner, and the optional peer dependency "typescript" is not installed here. Install it (npm install --save-dev typescript), or drop the "${DEPENDENCY_DIRECTION_GATE}" section from your configuration to stop invoking this gate. No other gate needs it.`,
-        };
+        throw error;
     }
 }
 const orderViolations = (violations) => [...violations].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);