@cplieger/deadset-ts 3.4.0 → 3.5.0

package/src/config.ts

@@ -122,6 +122,34 @@ export interface LifecycleContract {
   readonly members: readonly string[];
 }
 
+/**
+ * One analyzer the orchestrator may run, in exactly one of two shapes: an installed
+ * analyzer, named by its command alone, or an acquirable one, which also names the
+ * artifact acquisition fetches and verifies. This analyzer validates and prints the
+ * list and runs nothing from it.
+ */
+export type Provider =
+  | {
+      readonly shape: "installed";
+      readonly name: string;
+      readonly languages: readonly Language[];
+      readonly command: string;
+    }
+  | {
+      readonly shape: "acquirable";
+      readonly name: string;
+      readonly languages: readonly Language[];
+      readonly command: string;
+      readonly source: string;
+      readonly version: string;
+      readonly digest: string;
+    };
+
+/** The analyzers the orchestrator runs. */
+export interface Providers {
+  readonly analyzers: readonly Provider[];
+}
+
 /** The section the TypeScript analyzer owns. */
 export interface TSSection {
   readonly testFiles: readonly string[];
@@ -152,6 +180,7 @@ export interface Config {
   readonly severity: ReadonlyMap<string, Severity>;
   readonly exemptionsDisabled: readonly string[];
   readonly reporters: Reporters;
+  readonly providers: Providers;
   readonly ts: TSSection;
 }
 
@@ -184,6 +213,12 @@ export function defaultConfig(): Config {
       maxFindings: 0,
       failOn: "deny",
     },
+    providers: {
+      analyzers: [
+        { shape: "installed", name: "deadset-go", languages: ["go"], command: "deadset-go" },
+        { shape: "installed", name: "deadset-ts", languages: ["ts"], command: "deadset-ts" },
+      ],
+    },
     ts: {
       testFiles: ["**/*.test.{ts,tsx,mts,cts}"],
       entryFiles: [],
@@ -246,8 +281,8 @@ export type ErrorKind =
    */
   | "malformed"
   /**
-   * A key the closed key list does not declare, or a severity key naming a kind
-   * whose severity the Contract fixes.
+   * A key the closed key list does not declare, or a severity key naming no live
+   * kind or a kind whose severity the Contract fixes.
    */
   | "unimplemented-key"
   /** A resolved configuration no source supplied a target kind for. */

package/src/kinds.ts

@@ -10,3 +10,44 @@
  * code the Contract fixes arrives here as a failing test.
  */
 export const FIXED_SEVERITY_CODES: readonly string[] = ["DS1703", "DS1704"];
+
+/**
+ * The code of every live issue kind, in ascending order. A severity key names one of
+ * them or a family prefix whose range holds one; a key naming a retired code, an
+ * unassigned code or a range holding no live kind is an unimplemented key, so every
+ * severity a configuration sets is one some analyzer reports under. A test compares
+ * this list against the Contract release the analyzer is written against.
+ */
+export const LIVE_CODES: readonly string[] = [
+  "DS1001",
+  "DS1002",
+  "DS1003",
+  "DS1004",
+  "DS1005",
+  "DS1006",
+  "DS1101",
+  "DS1102",
+  "DS1103",
+  "DS1104",
+  "DS1201",
+  "DS1203",
+  "DS1204",
+  "DS1301",
+  "DS1302",
+  "DS1303",
+  "DS1501",
+  "DS1502",
+  "DS1601",
+  "DS1605",
+  "DS1701",
+  "DS1702",
+  "DS1703",
+  "DS1704",
+  "DS1705",
+  "DS1801",
+  "DS1802",
+  "DS1803",
+  "DS1805",
+  "DS1807",
+  "DS1809",
+];

package/src/print.ts

@@ -1,4 +1,10 @@
-import { renderOrigin, type Config, type DeclarationEntry, type Provenance } from "./config.ts";
+import {
+  renderOrigin,
+  type Config,
+  type DeclarationEntry,
+  type Provenance,
+  type Provider,
+} from "./config.ts";
 
 /** One declaration entry as a document writes it: the members of its shape alone. */
 function declarationOf(entry: DeclarationEntry): Record<string, string> {
@@ -12,6 +18,15 @@ function declarationOf(entry: DeclarationEntry): Record<string, string> {
   }
 }
 
+/** One provider entry as a document writes it: the members of its shape alone. */
+function providerOf(entry: Provider): Record<string, unknown> {
+  const installed = { name: entry.name, languages: entry.languages, command: entry.command };
+  if (entry.shape === "installed") {
+    return installed;
+  }
+  return { ...installed, source: entry.source, version: entry.version, digest: entry.digest };
+}
+
 /**
  * The resolved configuration and its provenance as one JSON object, indented,
  * ending in a newline.
@@ -55,6 +70,7 @@ export function printConfig(config: Config, provenance: Provenance): string {
       max_findings: config.reporters.maxFindings,
       fail_on: config.reporters.failOn,
     },
+    providers: { analyzers: config.providers.analyzers.map(providerOf) },
     go: {},
     ts: {
       test_files: config.ts.testFiles,

package/src/resolve.ts

@@ -14,13 +14,14 @@ import {
   type LifecycleContract,
   type Origin,
   type Provenance,
+  type Provider,
   type Severity,
   type Sort,
   type Source,
   type TargetKind,
   type TemplateDelimiters,
 } from "./config.ts";
-import { FIXED_SEVERITY_CODES } from "./kinds.ts";
+import { FIXED_SEVERITY_CODES, LIVE_CODES } from "./kinds.ts";
 import {
   checkDocument,
   malformed,
@@ -39,6 +40,13 @@ 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"] as const;
 
 /** The members only a platform build configuration carries. */
 const PLATFORM_MEMBERS = ["os", "arch", "tags"] as const;
@@ -94,6 +102,7 @@ interface Doc {
   readonly cascade: Cascade | undefined;
   readonly maxFindings: number | undefined;
   readonly failOn: Severity | undefined;
+  readonly providers: readonly Provider[] | undefined;
   readonly testFiles: readonly string[] | undefined;
   readonly entryFiles: readonly string[] | undefined;
   readonly injectionRegistrations: readonly DeclarationEntry[] | undefined;
@@ -382,8 +391,8 @@ function readDelimiters(
 }
 
 /**
- * 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: string, path: string, reason: string): ConfigError {
   return new ConfigError(
@@ -414,16 +423,23 @@ function spellCodes(codes: readonly string[]): string {
   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: string): boolean {
+  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: Record<string, unknown> | undefined,
@@ -443,6 +459,15 @@ function readSeverity(
         "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(
@@ -612,6 +637,90 @@ function readLifecycleContracts(
   );
 }
 
+/** One string member a provider entry requires, refused where it fails `pattern`. */
+function readMatching(
+  entry: Record<string, unknown>,
+  name: string,
+  at: string,
+  label: string,
+  pattern: RegExp,
+): string {
+  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: unknown, at: string, label: string): Provider {
+  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: Record<string, unknown> | undefined,
+  label: string,
+): readonly Provider[] | undefined {
+  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 as unknown[]).map((entry, index) =>
+    readProvider(entry, `${path}[${String(index)}]`, label),
+  );
+  const first = new Map<string, number>();
+  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
@@ -628,6 +737,7 @@ function readDoc(value: unknown, label: string): Doc {
   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);
@@ -679,6 +789,7 @@ function readDoc(value: unknown, label: string): Doc {
     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(
@@ -959,6 +1070,9 @@ function settleAll(inputs: Inputs): { config: Config; provenance: Map<string, Or
       ),
       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),

package/src/run.ts

@@ -59,8 +59,15 @@ export const SETTING_OPTIONS: ReadonlyMap<string, string> = new Map([
 /** The options that take a value and are not settings. */
 const PLAIN_OPTIONS: ReadonlySet<string> = new Set(["target", "config", "central", "scope"]);
 
-/** The setting options whose value is a number rather than a string. */
-const NUMBER_OPTIONS: ReadonlySet<string> = 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: ReadonlySet<string> = new Set(["max-findings"]);
+
+/** An integer as an option writes it: an optional minus sign and digits alone. */
+const INTEGER_TEXT = /^-?[0-9]+$/u;
 
 /** One invocation's options, by name, with the verb's remaining arguments. */
 interface Options {
@@ -145,7 +152,7 @@ function inputsOf(host: Host, options: Options): Inputs {
     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/src/schema.ts

@@ -19,14 +19,17 @@ export type KeyKind = "leaf" | "section" | "map" | "list" | "object";
 
 /**
  * One node of the closed key list. `members` holds a section's declared members,
- * or a list entry's, and is absent otherwise.
+ * or a list entry's, and is absent otherwise. `integer` marks a leaf of the
+ * integer type, whose number the document writes as digits alone.
  */
 export interface KeyNode {
   readonly kind: KeyKind;
   readonly members?: Readonly<Record<string, KeyNode>>;
+  readonly integer?: true;
 }
 
 const leaf: KeyNode = { kind: "leaf" };
+const integer: KeyNode = { kind: "leaf", integer: true };
 
 /** A list of declarations, each entry in one of the three shapes the `ts` section states. */
 const declarations: KeyNode = {
@@ -73,10 +76,26 @@ export const SCHEMA_ROOT: KeyNode = {
         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",
@@ -305,6 +324,28 @@ function skipScalar(cursor: Cursor): void {
   }
 }
 
+/** 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: string, at: string, label: string): void {
+  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: Cursor, at: string, node: KeyNode, label: string): void {
   skipSpace(cursor);
   const ch = cursor.text.charCodeAt(cursor.at);
@@ -322,7 +363,11 @@ function walkValue(cursor: Cursor, at: string, node: KeyNode, label: string): vo
     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: Cursor, at: string, node: KeyNode, label: string): void {

package/src/scope.ts

@@ -1,5 +1,7 @@
+import { ConfigError } from "./config.ts";
 import type { Host } from "./host.ts";
 import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.ts";
+import { checkDocument, type KeyNode } from "./schema.ts";
 
 /** The roles a scope document declares for a module. */
 export const ROLE_TARGET = "target";
@@ -43,20 +45,44 @@ export interface Scope {
   readonly consumers: readonly Module[];
 }
 
-const DECLARED_KEYS = new Set(["target", "workspace", "consumers"]);
-const MODULE_KEYS = new Set(["id", "role", "path"]);
+const MODULE: KeyNode = {
+  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: KeyNode = {
+  kind: "section",
+  members: {
+    target: MODULE,
+    workspace: { kind: "leaf" },
+    consumers: { kind: "list", members: MODULE.members ?? {} },
+  },
+};
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function stringMember(parent: Record<string, unknown>, name: string, at: string): string {
+/**
+ * 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: Record<string, unknown>,
+  name: string,
+  at: string,
+): string | undefined {
   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;
 }
@@ -65,33 +91,51 @@ function readModule(value: unknown, at: string, role: string, documentDir: strin
   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: string, file: string): void {
+  try {
+    checkDocument(text, SCOPE_ROOT, `scope: ${file}`);
+  } catch (error: unknown) {
+    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.
  */
@@ -119,11 +163,8 @@ export function readScope(host: Host, file: string): Scope {
   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`);