@cplieger/deadset-ts 1.2.0 → 2.0.0

package/dist/src/run.js

@@ -0,0 +1,249 @@
+import { ConfigError } from "./config.js";
+import { diagnosticErrors, discoverProjects, DiscoveryError, renderDiagnostic, } from "./discover.js";
+import { joinPath, resolvePath } from "./paths.js";
+import { printConfig } from "./print.js";
+import { resolve } from "./resolve.js";
+import { readScope, ScopeError, scopeForDir } from "./scope.js";
+import { diagnosticsOf, openEngine, runSession } from "./session.js";
+import { CONTRACT_VERSION } from "./version.js";
+/** The repository configuration's name at the target root. */
+const REPOSITORY_DOCUMENT = "deadset.json";
+/** The exit codes the Contract's exit-code table names. */
+const EXIT_CLEAN = 0;
+const EXIT_USAGE = 2;
+const EXIT_FAILURE = 3;
+const VERBS = [
+    "analyze",
+    "explain",
+    "print-config",
+    "print-projects",
+    "print-roots",
+    "print-retained",
+    "describe",
+    "version",
+];
+const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`;
+/**
+ * The tokens whose presence in an option's name makes that option a request to
+ * edit a source file. The set is closed, and a token is matched in any position of
+ * the name.
+ */
+const SOURCE_EDIT_TOKENS = ["fix", "edit", "delete", "rewrite"];
+/**
+ * Maps an option name to the setting it supplies, so one entry registers the
+ * option, supplies the document resolution reads, and gives the spelling the
+ * setting's provenance names.
+ *
+ * An option's name is this command's own vocabulary, chosen for how it reads on a
+ * command line, and its path is the setting of the Contract's configuration schema
+ * that option supplies. The two are mapped here and never derived from one
+ * another, so this table is the authority for both: a setting reaches the command
+ * line only by an entry, and a path names a key the schema declares.
+ */
+export const SETTING_OPTIONS = new Map([
+    ["min-confidence", "analysis.min_confidence"],
+    ["sort", "reporters.sort"],
+    ["cascade", "reporters.cascade"],
+    ["max-findings", "reporters.max_findings"],
+    ["fail-on", "reporters.fail_on"],
+]);
+/** The options that take a value and are not settings. */
+const PLAIN_OPTIONS = new Set(["target", "config", "central", "scope"]);
+/** The setting options whose value is a number rather than a string. */
+const NUMBER_OPTIONS = new Set(["max-findings"]);
+/**
+ * The first option whose name carries a source-edit token, because every verb
+ * reports and never edits. The match is on the name alone, so an option whose
+ * value carries a token is not a request.
+ */
+function sourceEditOption(args) {
+    for (const arg of args) {
+        if (!arg.startsWith("-")) {
+            continue;
+        }
+        const spelled = arg.split("=", 1)[0] ?? arg;
+        const name = spelled.replace(/^-+/u, "");
+        if (SOURCE_EDIT_TOKENS.some((token) => name.includes(token))) {
+            return spelled;
+        }
+    }
+    return undefined;
+}
+/** Reads one verb's options, refusing a name this command does not offer. */
+function readOptions(args) {
+    const named = new Map();
+    for (const arg of args) {
+        if (!arg.startsWith("-")) {
+            throw new ConfigError("malformed", "", `unexpected argument ${JSON.stringify(arg)}`);
+        }
+        const [spelled, ...rest] = arg.split("=");
+        const name = (spelled ?? "").replace(/^-+/u, "");
+        if (!PLAIN_OPTIONS.has(name) && !SETTING_OPTIONS.has(name)) {
+            throw new ConfigError("malformed", "", `unknown option ${JSON.stringify(spelled ?? arg)}`);
+        }
+        if (rest.length === 0) {
+            throw new ConfigError("malformed", "", `option ${JSON.stringify(spelled ?? arg)} takes a value`);
+        }
+        named.set(name, rest.join("="));
+    }
+    return { named };
+}
+function readFileOr(host, path, orUndefined) {
+    try {
+        return host.readFile(resolvePath(host.workingDirectory(), path));
+    }
+    catch (error) {
+        if (orUndefined) {
+            return undefined;
+        }
+        throw new ConfigError("malformed", "", `${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * The configuration documents one invocation reads: the repository configuration
+ * at the target root or the path an option named, the central configuration, and
+ * the settings the options supply as one flag document.
+ */
+function inputsOf(host, options) {
+    const target = options.named.get("target") ?? ".";
+    const named = options.named.get("config");
+    const repositoryLabel = named ?? joinPath(target, REPOSITORY_DOCUMENT);
+    const repository = readFileOr(host, repositoryLabel, named === undefined);
+    const centralLabel = options.named.get("central");
+    const central = centralLabel === undefined ? undefined : readFileOr(host, centralLabel, false);
+    const flat = {};
+    const flagLabels = new Map();
+    for (const [name, path] of SETTING_OPTIONS) {
+        const value = options.named.get(name);
+        if (value === undefined) {
+            continue;
+        }
+        flat[path] = NUMBER_OPTIONS.has(name) ? Number(value) : value;
+        flagLabels.set(path, `--${name}`);
+    }
+    const flags = Object.keys(flat).length === 0 ? undefined : JSON.stringify(flat);
+    return {
+        ...(flags === undefined ? {} : { flags }),
+        ...(repository === undefined ? {} : { repository, repositoryLabel }),
+        ...(central === undefined || centralLabel === undefined ? {} : { central, centralLabel }),
+        flagLabels,
+    };
+}
+/** The scope one invocation analyzes: the document an option named, or the target. */
+function scopeOf(host, options) {
+    const document = options.named.get("scope");
+    if (document !== undefined) {
+        return readScope(host, document);
+    }
+    return scopeForDir(host, options.named.get("target") ?? ".");
+}
+/**
+ * Runs the deadset-ts command line over `args` (the arguments after the program
+ * name) and returns the process exit code: 0 for a completed verb, 2 for a usage
+ * error or a configuration this analyzer refuses, 3 for a failure that produced no
+ * answer. It writes nothing outside `out` and `err` and never exits the process,
+ * so a caller decides what the code means.
+ *
+ * An option asking for a source edit is refused before the verb is read: this
+ * analyzer reports and never edits a source file.
+ *
+ * `host` is the platform the run reads, the version it reports included;
+ * `openClient` opens the compiler client a verb that reads projects needs.
+ * Both are parameters because both are the platform, which no module below this one
+ * names: the command entry binds them, and a caller that wants to watch what a run
+ * reads supplies its own.
+ */
+export function run(args, out, err, host, openClient = (collectTiming) => openEngine({ collectTiming })) {
+    const editing = sourceEditOption(args);
+    if (editing !== undefined) {
+        err.write(`deadset-ts: ${editing} is not supported: deadset-ts reports and never edits a source file\n`);
+        err.write(USAGE);
+        return EXIT_USAGE;
+    }
+    const verb = args[0];
+    if (verb === "version") {
+        out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
+        return EXIT_CLEAN;
+    }
+    if (verb === "print-config") {
+        return printConfigVerb(args.slice(1), out, err, host);
+    }
+    if (verb === "print-projects") {
+        return printProjectsVerb(args.slice(1), out, err, host, openClient);
+    }
+    if (verb !== undefined && VERBS.includes(verb)) {
+        err.write(`deadset-ts: ${verb} is not implemented\n`);
+        return EXIT_USAGE;
+    }
+    if (verb !== undefined) {
+        err.write(`deadset-ts: unknown verb ${JSON.stringify(verb)}\n`);
+    }
+    err.write(USAGE);
+    return EXIT_USAGE;
+}
+/** Writes the resolved configuration with the source of every setting. */
+function printConfigVerb(args, out, err, host) {
+    try {
+        const options = readOptions(args);
+        const { config, provenance } = resolve(inputsOf(host, options));
+        out.write(printConfig(config, provenance));
+        return EXIT_CLEAN;
+    }
+    catch (error) {
+        return refuse(error, err);
+    }
+}
+/**
+ * Writes the compiler configuration of every project one run analyzes, one per
+ * line, in discovery order, having read each project's diagnostics first.
+ */
+function printProjectsVerb(args, out, err, host, openClient) {
+    let engine;
+    try {
+        const options = readOptions(args);
+        const scope = scopeOf(host, options);
+        engine = openClient(false);
+        const discovered = discoverProjects(engine, host, scope);
+        const failures = [];
+        const { projects } = runSession(engine, discovered.configFiles, (project) => {
+            const errors = diagnosticErrors(diagnosticsOf(project));
+            failures.push(...errors.map(renderDiagnostic));
+            return project.configFile;
+        });
+        if (failures.length > 0) {
+            for (const line of failures) {
+                err.write(`${line}\n`);
+            }
+            err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
+            return EXIT_FAILURE;
+        }
+        for (const configFile of projects) {
+            out.write(`${configFile}\n`);
+        }
+        return EXIT_CLEAN;
+    }
+    catch (error) {
+        engine?.close();
+        return refuse(error, err);
+    }
+}
+/** Turns one refusal into the exit code the Contract's table gives it. */
+function refuse(error, err) {
+    if (error instanceof ConfigError) {
+        err.write(`deadset-ts: ${error.message}\n`);
+        err.write(USAGE);
+        return EXIT_USAGE;
+    }
+    if (error instanceof DiscoveryError) {
+        for (const diagnostic of error.diagnostics) {
+            err.write(`${renderDiagnostic(diagnostic)}\n`);
+        }
+        err.write(`deadset-ts: ${error.message}\n`);
+        return EXIT_FAILURE;
+    }
+    if (error instanceof ScopeError) {
+        err.write(`deadset-ts: ${error.message}\n`);
+        return EXIT_FAILURE;
+    }
+    throw error;
+}

package/dist/src/schema.js

@@ -0,0 +1,335 @@
+import { ConfigError } from "./config.js";
+const leaf = { kind: "leaf" };
+/**
+ * The closed key list the Contract's configuration schema declares, derived from
+ * that schema key by key. A test pins the two equal, so a Contract change that
+ * adds a key fails there rather than being silently unimplemented.
+ */
+export const SCHEMA_ROOT = {
+    kind: "section",
+    members: {
+        contract_version: leaf,
+        target: { kind: "section", members: { kind: leaf } },
+        analysis: {
+            kind: "section",
+            members: {
+                languages: leaf,
+                min_confidence: leaf,
+                generated_files: leaf,
+                consumer_tests: leaf,
+                configurations: {
+                    kind: "list",
+                    members: { id: leaf, os: leaf, arch: leaf, tags: leaf },
+                },
+                matrix: { kind: "section", members: { complete: leaf } },
+                template_dirs: leaf,
+                template_delimiters: {
+                    kind: "object",
+                    members: { left: leaf, right: leaf },
+                },
+            },
+        },
+        consumers: { kind: "section", members: { complete: leaf } },
+        roots: { kind: "section", members: { patterns: leaf } },
+        severity: { kind: "map" },
+        exemptions: { kind: "section", members: { disabled: leaf } },
+        reporters: {
+            kind: "section",
+            members: {
+                formats: leaf,
+                sort: leaf,
+                cascade: leaf,
+                max_findings: leaf,
+                fail_on: leaf,
+            },
+        },
+        go: { kind: "section", members: {} },
+        ts: { kind: "section", members: { test_files: leaf, entry_files: leaf } },
+        provenance: { kind: "map" },
+    },
+};
+/** The name of the severity object, whose member names the key list leaves open. */
+export const SEVERITY_SECTION = "severity";
+/**
+ * The node one member name resolves to, and whether the key list declares it. A
+ * member of an open object, and any member below a setting, resolves to a leaf,
+ * so the walk descends far enough to find a repeated member at any depth.
+ */
+function memberOf(node, name) {
+    if (node.kind === "section" || node.kind === "list" || node.kind === "object") {
+        const members = node.members ?? {};
+        return Object.hasOwn(members, name) ? members[name] : undefined;
+    }
+    return leaf;
+}
+function joinKey(at, name) {
+    return at === "" ? name : `${at}.${name}`;
+}
+function collect(node, at, keys, settingsOnly) {
+    for (const [name, child] of Object.entries(node.members ?? {})) {
+        const path = joinKey(at, name);
+        if (!settingsOnly) {
+            keys.push(path);
+            collect(child, child.kind === "list" ? `${path}[]` : path, keys, settingsOnly);
+            continue;
+        }
+        if (child.kind === "leaf" || child.kind === "list" || child.kind === "object") {
+            keys.push(path);
+            continue;
+        }
+        collect(child, path, keys, settingsOnly);
+    }
+}
+/**
+ * Every key the closed key list declares, as a dotted path, in ascending order:
+ * the sections, the settings, and the two open objects. A list's entry members
+ * are spelled under the list's own path followed by empty brackets.
+ */
+export function declaredKeys() {
+    const keys = [];
+    collect(SCHEMA_ROOT, "", keys, false);
+    return keys.sort();
+}
+/**
+ * The dotted path of every setting that holds one value, in ascending order. A
+ * list and a setting written as an object are each one setting, their members not
+ * addressable on their own, and the severity object is not among them: it
+ * resolves per code.
+ */
+export function settingPaths() {
+    const paths = [];
+    collect(SCHEMA_ROOT, "", paths, true);
+    return paths.sort();
+}
+/**
+ * Whether one dotted path names a setting a source may supply: a setting of the
+ * closed key list, or one code of the severity object, whose member names the key
+ * list leaves open. It is the predicate the command maps its own flag names
+ * through, so a flag that would be refused as an unimplemented key is a failing
+ * test rather than a flag nothing reads.
+ *
+ * A section holds no value of its own, so `analysis` is false. A setting written
+ * as an object is supplied whole, so `analysis.template_delimiters` is true and
+ * `analysis.template_delimiters.left` is false. A severity code is a declared
+ * setting whatever it names, so `severity.DS9999` is true here and refused by
+ * resolution: this answers the shape of a path, and resolution answers the
+ * vocabulary.
+ */
+export function declaresSetting(path) {
+    if (settingPaths().includes(path)) {
+        return true;
+    }
+    const dot = path.indexOf(".");
+    if (dot < 0) {
+        return false;
+    }
+    const code = path.slice(dot + 1);
+    return path.slice(0, dot) === SEVERITY_SECTION && code !== "" && !code.includes(".");
+}
+/** The Levenshtein distance between two strings, counted in code points. */
+function editDistance(a, b) {
+    const from = Array.from(a);
+    const to = Array.from(b);
+    let previous = Array.from({ length: to.length + 1 }, (_unused, index) => index);
+    let current = new Array(to.length + 1).fill(0);
+    for (let i = 1; i <= from.length; i += 1) {
+        current[0] = i;
+        for (let j = 1; j <= to.length; j += 1) {
+            const substitution = (previous[j - 1] ?? 0) + (from[i - 1] === to[j - 1] ? 0 : 1);
+            current[j] = Math.min(substitution, (previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1);
+        }
+        [previous, current] = [current, previous];
+    }
+    return previous[to.length] ?? 0;
+}
+function sharedSegments(a, b) {
+    let shared = 0;
+    while (shared < a.length && shared < b.length && a[shared] === b[shared]) {
+        shared += 1;
+    }
+    return shared;
+}
+/**
+ * The implemented key closest to `key`: the one sharing the most leading dotted
+ * segments, and among those the smallest edit distance over the whole path, ties
+ * broken in ascending order.
+ */
+export function nearestKey(key) {
+    const segments = key.split(".");
+    let nearest = "";
+    let bestShared = -1;
+    let bestDistance = 0;
+    for (const candidate of declaredKeys()) {
+        const shared = sharedSegments(segments, candidate.split("."));
+        const distance = editDistance(key, candidate);
+        if (shared < bestShared || (shared === bestShared && distance >= bestDistance)) {
+            continue;
+        }
+        nearest = candidate;
+        bestShared = shared;
+        bestDistance = distance;
+    }
+    return nearest;
+}
+/** A refusal of a document that is not one instance of the closed key list. */
+export function malformed(label, path, detail) {
+    const message = path === "" ? `${label}: ${detail}` : `${label}: ${path}: ${detail}`;
+    return new ConfigError("malformed", path, message);
+}
+/**
+ * A refusal of a key the closed key list does not declare, naming the nearest key
+ * it does.
+ */
+export function unimplementedKey(label, path) {
+    const nearest = nearestKey(path);
+    let hint = "";
+    if (nearest === path) {
+        hint = `; ${JSON.stringify(path)} is one setting written as nested objects, not as one key`;
+    }
+    else if (nearest !== "") {
+        hint = `; the nearest implemented key is ${JSON.stringify(nearest)}`;
+    }
+    return new ConfigError("unimplemented-key", path, `${label}: key ${JSON.stringify(path)} is not implemented${hint}`);
+}
+const SPACE = new Set([0x20, 0x09, 0x0a, 0x0d]);
+function skipSpace(cursor) {
+    while (cursor.at < cursor.text.length && SPACE.has(cursor.text.charCodeAt(cursor.at))) {
+        cursor.at += 1;
+    }
+}
+/**
+ * The string literal at the cursor, decoded by the standard library: the walk
+ * finds the literal's extent and the parse reads it, so an escaped member name
+ * compares equal to the name it spells.
+ */
+function readName(cursor, at, label) {
+    const start = cursor.at;
+    cursor.at += 1;
+    while (cursor.at < cursor.text.length) {
+        const ch = cursor.text.charCodeAt(cursor.at);
+        if (ch === 0x5c) {
+            cursor.at += 2;
+            continue;
+        }
+        cursor.at += 1;
+        if (ch === 0x22) {
+            return JSON.parse(cursor.text.slice(start, cursor.at));
+        }
+    }
+    throw malformed(label, at, "a member name is not terminated");
+}
+function skipScalar(cursor) {
+    while (cursor.at < cursor.text.length) {
+        const ch = cursor.text.charCodeAt(cursor.at);
+        if (ch === 0x2c || ch === 0x7d || ch === 0x5d || SPACE.has(ch)) {
+            return;
+        }
+        cursor.at += 1;
+    }
+}
+function walkValue(cursor, at, node, label) {
+    skipSpace(cursor);
+    const ch = cursor.text.charCodeAt(cursor.at);
+    if (ch === 0x7b) {
+        cursor.at += 1;
+        walkObject(cursor, at, node, label);
+        return;
+    }
+    if (ch === 0x5b) {
+        cursor.at += 1;
+        walkArray(cursor, at, node, label);
+        return;
+    }
+    if (ch === 0x22) {
+        readName(cursor, at, label);
+        return;
+    }
+    skipScalar(cursor);
+}
+function walkObject(cursor, at, node, label) {
+    const seen = new Set();
+    for (;;) {
+        skipSpace(cursor);
+        const ch = cursor.text.charCodeAt(cursor.at);
+        if (ch === 0x7d) {
+            cursor.at += 1;
+            return;
+        }
+        if (ch === 0x2c) {
+            cursor.at += 1;
+            continue;
+        }
+        if (ch !== 0x22) {
+            throw malformed(label, at, "a member name is expected");
+        }
+        const name = readName(cursor, at, label);
+        const path = joinKey(at, name);
+        if (seen.has(name)) {
+            throw malformed(label, path, `member ${JSON.stringify(name)} is written twice, so neither value is chosen`);
+        }
+        seen.add(name);
+        const child = memberOf(node, name);
+        if (child === undefined) {
+            throw unimplementedKey(label, path);
+        }
+        skipSpace(cursor);
+        if (cursor.text.charCodeAt(cursor.at) !== 0x3a) {
+            throw malformed(label, path, "a member name is followed by a colon");
+        }
+        cursor.at += 1;
+        walkValue(cursor, path, child, label);
+    }
+}
+function walkArray(cursor, at, node, label) {
+    const entry = node.kind === "list" ? { kind: "section", members: node.members ?? {} } : leaf;
+    let index = 0;
+    for (;;) {
+        skipSpace(cursor);
+        const ch = cursor.text.charCodeAt(cursor.at);
+        if (ch === 0x5d) {
+            cursor.at += 1;
+            return;
+        }
+        if (ch === 0x2c) {
+            cursor.at += 1;
+            continue;
+        }
+        walkValue(cursor, `${at}[${index}]`, entry, label);
+        index += 1;
+    }
+}
+/**
+ * Walks one document's text against the closed key list, refusing a member the
+ * key list does not declare and a member one object writes twice, each naming its
+ * dotted path. The document is already known to parse.
+ */
+export function checkDocument(text, node, label) {
+    const cursor = { text, at: 0 };
+    walkValue(cursor, "", node, label);
+}
+/**
+ * The flag document, whose keys are dotted setting paths, rewritten as the nested
+ * object the closed key list declares, so one decoder reads every source. A key
+ * naming no setting is refused.
+ */
+export function nestFlags(flat, label) {
+    const nested = {};
+    for (const path of Object.keys(flat).sort()) {
+        if (!declaresSetting(path)) {
+            throw unimplementedKey(label, path);
+        }
+        const segments = path.split(".");
+        let into = nested;
+        for (const segment of segments.slice(0, -1)) {
+            const child = into[segment] ?? {};
+            if (typeof child !== "object" || Array.isArray(child)) {
+                throw malformed(label, path, `the flag document sets ${JSON.stringify(segment)} twice`);
+            }
+            into[segment] = child;
+            into = child;
+        }
+        const last = segments[segments.length - 1] ?? "";
+        into[last] = flat[path];
+    }
+    return nested;
+}

package/dist/src/scope.js

@@ -0,0 +1,116 @@
+import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.js";
+/** The roles a scope document declares for a module. */
+export const ROLE_TARGET = "target";
+export const ROLE_CONSUMER = "consumer";
+/**
+ * A scope document above this length is refused rather than decoded. It names one
+ * target and its consumers, so a larger file is not one.
+ */
+const MAX_DOCUMENT_LENGTH = 1 << 20;
+/**
+ * A scope document that cannot be read as one. It ends the run with the failure
+ * code: the run could not learn what to analyze, so it produced no answer.
+ */
+export class ScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScopeError";
+    }
+}
+const DECLARED_KEYS = new Set(["target", "workspace", "consumers"]);
+const MODULE_KEYS = new Set(["id", "role", "path"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringMember(parent, name, at) {
+    if (!Object.hasOwn(parent, name)) {
+        return "";
+    }
+    const value = parent[name];
+    if (typeof value !== "string") {
+        throw new ScopeError(`scope: ${at}.${name} is not a string`);
+    }
+    return value;
+}
+function readModule(value, at, role, documentDir) {
+    if (!isRecord(value)) {
+        throw new ScopeError(`scope: ${at} is not an object`);
+    }
+    for (const name of Object.keys(value)) {
+        if (!MODULE_KEYS.has(name)) {
+            throw new ScopeError(`scope: ${at}.${name} is not a declared key`);
+        }
+    }
+    const declared = stringMember(value, "role", at);
+    if (declared !== "" && declared !== role) {
+        throw new ScopeError(`scope: ${at}.role is ${JSON.stringify(declared)}, want ${JSON.stringify(role)}`);
+    }
+    const path = stringMember(value, "path", at);
+    if (path === "") {
+        throw new ScopeError(`scope: ${at}.path names nothing`);
+    }
+    return {
+        id: stringMember(value, "id", at),
+        path: isAbsolutePath(path) ? path : joinPath(documentDir, path),
+    };
+}
+/**
+ * Decodes the scope document at `file`. Decoding is strict: an undeclared key is an
+ * error, and a relative path inside the document resolves against the document's
+ * own directory.
+ *
+ * The `workspace` key the format declares is read and carries nothing here: it
+ * names the file a Go consumer resolves the target through, and a TypeScript
+ * project resolves one through its own compiler configuration.
+ */
+export function readScope(host, file) {
+    const absolute = resolvePath(host.workingDirectory(), file);
+    let text;
+    try {
+        text = host.readFile(absolute);
+    }
+    catch (error) {
+        throw new ScopeError(`scope: ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (text.length > MAX_DOCUMENT_LENGTH) {
+        throw new ScopeError(`scope: ${file} is longer than ${String(MAX_DOCUMENT_LENGTH)} characters`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ScopeError(`scope: ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(value)) {
+        throw new ScopeError(`scope: ${file} is not one JSON object`);
+    }
+    for (const name of Object.keys(value)) {
+        if (!DECLARED_KEYS.has(name)) {
+            throw new ScopeError(`scope: ${file}: ${name} is not a declared key`);
+        }
+    }
+    const documentDir = dirnamePath(absolute);
+    if (!Object.hasOwn(value, "target")) {
+        throw new ScopeError(`scope: ${file} names no target`);
+    }
+    const target = readModule(value["target"], "target", ROLE_TARGET, documentDir);
+    const listed = Object.hasOwn(value, "consumers") ? value["consumers"] : [];
+    if (!Array.isArray(listed)) {
+        throw new ScopeError(`scope: ${file}: consumers is not an array`);
+    }
+    const consumers = listed.map((entry, index) => readModule(entry, `consumers[${String(index)}]`, ROLE_CONSUMER, documentDir));
+    return { target, consumers };
+}
+/** The single-package scope one directory is, when no scope document is given. */
+export function scopeForDir(host, dir) {
+    const path = resolvePath(host.workingDirectory(), dir);
+    const kind = host.kindOf(path);
+    if (kind === "absent") {
+        throw new ScopeError(`scope: ${path} does not exist`);
+    }
+    if (kind !== "directory") {
+        throw new ScopeError(`scope: ${path} is not a directory`);
+    }
+    return { target: { id: "", path }, consumers: [] };
+}