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

package/dist/src/conventions.js

@@ -5,14 +5,19 @@
  * directory a configuration property moves read from the property's literal value.
  * No configuration file is run.
  */
-import { isArrayLiteralExpression, isAsExpression, isBinaryExpression, isCallExpression, isClassDeclaration, isComputedPropertyName, isExportAssignment, isExportDeclaration, isExpressionStatement, isFunctionDeclaration, isIdentifier, isImportDeclaration, isNamedExports, isNamespaceImport, isNoSubstitutionTemplateLiteral, isNonNullExpression, isNumericLiteral, isObjectBindingPattern, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isSatisfiesExpression, isShorthandPropertyAssignment, isSpreadAssignment, isStringLiteral, isVariableStatement, SyntaxKind, } from "@typescript/native/ast";
+import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isClassDeclaration, isComputedPropertyName, isExportAssignment, isExportDeclaration, isExpressionStatement, isFunctionDeclaration, isIdentifier, isImportDeclaration, isNamedExports, isNamespaceImport, isNoSubstitutionTemplateLiteral, isNumericLiteral, isObjectBindingPattern, isObjectLiteralExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isStringLiteral, isVariableStatement, SyntaxKind, } from "@typescript/native/ast";
 import { lineOf } from "./component-files.js";
 import { CONVENTION_ROWS, } from "./convention-rows.js";
 import { documentStrings } from "./configuration-files.js";
-import { globExpression } from "./glob.js";
-import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from "./paths.js";
+import { ancestors, dirnamePath, joinPath, normalizePath, relativePath, resolvePath, } from "./paths.js";
 import { satisfies } from "./version-range.js";
-import { yamlDocument } from "./yaml-document.js";
+import { bytewise } from "./text/compare.js";
+import { isRecord } from "./json-document.js";
+import { unwrapped } from "./unwrap.js";
+import { filesIn } from "./fs/tree.js";
+import { INSTALLED_PACKAGES, MANIFEST, readJSON } from "./fs/manifest.js";
+import { globExpression } from "./text/glob.js";
+import { yamlDocument } from "./text/yaml.js";
 const JSON_EXTENSION = ".json";
 /**
  * A configuration file its tool reads as a YAML document, read as the JSON document it
@@ -29,17 +34,6 @@ const DEPENDENCY_SECTIONS = [
     "peerDependencies",
     "optionalDependencies",
 ];
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function readJSON(host, path) {
-    try {
-        return JSON.parse(host.readFile(path));
-    }
-    catch {
-        return undefined;
-    }
-}
 function declares(manifest, name, sections = DEPENDENCY_SECTIONS) {
     if (!isRecord(manifest)) {
         return false;
@@ -55,32 +49,15 @@ function declares(manifest, name, sections = DEPENDENCY_SECTIONS) {
  * none, or `undefined` where no `node_modules` holds it.
  */
 function installedVersion(host, dir, name) {
-    for (let at = normalizePath(dir);; at = dirnamePath(at)) {
-        const path = joinPath(at, "node_modules", name, "package.json");
+    for (const at of ancestors(dir)) {
+        const path = joinPath(at, INSTALLED_PACKAGES, name, MANIFEST);
         if (host.kindOf(path) === "file") {
             const manifest = readJSON(host, path);
             const version = isRecord(manifest) ? manifest["version"] : undefined;
             return typeof version === "string" ? version : "";
         }
-        if (dirnamePath(at) === at) {
-            return undefined;
-        }
     }
-}
-/** Whether one node wraps an expression without changing its value. */
-function isWrapper(node) {
-    return (isParenthesizedExpression(node) ||
-        isAsExpression(node) ||
-        isSatisfiesExpression(node) ||
-        isNonNullExpression(node));
-}
-/** The expression a wrapper that changes no value holds. */
-function unwrapped(node) {
-    let at = node;
-    while (isWrapper(at)) {
-        at = at.expression;
-    }
-    return at;
+    return undefined;
 }
 /** The key one property is written with, where it is written as a name or as literal text. */
 function keyOf(property) {
@@ -569,17 +546,7 @@ function expand(template, resolved) {
 /** The configuration files in one directory that one glob names, by name. */
 function configurationFiles(host, dir, glob) {
     const expression = globExpression(glob);
-    let entries;
-    try {
-        entries = host.readDirectory(dir);
-    }
-    catch {
-        return [];
-    }
-    return entries
-        .filter((entry) => !entry.directory && expression.test(entry.name))
-        .map((entry) => entry.name)
-        .sort();
+    return filesIn(host, dir, (name) => expression.test(name));
 }
 function resolveMove(host, parse, dir, row, move, resolved) {
     const set = [];
@@ -667,7 +634,7 @@ function shortNameUses(host, parse, dir, manifest, readings) {
             }
         }
     }
-    return [...used].filter((name) => declared.has(name)).sort(compare);
+    return [...used].filter((name) => declared.has(name)).sort(bytewise);
 }
 /**
  * The package one value of a prefixed-name reading names, or none: ESLint's own naming,
@@ -718,7 +685,7 @@ function prefixedNameUses(host, parse, dir, manifest, readings) {
             }
         }
     }
-    return [...used].sort(compare);
+    return [...used].sort(bytewise);
 }
 /** The declared dependencies an applied row's helper settings use. */
 function helperUses(host, parse, dir, manifest, readings) {
@@ -775,13 +742,6 @@ function packageKeyUses(host, parse, dir, manifest, keys) {
         text.startsWith(`${name}/`) ||
         (text.startsWith(`${name}:`) && text.length > name.length + 1)));
 }
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
-    }
-    return a < b ? -1 : 1;
-}
 /**
  * What the rows decide over the manifests the analysis reads. A row `disabled` names
  * is skipped before anything is read for it.
@@ -795,7 +755,7 @@ export function readConventions(host, parse, manifests, disabled, rows = CONVENT
     const selected = new Map();
     const testFiles = new Set();
     for (const manifest of manifests) {
-        const declared = readJSON(host, joinPath(manifest.dir, "package.json"));
+        const declared = readJSON(host, joinPath(manifest.dir, MANIFEST));
         const versions = new Map();
         const missing = new Set();
         for (const row of rows) {
@@ -893,15 +853,15 @@ export function readConventions(host, parse, manifests, disabled, rows = CONVENT
         }
     }
     const unique = [...new Map(applied.map((one) => [JSON.stringify(one), one])).values()];
-    unique.sort((a, b) => compare(a.name, b.name) ||
-        compare(a.manifest, b.manifest) ||
-        compare(JSON.stringify(a), JSON.stringify(b)));
+    unique.sort((a, b) => bytewise(a.name, b.name) ||
+        bytewise(a.manifest, b.manifest) ||
+        bytewise(JSON.stringify(a), JSON.stringify(b)));
     return {
         applied: unique,
         globs,
         generated,
         failures,
-        uses: [...uses].sort(compare),
+        uses: [...uses].sort(bytewise),
         selected,
         testFiles,
     };

package/dist/src/dependencies.js

@@ -10,14 +10,15 @@ import { isArrayLiteralExpression, isCallExpression, isExportDeclaration, isExpr
 import { automaticTypes } from "./automatic-types.js";
 import { configurationFiles, declaredIn as declaredBeside, dependenciesNamed, moduleStrings, outsideChain, } from "./configuration-files.js";
 import { nodeKey, packageScope } from "./inventory.js";
-import { scriptTokens } from "./manifest.js";
-import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.js";
+import { ancestors, dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath, } from "./paths.js";
 import { UNANSWERED } from "./query.js";
 import { sourceFilesOf } from "./source-files.js";
 import { workflowCommands, workflowTokens } from "./workflow-steps.js";
-const MANIFEST = "package.json";
-const MODULES_DIR = "node_modules";
-const MODULES_SEGMENT = `/${MODULES_DIR}/`;
+import { bytewise } from "./text/compare.js";
+import { isRecord } from "./json-document.js";
+import { inInstalledPackages, INSTALLED_PACKAGES, MANIFEST, readDocument } from "./fs/manifest.js";
+import { commandsOf, scriptTokens } from "./text/shell.js";
+const MODULES_SEGMENT = `/${INSTALLED_PACKAGES}/`;
 const TYPES_SCOPE = "@types/";
 /** A script token naming a JavaScript file by a path no expansion changes. */
 const SCRIPT_FILE = /^[^$`{*?[~]+\.(?:js|mjs|cjs)$/u;
@@ -39,25 +40,6 @@ export function configurationNeeds(packages) {
 }
 /** The key of {@link ProjectNeeds.at} for a use no file of the target governs. */
 const ANYWHERE = "";
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** One JSON document's decoded value, or undefined where it cannot be read or parsed. */
-function readJSON(host, path) {
-    let text;
-    try {
-        text = host.readFile(path);
-    }
-    catch {
-        return undefined;
-    }
-    try {
-        return { text, value: JSON.parse(text) };
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * The package a bare module specifier names: its first segment, or its first two
  * where it starts with a scope. A relative, absolute or scheme-prefixed specifier and
@@ -280,7 +262,7 @@ export function projectNeeds(project, held, host, targetRoot, parse) {
     }
     for (const { strings, manifestDirs } of configuration.documents) {
         for (const manifestDir of manifestDirs) {
-            const names = declaredAt(joinPath(manifestDir, "package.json"));
+            const names = declaredAt(joinPath(manifestDir, MANIFEST));
             for (const text of strings) {
                 use([PROJECT_OWNER], dependenciesNamed(text, names), joinPath(manifestDir, MANIFEST));
             }
@@ -289,7 +271,7 @@ export function projectNeeds(project, held, host, targetRoot, parse) {
     const ranFiles = outsideChain(host, targetRoot, files, parse, scriptRunFiles(host, targetRoot, files));
     for (const { file, manifestDirs } of [...configuration.outside, ...ranFiles]) {
         for (const manifestDir of manifestDirs) {
-            const names = declaredAt(joinPath(manifestDir, "package.json"));
+            const names = declaredAt(joinPath(manifestDir, MANIFEST));
             for (const { text } of moduleStrings(file)) {
                 use([PROJECT_OWNER], dependenciesNamed(text, names), joinPath(manifestDir, MANIFEST));
             }
@@ -307,8 +289,8 @@ function scriptRunFiles(host, targetRoot, files) {
     const root = resolvePath(host.workingDirectory(), targetRoot);
     const dirs = new Set([root]);
     for (const name of files.byName.keys()) {
-        for (let dir = dirnamePath(name); !dirs.has(dir); dir = dirnamePath(dir)) {
-            if (relativePath(root, dir) === undefined) {
+        for (const dir of ancestors(dirnamePath(name), root)) {
+            if (dirs.has(dir)) {
                 break;
             }
             dirs.add(dir);
@@ -318,7 +300,7 @@ function scriptRunFiles(host, targetRoot, files) {
         [root, new Set(workflowTokens(host, root))],
     ]);
     for (const dir of dirs) {
-        const read = readJSON(host, joinPath(dir, MANIFEST));
+        const read = readDocument(host, joinPath(dir, MANIFEST));
         if (read !== undefined && isRecord(read.value)) {
             const own = scriptTokensOf(read.value);
             tokens.set(dir, dir === root ? new Set([...own, ...(tokens.get(root) ?? [])]) : own);
@@ -330,7 +312,8 @@ function scriptRunFiles(host, targetRoot, files) {
             const path = SCRIPT_FILE.test(token) ? resolvePath(manifestDir, token) : undefined;
             const below = path === undefined ? undefined : relativePath(root, path);
             if (path !== undefined &&
-                below?.split("/").includes(MODULES_DIR) === false &&
+                below !== undefined &&
+                !inInstalledPackages(below) &&
                 !files.byName.has(path) &&
                 host.kindOf(path) === "file") {
                 found.push({ path, manifestDir });
@@ -600,8 +583,8 @@ function lineAndColumn(text, offset) {
 }
 /** The installed copy of one dependency, read where the package manager puts it for the target. */
 function installedOf(host, root, name) {
-    for (let dir = root;; dir = dirnamePath(dir)) {
-        const read = readJSON(host, joinPath(dir, MODULES_DIR, name, MANIFEST));
+    for (const dir of ancestors(root)) {
+        const read = readDocument(host, joinPath(dir, INSTALLED_PACKAGES, name, MANIFEST));
         if (read !== undefined && isRecord(read.value)) {
             const bin = read.value["bin"];
             const peers = read.value["peerDependencies"];
@@ -617,10 +600,8 @@ function installedOf(host, root, name) {
                         : [],
             };
         }
-        if (dirnamePath(dir) === dir) {
-            return undefined;
-        }
     }
+    return undefined;
 }
 /** Every dependency the manifest text at `path` declares, in the order the text writes them. */
 function declaredIn(text, manifest, path, scope) {
@@ -694,8 +675,6 @@ const PRELOADING_PROGRAMS = new Set([
 /** The programs that run the command after them, and an environment assignment before it. */
 const LAUNCHERS = new Set(["cross-env", "env", "npx"]);
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/u;
-/** The commands one script string runs, split at the shell's list and pipeline operators. */
-const COMMAND_SEPARATORS = /&&|\|\||;|\||&/u;
 /**
  * The command strings one manifest runs: each of its `scripts`, and the `exec` command of
  * nodemon's configuration, in the manifest's `nodemonConfig` or the `nodemon.json` beside
@@ -704,7 +683,10 @@ const COMMAND_SEPARATORS = /&&|\|\||;|\||&/u;
  */
 function manifestCommands(host, dir, manifest) {
     const scripts = manifest["scripts"];
-    const nodemon = [manifest["nodemonConfig"], readJSON(host, joinPath(dir, "nodemon.json"))?.value];
+    const nodemon = [
+        manifest["nodemonConfig"],
+        readDocument(host, joinPath(dir, "nodemon.json"))?.value,
+    ];
     return [
         ...(isRecord(scripts) ? Object.values(scripts) : []),
         ...nodemon.map((config) => (isRecord(config) ? config["exec"] : undefined)),
@@ -718,7 +700,7 @@ function manifestCommands(host, dir, manifest) {
 function preloadsOf(scripts) {
     const found = new Set();
     for (const script of scripts) {
-        for (const command of script.split(COMMAND_SEPARATORS)) {
+        for (const command of commandsOf(script)) {
             const tokens = scriptTokens(command);
             let at = 0;
             while (at < tokens.length &&
@@ -833,7 +815,7 @@ export function dependenciesOf(host, targetRoot, perProject, candidates, members
     const peers = new Map();
     const uninstalledHere = new Set(nested);
     for (const [dir, path] of manifests) {
-        const read = readJSON(host, joinPath(dir, MANIFEST));
+        const read = readDocument(host, joinPath(dir, MANIFEST));
         if (read === undefined || !isRecord(read.value)) {
             continue;
         }
@@ -909,7 +891,7 @@ export function dependenciesOf(host, targetRoot, perProject, candidates, members
     const heldBy = new Map();
     for (const [key, held] of holders) {
         if (!live.has(key) && !ran.has(key)) {
-            heldBy.set(key, [...held].sort((a, b) => (a < b ? -1 : 1)));
+            heldBy.set(key, [...held].sort(bytewise));
         }
     }
     const users = new Map();
@@ -921,7 +903,7 @@ export function dependenciesOf(host, targetRoot, perProject, candidates, members
     for (const id of candidates) {
         const sole = [...(uses.get(id) ?? [])].filter((one) => users.get(one) === 1 && names.has(one));
         if (sole.length > 0) {
-            lastUses.set(id, sole.sort((a, b) => (a < b ? -1 : 1)));
+            lastUses.set(id, sole.sort(bytewise));
         }
     }
     const owners = new Map();
@@ -933,7 +915,7 @@ export function dependenciesOf(host, targetRoot, perProject, candidates, members
         }
     }
     const fileLastUses = new Map();
-    for (const [one, held] of [...owners].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    for (const [one, held] of [...owners].sort(([a], [b]) => bytewise(a, b))) {
         const paths = new Set([...held].map((owner) => owner.replace(/:\d+:\d+$/u, "")));
         const [path] = paths;
         if (paths.size === 1 && path !== undefined && path !== PROJECT_OWNER) {

package/dist/src/discover.js

@@ -3,10 +3,15 @@ import { baseUrlPaths } from "./base-url.js";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
 import { SetupError } from "./setup-failure.js";
 import { writtenPath } from "./workspace-programs.js";
-/** Directory names discovery does not descend into. */
-export const IGNORED_DIRECTORIES = new Set(["node_modules", ".git"]);
-/** A compiler configuration file discovery recognises under a root. */
-const CONFIG_FILE = /^tsconfig.*\.json$/u;
+import { filesBelow } from "./fs/tree.js";
+import { LANGUAGE, message } from "./product.js";
+import { LANGUAGE_ROWS } from "./contract/contract.generated.js";
+import { globExpression } from "./text/glob.js";
+const MARKERS = LANGUAGE_ROWS[LANGUAGE].markers.map(globExpression);
+/** Whether one file name is a compiler configuration's: one of the language row's markers. */
+export function isConfigFile(name) {
+    return MARKERS.some((marker) => marker.test(name));
+}
 /**
  * A run that cannot read what it was asked to analyze. It ends the run with the
  * failure code and no finding list: a configuration file the compiler cannot read,
@@ -111,40 +116,9 @@ export function targetRelative(text, targetRoot) {
 export function isGuess(discovery, configFile) {
     return discovery.derived && !discovery.fromScope.includes(configFile);
 }
-/**
- * The configuration files below `root`, in ascending path order, skipping an
- * ignored directory. A directory that cannot be read is skipped: a tree the
- * analysis may not enter names no project.
- */
+/** The configuration files below `root`, by absolute path in ascending order. */
 function configFilesUnder(host, root) {
-    const found = [];
-    const pending = [root];
-    while (pending.length > 0) {
-        const dir = pending.pop();
-        if (dir === undefined) {
-            break;
-        }
-        let entries;
-        try {
-            entries = host.readDirectory(dir);
-        }
-        catch {
-            continue;
-        }
-        for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : 1))) {
-            const path = joinPath(dir, entry.name);
-            if (entry.directory) {
-                if (!IGNORED_DIRECTORIES.has(entry.name)) {
-                    pending.push(path);
-                }
-                continue;
-            }
-            if (CONFIG_FILE.test(entry.name)) {
-                found.push(path);
-            }
-        }
-    }
-    return found.sort();
+    return filesBelow(host, root, isConfigFile).map((path) => joinPath(root, path));
 }
 /**
  * The configuration file the scope names for the target directly, where its path
@@ -211,7 +185,7 @@ export function consumerProjects(engine, host, root) {
     if (kind !== "directory") {
         throw new DiscoveryError(`the consumer ${root} is not a directory`, []);
     }
-    const found = derivedFrom(engine, host, configFilesUnder(host, root), () => true);
+    const found = derivedFrom(engine, host, [...configFilesUnder(host, root)], () => true);
     if (found.length === 0) {
         throw new DiscoveryError(`the consumer ${root} holds no compiler configuration, so none of its references can be read`, []);
     }
@@ -253,7 +227,7 @@ function readConfiguration(engine, configFile) {
             : { reason: `TS${String(circular.code)}: ${circular.text.replace("{0}", () => configFile)}` };
     }
     catch (error) {
-        return { reason: error instanceof Error ? error.message : String(error) };
+        return { reason: message(error) };
     }
 }
 /**
@@ -362,7 +336,7 @@ function derivedProjects(engine, host, scope) {
  * package whose sources ship as TypeScript is analyzed as it stands.
  */
 export function discoverProjects(engine, host, scope, configurations = []) {
-    const declared = configurations.filter((entry) => entry.shape === "project");
+    const declared = configurations.filter((entry) => "project" in entry);
     if (declared.length > 0) {
         return declaredProjects(engine, host, scope.target.path, declared);
     }

package/dist/src/edges.js

@@ -4,153 +4,69 @@
  * 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 { 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 { 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;
-}
-function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** 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 (!isObject(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, error instanceof Error ? error.message : String(error), DOCUMENT_WANT);
-    }
-    if (!isObject(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;
-}
-/** Two strings ordered bytewise. */
-function compare(a, b) {
-    if (a === b) {
-        return 0;
     }
-    return a < b ? -1 : 1;
+    return sides;
 }
 /**
  * Evaluates every declared side of this language over the run's findings. A side naming a
@@ -191,6 +107,6 @@ export function evaluateEdges(findings, sides, symbols) {
             return { ...side, state: "dead", finding };
         });
     });
-    evaluations.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+    evaluations.sort((a, b) => bytewise(a.edge, b.edge) || bytewise(a.side, b.side));
     return { findings: findings.filter((_finding, at) => !pending.has(at)), evaluations };
 }

package/dist/src/element-access.js

@@ -8,6 +8,7 @@ import { isArrayLiteralExpression, isArrowFunction, isBinaryExpression, isCallEx
 import { nodeKey } from "./inventory.js";
 import { renderPosition } from "./position.js";
 import { UNANSWERED } from "./query.js";
+import { parenthesesRemoved } from "./unwrap.js";
 /** The assignment operators that read their target before they write it. */
 const COMPOUND = new Set([
     SyntaxKind.PlusEqualsToken,
@@ -47,12 +48,9 @@ function useOf(node) {
     }
     return "read";
 }
-function unwrapped(node) {
-    return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
 /** Whether an index is a literal the checker resolves to a member by its own text. */
 function isLiteralIndex(node) {
-    const at = unwrapped(node);
+    const at = parenthesesRemoved(node);
     return isStringLiteral(at) || isNumericLiteral(at) || isNoSubstitutionTemplateLiteral(at);
 }
 /**
@@ -195,7 +193,7 @@ export function elementAccessReferences(project, held, chains, root, testFiles)
     const parameterOf = new Map();
     const byCallable = new Map();
     for (const candidate of candidates) {
-        const index = unwrapped(candidate.access.argumentExpression);
+        const index = parenthesesRemoved(candidate.access.argumentExpression);
         const fn = isIdentifier(index) ? enclosingFunction(candidate.access) : undefined;
         const callable = fn === undefined ? undefined : callableOf(fn);
         if (callable === undefined || !isIdentifier(index)) {
@@ -252,7 +250,7 @@ export function elementAccessReferences(project, held, chains, root, testFiles)
             continue;
         }
         // An object that is a parameter too is read as the argument each call passes there.
-        const object = unwrapped(candidate.access.expression);
+        const object = parenthesesRemoved(candidate.access.expression);
         const objectAt = isIdentifier(object)
             ? deferred.callable.parameters.findIndex((parameter) => isIdentifier(parameter.name) && parameter.name.text === object.text)
             : -1;