eval-quality 3.0.0 → 3.2.0

package/dist/gates/check-licenses.mjs

@@ -0,0 +1,378 @@
+// Holds every entry in a resolved lockfile against an allowlist of SPDX
+// identifiers, and fails closed on an entry whose `resolved` is not the registry
+// tarball for that entry's own name and version.
+//
+// Reads `package-lock.json` directly rather than walking `node_modules`: the
+// lockfile records a `license` field for every entry, including optional
+// platform binaries never installed on this runner's OS/CPU (Biome and friends
+// ship one lock entry per platform). Walking node_modules would silently miss
+// every foreign-platform entry. Needs no install.
+//
+// A pure scanner over a parsed lockfile and the data its caller supplies. It
+// carries no allowlist, no policy and no exception of its own, so this
+// repository's licence policy is data in `eval-quality.config.json` exactly as a
+// consumer's is. `scripts/gates-cli.ts` is the entry point that reads that file,
+// resolves the policy for each lockfile, and decides which exceptions still
+// hold.
+const REGISTRY_PREFIX = 'https://registry.npmjs.org/';
+/**
+ * `error.code` on the refusal a caller repairs by pointing the gate at a real
+ * lockfile. `audit-lockfile-age.mjs` exports the same string and
+ * `tests/architecture/published-gates.test.ts` holds the two equal: neither gate
+ * may import from `node_modules` and there is no module between them, so the
+ * constant is declared twice for the reason `WINDOW_DAYS_DEFAULT` is.
+ */
+export const LOCKFILE_SHAPE_ERROR = 'EVAL_QUALITY_LOCKFILE_SHAPE';
+function refuseLockfileShape(message) {
+    const error = new Error(message);
+    error.code = LOCKFILE_SHAPE_ERROR;
+    return error;
+}
+// The one URL the public registry serves `name@version` from. A scoped name's
+// tarball basename is the segment after the slash, so `@scope/pkg` at 1.0.0 is
+// `https://registry.npmjs.org/@scope/pkg/-/pkg-1.0.0.tgz`.
+function registryTarballUrl(name, version) {
+    const basename = name.startsWith('@')
+        ? name.slice(name.indexOf('/') + 1)
+        : name;
+    return `${REGISTRY_PREFIX}${name}/-/${basename}-${version}.tgz`;
+}
+// Strips a single layer of balanced outer parentheses at a time, e.g. "(MIT OR Apache-2.0)" ->
+// "MIT OR Apache-2.0". Only strips when the opening paren's match is the expression's final
+// character (a true outer wrap), not when parens merely appear inside, e.g. "(MIT) OR (ISC)".
+function stripOuterParens(expr) {
+    let s = expr.trim();
+    while (s.startsWith('(') && s.endsWith(')')) {
+        let depth = 0;
+        let wrapsWhole = true;
+        for (let i = 0; i < s.length; i++) {
+            if (s[i] === '(')
+                depth++;
+            else if (s[i] === ')') {
+                depth--;
+                if (depth === 0 && i !== s.length - 1) {
+                    wrapsWhole = false;
+                    break;
+                }
+            }
+        }
+        if (!wrapsWhole)
+            break;
+        s = s.slice(1, -1).trim();
+    }
+    return s;
+}
+// Splits `expr` on top-level occurrences of `token` (e.g. " OR ", " AND "), ignoring occurrences
+// nested inside parentheses.
+function splitTopLevel(expr, token) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < expr.length; i++) {
+        const ch = expr[i];
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        else if (depth === 0 && expr.slice(i, i + token.length) === token) {
+            parts.push(expr.slice(start, i));
+            i += token.length - 1;
+            start = i + 1;
+        }
+    }
+    parts.push(expr.slice(start));
+    return parts;
+}
+// Recursively evaluates an SPDX-ish licence expression: OR passes if any operand is allowlisted,
+// AND passes only if every operand is. A bare identifier (including a "X WITH exception" compound,
+// UNLICENSED, or anything unparseable) passes only via exact allowlist membership, so those all fail
+// closed without special-casing.
+function isAllowed(licenseExpr, allowlist) {
+    if (!licenseExpr || typeof licenseExpr !== 'string')
+        return false;
+    const stripped = stripOuterParens(licenseExpr.trim());
+    if (stripped === '')
+        return false;
+    const orParts = splitTopLevel(stripped, ' OR ');
+    if (orParts.length > 1)
+        return orParts.some((part) => isAllowed(part, allowlist));
+    const andParts = splitTopLevel(stripped, ' AND ');
+    if (andParts.length > 1)
+        return andParts.every((part) => isAllowed(part, allowlist));
+    return allowlist.has(stripped);
+}
+function licenseStringOf(meta) {
+    const license = meta.license;
+    if (typeof license === 'string')
+        return license;
+    if (license &&
+        typeof license === 'object' &&
+        typeof license.type === 'string')
+        return license.type;
+    return null;
+}
+// One scoped exception, applied to one entry. `prefix` names a family of
+// packages and `license` is the single identifier the exception adds to the
+// allowlist for that family; the expression is then read by the rule every other
+// entry is read by. So an AND still needs every operand covered and a WITH
+// compound still has to sit in the list exactly: `Apache-2.0 AND
+// LGPL-3.0-or-later` is tolerated where the exception names the LGPL term and
+// the allowlist carries Apache-2.0, and `LGPL-3.0-or-later AND AGPL-3.0-only` is
+// not. A substring test here kept tolerating a family the day its expression
+// widened to carry a term nobody agreed to. The caller has already decided this
+// exception applies to this lockfile and that its marker still holds.
+function isTolerated(tolerance, meta, name, license, allowlist) {
+    if (!name.startsWith(tolerance.prefix))
+        return false;
+    if (tolerance.optional !== false && meta.optional !== true)
+        return false;
+    return isAllowed(license, new Set([...allowlist, tolerance.license]));
+}
+// Resolves how npm's hoisting algorithm would look up dependency `name` starting from the package
+// at `fromPath`: its own node_modules first, then each ancestor's, ending at the root.
+//
+// Must split on "/node_modules/" boundaries, not bare "/": a scoped package's path
+// (node_modules/@scope/name) has three segments per nesting level, not two, so striding by two
+// undershoots every scoped ancestor and never reaches the root scope "". That silently drops the
+// dependency edge for anything nested under a scoped package - including every @biomejs/cli-*
+// platform binary - and findDependencyPath falls back to the raw lockfile key instead of the real
+// require-chain.
+function ancestorScopesOf(pkgPath) {
+    if (pkgPath === '')
+        return [''];
+    const scopes = [];
+    let scope = pkgPath;
+    for (;;) {
+        scopes.push(scope);
+        const boundary = scope.lastIndexOf('/node_modules/');
+        if (boundary === -1)
+            break;
+        scope = scope.slice(0, boundary);
+    }
+    scopes.push('');
+    return scopes;
+}
+function resolveDependency(packages, fromPath, name) {
+    for (const scope of ancestorScopesOf(fromPath)) {
+        const candidate = scope
+            ? `${scope}/node_modules/${name}`
+            : `node_modules/${name}`;
+        if (packages[candidate])
+            return candidate;
+    }
+    return null;
+}
+function buildEdges(packages) {
+    const edges = new Map();
+    for (const [path, meta] of Object.entries(packages)) {
+        const wantedNames = new Set([
+            ...Object.keys(meta.dependencies ?? {}),
+            ...Object.keys(meta.optionalDependencies ?? {}),
+            ...Object.keys(meta.peerDependencies ?? {}),
+            ...(path === '' ? Object.keys(meta.devDependencies ?? {}) : []),
+        ]);
+        const list = [];
+        for (const name of wantedNames) {
+            const resolved = resolveDependency(packages, path, name);
+            if (resolved)
+                list.push({ name, childPath: resolved });
+        }
+        edges.set(path, list);
+    }
+    return edges;
+}
+// Breadth-first search from the root over the lockfile's dependency edges (walking edges, not
+// `npm ls`, since this script needs no install) to find one shortest chain of require-names that
+// reaches `targetPath`.
+function findDependencyPath(packages, edges, targetPath) {
+    const rootName = packages['']?.name ?? '(root)';
+    if (targetPath === '')
+        return rootName;
+    const visited = new Set(['']);
+    const queue = [''];
+    const parent = new Map(); // childPath -> { parentPath, name }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const { name, childPath } of edges.get(current) ?? []) {
+            if (visited.has(childPath))
+                continue;
+            visited.add(childPath);
+            parent.set(childPath, { parentPath: current, name });
+            if (childPath === targetPath) {
+                const chain = [];
+                let cursor = targetPath;
+                while (cursor !== '') {
+                    const step = parent.get(cursor);
+                    chain.unshift(step.name);
+                    cursor = step.parentPath;
+                }
+                return [rootName, ...chain].join(' > ');
+            }
+            queue.push(childPath);
+        }
+    }
+    return targetPath; // unreachable via declared edges; fall back to the raw lockfile key
+}
+/**
+ * `options.allowlist` is required and has no default. An absent allowlist either
+ * 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.
+ */
+export function checkLicenses(lockfile, options = {}) {
+    const allowed = options.allowlist;
+    if (!Array.isArray(allowed) || allowed.length === 0) {
+        throw new Error('check-licenses: no allowlist was supplied; the licences gate carries none of its own');
+    }
+    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
+    // something that is not a lockfile at all, into a run that reported success
+    // over zero entries: a gate that scanned nothing, in the words of a gate that
+    // passed.
+    const packages = lockfile?.packages;
+    if (packages === null ||
+        typeof packages !== 'object' ||
+        Array.isArray(packages)) {
+        throw refuseLockfileShape(`check-licenses: ${source} carries no "packages" object (lockfileVersion ${JSON.stringify(lockfile?.lockfileVersion ?? null)}); every entry is read from there, so this run would have passed over nothing. npm writes "packages" from lockfileVersion 2 onward.`);
+    }
+    // A `link: true` entry is a workspace symlink, not an installed artifact with its own licence -
+    // audit-lockfile-age.mjs already excludes these; this script should agree instead of flagging a
+    // symlink for a `license` field it was never going to have.
+    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();
+        const version = meta.version ?? '(unknown)';
+        // `resolved` is the URL `npm ci` fetches, and `integrity` is checked against
+        // whatever that URL returns, so an entry can declare one package and install
+        // another. Pinning the host alone left that open: an entry naming
+        // `lodash@4.17.21` and resolving to `attacker-pkg-9.9.9.tgz` on
+        // registry.npmjs.org passed, and the licence being read was never the licence
+        // 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({
+                path: pkgPath,
+                name,
+                version,
+                license: meta.license ?? null,
+                reason: `resolved=${JSON.stringify(meta.resolved ?? null)} is not ${name}@${version}'s registry tarball ${expected}`,
+            });
+            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));
+        if (tolerance !== undefined) {
+            tolerated.push(`${name}@${version}`);
+            reasons.add(tolerance.reason);
+            continue;
+        }
+        // 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();
+    readByEvidence.sort((a, b) => a.entry < b.entry ? -1 : a.entry > b.entry ? 1 : 0);
+    const report = {
+        violations,
+        entryCount: entries.length,
+        tolerated,
+        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`);