eval-quality 3.1.0 → 3.3.0

package/dist/gates/gates-cli.js

@@ -24,12 +24,17 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import process from 'node:process';
-import { auditLockfileAge, LOCKFILE_SHAPE_ERROR, } from './audit-lockfile-age.mjs';
+import { auditLockfileAge, LOCKFILE_SHAPE_ERROR, readPublishCache, } from './audit-lockfile-age.mjs';
 import { runDependencyDirection } from './check-dependency-direction.js';
+import { DOC_CLAIM_PATH, runDocClaims } from './check-doc-claims.js';
+import { DOC_COUNT_SOURCE, runDocCounts } from './check-doc-counts.js';
+import { DOC_PATH_ERROR, runDocInvocations } from './check-doc-invocations.mjs';
 import { checkLicenses } from './check-licenses.mjs';
-import { DEFAULT_CONFIG_FILE, GATE_NAMES, loadDependencyDirectionConfig, loadFieldOwnershipConfig, loadLicencesConfig, loadLockfileAgeConfig, loadPackageBoundaryConfig, } from './gate-config.js';
+import { DEFAULT_CONFIG_FILE, GATE_NAMES, loadDependencyDirectionConfig, loadDocClaimsConfig, loadDocCountsConfig, loadDocInvocationsConfig, loadFieldOwnershipConfig, loadLicencesConfig, loadLockfileAgeConfig, loadPackageBoundaryConfig, } from './gate-config.js';
 import { runFieldOwnership, TYPESCRIPT_UNAVAILABLE, } from './lineage-ownership.js';
-import { runPackageBoundary, SCAN_PATH_ERROR, SCAN_UNREADABLE, } from './package-boundary.js';
+import { MODULE_VALUE_ERROR } from './module-value.js';
+import { runPackageBoundary } from './package-boundary.js';
+import { SCAN_PATH_ERROR, SCAN_UNREADABLE } from './scanned-paths.js';
 const EXIT_OK = 0;
 /** The gate ran and found what it exists to find. */
 const EXIT_GATE_FAILED = 1;
@@ -51,6 +56,9 @@ const GATE_SUMMARY = {
     'dependency-direction': 'every import in the trees you name, against a layer graph you declare',
     'package-boundary': 'every line your package would publish, against the patterns you forbid',
     'field-ownership': 'every write to a field you own, against the modules you let write it',
+    'doc-invocations': 'every fenced command in your pages, against the exit code the page claims',
+    'doc-counts': 'every hand-written count in your pages, against the thing it counts',
+    'doc-claims': 'every prose claim in your pages, against the tree those pages describe',
 };
 /** The widest gate name, plus the two spaces that separate it from its summary. */
 const GATE_COLUMN = Math.max(...GATE_NAMES.map((gate) => gate.length)) + 2;
@@ -71,6 +79,10 @@ dependency-direction and field-ownership read your source with the TypeScript
 scanner, so those two need the optional peer dependency "typescript". Install it
 only if you run one of them; each refuses by name when it is absent.
 
+doc-counts and doc-claims read values out of modules your configuration names,
+which means importing them, which runs them. doc-invocations runs the commands
+your pages document, each inside a temporary directory it owns.
+
 Exit codes: ${EXIT_OK} the gate passed, ${EXIT_GATE_FAILED} the gate failed, ${EXIT_USAGE} a usage or configuration error.`;
 const writeOut = (line) => {
     process.stdout.write(`${line}\n`);
@@ -157,28 +169,120 @@ async function readLockfile(root, relative, configFile, gate) {
         throw new ConfigurationError(`${path} ${detail}; ${configFile}'s "${gate}" section names it under lockfiles`);
     }
 }
+/**
+ * The committed publication cache, if the section names one. A path that is not
+ * there is a configuration error rather than a silent full-fetch run: a mistyped
+ * path would read as a cache answering nothing, which is the shape that turns a
+ * gate into one that passes for the wrong reason.
+ */
+async function readCache(configFile, root, named) {
+    if (named === undefined)
+        return {};
+    const path = resolve(root, named);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        const detail = code === 'ENOENT'
+            ? 'does not exist'
+            : `could not be read: ${error instanceof Error ? error.message : String(error)}`;
+        throw new ConfigurationError(`${path} ${detail}; ${configFile}'s "lockfile-age" section names it under cache`);
+    }
+    try {
+        return readPublishCache(JSON.parse(text), path);
+    }
+    catch (error) {
+        throw new ConfigurationError(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Which (row, lockfile) pairs a run has not yet seen reach an entry. A row
+ * naming two lockfiles is held in each: a scope where it never reaches anything
+ * is a value nobody is holding, whatever it reaches in the other.
+ *
+ * The refusal comes after every lockfile has reported, and it never outranks a
+ * gate failure: a run that found a violation exits 1 and prints the stale rows
+ * as a diagnostic, because a caller branching on the code must see the finding
+ * first. The usage code is for the run that would otherwise have passed.
+ */
+class UnreachedRows {
+    pending = new Map();
+    constructor(rows) {
+        for (const row of rows)
+            this.pending.set(row, new Set(row.lockfiles));
+    }
+    reached(row, lockfile) {
+        this.pending.get(row)?.delete(lockfile);
+    }
+    /** Each stale row with the lockfiles it reached nothing in, or nothing. */
+    remaining() {
+        return [...this.pending]
+            .filter(([, lockfiles]) => lockfiles.size > 0)
+            .map(([row, lockfiles]) => ({ row, lockfiles: [...lockfiles] }));
+    }
+}
+function exitAfter(passed, stale) {
+    if (stale !== null)
+        writeDiagnostic(`\n${BINARY}: ${stale}`);
+    if (!passed)
+        return EXIT_GATE_FAILED;
+    return stale === null ? EXIT_OK : EXIT_USAGE;
+}
 async function runLockfileAge(configFile, root, section) {
+    const cache = await readCache(configFile, root, section.cache);
     const now = new Date();
     // The line `.github/actions/audit-lockfile-age/action.yml` greps for: a
     // clock-parsing bug that made every entry look permanently old would
     // otherwise be invisible.
     writeOut(`Effective clock: ${now.toISOString()}`);
+    if (section.cache !== undefined) {
+        writeOut(`lockfile-age: ${Object.keys(cache).length} publication time(s) read from ${section.cache}; only an entry absent from it is fetched.`);
+    }
     let passed = true;
+    const unreached = new UnreachedRows(section.exclude ?? []);
     for (const relative of section.lockfiles) {
         const lockfile = await readLockfile(root, relative, configFile, 'lockfile-age');
+        const exclusions = (section.exclude ?? []).filter((row) => row.lockfiles.includes(relative));
         const report = (await auditLockfileAge({
             lockfile,
             now,
             windowDays: section.windowDays,
+            exclude: exclusions.map((row) => row.name),
             source: relative,
+            cache,
         }));
+        // The exclusions are part of what the run did, on a failing run as on a
+        // passing one, so they print on both with the scanned total beside them,
+        // each with the reason its row gave.
+        const excluded = report.excludedEntries;
+        const writeExcluded = () => {
+            for (const entry of excluded) {
+                const row = exclusions.find((candidate) => candidate.name === entry.name);
+                if (row !== undefined)
+                    unreached.reached(row, relative);
+                writeOut(`  excluded: ${entry.name}@${entry.version} (${entry.path})`);
+                if (row !== undefined)
+                    writeOut(`    because: ${row.reason}`);
+            }
+        };
         if (report.youngEntries.length === 0 &&
             report.unfetchableEntries.length === 0 &&
             report.offRegistryEntries.length === 0) {
-            writeOut(`lockfile-age ${relative}: passed, ${report.entries.length} entrie(s), all published before ${report.cutoff.toISOString()}.`);
+            const cutoff = report.cutoff.toISOString();
+            const scanned = report.entries.length;
+            writeOut(excluded.length === 0
+                ? `lockfile-age ${relative}: passed, ${scanned} entrie(s), all published before ${cutoff}.`
+                : `lockfile-age ${relative}: passed, ${scanned} entrie(s), ${scanned - excluded.length} published before ${cutoff} and ${excluded.length} excluded by name.`);
+            writeExcluded();
             continue;
         }
         passed = false;
+        if (excluded.length > 0) {
+            writeOut(`lockfile-age ${relative}: ${report.entries.length} entrie(s), ${excluded.length} excluded by name.`);
+            writeExcluded();
+        }
         if (report.offRegistryEntries.length > 0) {
             writeDiagnostic(`\nlockfile-age ${relative}: failed closed, ${report.offRegistryEntries.length} entrie(s) do not resolve to the npm registry:`);
             for (const entry of report.offRegistryEntries) {
@@ -198,7 +302,12 @@ async function runLockfileAge(configFile, root, section) {
             }
         }
     }
-    return passed;
+    const stale = unreached.remaining();
+    return exitAfter(passed, stale.length === 0
+        ? null
+        : `${configFile}'s "lockfile-age" section excludes ${stale
+            .map(({ row, lockfiles }) => `"${row.name}" in ${lockfiles.join(', ')}`)
+            .join('; ')}, and no entry there carries that name; the package left the lockfile or the name is mistyped, so remove the row or narrow its lockfiles`);
 }
 /** A tolerance holds only while its marker does, so the file is read on every run. */
 async function markerHolds(root, marker) {
@@ -214,6 +323,7 @@ async function markerHolds(root, marker) {
 }
 async function runLicences(configFile, root, section) {
     let passed = true;
+    const unreached = new UnreachedRows(section.undeclared ?? []);
     for (const relative of section.lockfiles) {
         const lockfile = await readLockfile(root, relative, configFile, 'licences');
         const policy = section.policies?.[relative];
@@ -229,32 +339,57 @@ async function runLicences(configFile, root, section) {
                 continue;
             applicable.push(tolerance);
         }
+        const undeclared = (section.undeclared ?? []).filter((row) => row.lockfiles.includes(relative));
         const report = checkLicenses(lockfile, {
             allowlist,
             label,
             tolerances: applicable,
+            undeclared,
             source: relative,
         });
-        if (report.violations.length === 0) {
-            writeOut(`licences ${relative}: passed against ${label}, ${report.entryCount} entrie(s), all allowlisted.`);
-            if (policy !== undefined)
-                writeOut(`  ${label}: ${policy.reason}`);
+        for (const row of undeclared) {
+            if (!report.unusedUndeclared.includes(row.prefix)) {
+                unreached.reached(row, relative);
+            }
+        }
+        // An entry read by evidence is printed on every run that used the row,
+        // and apart from the tolerated: a tolerance widens the allowlist for a
+        // licence the entry declares, and this row supplies one the entry does not.
+        // Both print on a failing run too, since both are part of what the run did.
+        const writeExceptions = () => {
+            for (const reading of report.readByEvidence) {
+                writeOut(`  read by evidence: ${reading.entry} as ${reading.readAs}`);
+                writeOut(`    evidence: ${reading.evidence}`);
+                writeOut(`    because: ${reading.reason}`);
+            }
             if (report.tolerated.length > 0) {
                 writeOut(`  tolerated: ${report.tolerated.join(', ')}`);
                 for (const reason of report.toleranceReasons) {
                     writeOut(`  because: ${reason}`);
                 }
             }
+        };
+        if (report.violations.length === 0) {
+            writeOut(`licences ${relative}: passed against ${label}, ${report.entryCount} entrie(s), all allowlisted.`);
+            if (policy !== undefined)
+                writeOut(`  ${label}: ${policy.reason}`);
+            writeExceptions();
             continue;
         }
         passed = false;
+        writeExceptions();
         writeDiagnostic(`\nlicences ${relative}: ${report.violations.length} entrie(s) outside ${label}:`);
         for (const violation of report.violations) {
             writeDiagnostic(`  - ${violation.name}@${violation.version}: license=${JSON.stringify(violation.license)}${violation.reason ? ` (${violation.reason})` : ''}`);
             writeDiagnostic(`    dependency path: ${violation.dependencyPath}`);
         }
     }
-    return passed;
+    const stale = unreached.remaining();
+    return exitAfter(passed, stale.length === 0
+        ? null
+        : `${configFile}'s "licences" section reads ${stale
+            .map(({ row, lockfiles }) => `"${row.prefix}" in ${lockfiles.join(', ')}`)
+            .join('; ')} by evidence, and no entry there under that prefix declares no licence; the package now declares one or the prefix is mistyped, so remove the row or narrow its lockfiles`);
 }
 /** The order every violation report prints in, so two runs read the same. */
 const byFileThenLine = (violations) => [...violations].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
@@ -309,6 +444,47 @@ async function runOwnership(root, section) {
     }
     return EXIT_GATE_FAILED;
 }
+/**
+ * The three documentation gates share a report shape: a summary line that is
+ * written whatever the outcome, and a list of failures. The summary on a clean
+ * run is what stops a gate reading as green because it scanned nothing.
+ */
+function reportDocFailures(gate, failures, noun) {
+    if (failures.length === 0)
+        return EXIT_OK;
+    writeDiagnostic(`\n${gate}: ${failures.length} ${noun}:`);
+    for (const failure of failures)
+        writeDiagnostic(`  ${failure}`);
+    return EXIT_GATE_FAILED;
+}
+function runInvocations(root, section) {
+    const report = runDocInvocations(root, section);
+    writeOut(`doc-invocations: ${report.scanned} invocation(s) scanned across ${report.pages} page(s), ` +
+        `${report.judged} run faithfully over real inputs, ${report.compared} with their output compared, ` +
+        `${report.failures.length} failure(s)`);
+    if (report.failures.length === 0)
+        return EXIT_OK;
+    writeDiagnostic(`\ndoc-invocations: ${report.failures.length} failing invocation(s):`);
+    for (const failure of [...report.failures].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1)) {
+        writeDiagnostic(`  ${failure.file}:${failure.line} [${failure.reason}] ${failure.invocation}`);
+        for (const line of failure.stderr.split('\n')) {
+            if (line !== '')
+                writeDiagnostic(`    ${line}`);
+        }
+    }
+    return EXIT_GATE_FAILED;
+}
+async function runCounts(root, section) {
+    const report = await runDocCounts(root, section);
+    writeOut(`doc-counts: ${report.numerals} numeral(s) across ${report.files} file(s) held against their source, ` +
+        `plus ${report.digits} count(s) written as digits, ${report.failures.length} disagreement(s)`);
+    return reportDocFailures('doc-counts', report.failures, 'count(s) disagree with their source');
+}
+async function runClaims(root, section) {
+    const report = await runDocClaims(root, section);
+    writeOut(`doc-claims: ${report.summary}`);
+    return reportDocFailures('doc-claims', report.failures, 'prose claim(s) disagree with the tree');
+}
 async function run(invocation) {
     if (invocation.kind === 'help') {
         writeOut(USAGE);
@@ -329,15 +505,13 @@ async function run(invocation) {
             const loaded = await loadLockfileAgeConfig(options);
             if (loaded.kind === 'refused')
                 return refused(loaded.message);
-            const passed = await runLockfileAge(loaded.path, dirname(loaded.path), loaded.section);
-            return passed ? EXIT_OK : EXIT_GATE_FAILED;
+            return runLockfileAge(loaded.path, dirname(loaded.path), loaded.section);
         }
         case 'licences': {
             const loaded = await loadLicencesConfig(options);
             if (loaded.kind === 'refused')
                 return refused(loaded.message);
-            const passed = await runLicences(loaded.path, dirname(loaded.path), loaded.section);
-            return passed ? EXIT_OK : EXIT_GATE_FAILED;
+            return runLicences(loaded.path, dirname(loaded.path), loaded.section);
         }
         case 'dependency-direction': {
             const loaded = await loadDependencyDirectionConfig(options);
@@ -357,6 +531,24 @@ async function run(invocation) {
                 return refused(loaded.message);
             return runOwnership(dirname(loaded.path), loaded.section);
         }
+        case 'doc-invocations': {
+            const loaded = await loadDocInvocationsConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            return runInvocations(dirname(loaded.path), loaded.section);
+        }
+        case 'doc-counts': {
+            const loaded = await loadDocCountsConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            return runCounts(dirname(loaded.path), loaded.section);
+        }
+        case 'doc-claims': {
+            const loaded = await loadDocClaimsConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            return runClaims(dirname(loaded.path), loaded.section);
+        }
     }
     // Exhaustive over `GateName`: a gate added to `GATE_NAMES` with no arm above
     // is a type error here rather than a binary that names it in its usage text
@@ -368,11 +560,12 @@ async function run(invocation) {
  * The refusals a gate raises as a coded error rather than as a return value,
  * and the exit each takes.
  *
- * A lockfile or a path the configuration named and the tree does not have is a
- * configuration error, so it takes the usage code: the repair is in the file.
- * So is an absent optional peer dependency. A tree the scan could not read to
- * the end takes the gate's own failure code instead, because that gate ran and
- * refused rather than being misinvoked.
+ * A lockfile, a page root, a built entry point, or a module export the
+ * configuration named and the tree does not have is a configuration error, so it
+ * takes the usage code: the repair is in the file. So is an absent optional peer
+ * dependency. A tree the scan could not read to the end takes the gate's own
+ * failure code instead, because that gate ran and refused rather than being
+ * misinvoked.
  *
  * Sharing one code across the two would let "scanned nothing" and "found
  * nothing" answer a caller the same way, which is the pass these refusals exist
@@ -382,6 +575,10 @@ const CODED_EXITS = new Map([
     [LOCKFILE_SHAPE_ERROR, EXIT_USAGE],
     [SCAN_PATH_ERROR, EXIT_USAGE],
     [TYPESCRIPT_UNAVAILABLE, EXIT_USAGE],
+    [DOC_PATH_ERROR, EXIT_USAGE],
+    [DOC_CLAIM_PATH, EXIT_USAGE],
+    [DOC_COUNT_SOURCE, EXIT_USAGE],
+    [MODULE_VALUE_ERROR, EXIT_USAGE],
     [SCAN_UNREADABLE, EXIT_GATE_FAILED],
 ]);
 async function main(argv) {

package/dist/gates/lineage-ownership.js

@@ -31,40 +31,37 @@
 // 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 './package-boundary.js';
+import { discoverEntries, RelativePath, RelativePrefix, ScannedPathList, } from './scanned-paths.js';
+import { loadTypeScriptScanner, TYPESCRIPT_UNAVAILABLE, } from './typescript-scanner.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 () => {
+export { TYPESCRIPT_UNAVAILABLE };
+const importTokenScanner = (gate) => 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'),
-    ]);
+    // the loader runs first and its refusal is the one a consumer reads; the
+    // import of `token-scan.ts` follows only once the scanner is known to be there.
+    const ast = await loadTypeScriptScanner(gate);
+    const scan = await import('./token-scan.js');
     return {
         scanTokens: scan.scanTokens,
         computeLineStarts: scan.computeLineStarts,
         lineOf: scan.lineOf,
+        // `loadTypeScriptScanner` types `SyntaxKind` as a generic
+        // `Readonly<Record<string, number>>`, since its own shape check indexes
+        // it by whichever member name each of the three scanner modules reads.
+        // That check has already run and passed by the time this line executes,
+        // so every member this file reads off `Syntax` is verified present; the
+        // double cast is regaining the precise type the runtime check earned.
         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.
+ * The tokenizer, or the refusal `loadTypeScriptScanner` throws naming the
+ * dependency and the gate that needs it. `load` is injectable so a test can
+ * exercise that refusal without uninstalling anything the test runner itself
+ * needs.
  */
-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.`);
-    }
+export async function loadTokenScanner(gate, load = importTokenScanner(gate)) {
+    return load();
 }
 const Identifier = z
     .string()

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`);
+}