eval-quality 3.0.0 → 3.2.0

package/dist/gates/lineage-ownership.js

@@ -0,0 +1,364 @@
+// A published gate: field ownership.
+//
+// The rule is "only these modules may write these fields, and each of them has
+// to write every one it is named for". A consumer declares four things: the
+// fields it owns, the path prefixes where declaring them is always allowed,
+// the modules permitted to write them, and the helper identifiers that count as
+// a write because they set the fields on a caller's behalf. Nothing in the gate
+// knows what the fields mean.
+//
+// That is what makes it worth publishing. The rule shipped here holds two
+// lineage fields against the stages allowed to mint them, and the same rule
+// holds an `id` nothing but a factory may assign, an `updatedAt` one repository
+// layer owns, a `tenantId` written only where a request is authorized, or any
+// other field whose value is a claim rather than a convenience. A consumer with
+// no lineage concept at all is the ordinary case.
+//
+// Both directions are checked, because both go wrong. A write outside the
+// declared set is the obvious one. A declared writer that writes none of its
+// fields is the likelier regression: a rename empties the list and every
+// remaining check keeps passing over a rule nothing enforces.
+//
+// Token-anchored, so the gate reads TypeScript source through the typescript
+// package's own scanner. `typescript` is loaded on first use rather than at
+// import, so this module carries no `typescript` on its load path and the gate
+// refuses by name when the dependency is absent instead of failing to load.
+//
+// Every rule is fail-closed: an ambiguous shape is reported, since an owned
+// field outside its declared home is worth a human look either way.
+//
+// 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';
+import { discoverEntries, RelativePath, RelativePrefix, ScannedPathList, } from './scanned-paths.js';
+/** The gate needs `typescript` and could not resolve it. */
+export const TYPESCRIPT_UNAVAILABLE = 'EVAL_QUALITY_TYPESCRIPT_UNAVAILABLE';
+const codedError = (code, message) => Object.assign(new Error(message), { code });
+const importTokenScanner = async () => {
+    // `token-scan.ts` imports `typescript/unstable/ast` at its own top level, so
+    // this is the one place the dependency is reached and the one place its
+    // absence can be turned into a sentence.
+    const [ast, scan] = await Promise.all([
+        import('typescript/unstable/ast'),
+        import('./token-scan.js'),
+    ]);
+    return {
+        scanTokens: scan.scanTokens,
+        computeLineStarts: scan.computeLineStarts,
+        lineOf: scan.lineOf,
+        syntax: ast.SyntaxKind,
+    };
+};
+/**
+ * The tokenizer, or a refusal naming the dependency and the gate that needs it.
+ * `load` is injectable so the refusal has a test that does not require
+ * uninstalling anything.
+ */
+export async function loadTokenScanner(gate, load = importTokenScanner) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        if (error.code !== 'ERR_MODULE_NOT_FOUND') {
+            throw error;
+        }
+        throw codedError(TYPESCRIPT_UNAVAILABLE, `the ${gate} gate reads your source through the typescript package's own scanner, and typescript did not resolve. Install typescript to run this gate; every other gate needs nothing beyond this package.`);
+    }
+}
+const Identifier = z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/, 'is not an identifier; the scan matches a name as the tokenizer sees it, so a member expression or a quoted key cannot be written here');
+export const FieldOwnershipSection = z
+    .strictObject({
+    paths: ScannedPathList.describe('The source the scan reads. Give it the extensions your source uses; a file outside these paths is neither held nor counted.'),
+    fields: z
+        .array(Identifier)
+        .min(1)
+        .describe('The field names you own. A write to any of them outside the declared set is a violation.'),
+    declarations: z
+        .array(RelativePrefix)
+        .default([])
+        .describe('Path prefixes where naming a field is always allowed, whatever the writer list says: where the schema, the type, and the factory that defines the shape live. A file under one of these is exempt entirely.'),
+    writers: z
+        .array(RelativePath)
+        .min(1)
+        .describe('The modules permitted to write the fields. Each one has to write every field, so a rename that empties this list fails here instead of quietly disabling the rule.'),
+    helpers: z
+        .array(Identifier)
+        .default([])
+        .describe("Identifiers that write the fields on a caller's behalf. Naming one outside the writer list is the same write one line further out, so the scan reports the call, the import, and an aliased import alike. A write routed through a helper you have not named here is invisible to this gate."),
+})
+    .superRefine((section, ctx) => {
+    const overlap = section.fields.filter((field) => section.helpers.includes(field));
+    if (overlap.length > 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['helpers'],
+            message: `names ${overlap.join(', ')}, which is also a field; one name cannot be both, since a field is reported by position and a helper by mention`,
+        });
+    }
+})
+    .describe('Fails on a write to a field you own from a module you did not declare, and on a declared module that writes none of the fields it is named for.');
+export const rulesOf = (section) => ({
+    fields: new Set(section.fields),
+    declarations: section.declarations,
+    writers: section.writers,
+    helpers: new Set(section.helpers),
+});
+/** How far back the enclosing-bracket search runs before giving up and reporting. */
+const MAX_LOOKBACK = 500;
+const kindsOf = (syntax) => ({
+    syntax,
+    binders: new Set([
+        syntax.ConstKeyword,
+        syntax.LetKeyword,
+        syntax.VarKeyword,
+        syntax.ImportKeyword,
+    ]),
+    typeDeclarers: new Set([syntax.TypeKeyword, syntax.InterfaceKeyword]),
+    typeHeads: new Set([syntax.LessThanToken, syntax.ExtendsKeyword]),
+});
+function isPermitted(file, rules) {
+    if (rules.declarations.some((prefix) => file.startsWith(prefix)))
+        return true;
+    return rules.writers.includes(file);
+}
+const assigns = (kinds, kind) => kind !== undefined &&
+    kind >= kinds.syntax.FirstAssignment &&
+    kind <= kinds.syntax.LastAssignment;
+/**
+ * True when the token at `index` starts a member of the literal around it. A
+ * formatter writes TS type members newline-separated with no separator and often
+ * behind `readonly`, so a line break counts alongside `{`, `,` and `;`.
+ */
+function opensMember(kinds, tokens, lines, index) {
+    const previous = tokens[index - 1];
+    if (previous === undefined)
+        return false;
+    if (previous.kind === kinds.syntax.OpenBraceToken ||
+        previous.kind === kinds.syntax.CommaToken ||
+        previous.kind === kinds.syntax.SemicolonToken ||
+        previous.kind === kinds.syntax.ReadonlyKeyword) {
+        return true;
+    }
+    return (lines[index - 1] ?? 0) < (lines[index] ?? 0);
+}
+/**
+ * Walks back to the nearest unmatched opening bracket. A `{` is a literal, and
+ * a `:` before it or a `type`/`interface` in its statement makes it a type
+ * literal. A `{` a binder introduced is a destructuring pattern, and a `(` or
+ * `[` reached first is a parameter list or an index; both are reads.
+ */
+function enclosureOf(kinds, tokens, lines, index) {
+    const { syntax } = kinds;
+    let braces = 0;
+    let parens = 0;
+    let brackets = 0;
+    const floor = Math.max(0, index - MAX_LOOKBACK);
+    for (let i = index - 1; i >= floor; i--) {
+        const kind = tokens[i]?.kind;
+        if (kind === syntax.CloseBraceToken)
+            braces++;
+        else if (kind === syntax.CloseParenToken)
+            parens++;
+        else if (kind === syntax.CloseBracketToken)
+            brackets++;
+        else if (kind === syntax.OpenParenToken && parens-- === 0)
+            return 'read';
+        else if (kind === syntax.OpenBracketToken && brackets-- === 0) {
+            return 'read';
+        }
+        else if (kind === syntax.OpenBraceToken && braces-- === 0) {
+            const before = tokens[i - 1]?.kind ?? -1;
+            if (kinds.binders.has(before))
+                return 'read';
+            if (kinds.typeHeads.has(before))
+                return 'type-literal';
+            // A `{` after a colon is a type annotation, unless the name before that
+            // colon is itself a member of a value literal: `lineage: { id: null }`
+            // is a nested value, while `row: { id: Id }` in a parameter list is a
+            // shape.
+            if (before === syntax.ColonToken) {
+                if (kinds.binders.has(tokens[i - 3]?.kind ?? -1))
+                    return 'type-literal';
+                return enclosureOf(kinds, tokens, lines, i - 2) === 'value-literal'
+                    ? 'value-literal'
+                    : 'type-literal';
+            }
+            return declaresType(kinds, tokens, i) ? 'type-literal' : 'value-literal';
+        }
+    }
+    // Unresolved within the window: report it.
+    return 'value-literal';
+}
+/** True when a `type` or `interface` keyword opens the statement holding the `{` at `open`. */
+function declaresType(kinds, tokens, open) {
+    const { syntax } = kinds;
+    const floor = Math.max(0, open - MAX_LOOKBACK);
+    for (let i = open - 1; i >= floor; i--) {
+        const kind = tokens[i]?.kind;
+        if (kind === undefined)
+            return false;
+        if (kinds.typeDeclarers.has(kind))
+            return true;
+        if (kind === syntax.SemicolonToken ||
+            kind === syntax.OpenBraceToken ||
+            kind === syntax.CloseBraceToken ||
+            kinds.binders.has(kind)) {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * What a bare-identifier occurrence is. Any assignment operator makes it an
+ * assignment wherever it appears. A name opening a member of an object or type
+ * literal declares the field; a type literal is reported too, and `scanFile`
+ * keeps it out of the write count.
+ */
+function writeKind(kinds, tokens, lines, index) {
+    const { syntax } = kinds;
+    const next = tokens[index + 1]?.kind;
+    if (assigns(kinds, next))
+        return 'assignment';
+    if (tokens[index - 1]?.kind === syntax.DotToken)
+        return undefined;
+    if (next !== syntax.ColonToken &&
+        next !== syntax.CommaToken &&
+        next !== syntax.CloseBraceToken) {
+        return undefined;
+    }
+    // `return count }` and `[id, x]` use a name bound elsewhere, so only a member
+    // start reaches the enclosure walk.
+    if (!opensMember(kinds, tokens, lines, index))
+        return undefined;
+    switch (enclosureOf(kinds, tokens, lines, index)) {
+        case 'value-literal':
+            return 'literal';
+        case 'type-literal':
+            return 'type';
+        default:
+            return undefined;
+    }
+}
+/**
+ * True when this member is a field given a value inside a value literal. A
+ * shorthand binds a name and every type position declares a shape, so neither
+ * can stand in for the write a declared writer owes. The enclosure decides it,
+ * since a denylist of type names cannot be completed: an alias, a branded type,
+ * and a literal type all read like values.
+ */
+function mints(kinds, tokens, index) {
+    return tokens[index + 1]?.kind === kinds.syntax.ColonToken;
+}
+function scanFile(file, source, rules, scanner, kinds, violations) {
+    const { syntax } = kinds;
+    const tokens = scanner.scanTokens(source);
+    const lineStarts = scanner.computeLineStarts(source);
+    const lines = tokens.map((token) => scanner.lineOf(lineStarts, token.start));
+    const permitted = isPermitted(file, rules);
+    const written = new Set();
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === undefined)
+            continue;
+        const line = lines[i] ?? 1;
+        // A string spelling an owned field reaches it through a computed key, a
+        // bracket assignment, `Object.defineProperty`, or `Reflect.set`. All four
+        // look alike at this level, so any of them is reported.
+        if (token.kind === syntax.StringLiteral ||
+            token.kind === syntax.NoSubstitutionTemplateLiteral) {
+            if (permitted || !rules.fields.has(token.value))
+                continue;
+            violations.push({
+                file,
+                line,
+                subject: token.value,
+                rule: 'names an owned field as a string, which reaches it through a computed key or a reflective set',
+            });
+            continue;
+        }
+        if (token.kind !== syntax.Identifier)
+            continue;
+        if (rules.fields.has(token.value)) {
+            const kind = writeKind(kinds, tokens, lines, i);
+            if (kind === undefined)
+                continue;
+            if (kind === 'assignment' ||
+                (kind === 'literal' && mints(kinds, tokens, i))) {
+                written.add(token.value);
+            }
+            if (permitted)
+                continue;
+            violations.push({
+                file,
+                line,
+                subject: token.value,
+                rule: `only a declared path or a declared writer may set this field; this is a ${kind} position`,
+            });
+            continue;
+        }
+        if (rules.helpers.has(token.value) && !permitted) {
+            violations.push({
+                file,
+                line,
+                subject: token.value,
+                rule: `${token.value}() sets the owned fields, so naming it outside the writer list is the same write one line further out`,
+            });
+        }
+    }
+    return written;
+}
+/**
+ * Scans every file in `files` (repo-relative POSIX path -> source text) and
+ * returns every violation, in no particular cross-file order. Pure and
+ * synchronous over the map, so one function backs both the real scan and a
+ * synthetic test map.
+ */
+export function scanFieldOwnership(files, rules, scanner, options) {
+    const kinds = kindsOf(scanner.syntax);
+    const violations = [];
+    const writesByFile = new Map();
+    for (const [file, source] of files) {
+        writesByFile.set(file, scanFile(file, source, rules, scanner, kinds, violations));
+    }
+    for (const module of rules.writers) {
+        const written = writesByFile.get(module);
+        if (written === undefined) {
+            if (!options.wholeTree)
+                continue;
+            violations.push({
+                file: module,
+                line: 1,
+                subject: module,
+                rule: 'the configuration names this module as a writer and no such file was scanned; a rename emptied the writer list',
+            });
+            continue;
+        }
+        for (const field of rules.fields) {
+            if (written.has(field))
+                continue;
+            violations.push({
+                file: module,
+                line: 1,
+                subject: field,
+                rule: 'the configuration names this module as a writer of this field and it writes none',
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * The gate, over a consumer's tree. `root` is the directory its configuration
+ * file sits in.
+ */
+export async function runFieldOwnership(root, section, gate = 'field-ownership', load) {
+    const scanner = await loadTokenScanner(gate, load);
+    const { entries } = await discoverEntries(root, section.paths, gate);
+    const violations = scanFieldOwnership(entries, rulesOf(section), scanner, {
+        wholeTree: true,
+    });
+    return { violations, scanned: entries.size };
+}

package/dist/gates/module-value.js

@@ -0,0 +1,187 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// How a configuration names a value it cannot spell in JSON.
+//
+// The three documentation gates hold a page against something the repository
+// computes: how many contracts a corpus carries, which stages perform a
+// comparison, which schema a worked example parses against, whether a claim
+// that was true when it was written still is. None of those is a literal, and
+// writing one into the configuration would create exactly the setting this
+// format does not have: a number or a list a hand keeps in step with the code
+// beside it.
+//
+// So a source is a module path and an export name. The gate imports the
+// consumer's own module and reads the value out of it, which puts the
+// computation in the consumer's code, where it can be tested, and leaves the
+// configuration naming it.
+//
+// The module is the consumer's, and importing it runs it. That is the same
+// trust a lint plugin or a test setup file has, and the published page says so
+// plainly, so a consumer choosing to point a gate at a module knows what the
+// gate does with it.
+//
+// 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 { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { RelativePath } from './scanned-paths.js';
+/** A module a configuration named that could not be imported or read. */
+export const MODULE_VALUE_ERROR = 'EVAL_QUALITY_MODULE_VALUE';
+const NonEmpty = z.string().min(1);
+/**
+ * What to take from the export. `value` is the export itself, `length` its
+ * `length`, and `keys` the number of its own enumerable keys.
+ *
+ * Three rather than one, because the alternative is a configuration naming a
+ * separate `…_COUNT` export beside every list, which is a second value a hand
+ * maintains in step with the first.
+ */
+export const Take = z.enum(['value', 'length', 'keys']);
+export const ModuleValue = z
+    .strictObject({
+    module: RelativePath.describe('The module to import, relative to the configuration file. It is imported, so it runs.'),
+    export: NonEmpty.describe('The export to read. A default export is named "default".'),
+    path: z
+        .array(NonEmpty)
+        .optional()
+        .describe('Properties to walk from the export before taking anything, so one exported table can back several sources.'),
+    take: Take.default('value').describe('What to take: the value itself, its length, or the number of its own keys.'),
+})
+    .describe('A value this configuration cannot spell: a module of yours, an export of that module, and what to take from it.');
+const codedError = (message) => Object.assign(new Error(message), { code: MODULE_VALUE_ERROR });
+const detail = (error) => error instanceof Error ? error.message : String(error);
+/** How a source reads in a refusal, so every message names the same thing. */
+export const nameOf = (source) => {
+    const walked = source.path === undefined ? '' : `.${source.path.join('.')}`;
+    return `${source.module}'s ${source.export}${walked}`;
+};
+const typeOf = (value) => value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+/**
+ * The value behind one source. Every refusal names the module, the export and
+ * what was found, because those are the three things the reader has to compare
+ * against their own tree.
+ *
+ * Imports are not cached here. Node caches a module by URL for the life of the
+ * process, so two sources naming one module import it once.
+ */
+export async function readModuleValue(root, source) {
+    const url = pathToFileURL(resolve(root, source.module));
+    let module;
+    try {
+        module = (await import(__rewriteRelativeImportExtension(url.href)));
+    }
+    catch (error) {
+        throw codedError(`${source.module} could not be imported: ${detail(error)}`);
+    }
+    if (!(source.export in module)) {
+        // `default` stays in the listing. Filtering it out told a module whose only
+        // export is a default that it exports nothing, while `export: "default"`
+        // would have resolved.
+        const exported = Object.keys(module).sort();
+        throw codedError(`${source.module} exports no "${source.export}"; it exports ${exported.length === 0 ? 'nothing' : exported.join(', ')}`);
+    }
+    let value = module[source.export];
+    for (const key of source.path ?? []) {
+        if (value === null || typeof value !== 'object') {
+            throw codedError(`${nameOf(source)}: "${key}" was reached on ${typeOf(value)}, which has no properties`);
+        }
+        const holder = value;
+        if (!(key in holder)) {
+            throw codedError(`${nameOf(source)}: "${key}" is absent; the keys there are ${Object.keys(holder).sort().join(', ')}`);
+        }
+        value = holder[key];
+    }
+    return value;
+}
+/**
+ * The count behind a value, however the configuration asked for it. Shared, so a
+ * module export and a value walked out of a JSON file answer to one rule and one
+ * wording rather than to two that drift.
+ *
+ * `where` is what the refusal names, which differs per caller: a module export
+ * for one, a file and a key path for the other.
+ */
+export function takeCount(value, take, where) {
+    if (take === 'value') {
+        if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+            return value;
+        }
+        throw codedError(`${where} is ${typeOf(value)} and take is "value", so a count was expected; a list takes "length" and a table takes "keys"`);
+    }
+    if (take === 'length') {
+        // A string has a length and counting its characters is never what a page
+        // meant, so it is refused rather than answered. Every other `length` a
+        // configuration can reach is a list's.
+        if (typeof value === 'string') {
+            throw codedError(`${where} is a string and take is "length", which would count its characters; a page counts members, so name a list`);
+        }
+        const length = value?.length;
+        if (typeof length === 'number' && Number.isInteger(length) && length >= 0) {
+            return length;
+        }
+        throw codedError(`${where} is ${typeOf(value)} and take is "length", which it has none of`);
+    }
+    if (value === null || typeof value !== 'object') {
+        throw codedError(`${where} is ${typeOf(value)} and take is "keys", which only an object has`);
+    }
+    return Object.keys(value).length;
+}
+/** A source that has to answer a number, which is every count a page carries. */
+export async function readModuleCount(root, source) {
+    return takeCount(await readModuleValue(root, source), source.take, nameOf(source));
+}
+/** A source that has to answer a list of strings, which is every transcribed set. */
+export async function readModuleStrings(root, source) {
+    const value = await readModuleValue(root, source);
+    if (!Array.isArray(value) || value.some((each) => typeof each !== 'string')) {
+        throw codedError(`${nameOf(source)} is ${typeOf(value)}, and a list of strings was expected`);
+    }
+    return value;
+}
+/** A source that has to answer one string, which is every transcription. */
+export async function readModuleText(root, source) {
+    const value = await readModuleValue(root, source);
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'function') {
+        const produced = await value();
+        if (typeof produced === 'string')
+            return produced;
+        throw codedError(`${nameOf(source)} is a function and it returned ${typeOf(produced)}; a transcription source returns the text`);
+    }
+    throw codedError(`${nameOf(source)} is ${typeOf(value)}, and a string or a function returning one was expected`);
+}
+/**
+ * A source that has to answer a predicate's verdict. A boolean export settles a
+ * claim that a constant decides; a function export settles one that needs the
+ * tree read, and it is awaited so a reader may be asynchronous.
+ */
+export async function readModuleVerdict(root, source) {
+    const value = await readModuleValue(root, source);
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'function') {
+        const produced = await value();
+        if (typeof produced === 'boolean')
+            return produced;
+        throw codedError(`${nameOf(source)} is a function and it returned ${typeOf(produced)}; a predicate answers true or false`);
+    }
+    throw codedError(`${nameOf(source)} is ${typeOf(value)}, and a boolean or a function returning one was expected`);
+}
+export async function readModuleParser(root, source) {
+    const value = await readModuleValue(root, source);
+    if (value !== null &&
+        typeof value === 'object' &&
+        typeof value.safeParse === 'function') {
+        return value;
+    }
+    throw codedError(`${nameOf(source)} is ${typeOf(value)} and has no safeParse; a schema source names a Zod schema`);
+}