@cplieger/deadset-ts 3.3.1 → 3.5.0

package/dist/src/resolve.js

@@ -1,5 +1,5 @@
 import { ConfigError, defaultConfig, } from "./config.js";
-import { FIXED_SEVERITY_CODES } from "./kinds.js";
+import { FIXED_SEVERITY_CODES, LIVE_CODES } from "./kinds.js";
 import { checkDocument, malformed, nestFlags, SCHEMA_ROOT, SEVERITY_SECTION, } from "./schema.js";
 /** Names the command-line flags in a refusal, where a document is named by its path. */
 const FLAGS_LABEL = "the command-line flags";
@@ -8,6 +8,12 @@ const FAMILY_KEY_LENGTH = 4;
 const SEVERITY_KEY = /^DS[0-9]{2}([0-9]{2})?$/u;
 const EXEMPTION_CLASS = /^[a-z][a-z0-9-]*$/u;
 const CONTRACT_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/u;
+const ANALYZER_NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/u;
+const PROVIDER_SOURCE = /^(go|npm):[^ \t\r\n]+$/u;
+const PROVIDER_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/u;
+const PROVIDER_DIGEST = /^sha256:[0-9a-f]{64}$/u;
+/** The members only an acquirable provider entry carries. */
+const ACQUIRABLE_MEMBERS = ["source", "version", "digest"];
 /** The members only a platform build configuration carries. */
 const PLATFORM_MEMBERS = ["os", "arch", "tags"];
 /** The member only a project build configuration carries. */
@@ -223,8 +229,8 @@ function readDelimiters(analysis, label) {
     };
 }
 /**
- * A severity key that names no setting, because the Contract fixes the severity of
- * the kind or kinds it names.
+ * A severity key that names no setting: it names no live kind, or the Contract
+ * fixes the severity of the kind or kinds it names.
  */
 function unimplementedSeverityKey(label, path, reason) {
     return new ConfigError("unimplemented-key", path, `${label}: key ${JSON.stringify(path)} is not implemented: ${reason}`);
@@ -245,16 +251,19 @@ function spellCodes(codes) {
     }
     return `${codes.slice(0, -1).join(", ")} and ${String(codes[codes.length - 1])}`;
 }
+/** Whether one severity key names a live kind: the code itself, or a family holding one. */
+function namesLiveKind(code) {
+    return LIVE_CODES.some((candidate) => code === candidate || (code.length === FAMILY_KEY_LENGTH && candidate.startsWith(code)));
+}
 /**
  * The severity object, one code at a time.
  *
- * A key is one issue-kind code or one two-digit family prefix, and a key naming a
- * kind whose severity the Contract fixes, or a family prefix whose range holds
- * one, is an unimplemented key rather than a setting.
+ * A key is one issue-kind code or one two-digit family prefix. A key naming no
+ * live kind, and a key naming a kind whose severity the Contract fixes or a family
+ * prefix whose range holds one, is an unimplemented key rather than a setting.
  *
- * Whether a key names a kind this analyzer reports is not decided here. This
- * analyzer reports no issue kind, so the question has one answer for every key
- * and asking it would refuse the whole object.
+ * Whether a key names a kind this analyzer reports is not decided here: a live
+ * kind of another language is a setting the analyzer of that language reads.
  */
 function readSeverity(document, label) {
     const object = section(document, SEVERITY_SECTION, SEVERITY_SECTION, label);
@@ -267,6 +276,11 @@ function readSeverity(document, label) {
         if (!SEVERITY_KEY.test(code)) {
             throw unimplementedSeverityKey(label, path, "a severity key is one issue-kind code or one two-digit family prefix");
         }
+        if (!namesLiveKind(code)) {
+            throw unimplementedSeverityKey(label, path, code.length === FAMILY_KEY_LENGTH
+                ? "the family this prefix names holds no live issue kind"
+                : "the code names no live issue kind");
+        }
         const fixed = fixedByContract(code);
         if (fixed.length > 0) {
             throw unimplementedSeverityKey(label, path, `the Contract fixes the severity of ${spellCodes(fixed)}, which this key names`);
@@ -292,6 +306,160 @@ function readExemptions(document, label) {
     }
     return disabled;
 }
+/** The members that name a declaration, each belonging to exactly one shape. */
+const SHAPE_MEMBERS = ["symbol", "module", "name", "global"];
+/** The prefix of a stable symbol reference in the TypeScript form. */
+const SYMBOL_PREFIX = "ts://";
+/**
+ * A bare specifier: neither relative nor absolute, and not one the package's own
+ * imports field maps, each of which names a file of the analyzed program.
+ */
+const BARE_SPECIFIER = /^[^./#]/u;
+/**
+ * One declaration entry, read as the one shape its members name. An entry carrying
+ * members of two shapes, or of none, is refused at the entry, as is a module named
+ * without the declaration's path or a path without its module.
+ */
+function readDeclaration(entry, at, label) {
+    if (!isRecord(entry)) {
+        throw malformed(label, at, "is not an object");
+    }
+    const named = SHAPE_MEMBERS.filter((name) => Object.hasOwn(entry, name));
+    if (named.length === 1 && named[0] === "symbol") {
+        const symbol = requireMember(readString(entry, "symbol", `${at}.symbol`, label), `${at}.symbol`, label);
+        if (!symbol.startsWith(SYMBOL_PREFIX)) {
+            throw malformed(label, `${at}.symbol`, `${JSON.stringify(symbol)} is not a ts:// reference`);
+        }
+        return { shape: "symbol", symbol };
+    }
+    if (named.length === 1 && named[0] === "global") {
+        const path = `${at}.global`;
+        return {
+            shape: "global",
+            global: requireMember(readString(entry, "global", path, label), path, label),
+        };
+    }
+    if (named.length === 2 && named.includes("module") && named.includes("name")) {
+        const module = requireMember(readString(entry, "module", `${at}.module`, label), `${at}.module`, label);
+        if (!BARE_SPECIFIER.test(module)) {
+            throw malformed(label, `${at}.module`, `${JSON.stringify(module)} is not a bare specifier: a file of the analyzed program is named by its symbol`);
+        }
+        const path = `${at}.name`;
+        return {
+            shape: "module",
+            module,
+            name: requireMember(readString(entry, "name", path, label), path, label),
+        };
+    }
+    throw malformed(label, at, named.length === 0
+        ? 'names no declaration: an entry carries "symbol", "module" with "name", or "global"'
+        : `carries ${spell(named)}, which is not one of "symbol", "module" with "name", or "global"`);
+}
+/** One array of declaration entries, absent where the document does not write it. */
+function readDeclarations(parent, name, path, label) {
+    const value = member(parent, name);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw malformed(label, path, "is not an array");
+    }
+    return value.map((entry, index) => readDeclaration(entry, `${path}[${String(index)}]`, label));
+}
+/**
+ * One lifecycle contract. The member names are required, and the entry names at least
+ * one component declaration or one base class, because a contract naming neither
+ * makes no class a component and so retains nothing.
+ */
+function readLifecycleContract(entry, at, label) {
+    if (!isRecord(entry)) {
+        throw malformed(label, at, "is not an object");
+    }
+    const components = readDeclarations(entry, "components", `${at}.components`, label) ?? [];
+    const bases = readDeclarations(entry, "bases", `${at}.bases`, label) ?? [];
+    const members = readStrings(entry, "members", `${at}.members`, label, 1);
+    if (members === undefined) {
+        throw malformed(label, `${at}.members`, "is required and names nothing");
+    }
+    if (components.length === 0 && bases.length === 0) {
+        throw malformed(label, at, 'names no declaration in "components" and no class in "bases", so it makes no class a component');
+    }
+    return { components, bases, members };
+}
+/** The lifecycle contracts, one per framework the project declares. */
+function readLifecycleContracts(ts, label) {
+    const path = "ts.lifecycle_contracts";
+    const value = member(ts, "lifecycle_contracts");
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw malformed(label, path, "is not an array");
+    }
+    return value.map((entry, index) => readLifecycleContract(entry, `${path}[${String(index)}]`, label));
+}
+/** One string member a provider entry requires, refused where it fails `pattern`. */
+function readMatching(entry, name, at, label, pattern) {
+    const path = `${at}.${name}`;
+    const value = requireMember(readString(entry, name, path, label), path, label);
+    if (!pattern.test(value)) {
+        throw malformed(label, path, `${JSON.stringify(value)} does not match ${pattern.source}`);
+    }
+    return value;
+}
+/**
+ * One provider entry, read as the one shape its members name: a member only an
+ * acquirable analyzer carries makes it acquirable, and then it carries all three.
+ */
+function readProvider(entry, at, label) {
+    if (!isRecord(entry)) {
+        throw malformed(label, at, "is not an object");
+    }
+    const name = readMatching(entry, "name", at, label, ANALYZER_NAME);
+    const languages = readStrings(entry, "languages", `${at}.languages`, label, 1, LANGUAGES);
+    if (languages === undefined) {
+        throw malformed(label, `${at}.languages`, "is required and names nothing");
+    }
+    const commandPath = `${at}.command`;
+    const command = requireMember(readString(entry, "command", commandPath, label), commandPath, label);
+    if (!ACQUIRABLE_MEMBERS.some((member) => Object.hasOwn(entry, member))) {
+        return { shape: "installed", name, languages, command };
+    }
+    return {
+        shape: "acquirable",
+        name,
+        languages,
+        command,
+        source: readMatching(entry, "source", at, label, PROVIDER_SOURCE),
+        version: readMatching(entry, "version", at, label, PROVIDER_VERSION),
+        digest: readMatching(entry, "digest", at, label, PROVIDER_DIGEST),
+    };
+}
+/**
+ * The provider list. Every file a run writes for an analyzer is keyed by the
+ * entry's name, so a list naming one name twice is refused at the later entry.
+ */
+function readProviders(providers, label) {
+    const path = "providers.analyzers";
+    const value = member(providers, "analyzers");
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw malformed(label, path, "is not an array");
+    }
+    const read = value.map((entry, index) => readProvider(entry, `${path}[${String(index)}]`, label));
+    const first = new Map();
+    read.forEach((entry, index) => {
+        const earlier = first.get(entry.name);
+        if (earlier !== undefined) {
+            throw malformed(label, `${path}[${String(index)}].name`, `${JSON.stringify(entry.name)} is already the name of ${path}[${String(earlier)}], ` +
+                "and every entry's name keys the files a run writes for it");
+        }
+        first.set(entry.name, index);
+    });
+    return read;
+}
 /**
  * Reads one already-parsed configuration document as the settings it supplies,
  * refusing every constraint the closed key list declares that a parse cannot
@@ -308,6 +476,7 @@ function readDoc(value, label) {
     const consumers = section(value, "consumers", "consumers", label);
     const roots = section(value, "roots", "roots", label);
     const reporters = section(value, "reporters", "reporters", label);
+    const providers = section(value, "providers", "providers", label);
     const ts = section(value, "ts", "ts", label);
     section(value, "go", "go", label);
     section(value, "provenance", "provenance", label);
@@ -335,8 +504,12 @@ function readDoc(value, label) {
         cascade: readEnum(reporters, "cascade", "reporters.cascade", label, CASCADES),
         maxFindings: readCount(reporters, "max_findings", "reporters.max_findings", label),
         failOn: readEnum(reporters, "fail_on", "reporters.fail_on", label, SEVERITIES),
+        providers: readProviders(providers, label),
         testFiles: readStrings(ts, "test_files", "ts.test_files", label, 1),
         entryFiles: readStrings(ts, "entry_files", "ts.entry_files", label, 0),
+        injectionRegistrations: readDeclarations(ts, "injection_registrations", "ts.injection_registrations", label),
+        lifecycleContracts: readLifecycleContracts(ts, label),
+        serializers: readDeclarations(ts, "serializers", "ts.serializers", label),
     };
 }
 /** Parses one document's text and walks it against the closed key list. */
@@ -535,9 +708,15 @@ function settleAll(inputs) {
             maxFindings: at("reporters.max_findings", defaults.reporters.maxFindings, (doc) => doc.maxFindings),
             failOn: at("reporters.fail_on", defaults.reporters.failOn, (doc) => doc.failOn),
         },
+        providers: {
+            analyzers: at("providers.analyzers", defaults.providers.analyzers, (doc) => doc.providers),
+        },
         ts: {
             testFiles: at("ts.test_files", defaults.ts.testFiles, (doc) => doc.testFiles),
             entryFiles: at("ts.entry_files", defaults.ts.entryFiles, (doc) => doc.entryFiles),
+            injectionRegistrations: at("ts.injection_registrations", defaults.ts.injectionRegistrations, (doc) => doc.injectionRegistrations),
+            lifecycleContracts: at("ts.lifecycle_contracts", defaults.ts.lifecycleContracts, (doc) => doc.lifecycleContracts),
+            serializers: at("ts.serializers", defaults.ts.serializers, (doc) => doc.serializers),
         },
     };
     return { config, provenance };

package/dist/src/run.js

@@ -47,8 +47,14 @@ export const SETTING_OPTIONS = new Map([
 ]);
 /** 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 setting options whose value is an integer rather than a string. A value
+ * written other than as digits is passed on as the string it is, so resolution
+ * refuses it by its type rather than reading `1e2` as 100.
+ */
+const INTEGER_OPTIONS = new Set(["max-findings"]);
+/** An integer as an option writes it: an optional minus sign and digits alone. */
+const INTEGER_TEXT = /^-?[0-9]+$/u;
 /**
  * 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
@@ -116,7 +122,7 @@ function inputsOf(host, options) {
         if (value === undefined) {
             continue;
         }
-        flat[path] = NUMBER_OPTIONS.has(name) ? Number(value) : value;
+        flat[path] = INTEGER_OPTIONS.has(name) && INTEGER_TEXT.test(value) ? Number(value) : value;
         flagLabels.set(path, `--${name}`);
     }
     const flags = Object.keys(flat).length === 0 ? undefined : JSON.stringify(flat);

package/dist/src/schema.js

@@ -1,5 +1,11 @@
 import { ConfigError } from "./config.js";
 const leaf = { kind: "leaf" };
+const integer = { kind: "leaf", integer: true };
+/** A list of declarations, each entry in one of the three shapes the `ts` section states. */
+const declarations = {
+    kind: "list",
+    members: { symbol: leaf, module: leaf, name: leaf, global: 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
@@ -39,12 +45,40 @@ export const SCHEMA_ROOT = {
                 formats: leaf,
                 sort: leaf,
                 cascade: leaf,
-                max_findings: leaf,
+                max_findings: integer,
                 fail_on: leaf,
             },
         },
+        providers: {
+            kind: "section",
+            members: {
+                analyzers: {
+                    kind: "list",
+                    members: {
+                        name: leaf,
+                        languages: leaf,
+                        command: leaf,
+                        source: leaf,
+                        version: leaf,
+                        digest: leaf,
+                    },
+                },
+            },
+        },
         go: { kind: "section", members: {} },
-        ts: { kind: "section", members: { test_files: leaf, entry_files: leaf } },
+        ts: {
+            kind: "section",
+            members: {
+                test_files: leaf,
+                entry_files: leaf,
+                injection_registrations: declarations,
+                lifecycle_contracts: {
+                    kind: "list",
+                    members: { components: declarations, bases: declarations, members: leaf },
+                },
+                serializers: declarations,
+            },
+        },
         provenance: { kind: "map" },
     },
 };
@@ -227,6 +261,21 @@ function skipScalar(cursor) {
         cursor.at += 1;
     }
 }
+/** A number the document writes as an optional minus sign and digits alone. */
+const INTEGER_TEXT = /^-?[0-9]+$/u;
+/** The start of a JSON number: a minus sign or a digit. */
+const NUMBER_START = /^[-0-9]/u;
+/**
+ * Refuses a number written with a fraction or an exponent where the key list
+ * declares an integer. A parse reads `100.0` and `1e2` as the integer 100, so only
+ * the text can tell them apart. A scalar that is no number is the decoder's to
+ * refuse by its type.
+ */
+function checkInteger(text, at, label) {
+    if (NUMBER_START.test(text) && !INTEGER_TEXT.test(text)) {
+        throw malformed(label, at, `${text} is written with a fraction or an exponent, and an integer is digits alone`);
+    }
+}
 function walkValue(cursor, at, node, label) {
     skipSpace(cursor);
     const ch = cursor.text.charCodeAt(cursor.at);
@@ -244,7 +293,11 @@ function walkValue(cursor, at, node, label) {
         readName(cursor, at, label);
         return;
     }
+    const start = cursor.at;
     skipScalar(cursor);
+    if (node.integer === true) {
+        checkInteger(cursor.text.slice(start, cursor.at), at, label);
+    }
 }
 function walkObject(cursor, at, node, label) {
     const seen = new Set();

package/dist/src/scope.js

@@ -1,4 +1,6 @@
+import { ConfigError } from "./config.js";
 import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.js";
+import { checkDocument } from "./schema.js";
 /** The roles a scope document declares for a module. */
 export const ROLE_TARGET = "target";
 export const ROLE_CONSUMER = "consumer";
@@ -17,18 +19,37 @@ export class ScopeError extends Error {
         this.name = "ScopeError";
     }
 }
-const DECLARED_KEYS = new Set(["target", "workspace", "consumers"]);
-const MODULE_KEYS = new Set(["id", "role", "path"]);
+const MODULE = {
+    kind: "section",
+    members: { id: { kind: "leaf" }, role: { kind: "leaf" }, path: { kind: "leaf" } },
+};
+/** The closed key list of the scope document, compared as bytes. */
+const SCOPE_ROOT = {
+    kind: "section",
+    members: {
+        target: MODULE,
+        workspace: { kind: "leaf" },
+        consumers: { kind: "list", members: MODULE.members ?? {} },
+    },
+};
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * One string member, or undefined where the document omits it. A member the
+ * document writes is a string holding at least one character, so `null` and `""`
+ * are refused rather than read as absent.
+ */
 function stringMember(parent, name, at) {
     if (!Object.hasOwn(parent, name)) {
-        return "";
+        return undefined;
     }
     const value = parent[name];
     if (typeof value !== "string") {
-        throw new ScopeError(`scope: ${at}.${name} is not a string`);
+        throw new ScopeError(`scope: ${at === "" ? name : `${at}.${name}`} is not a string`);
+    }
+    if (value === "") {
+        throw new ScopeError(`scope: ${at === "" ? name : `${at}.${name}`} names nothing`);
     }
     return value;
 }
@@ -36,30 +57,46 @@ 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) {
+    if (declared !== undefined && declared !== role) {
         throw new ScopeError(`scope: ${at}.role is ${JSON.stringify(declared)}, want ${JSON.stringify(role)}`);
     }
     const path = stringMember(value, "path", at);
-    if (path === "") {
+    if (path === undefined) {
         throw new ScopeError(`scope: ${at}.path names nothing`);
     }
     return {
-        id: stringMember(value, "id", at),
+        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.
+ * Walks the document's text against the closed key list, refusing a key the list
+ * does not declare, compared as bytes, and a key one object writes twice, which a
+ * parse cannot report because it keeps the last value.
+ */
+function checkKeys(text, file) {
+    try {
+        checkDocument(text, SCOPE_ROOT, `scope: ${file}`);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            // The configuration's refusal names the nearest configuration key, which a
+            // scope document does not have.
+            throw new ScopeError(error.kind === "unimplemented-key"
+                ? `scope: ${file}: ${error.key} is not a declared key`
+                : error.message);
+        }
+        throw error;
+    }
+}
+/**
+ * Decodes the scope document at `file`. Decoding is strict: an undeclared key, a
+ * key written twice in one object, and a value of a type the document does not
+ * admit, `null` included, are errors, 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
+ * The `workspace` key the format declares is checked 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.
  */
@@ -85,11 +122,8 @@ export function readScope(host, file) {
     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`);
-        }
-    }
+    checkKeys(text, file);
+    stringMember(value, "workspace", "");
     const documentDir = dirnamePath(absolute);
     if (!Object.hasOwn(value, "target")) {
         throw new ScopeError(`scope: ${file} names no target`);