@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.20

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

@@ -5,9 +5,8 @@
  * target holds, the members are read at each call, by the type of the argument it passes.
  */
 import { isArrayLiteralExpression, isArrowFunction, isBinaryExpression, isCallExpression, isElementAccessExpression, isForInStatement, isForOfStatement, isFunctionDeclaration, isFunctionExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isNumericLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, isVariableDeclaration, isVariableDeclarationList, isVariableStatement, NodeFlags, SyntaxKind, } from "@typescript/native/ast";
-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 +46,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);
 }
 /**
@@ -155,174 +151,191 @@ function assigns(body, name) {
     return found;
 }
 /**
- * The references the element accesses of one project's own files make to the members their
- * index's literal type names, each made by the declaration holding the access or the call.
+ * The reads the element accesses of a side's files make of the members their index's literal
+ * type names, each made by the declaration holding the access or the call. A type the checker
+ * leaves unanswered holds what its answer could have read.
  */
-export function elementAccessReferences(project, held, chains, root, testFiles) {
-    const queries = project.queries;
-    const candidates = [];
-    const calls = new Map();
-    const names = [];
-    for (const file of project.ownSourceFiles()) {
-        const fileId = held.declarations.get(nodeKey(file, file));
-        if (fileId === undefined) {
-            continue;
-        }
-        const visit = (node, from) => {
-            const holder = held.declarations.get(nodeKey(file, node)) ?? from;
-            if (isElementAccessExpression(node) && !isLiteralIndex(node.argumentExpression)) {
-                candidates.push({ file, from: holder, access: node, use: useOf(node) });
-            }
-            if (isCallExpression(node)) {
-                calls.set(node, { file, from: holder });
-            }
-            if (isIdentifier(node)) {
-                names.push(node);
-            }
-            node.forEachChild((child) => {
-                visit(child, holder);
-            });
-        };
-        file.forEachChild((child) => {
-            visit(child, fileId);
-        });
-    }
-    if (candidates.length === 0) {
-        return [];
-    }
-    // A parameter index is decided at the calls only where the function is a callable every
-    // use of which is a call, so the symbols of the parameters and of every name are read.
-    const parameterOf = new Map();
-    const byCallable = new Map();
-    for (const candidate of candidates) {
-        const index = unwrapped(candidate.access.argumentExpression);
-        const fn = isIdentifier(index) ? enclosingFunction(candidate.access) : undefined;
-        const callable = fn === undefined ? undefined : callableOf(fn);
-        if (callable === undefined || !isIdentifier(index)) {
-            continue;
-        }
-        const at = callable.parameters.findIndex((parameter) => isIdentifier(parameter.name) && parameter.name.text === index.text);
-        if (at < 0 || assigns(callable.body, index.text)) {
-            continue;
-        }
-        parameterOf.set(candidate, { callable, at });
-        byCallable.set(callable.name, [...(byCallable.get(callable.name) ?? []), candidate]);
-    }
-    const callableNames = [...byCallable.keys()];
-    const spelled = new Set(callableNames.map((name) => name.text));
-    const sameName = names.filter((name) => spelled.has(name.text));
-    const symbols = queries.symbolsAt([...callableNames, ...sameName]);
-    const symbolOf = new Map();
-    [...callableNames, ...sameName].forEach((node, at) => {
-        const symbol = symbols[at];
-        if (symbol !== UNANSWERED && symbol !== undefined) {
-            symbolOf.set(node, symbol);
-        }
-    });
-    const callsOf = new Map();
-    for (const name of callableNames) {
-        const symbol = symbolOf.get(name);
-        let found = symbol === undefined ? undefined : [];
-        for (const use of sameName) {
-            if (found === undefined) {
-                break;
-            }
-            if (use === name || symbolOf.get(use) !== symbol) {
-                continue;
-            }
-            const parent = use.parent;
-            found =
-                isCallExpression(parent) && parent.expression === use ? [...found, parent] : undefined;
-        }
-        callsOf.set(name, found);
-    }
-    const lookups = [];
-    for (const candidate of candidates) {
-        const deferred = parameterOf.get(candidate);
-        const sites = deferred === undefined ? undefined : callsOf.get(deferred.callable.name);
-        if (deferred === undefined || sites === undefined) {
-            lookups.push({
-                file: candidate.file,
-                from: candidate.from,
-                at: candidate.access.argumentExpression,
-                object: candidate.access.expression,
-                index: candidate.access.argumentExpression,
-                use: candidate.use,
-            });
-            continue;
-        }
-        // An object that is a parameter too is read as the argument each call passes there.
-        const object = unwrapped(candidate.access.expression);
-        const objectAt = isIdentifier(object)
-            ? deferred.callable.parameters.findIndex((parameter) => isIdentifier(parameter.name) && parameter.name.text === object.text)
-            : -1;
-        for (const call of sites) {
-            const parameter = deferred.callable.parameters[deferred.at];
-            const index = call.arguments[deferred.at] ?? parameter?.initializer;
-            const site = calls.get(call);
-            if (index === undefined || site === undefined) {
-                continue;
-            }
-            lookups.push({
-                file: site.file,
-                from: site.from,
-                at: call,
-                object: (objectAt < 0 ? undefined : call.arguments[objectAt]) ?? candidate.access.expression,
-                index,
-                use: candidate.use,
-            });
-        }
-    }
-    const nodes = lookups.flatMap((one) => [one.index, one.object]);
-    const types = queries.typesAt(nodes);
-    const typeOf = (node, at) => {
-        const type = types[at];
-        return nodes[at] === node && type !== UNANSWERED ? type : undefined;
-    };
-    // A type parameter's body serves every instantiation, so it reads what its constraint admits.
-    const keysOf = (type) => {
-        if (!type.isTypeParameter()) {
-            return type;
-        }
-        const constraint = queries.constraintOf(type);
-        return constraint === UNANSWERED || constraint === undefined ? type : constraint;
-    };
-    const partsOf = (type) => {
-        const parts = queries.constituents(type);
-        return parts === UNANSWERED ? [type] : parts;
-    };
-    const found = [];
-    lookups.forEach((lookup, at) => {
-        const indexType = typeOf(lookup.index, 2 * at);
-        const objectType = typeOf(lookup.object, 2 * at + 1);
-        const literals = indexType === undefined ? undefined : literalNames(partsOf(keysOf(indexType)));
-        if (objectType === undefined || literals === undefined) {
-            return;
-        }
-        const position = renderPosition(lookup.file, root, lookup.at.getStart());
-        for (const part of partsOf(objectType)) {
-            const properties = queries.propertiesOf(part);
-            for (const property of properties === UNANSWERED ? [] : properties) {
-                if (!literals.has(property.escapedName)) {
-                    continue;
+export const elementAccess = {
+    start() {
+        const candidates = [];
+        const calls = new Map();
+        const names = [];
+        return {
+            visit(node, { file, from }) {
+                if (isElementAccessExpression(node) && !isLiteralIndex(node.argumentExpression)) {
+                    candidates.push({ file, from, access: node, use: useOf(node) });
+                }
+                if (isCallExpression(node)) {
+                    calls.set(node, { file, from });
                 }
-                for (const to of chains.declarationsOf(property)) {
-                    for (const use of lookup.use === "both" ? ["read", "write"] : [lookup.use]) {
+                if (isIdentifier(node)) {
+                    names.push(node);
+                }
+            },
+            reads({ project, chains }) {
+                const found = [];
+                if (candidates.length === 0) {
+                    return found;
+                }
+                const queries = project.queries;
+                // A parameter index is decided at the calls only where the function is a callable every
+                // use of which is a call, so the symbols of the parameters and of every name are read.
+                const parameterOf = new Map();
+                const byCallable = new Map();
+                for (const candidate of candidates) {
+                    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)) {
+                        continue;
+                    }
+                    const at = callable.parameters.findIndex((parameter) => isIdentifier(parameter.name) && parameter.name.text === index.text);
+                    if (at < 0 || assigns(callable.body, index.text)) {
+                        continue;
+                    }
+                    parameterOf.set(candidate, { callable, at });
+                    byCallable.set(callable.name, [...(byCallable.get(callable.name) ?? []), candidate]);
+                }
+                const callableNames = [...byCallable.keys()];
+                const spelled = new Set(callableNames.map((name) => name.text));
+                const sameName = names.filter((name) => spelled.has(name.text));
+                const asked = [...callableNames, ...sameName];
+                const symbols = queries.symbolsAt(asked);
+                const symbolOf = new Map();
+                asked.forEach((node, at) => {
+                    const symbol = symbols[at];
+                    if (symbol !== undefined) {
+                        symbolOf.set(node, symbol);
+                    }
+                });
+                const callsOf = new Map();
+                for (const name of callableNames) {
+                    const symbol = symbolOf.get(name);
+                    let sites = symbol === undefined || symbol === UNANSWERED ? undefined : [];
+                    for (const use of sameName) {
+                        if (sites === undefined) {
+                            break;
+                        }
+                        const other = symbolOf.get(use);
+                        if (use === name || (other !== symbol && other !== UNANSWERED)) {
+                            continue;
+                        }
+                        // A use the checker could not resolve may be the function's, read where it is not called.
+                        const parent = use.parent;
+                        sites =
+                            other !== UNANSWERED && isCallExpression(parent) && parent.expression === use
+                                ? [...sites, parent]
+                                : undefined;
+                    }
+                    callsOf.set(name, sites);
+                }
+                const lookups = [];
+                for (const candidate of candidates) {
+                    const deferred = parameterOf.get(candidate);
+                    const sites = deferred === undefined ? undefined : callsOf.get(deferred.callable.name);
+                    if (deferred === undefined || sites === undefined) {
+                        lookups.push({
+                            file: candidate.file,
+                            from: candidate.from,
+                            at: candidate.access.argumentExpression,
+                            object: candidate.access.expression,
+                            index: candidate.access.argumentExpression,
+                            use: candidate.use,
+                        });
+                        continue;
+                    }
+                    // An object that is a parameter too is read as the argument each call passes there.
+                    const object = parenthesesRemoved(candidate.access.expression);
+                    const objectAt = isIdentifier(object)
+                        ? deferred.callable.parameters.findIndex((parameter) => isIdentifier(parameter.name) && parameter.name.text === object.text)
+                        : -1;
+                    for (const call of sites) {
+                        const parameter = deferred.callable.parameters[deferred.at];
+                        const index = call.arguments[deferred.at] ?? parameter?.initializer;
+                        const site = calls.get(call);
+                        if (index === undefined || site === undefined) {
+                            continue;
+                        }
+                        lookups.push({
+                            file: site.file,
+                            from: site.from,
+                            at: call,
+                            object: (objectAt < 0 ? undefined : call.arguments[objectAt]) ??
+                                candidate.access.expression,
+                            index,
+                            use: candidate.use,
+                        });
+                    }
+                }
+                const nodes = lookups.flatMap((one) => [one.index, one.object]);
+                const types = queries.typesAt(nodes);
+                // A type parameter's body serves every instantiation, so it reads what its constraint admits.
+                const keysOf = (type) => {
+                    if (!type.isTypeParameter()) {
+                        return type;
+                    }
+                    const constraint = queries.constraintOf(type);
+                    return constraint === UNANSWERED || constraint === undefined ? type : constraint;
+                };
+                const partsOf = (type) => {
+                    const parts = queries.constituents(type);
+                    return parts === UNANSWERED ? [type] : parts;
+                };
+                lookups.forEach((lookup, at) => {
+                    const indexType = types[2 * at];
+                    const objectType = types[2 * at + 1];
+                    const literals = indexType === undefined || indexType === UNANSWERED
+                        ? undefined
+                        : literalNames(partsOf(keysOf(indexType)));
+                    if (indexType === UNANSWERED || objectType === UNANSWERED) {
                         found.push({
+                            kind: "held",
                             from: lookup.from,
-                            to,
-                            position,
-                            use,
-                            resolution: "keyed",
-                            test: testFiles.has(position.path),
+                            ...(literals === undefined ? {} : { names: [...literals] }),
+                            ...(objectType === UNANSWERED || objectType === undefined
+                                ? literals === undefined
+                                    ? { members: true }
+                                    : {}
+                                : { types: partsOf(objectType) }),
                         });
+                        return;
                     }
-                }
-            }
-        }
-    });
-    return found;
-}
+                    if (objectType === undefined || literals === undefined) {
+                        return;
+                    }
+                    for (const part of partsOf(objectType)) {
+                        const properties = queries.propertiesOf(part);
+                        if (properties === UNANSWERED) {
+                            found.push({ kind: "held", from: lookup.from, names: [...literals] });
+                            continue;
+                        }
+                        for (const property of properties) {
+                            if (!literals.has(property.escapedName)) {
+                                continue;
+                            }
+                            for (const to of chains.declarationsOf(property)) {
+                                for (const use of lookup.use === "both"
+                                    ? ["read", "write"]
+                                    : [lookup.use]) {
+                                    found.push({
+                                        kind: "named",
+                                        from: lookup.from,
+                                        to,
+                                        file: lookup.file,
+                                        at: lookup.at,
+                                        use,
+                                        via: "keyed",
+                                    });
+                                }
+                            }
+                        }
+                    }
+                });
+                return found;
+            },
+        };
+    },
+};
 /** The names a union of literal types spells, or none where a constituent is no string or number literal. */
 function literalNames(parts) {
     const names = new Set();