@cplieger/deadset-ts 8.0.0-dev.7 → 8.0.0-dev.8

package/dist/src/edges.js

@@ -4,144 +4,68 @@
  * never resolves the paired symbol: the other language's analyzer decides whether the
  * pairing is a use, and the merge reads the two evaluations together.
  */
-import { ConfigError } from "./config.js";
-import { isRecord, positionAt, walkDocument } from "./json-document.js";
-import { joinPath } from "./paths.js";
+import { EDGES_SCHEMA } from "./contract/config.generated.js";
+import { readTargetDocument } from "./fs/document.js";
+import { dotted, placeIn, positionAt, readStrict, StrictJSONError } from "./json-document.js";
 import { positionKey } from "./position.js";
+import { firstRefusal } from "./schema.js";
 import { isPartSubject } from "./suppress.js";
 import { bytewise } from "./text/compare.js";
-import { message } from "./product.js";
+import { UsageError } from "./usage.js";
 /** The name and the location the Contract fixes for the edges document. */
 export const EDGES_FILE = "deadset-edges.json";
 /** The language prefix of every reference this analyzer evaluates. */
 const OWN_PREFIX = "ts://";
-/** The closed key list of the document and of one edge. */
-const DOCUMENT_KEYS = new Set(["description", "edges"]);
-const EDGE_KEYS = new Set(["id", "because", "provides", "used_by"]);
-/** An edge identifier: solidus-separated segments of ASCII letters, digits, `_`, `.` and `-`. */
-const ID_FORM = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/u;
-/** A reference naming one symbol of some language: `<language>://<scope>#<fragment>`. */
-const REFERENCE_FORM = /^[a-z][a-z0-9]*:\/\/[^ \t\r\n#]+#[^ \t\r\n]*$/u;
-const DOCUMENT_WANT = "an object carrying the edges array, and an optional description";
-const EDGE_WANT = "an edge naming id, provides and used_by, each a string, and an optional because";
-const ID_WANT = "one or more solidus-separated segments of ASCII letters, digits, underscore, full stop and hyphen";
-const REFERENCE_WANT = "a stable symbol reference naming one symbol exactly, <language>://<scope>#<fragment>";
 /** An edges document the Contract refuses: a malformed input, answered with the usage code. */
-class EdgesError extends ConfigError {
-    constructor(at, text, want) {
-        super("malformed", EDGES_FILE, `${at}: ${text}: want ${want}`);
+class EdgesError extends UsageError {
+    constructor(at, reason) {
+        super(`${at}: ${reason}`);
         this.name = "EdgesError";
     }
 }
-/**
- * Whether a reference carries a wildcard outside a quoted or a computed component, which
- * would name a set of symbols rather than one.
- */
-function carriesWildcard(ref) {
-    let quoted = false;
-    let computed = false;
-    let escaped = false;
-    for (const char of ref) {
-        if (escaped) {
-            escaped = false;
-        }
-        else if (quoted && char === "\\") {
-            escaped = true;
-        }
-        else if (quoted) {
-            quoted = char !== "'";
-        }
-        else if (computed) {
-            computed = char !== "]";
-        }
-        else if (char === "'") {
-            quoted = true;
-        }
-        else if (char === "[") {
-            computed = true;
-        }
-        else if (char === "*") {
-            return true;
-        }
-    }
-    return false;
-}
-/** One edge, checked: the closed key list, the value types and the value forms. */
-function readEdge(value, at) {
-    const refuse = (text, want) => {
-        throw new EdgesError(at, text, want);
-    };
-    if (!isRecord(value)) {
-        return refuse(JSON.stringify(value), EDGE_WANT);
-    }
-    for (const [key, held] of Object.entries(value)) {
-        if (!EDGE_KEYS.has(key) || typeof held !== "string") {
-            refuse(`the member ${JSON.stringify(key)} holding ${JSON.stringify(held)}`, EDGE_WANT);
-        }
-    }
-    const edge = value;
-    const id = edge["id"] ?? refuse("an edge naming no id", EDGE_WANT);
-    const provides = edge["provides"] ?? refuse("an edge naming no provides side", EDGE_WANT);
-    const usedBy = edge["used_by"] ?? refuse("an edge naming no used_by side", EDGE_WANT);
-    if (!ID_FORM.test(id)) {
-        refuse(JSON.stringify(id), ID_WANT);
-    }
-    for (const ref of [provides, usedBy]) {
-        if (!REFERENCE_FORM.test(ref) || carriesWildcard(ref)) {
-            refuse(JSON.stringify(ref), REFERENCE_WANT);
-        }
-    }
-    return { id, provides, usedBy };
-}
+/** The sides of one edge, in the order a reader yields them. */
+const SIDE_NAMES = ["provides", "used_by"];
 /**
  * Every side of a declared edge that names a symbol of this language, in document order,
  * `provides` before `used_by` within an edge. An absent document declares no edge. The
- * document is strict JSON with a closed key list at both levels, and a defect in it is an
- * {@link EdgesError}.
+ * document is strict JSON held to the Contract's edges schema, and a defect in it is an
+ * {@link EdgesError} at the line and column of the edge it is in, where it is in one.
  */
 export function readEdgeSides(host, targetRoot) {
-    const file = joinPath(targetRoot, EDGES_FILE);
-    if (host.kindOf(file) === "absent") {
+    const text = readTargetDocument(host, targetRoot, EDGES_FILE);
+    if (text === undefined) {
         return [];
     }
-    const text = host.readFile(file);
-    let parsed;
+    let read;
     try {
-        parsed = JSON.parse(text);
+        read = readStrict(text, "edges");
     }
     catch (error) {
-        throw new EdgesError(EDGES_FILE, message(error), DOCUMENT_WANT);
-    }
-    if (!isRecord(parsed)) {
-        throw new EdgesError(EDGES_FILE, JSON.stringify(parsed), DOCUMENT_WANT);
-    }
-    const walk = walkDocument(text, "edges");
-    if (walk.twice !== undefined) {
-        throw new EdgesError(positionKey(positionAt(text, EDGES_FILE, walk.twice.offset)), `the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`, DOCUMENT_WANT);
+        if (!(error instanceof StrictJSONError)) {
+            throw error;
+        }
+        throw new EdgesError(positionKey(positionAt(text, EDGES_FILE, error.offset)), error.message);
     }
-    const unknown = Object.keys(parsed).find((key) => !DOCUMENT_KEYS.has(key));
-    const description = parsed["description"];
-    const edges = parsed["edges"];
-    if (unknown !== undefined ||
-        (description !== undefined && typeof description !== "string") ||
-        !Array.isArray(edges)) {
-        throw new EdgesError(EDGES_FILE, unknown === undefined ? EDGES_FILE : `the member ${JSON.stringify(unknown)}`, DOCUMENT_WANT);
+    const value = read.value;
+    const refused = firstRefusal(EDGES_SCHEMA, value);
+    if (refused !== undefined) {
+        const place = placeIn(value, refused.pointer, refused.member);
+        const offset = place.length > 1 ? read.starts.get(place[1] ?? "") : undefined;
+        const at = offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
+        const where = dotted(place);
+        throw new EdgesError(at, where === "" ? refused.reason : `${where}: ${refused.reason}`);
     }
+    const edges = value.edges;
     const sides = [];
-    edges.forEach((value, index) => {
-        const offset = walk.starts[index];
-        const at = offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
-        const edge = readEdge(value, at);
-        const named = [
-            ["provides", edge.provides],
-            ["used_by", edge.usedBy],
-        ];
-        for (const [side, symbol] of named) {
-            if (symbol.startsWith(OWN_PREFIX)) {
-                sides.push({ edge: edge.id, side, symbol });
+    for (const id of read.starts.keys()) {
+        const edge = String(id);
+        for (const side of SIDE_NAMES) {
+            const symbol = edges[edge]?.[side];
+            if (symbol?.startsWith(OWN_PREFIX) === true) {
+                sides.push({ edge, side, symbol });
             }
         }
-    });
+    }
     return sides;
 }
 /**

package/dist/src/exempt-classes.js

@@ -11,5 +11,3 @@ const VISIBILITY = new Map(TS_ROWS.map((row) => [row.class, row.typescriptVisibi
 export function typescriptVisibilityOf(exemptionClass) {
     return VISIBILITY.get(exemptionClass) ?? { private: false, privateName: false };
 }
-/** Every class of the vocabulary, whichever language it runs on, in the vocabulary's order. */
-export const EXEMPTION_CLASS_NAMES = EXEMPTION_CLASSES.map((row) => row.class);

package/dist/src/exempt.js

@@ -17,7 +17,7 @@ import { bytewise } from "./text/compare.js";
  * only switches nothing off here, so one configuration serves every analyzer.
  */
 export function disabledClasses(config) {
-    return new Set(config.exemptionsDisabled);
+    return new Set(config.exemptions.disabled);
 }
 /**
  * Whether a class whose row states `allowed` may retain a member of one visibility. A

package/dist/src/findings/completion.js

@@ -41,8 +41,9 @@ function everyDeclaredLoaded(boundary) {
  * naming its family, else the code's default.
  */
 function severityOf(input, code, fallback) {
-    const { config } = input;
-    return (config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback);
+    const { severity } = input.config;
+    const key = [code, code.slice(0, FAMILY_KEY_LENGTH)].find((one) => Object.hasOwn(severity, one));
+    return key === undefined ? fallback : (severity[key] ?? fallback);
 }
 /**
  * The declarations the roots name as a library's published API, each public member of a
@@ -165,7 +166,7 @@ function testUsedSubjects(input) {
 function rootsCeiling(input, finding, candidate, configurations) {
     const unreachable = candidate?.relation === "reachability" || finding.unreachableOnly === true;
     const unseen = new Set((input.files.unseenLoads ?? []).map((load) => load.configuration));
-    const complete = input.config.ts.rootsComplete && !configurations.some((one) => unseen.has(one));
+    const complete = input.config.ts.roots_complete && !configurations.some((one) => unseen.has(one));
     return unreachable && !complete ? "probable" : "certain";
 }
 /**
@@ -460,7 +461,7 @@ function dialed(finding, minConfidence) {
  * root withholds itself alone.
  */
 export function dialsOf(input, findings) {
-    const minConfidence = input.config.analysis.minConfidence;
+    const minConfidence = input.config.analysis.min_confidence;
     const components = new Set(findings
         .filter((finding) => finding.component.root &&
         dialed({ ...finding, confidence: componentConfidenceOf(finding) }, minConfidence))

package/dist/src/findings/emitters.js

@@ -86,7 +86,7 @@ function atPossible(input) {
     const { config } = input;
     return {
         ...input,
-        config: { ...config, analysis: { ...config.analysis, minConfidence: "possible" } },
+        config: { ...config, analysis: { ...config.analysis, min_confidence: "possible" } },
     };
 }
 /**

package/dist/src/findings/intra-function.js

@@ -98,7 +98,7 @@ export const intraFunction = (input) => {
         return symbol === undefined ? [] : [symbol.id];
     }));
     const { declared, loaded } = input.boundary.consumers;
-    const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+    const closed = input.config.consumers.complete && declared.every((id) => loaded.includes(id));
     const published = (id) => {
         const symbol = byId.get(id);
         return (symbol !== undefined &&

package/dist/src/findings/non-code-artifacts.js

@@ -10,8 +10,8 @@ const FILE_START = 1;
  * derived matrix is never complete.
  */
 function completeMatrix(config) {
-    return (config.analysis.matrixComplete &&
-        config.analysis.configurations.some((entry) => entry.shape === "project"));
+    return (config.analysis.matrix.complete &&
+        config.analysis.configurations.some((entry) => "project" in entry));
 }
 /** One finding about a whole file. */
 function fileFinding(code, file, message) {

package/dist/src/findings/unused-declarations.js

@@ -178,7 +178,7 @@ export const unusedDeclarations = (input) => [
  * remove unless the run includes generated files.
  */
 function unusedImports(input) {
-    const generated = input.config.analysis.generatedFiles === "include" ? undefined : input.files.generated;
+    const generated = input.config.analysis.generated_files === "include" ? undefined : input.files.generated;
     return input.intraFunction.imports.flatMap((binding) => binding.used || generated?.has(binding.position.path) === true
         ? []
         : [

package/dist/src/findings/visibility-narrowing.js

@@ -193,10 +193,10 @@ function unreachable(facts, at, symbol, candidate, input) {
 export function narrowings(input) {
     const facts = factsOf(input.swept.matrix.union);
     const { declared, loaded } = input.boundary.consumers;
-    const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+    const closed = input.config.consumers.complete && declared.every((id) => loaded.includes(id));
     const world = { closed, writeOnly: writeOnlyDeclarations(input) };
     const candidates = new Map(input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
-    const generated = input.config.analysis.generatedFiles === "include" ? undefined : input.files.generated;
+    const generated = input.config.analysis.generated_files === "include" ? undefined : input.files.generated;
     const findings = [];
     facts.graph.symbols.forEach((symbol, at) => {
         if (generated?.has(symbol.position.path) === true) {

package/dist/src/findings-pass.js

@@ -66,7 +66,7 @@ export function verdictOf(result, config) {
     if (result.totals.staleSuppressions > 0) {
         return EXIT_FINDINGS;
     }
-    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.failOn));
+    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.fail_on));
     return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 /**

package/dist/src/framework-lifecycle.js

@@ -16,8 +16,8 @@ import { must } from "./query.js";
 /** Every contract's components and bases, resolved in one pass over the entries. */
 function resolveContracts(project, held, contracts) {
     const entries = contracts.flatMap((contract) => [
-        ...contract.components,
-        ...contract.bases,
+        ...(contract.components ?? []),
+        ...(contract.bases ?? []),
     ]);
     const resolved = resolveEntries(project, held, entries);
     let next = 0;
@@ -28,8 +28,8 @@ function resolveContracts(project, held, contracts) {
     };
     return contracts.map((contract) => ({
         contract,
-        components: take(contract.components.length),
-        bases: take(contract.bases.length),
+        components: take(contract.components?.length ?? 0),
+        bases: take(contract.bases?.length ?? 0),
     }));
 }
 /** The classes a decorator or a call the contracts' components name makes a component. */
@@ -160,11 +160,11 @@ function byBases(project, held, chains, contracts) {
  */
 export function frameworkLifecycle(input) {
     const { project, held, targetRoot } = input;
-    if (input.ts.lifecycleContracts.length === 0) {
+    if (input.ts.lifecycle_contracts.length === 0) {
         return [];
     }
     const chains = aliasChains(project, held);
-    const contracts = resolveContracts(project, held, input.ts.lifecycleContracts);
+    const contracts = resolveContracts(project, held, input.ts.lifecycle_contracts);
     const components = [
         ...byComponents(project, held, chains, contracts),
         ...byBases(project, held, chains, contracts),
@@ -173,7 +173,7 @@ export function frameworkLifecycle(input) {
         return [];
     }
     const ids = new Set(components.map((one) => one.id));
-    const sides = input.ts.lifecycleContracts.some((contract) => contract.members.some((name) => name.endsWith(":static")))
+    const sides = input.ts.lifecycle_contracts.some((contract) => contract.members.some((name) => name.endsWith(":static")))
         ? ["instance", "static"]
         : ["instance"];
     const members = sides.map((side) => classMembers(project, held, ids, side));

package/dist/src/fs/document.js

@@ -0,0 +1,59 @@
+/**
+ * The one read of a document the target holds at its root, which a checkout under analysis
+ * controls: the repository configuration, the ignore file, the baseline and the edges
+ * document. The read stays inside the target root, takes a regular file alone, and holds no
+ * more of it than the Contract's document bound.
+ */
+import { CONFIG_MAX_BYTES } from "../contract/config.generated.js";
+import { joinPath, relativePath } from "../paths.js";
+import { message } from "../product.js";
+import { utf8Bytes } from "../reporters/sha256.js";
+import { UsageError } from "../usage.js";
+/**
+ * A document at the target root that is not one to read: its name resolves outside the
+ * target root or to anything but a regular file, or the read fails. Nothing is read from
+ * it, and the run ends with the failure code.
+ */
+export class TargetDocumentError extends Error {
+    constructor(label, reason) {
+        super(`${label}: ${reason}`);
+        this.name = "TargetDocumentError";
+    }
+}
+/** Refuses a document past the Contract's bound with the usage code, naming it `label`. */
+export function refuseOverBound(label, text) {
+    if (utf8Bytes(text).length > CONFIG_MAX_BYTES) {
+        throw new UsageError(`${label}: holds more than ${String(CONFIG_MAX_BYTES)} bytes`);
+    }
+}
+/** What `read` returns, or its throw as the document's {@link TargetDocumentError}. */
+function attempt(label, read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        throw new TargetDocumentError(label, message(error));
+    }
+}
+/**
+ * The text of the document `name` at the absolute `targetRoot`, undefined where nothing is
+ * there, each refusal naming it `label`. A document past the bound is read one byte past
+ * it and refused as {@link refuseOverBound} refuses it.
+ */
+export function readTargetDocument(host, targetRoot, name, label = name) {
+    const path = joinPath(targetRoot, name);
+    const kind = attempt(label, () => host.kindOf(path));
+    if (kind === "absent") {
+        return undefined;
+    }
+    const real = attempt(label, () => host.realPath(path));
+    if (relativePath(attempt(label, () => host.realPath(targetRoot)), real) === undefined) {
+        throw new TargetDocumentError(label, `resolves to ${real}, outside the target root`);
+    }
+    if (kind !== "file") {
+        throw new TargetDocumentError(label, "is not a regular file");
+    }
+    const text = attempt(label, () => host.readFile(real, CONFIG_MAX_BYTES + 1));
+    refuseOverBound(label, text);
+    return text;
+}

package/dist/src/injection-container.js

@@ -24,7 +24,7 @@ function isInjected(node) {
 /** The classes of the target a call whose callee an entry names passes, with that call's entry. */
 function registrations(input) {
     const { project, held } = input;
-    const resolved = resolveEntries(project, held, input.ts.injectionRegistrations);
+    const resolved = resolveEntries(project, held, input.ts.injection_registrations);
     if (!resolved.some(namesADeclaration)) {
         return [];
     }