eval-quality 2.0.0 → 3.1.0

package/dist/gates/package-boundary.js

@@ -0,0 +1,388 @@
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+/**
+ * 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
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * behavioral contract is one JSON object per line and the longest committed
+ * one is 13,333 characters. A bound sized to the threat this constant exists
+ * for, an actual megabyte-scale bundle, and not to this repository's own
+ * content, is a gate that fails on the tree it ships with, which is worse
+ * than the DoS surface it is meant to close.
+ *
+ * What is left uncovered: a pattern with nested quantifiers over a line shorter
+ * than the bound can still take far longer than the file deserves. That work is
+ * bounded, since the input is, and it is the consumer's own pattern over the
+ * consumer's own tree. Running each match in a worker with a wall-clock kill
+ * would close it and would make the scanner asynchronous and impure, which costs
+ * 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
+ * cannot take it and a reader of the report can tell a rule that fired from a
+ * 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({
+    file: RelativePath.default('package.json').describe('The manifest a registry publishes verbatim.'),
+    fields: z
+        .array(ManifestField)
+        .min(1)
+        .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.'),
+    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) => {
+    if (pattern.name === OVERLONG_LINE) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['name'],
+            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)}`,
+        });
+    }
+});
+export const PackageBoundarySection = z
+    .strictObject({
+    paths: ScannedPathList.describe('Everything the scan reads out of the tree. What you leave out is exempt, and leaving it out is the only exemption there is.'),
+    manifest: ManifestScan.optional(),
+    patterns: z
+        .array(ForbiddenPattern)
+        .min(1)
+        .max(MAX_PATTERNS)
+        .describe('The forbidden patterns, in precedence order. The first one that matches a logical line is the one the line is reported under, and no line is reported twice, so a specific spelling has to precede any shorter word contained in it: a pattern for a word that is a substring of a path you also forbid will otherwise take every one of those paths and the path pattern will never fire.'),
+})
+    .superRefine((section, ctx) => {
+    const seen = new Set();
+    section.patterns.forEach((pattern, index) => {
+        if (seen.has(pattern.name)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['patterns', index, 'name'],
+                message: `repeats "${pattern.name}"; a violation is reported under this name, so two patterns cannot share one`,
+            });
+        }
+        seen.add(pattern.name);
+    });
+})
+    .describe('Fails on any line of any scanned file that matches a pattern you declared. The scanned set is what a registry would publish out of your tree, so what this holds is the package as an installer receives it.');
+export const compileBoundaryPatterns = (patterns) => patterns.map((pattern) => ({
+    name: pattern.name,
+    regex: new RegExp(pattern.match, pattern.flags),
+    reason: pattern.reason,
+}));
+/** The comment markers a wrapped run is joined across. */
+const COMMENT_START = /^\s*(\/\/+|\/\*+|\*+\/?|#)/;
+const isCommentLine = (line) => COMMENT_START.test(line);
+/** Strips the marker so `* Widget` and `* 1.5` join into `Widget 1.5`. */
+const commentText = (line) => line
+    .replace(COMMENT_START, '')
+    .replace(/\*\/\s*$/, '')
+    .trim();
+/**
+ * One entry per logical line: a run of consecutive comment lines joins with
+ * single spaces and is attributed to the first line of the run, because a
+ * comment wraps at some column and a reference split across two physical lines
+ * is the ordinary shape. Every other line stands on its own, and its two joins
+ * are the same string.
+ */
+export function logicalLines(source) {
+    const physical = source.split('\n');
+    const logical = [];
+    let index = 0;
+    while (index < physical.length) {
+        const current = physical[index];
+        if (!isCommentLine(current)) {
+            logical.push({ line: index + 1, text: current, tight: current });
+            index += 1;
+            continue;
+        }
+        const parts = [];
+        const start = index;
+        while (index < physical.length) {
+            const line = physical[index];
+            if (!isCommentLine(line))
+                break;
+            const stripped = commentText(line);
+            if (stripped !== '')
+                parts.push(stripped);
+            index += 1;
+        }
+        logical.push({
+            line: start + 1,
+            text: parts.join(' '),
+            tight: parts.join(''),
+        });
+    }
+    return logical;
+}
+export function scanPackageBoundary(files, patterns) {
+    const violations = [];
+    for (const [file, source] of files) {
+        for (const { line, text, tight } of logicalLines(source)) {
+            if (text === '')
+                continue;
+            if (text.length > MAX_SCANNED_LINE) {
+                // Reported rather than skipped: a line the gate declined to match is
+                // a line nobody held, and silence there is the pass this bound would
+                // otherwise buy.
+                violations.push({
+                    file,
+                    line,
+                    pattern: OVERLONG_LINE,
+                    reason: `a logical line of ${text.length} characters is past the ${MAX_SCANNED_LINE}-character bound a pattern is matched within, so no pattern was run against it`,
+                    text: `${text.slice(0, 120)}...`,
+                });
+                continue;
+            }
+            for (const pattern of patterns) {
+                if (!pattern.regex.test(text) && !pattern.regex.test(tight))
+                    continue;
+                // One violation per logical line: the `break` is what makes the
+                // declared order decide the reported name. A line carrying two
+                // forbidden references is one edit either way.
+                violations.push({
+                    file,
+                    line,
+                    pattern: pattern.name,
+                    reason: pattern.reason,
+                    text,
+                });
+                break;
+            }
+        }
+    }
+    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);
+        return;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        into.set(key, String(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        into.set(key, value.map((each) => String(each)).join(' '));
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [name, nested] of Object.entries(value)) {
+            flattenField(`${key}.${name}`, nested, into);
+        }
+        return;
+    }
+    throw codedError(SCAN_PATH_ERROR, `${key} is null, so there is nothing to scan`);
+}
+export async function manifestEntries(root, manifest, gate) {
+    let text;
+    try {
+        text = await readFile(resolve(root, manifest.file), 'utf8');
+    }
+    catch (error) {
+        throw codedError(SCAN_PATH_ERROR, `${manifest.file} could not be read: ${detail(error)}; the "${gate}" section names it under manifest.file`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw codedError(SCAN_PATH_ERROR, `${manifest.file} is not valid JSON: ${detail(error)}`);
+    }
+    const entries = new Map();
+    for (const field of manifest.fields) {
+        let value = parsed;
+        for (const segment of field.split('.')) {
+            value =
+                value !== null && typeof value === 'object'
+                    ? value[segment]
+                    : undefined;
+        }
+        if (value === undefined) {
+            throw codedError(SCAN_PATH_ERROR, `${manifest.file} carries no "${field}", and the "${gate}" section names it under manifest.fields; a field that is not there would otherwise read as a field with nothing in it`);
+        }
+        flattenField(`${manifest.file}#${field}`, value, entries);
+    }
+    return entries;
+}
+/**
+ * The gate, over a consumer's tree. `root` is the directory its configuration
+ * file sits in, which is what makes a configuration self-contained wherever it
+ * is kept.
+ */
+export async function runPackageBoundary(root, section, gate = 'package-boundary') {
+    const { entries, counts } = await discoverEntries(root, section.paths, gate);
+    if (section.manifest !== undefined) {
+        const fields = await manifestEntries(root, section.manifest, gate);
+        for (const [key, value] of fields)
+            entries.set(key, value);
+        counts.push({ path: section.manifest.file, files: fields.size });
+    }
+    const violations = scanPackageBoundary(entries, compileBoundaryPatterns(section.patterns));
+    return { violations, counts, scanned: entries.size };
+}

package/dist/gates/token-scan.js

@@ -0,0 +1,203 @@
+// The one tokenizer both source-scanning gates share. Pure and synchronous.
+//
+// TypeScript 7.0.2 ships no in-process parser, and spawning the native `tsgo`
+// binary is too slow for a lint gate, so `createScanner` is the surface left.
+// Two of its context-dependent decisions belong to the parser, and `scanTokens`
+// makes them:
+//
+// A slash is division or the start of a regex depending on what came before.
+// Left alone, every regex body leaks into the stream as code: `/^#/` emits a
+// zero-width token forever, a backtick opens a template that runs to end of
+// file, `\/` opens a line comment that eats the rest of its line, and `{`
+// inside a character class shifts brace depth for every line after it. The
+// re-scan below decides it the way the parser does, from the previous token.
+//
+// The closing `}` of a template substitution is a brace or a template
+// continuation. Left alone the template's tail reads as code and its closing
+// backtick opens a second template, so the file's whole tail is fiction.
+//
+// Three guards catch what is left: a token that makes no progress, an
+// unterminated literal, and a stream that ends with an unbalanced brace or an
+// open template. Each throws with an offset instead of returning a stream a
+// gate would trust.
+import { computeLineStarts, createScanner, SyntaxKind, } from 'typescript/unstable/ast';
+/**
+ * Token kinds that can end an expression, so a following `/` is division. The
+ * type keywords are here for an `as` clause: `y as number / 2` is division.
+ */
+const ENDS_EXPRESSION = new Set([
+    SyntaxKind.Identifier,
+    SyntaxKind.NumericLiteral,
+    SyntaxKind.BigIntLiteral,
+    SyntaxKind.StringLiteral,
+    SyntaxKind.NoSubstitutionTemplateLiteral,
+    SyntaxKind.TemplateTail,
+    SyntaxKind.RegularExpressionLiteral,
+    SyntaxKind.CloseParenToken,
+    SyntaxKind.CloseBracketToken,
+    SyntaxKind.CloseBraceToken,
+    SyntaxKind.ThisKeyword,
+    SyntaxKind.SuperKeyword,
+    SyntaxKind.TrueKeyword,
+    SyntaxKind.FalseKeyword,
+    SyntaxKind.NullKeyword,
+    SyntaxKind.PlusPlusToken,
+    SyntaxKind.MinusMinusToken,
+    SyntaxKind.NumberKeyword,
+    SyntaxKind.StringKeyword,
+    SyntaxKind.BooleanKeyword,
+    SyntaxKind.AnyKeyword,
+    SyntaxKind.UnknownKeyword,
+    SyntaxKind.ObjectKeyword,
+    SyntaxKind.SymbolKeyword,
+    SyntaxKind.BigIntKeyword,
+    SyntaxKind.NeverKeyword,
+    SyntaxKind.VoidKeyword,
+    SyntaxKind.UndefinedKeyword,
+    SyntaxKind.ConstKeyword,
+]);
+/** A `(` after one of these heads a statement, so its `)` ends no expression. */
+const CONTROL_HEADS = new Set([
+    SyntaxKind.IfKeyword,
+    SyntaxKind.WhileKeyword,
+    SyntaxKind.ForKeyword,
+    SyntaxKind.CatchKeyword,
+    SyntaxKind.WithKeyword,
+]);
+/**
+ * A `{` after one of these is an object or type literal; anywhere else it opens
+ * a block. `=>` is deliberately absent: an arrow's braces are always a body,
+ * and an object-literal body needs parentheses, which `(` already covers.
+ */
+const LITERAL_HEADS = new Set([
+    SyntaxKind.OpenParenToken,
+    SyntaxKind.CommaToken,
+    SyntaxKind.ColonToken,
+    SyntaxKind.OpenBracketToken,
+    SyntaxKind.ReturnKeyword,
+    SyntaxKind.QuestionToken,
+    SyntaxKind.ExtendsKeyword,
+    SyntaxKind.LessThanToken,
+    SyntaxKind.BarToken,
+    SyntaxKind.AmpersandToken,
+]);
+/** Where a statement can begin, which is where a label can. */
+const STATEMENT_BOUNDARIES = new Set([
+    -1,
+    SyntaxKind.SemicolonToken,
+    SyntaxKind.OpenBraceToken,
+    SyntaxKind.CloseBraceToken,
+]);
+export function scanTokens(source) {
+    const scanner = createScanner(/* skipTrivia */ true, undefined, source);
+    const tokens = [];
+    // Brace depth at each open template's substitution, innermost last.
+    const templates = [];
+    // Whether each open `(` heads a statement and each open `{` opens a block,
+    // innermost last. A statement's `)` and a block's `}` end no expression, so
+    // a `/` after either starts a regex.
+    const controlParens = [];
+    const blockBraces = [];
+    let depth = 0;
+    let previousEnd = -1;
+    let previousKind = -1;
+    let beforePreviousKind = -1;
+    let thirdPreviousKind = -1;
+    let previousEnds = false;
+    /**
+     * True when the `:` just scanned labels a statement. A label needs an
+     * identifier at statement position, so a ternary's `g :` and a member's
+     * `a :` inside an open literal are both excluded.
+     */
+    const labelColon = () => previousKind === SyntaxKind.ColonToken &&
+        beforePreviousKind === SyntaxKind.Identifier &&
+        STATEMENT_BOUNDARIES.has(thirdPreviousKind) &&
+        blockBraces[blockBraces.length - 1] !== false;
+    while (true) {
+        let kind = scanner.scan();
+        if (kind === SyntaxKind.EndOfFile)
+            break;
+        if ((kind === SyntaxKind.SlashToken ||
+            kind === SyntaxKind.SlashEqualsToken) &&
+            !previousEnds) {
+            kind = scanner.reScanSlashToken();
+        }
+        const end = scanner.getTokenEnd();
+        if (end === previousEnd) {
+            throw new Error(`token scan made no progress at offset ${scanner.getTokenStart()}; the source is outside what this tokenizer can read`);
+        }
+        if (scanner.isUnterminated()) {
+            throw new Error(`token scan hit an unterminated literal at offset ${scanner.getTokenStart()}; everything after it would be read as the wrong kind of token`);
+        }
+        previousEnd = end;
+        let ends = ENDS_EXPRESSION.has(kind);
+        if (kind === SyntaxKind.OpenParenToken) {
+            // `p.catch(f)` is a call and `for await (…)` is a statement, so the
+            // token before the keyword decides both.
+            controlParens.push((CONTROL_HEADS.has(previousKind) &&
+                beforePreviousKind !== SyntaxKind.DotToken) ||
+                (previousKind === SyntaxKind.AwaitKeyword &&
+                    beforePreviousKind === SyntaxKind.ForKeyword));
+        }
+        else if (kind === SyntaxKind.CloseParenToken) {
+            if (controlParens.pop() === true)
+                ends = false;
+        }
+        else if (kind === SyntaxKind.OpenBraceToken) {
+            depth++;
+            blockBraces.push(!((LITERAL_HEADS.has(previousKind) ||
+                (previousKind >= SyntaxKind.FirstAssignment &&
+                    previousKind <= SyntaxKind.LastAssignment)) &&
+                !labelColon()));
+        }
+        else if (kind === SyntaxKind.CloseBraceToken) {
+            if (templates[templates.length - 1] === depth) {
+                kind = scanner.reScanTemplateToken(/* isTaggedTemplate */ false);
+                if (kind === SyntaxKind.TemplateTail)
+                    templates.pop();
+                ends = ENDS_EXPRESSION.has(kind);
+            }
+            else {
+                // A brace closing a real block or literal. Drop this and a later
+                // `}` is misread as a template continuation.
+                depth--;
+                if (blockBraces.pop() === true)
+                    ends = false;
+            }
+        }
+        if (kind === SyntaxKind.TemplateHead)
+            templates.push(depth);
+        // A postfix `!` inherits: `x! / 2` is division, `!/re/.test(s)` is a
+        // regex, and the token before the `!` is what separates them.
+        if (kind === SyntaxKind.ExclamationToken)
+            ends = previousEnds;
+        thirdPreviousKind = beforePreviousKind;
+        beforePreviousKind = previousKind;
+        previousKind = kind;
+        previousEnds = ends;
+        tokens.push({
+            kind,
+            text: scanner.getTokenText(),
+            value: scanner.getTokenValue(),
+            start: scanner.getTokenStart(),
+        });
+    }
+    if (depth !== 0 || templates.length > 0) {
+        throw new Error(`token scan ended with brace depth ${depth} and ${templates.length} open template(s); the stream desynced somewhere in this file`);
+    }
+    return tokens;
+}
+/** 1-indexed line holding `pos`, by binary search over `computeLineStarts`. */
+export function lineOf(lineStarts, pos) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if ((lineStarts[mid] ?? 0) <= pos)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low + 1;
+}
+export { computeLineStarts };

package/dist/index.d.ts

@@ -1,15 +1,25 @@
 export * from './application/index.ts';
 export type { ArtifactReference } from './core/schemas/artifact-reference.ts';
 export type { EvalContract } from './core/schemas/eval-contract.ts';
+export { EVAL_CONTRACT_SCHEMA_VERSION } from './core/schemas/eval-contract.ts';
 export type { EvaluatorConfiguration } from './core/schemas/evaluator-configuration.ts';
+export { EVALUATOR_CONFIGURATION_SCHEMA_VERSION } from './core/schemas/evaluator-configuration.ts';
 export type { EvidenceArtifact } from './core/schemas/evidence-artifact.ts';
+export { EVIDENCE_ARTIFACT_SCHEMA_VERSION } from './core/schemas/evidence-artifact.ts';
 export type { IsolationManifest } from './core/schemas/isolation-manifest.ts';
+export { ISOLATION_MANIFEST_SCHEMA_VERSION } from './core/schemas/isolation-manifest.ts';
 export type { PreflightCheck, PreflightVerdict, } from './core/schemas/preflight-verdict.ts';
+export { PREFLIGHT_VERDICT_SCHEMA_VERSION } from './core/schemas/preflight-verdict.ts';
 export type { PrivateArtifactManifest } from './core/schemas/private-artifact-manifest.ts';
+export { PRIVATE_ARTIFACT_MANIFEST_SCHEMA_VERSION } from './core/schemas/private-artifact-manifest.ts';
 export type { Probe } from './core/schemas/probe.ts';
+export { PROBE_SCHEMA_VERSION } from './core/schemas/probe.ts';
 export type { Rubric } from './core/schemas/rubric.ts';
 export type { ScoringPolicy } from './core/schemas/scoring-policy.ts';
+export { SCORING_POLICY_SCHEMA_VERSION } from './core/schemas/scoring-policy.ts';
 export type { SealedEvaluatorBrief } from './core/schemas/sealed-evaluator-brief.ts';
+export { SEALED_EVALUATOR_BRIEF_SCHEMA_VERSION } from './core/schemas/sealed-evaluator-brief.ts';
 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 = "2.0.0";
+export declare const VERSION = "3.1.0";

package/dist/index.js

@@ -18,5 +18,24 @@
 // second edge. The port vocabulary stays at the `eval-quality/conformance`
 // subpath, where AD-37 puts the conformance definition an adapter author
 // reads; the reference adapters stay at `eval-quality/adapters`.
+//
+// The schema versions ride that second edge beside the artifact types they
+// stamp, so a consumer satisfying AD-11's equality rule imports the number this
+// build reads. Ten of the twelve artifacts carry one: the two with an in-package
+// reader, the three this package stamps, and the five a caller assembles and
+// `score` validates. `artifact-reference` carries no lineage at all. A rubric
+// does carry a `schemaVersion`, and no constant here states it: this package
+// never parses a standalone rubric, and the eval contract embeds `RubricBody`,
+// the body without lineage.
 export * from './application/index.js';
-export const VERSION = '2.0.0';
+export { EVAL_CONTRACT_SCHEMA_VERSION } from './core/schemas/eval-contract.js';
+export { EVALUATOR_CONFIGURATION_SCHEMA_VERSION } from './core/schemas/evaluator-configuration.js';
+export { EVIDENCE_ARTIFACT_SCHEMA_VERSION } from './core/schemas/evidence-artifact.js';
+export { ISOLATION_MANIFEST_SCHEMA_VERSION } from './core/schemas/isolation-manifest.js';
+export { PREFLIGHT_VERDICT_SCHEMA_VERSION } from './core/schemas/preflight-verdict.js';
+export { PRIVATE_ARTIFACT_MANIFEST_SCHEMA_VERSION } from './core/schemas/private-artifact-manifest.js';
+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';