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

package/src/paths.ts

@@ -1,11 +1,7 @@
 /**
- * Filesystem paths, as the supported platform spells them: a solidus separates
- * segments and a leading solidus makes a path absolute.
- *
- * They are written here rather than taken from the platform's own library because
- * every module below the command line stays free of the platform, and because the
- * supported platform set is one, so a second spelling would be a rule nothing
- * exercises.
+ * Filesystem paths as the supported platform spells them: a solidus between segments, a
+ * leading one for an absolute path. They are written here rather than taken from the
+ * platform's library so every module below the command line stays free of the platform.
  */
 
 const SEPARATOR = "/";
@@ -67,6 +63,25 @@ export function dirnamePath(path: string): string {
   return cut === 0 ? SEPARATOR : normalized.slice(0, cut);
 }
 
+/**
+ * `dir` and every directory above it, nearest first, normalized. With `top`, the list ends
+ * at `top` and is empty where `dir` is neither `top` nor below it; without, it ends at the
+ * root of the path.
+ */
+export function ancestors(dir: string, top?: string): readonly string[] {
+  const end = top === undefined ? undefined : normalizePath(top);
+  const found: string[] = [];
+  for (let at = normalizePath(dir); ; at = dirnamePath(at)) {
+    if (end !== undefined && at !== end && relativePath(end, at) === undefined) {
+      return [];
+    }
+    found.push(at);
+    if (at === end || dirnamePath(at) === at) {
+      return found;
+    }
+  }
+}
+
 /**
  * The extension of one path's last segment, from its last full stop, or the empty string
  * where it has none. A segment that only starts with a full stop has none.
@@ -101,14 +116,11 @@ export function queriedModulePath(specifier: string): string | undefined {
 }
 
 /**
- * One path as it reads below a root, or undefined when it is not below the root.
- * Both are normalized first, so a root written with a trailing separator or a `.`
- * segment reaches the same answer, and the comparison is then lexical, so a root
- * and a path spelled through different symbolic links name nothing in common. The
- * root itself is not below itself.
- *
- * The caller resolves both against the same directory before calling: a relative
- * root and an absolute path are two spellings this cannot reconcile.
+ * One path as it reads below a root, or undefined when it is not strictly below the root:
+ * the root itself is not below itself. Both are normalized, then compared lexically, so a
+ * root and a path spelled through different symbolic links name nothing in common. The
+ * caller resolves both against the same directory first: a relative root and an absolute
+ * path cannot be reconciled.
  */
 export function relativePath(root: string, path: string): string | undefined {
   const at = normalizePath(root);

package/src/position.ts

@@ -1,5 +1,6 @@
 import type { SourceFile } from "@typescript/native/ast";
 import { relativePath } from "./paths.ts";
+import { bytewise } from "./text/compare.ts";
 
 /**
  * Where one declaration is written, as every report renders it.
@@ -87,7 +88,7 @@ export function positionKey(position: Position): string {
  */
 export function byPosition(a: Position, b: Position): number {
   if (a.path !== b.path) {
-    return a.path < b.path ? -1 : 1;
+    return bytewise(a.path, b.path);
   }
   if (a.line !== b.line) {
     return a.line - b.line;

package/src/print.ts

@@ -5,6 +5,7 @@ import {
   type Provenance,
   type Provider,
 } from "./config.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** One declaration entry as a document writes it: the members of its shape alone. */
 function declarationOf(entry: DeclarationEntry): Record<string, string> {
@@ -61,7 +62,7 @@ export function printConfig(config: Config, provenance: Provenance): string {
     },
     consumers: { complete: config.consumersComplete },
     roots: { patterns: config.rootPatterns },
-    severity: Object.fromEntries([...config.severity].sort(([a], [b]) => (a < b ? -1 : 1))),
+    severity: Object.fromEntries([...config.severity].sort(([a], [b]) => bytewise(a, b))),
     exemptions: { disabled: config.exemptionsDisabled },
     reporters: {
       formats: config.reporters.formats,
@@ -88,7 +89,7 @@ export function printConfig(config: Config, provenance: Provenance): string {
     },
     provenance: Object.fromEntries(
       [...provenance]
-        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .sort(([a], [b]) => bytewise(a, b))
         .map(([path, origin]) => [path, renderOrigin(origin)]),
     ),
   };

package/src/product.ts

@@ -0,0 +1,18 @@
+import { LANGUAGE_ROWS } from "./contract/contract.generated.ts";
+import type { Writer } from "./run.ts";
+
+/** The language this analyzer reads. */
+export const LANGUAGE = "ts";
+
+/** The analyzer's name: the one its language's row names, which every output spells it with. */
+export const PRODUCT = LANGUAGE_ROWS[LANGUAGE].analyzer;
+
+/** Writes one diagnostic line to the error stream, named for the analyzer. */
+export function diagnose(err: Writer, text: string): void {
+  err.write(`${PRODUCT}: ${text}\n`);
+}
+
+/** The text one thrown value carries. */
+export function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/references.ts

@@ -38,13 +38,13 @@ import {
   type ParameterDeclaration,
   type SourceFile,
 } from "@typescript/native/ast";
+import { parenthesesRemoved } from "./unwrap.ts";
 import type { Symbol as TSSymbol } from "@typescript/native/sync";
 import { aliasChains, type ChainTarget } from "./alias-chain.ts";
 import { contextualUses, type FlowAt, type LiteralAt } from "./contextual-uses.ts";
 import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
 import { specifierCandidates } from "./configuration-files.ts";
 import { namespaceUses } from "./namespace-objects.ts";
-import { globExpression } from "./glob.ts";
 import {
   declarationsByName,
   isParameterProperty,
@@ -73,6 +73,8 @@ import {
   type KeyedAccess,
 } from "./symbol-keys.ts";
 import { handedOn, valuesOf } from "./value-flow.ts";
+import { bytewise } from "./text/compare.ts";
+import { globExpression } from "./text/glob.ts";
 
 /**
  * Every use one project's own files make of the project's own declarations.
@@ -315,15 +317,6 @@ function isName(node: Node): boolean {
   return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
 }
 
-/** The expression one node is, through however many parentheses are written around it. */
-function unparenthesized(node: Node): Node {
-  let held = node;
-  while (isParenthesizedExpression(held)) {
-    held = held.expression;
-  }
-  return held;
-}
-
 /**
  * Records the name one store writes into.
  *
@@ -333,7 +326,7 @@ function unparenthesized(node: Node): Node {
  * target writes each name it binds, through its spreads and nested patterns.
  */
 function markWrite(target: Node, writes: Set<number>, accesses: Set<Node>): void {
-  const held = unparenthesized(target);
+  const held = parenthesesRemoved(target);
   if (isName(held)) {
     writes.add(held.pos);
     return;
@@ -348,7 +341,7 @@ function markWrite(target: Node, writes: Set<number>, accesses: Set<Node>): void
     accesses.add(held);
     // A store through a member's value lands in storage every holder of the value
     // reads, so it reads the member; a variable only ever stored into stays written.
-    if (!isPropertyAccessExpression(unparenthesized(held.expression))) {
+    if (!isPropertyAccessExpression(parenthesesRemoved(held.expression))) {
       markWrite(held.expression, writes, accesses);
     }
     return;
@@ -524,7 +517,7 @@ interface FileSites {
 
 /** Whether one node is `import.meta.url`. */
 function isImportMetaURL(node: Node): boolean {
-  const at = unparenthesized(node);
+  const at = parenthesesRemoved(node);
   return (
     isPropertyAccessExpression(at) &&
     isMetaProperty(at.expression) &&
@@ -536,7 +529,7 @@ function isImportMetaURL(node: Node): boolean {
 /** The module URL one node builds, where it builds one. */
 function moduleURLOf(node: Node): ModuleURL | undefined {
   const relative = (argument: Node | undefined): string | undefined => {
-    const at = argument === undefined ? undefined : unparenthesized(argument);
+    const at = argument === undefined ? undefined : parenthesesRemoved(argument);
     return at !== undefined &&
       (isStringLiteral(at) || isNoSubstitutionTemplateLiteral(at)) &&
       /^\.\.?\//u.test(at.text)
@@ -551,7 +544,7 @@ function moduleURLOf(node: Node): ModuleURL | undefined {
       : undefined;
   }
   if (isCallExpression(node)) {
-    const callee = unparenthesized(node.expression);
+    const callee = parenthesesRemoved(node.expression);
     const specifier = relative(node.arguments[0]);
     if (
       specifier !== undefined &&
@@ -869,7 +862,7 @@ export function testFileRulesOf(
       };
     }),
     ...(support === 0 ? [] : [{ rule: TEST_SUPPORT_RULE, matched: support }]),
-  ].sort((a, b) => compare(a.rule, b.rule));
+  ].sort((a, b) => bytewise(a.rule, b.rule));
 }
 
 const importedCache = new WeakMap<
@@ -1003,7 +996,7 @@ function aloneIn(
           nodes.every((node) => sameTarget.some((one) => inside(node, one.value))),
       )
       .map(([name]) => name)
-      .sort(compare);
+      .sort(bytewise);
     if (names.length > 0) {
       result.push({ index: write.index, names });
     }
@@ -1011,14 +1004,6 @@ function aloneIn(
   return result;
 }
 
-/** Two strings ordered bytewise, which is the order every set of a run is read in. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
  * Every reference one project's own files make to the project's own declarations, in
  * position order, and the files the test-file rules classified.
@@ -1677,9 +1662,9 @@ export function references<Brand>(
   found.sort(
     (a, b) =>
       byPosition(a.position, b.position) ||
-      compare(a.to, b.to) ||
-      compare(a.from, b.from) ||
-      compare(a.use, b.use),
+      bytewise(a.to, b.to) ||
+      bytewise(a.from, b.from) ||
+      bytewise(a.use, b.use),
   );
 
   return {
@@ -1687,7 +1672,7 @@ export function references<Brand>(
       consumer === undefined
         ? found
         : found.map((reference) => ({ ...reference, consumer: consumer.id })),
-    testFilePaths: tests.sort(compare),
+    testFilePaths: tests.sort(bytewise),
     cost: {
       batched,
       fileBatches,

package/src/report-schema.ts

@@ -0,0 +1,364 @@
+/**
+ * Holds a report to `contract/report.schema.json` and `contract/finding.schema.json`
+ * before it is written, reading the schemas the generator copies from the Contract, so
+ * this analyzer never writes a document a reader refuses. It evaluates the keywords the
+ * Contract's schemas use; the schemas' patterns are written to match alike in RE2 and in
+ * ECMAScript.
+ */
+
+import { REPORT_SCHEMAS, type Report } from "./contract/report.generated.ts";
+import { bytewise } from "./text/compare.ts";
+import { isRecord } from "./json-document.ts";
+
+/** One value a schema refuses: its JSON Pointer, the keyword, and why. */
+interface SchemaRefusal {
+  readonly pointer: string;
+  readonly keyword: string;
+  readonly reason: string;
+}
+
+type Schema = Readonly<Record<string, unknown>>;
+type Documents = Readonly<Record<string, Schema>>;
+
+/**
+ * Every keyword the validator evaluates or knows to carry no assertion. A schema naming
+ * another fails every check rather than passing values the keyword would refuse.
+ */
+const KEYWORDS: ReadonlySet<string> = new Set([
+  ...["$schema", "$id", "$comment", "$defs", "title", "description", "default", "examples"],
+  ...["$ref", "type", "enum", "const", "pattern", "minLength", "minimum", "maximum"],
+  ...["properties", "additionalProperties", "required", "minProperties"],
+  ...["items", "minItems", "maxItems", "uniqueItems"],
+  ...["allOf", "anyOf", "oneOf", "not", "if", "then", "else"],
+]);
+
+const patterns = new Map<string, RegExp>();
+
+function pattern(source: string): RegExp {
+  let held = patterns.get(source);
+  if (held === undefined) {
+    held = new RegExp(source, "u");
+    patterns.set(source, held);
+  }
+  return held;
+}
+
+function typeOf(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? "integer" : "number";
+  }
+  return typeof value;
+}
+
+function hasType(value: unknown, name: string): boolean {
+  const held = typeOf(value);
+  return held === name || (name === "number" && held === "integer");
+}
+
+/** One value's encoding with object members sorted, so two equal values encode alike. */
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonical).join(",")}]`;
+  }
+  if (isRecord(value)) {
+    return `{${Object.keys(value)
+      .sort(bytewise)
+      .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** A string's length in code points, which JSON Schema's minLength counts. */
+function codePoints(value: string): number {
+  let counted = 0;
+  for (const _point of value) {
+    counted += 1;
+  }
+  return counted;
+}
+
+const escape = (name: string): string => name.replaceAll("~", "~0").replaceAll("/", "~1");
+
+/** A schema evaluated in the document it is read from, so a relative `$ref` resolves there. */
+class Checker {
+  private readonly documents: Documents;
+
+  constructor(documents: Documents) {
+    this.documents = documents;
+  }
+
+  resolve(doc: string, ref: string): readonly [string, Schema] {
+    const [file = "", pointer = ""] = ref.split("#");
+    const target = file === "" ? doc : file;
+    let schema: unknown = this.documents[target];
+    for (const token of pointer.split("/").filter((one) => one !== "")) {
+      schema = isRecord(schema)
+        ? schema[token.replaceAll("~1", "/").replaceAll("~0", "~")]
+        : undefined;
+    }
+    if (!isRecord(schema)) {
+      throw new Error(`report schema: ${ref} names no schema`);
+    }
+    return [target, schema];
+  }
+
+  matches(doc: string, schema: Schema, value: unknown, at: string): boolean {
+    const found: SchemaRefusal[] = [];
+    this.check(doc, schema, value, at, found);
+    return found.length === 0;
+  }
+
+  check(doc: string, schema: Schema, value: unknown, at: string, found: SchemaRefusal[]): void {
+    for (const keyword of Object.keys(schema)) {
+      if (!KEYWORDS.has(keyword) && !keyword.startsWith("x-")) {
+        throw new Error(
+          `report schema: the keyword ${keyword} is not one this validator evaluates`,
+        );
+      }
+    }
+    const refuse = (keyword: string, reason: string, pointer = at): void => {
+      found.push({ pointer, keyword, reason });
+    };
+    if (typeof schema["$ref"] === "string") {
+      const [target, referenced] = this.resolve(doc, schema["$ref"]);
+      this.check(target, referenced, value, at, found);
+    }
+    const types = schema["type"];
+    const named = types === undefined ? [] : Array.isArray(types) ? types : [types];
+    if (named.length > 0 && !named.some((one) => hasType(value, String(one)))) {
+      refuse("type", `the value is ${typeOf(value)}, want ${named.join(", ")}`);
+      return;
+    }
+    this.checkValue(schema, value, refuse);
+    if (Array.isArray(value)) {
+      this.checkArray(doc, schema, value, at, found, refuse);
+    } else if (isRecord(value)) {
+      this.checkObject(doc, schema, value, at, found, refuse);
+    }
+    this.checkApplicators(doc, schema, value, at, found, refuse);
+  }
+
+  private checkValue(
+    schema: Schema,
+    value: unknown,
+    refuse: (keyword: string, reason: string) => void,
+  ): void {
+    const values = schema["enum"];
+    if (Array.isArray(values) && !values.some((one) => canonical(one) === canonical(value))) {
+      refuse("enum", `${canonical(value)} is not one of the values the schema lists`);
+    }
+    if (schema["const"] !== undefined && canonical(schema["const"]) !== canonical(value)) {
+      refuse("const", `${canonical(value)} is not ${canonical(schema["const"])}`);
+    }
+    if (typeof value === "string") {
+      if (typeof schema["pattern"] === "string" && !pattern(schema["pattern"]).test(value)) {
+        refuse("pattern", `${JSON.stringify(value)} does not match ${schema["pattern"]}`);
+      }
+      if (typeof schema["minLength"] === "number" && codePoints(value) < schema["minLength"]) {
+        refuse(
+          "minLength",
+          `${JSON.stringify(value)} is shorter than ${String(schema["minLength"])} characters`,
+        );
+      }
+    }
+    if (typeof value === "number") {
+      if (typeof schema["minimum"] === "number" && value < schema["minimum"]) {
+        refuse("minimum", `${String(value)} is below ${String(schema["minimum"])}`);
+      }
+      if (typeof schema["maximum"] === "number" && value > schema["maximum"]) {
+        refuse("maximum", `${String(value)} is above ${String(schema["maximum"])}`);
+      }
+    }
+  }
+
+  private checkObject(
+    doc: string,
+    schema: Schema,
+    value: Readonly<Record<string, unknown>>,
+    at: string,
+    found: SchemaRefusal[],
+    refuse: (keyword: string, reason: string) => void,
+  ): void {
+    const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+    const additional = schema["additionalProperties"];
+    for (const name of Object.keys(value).sort(bytewise)) {
+      const member = `${at}/${escape(name)}`;
+      const declared = properties[name];
+      if (isRecord(declared)) {
+        this.check(doc, declared, value[name], member, found);
+      } else if (additional === false) {
+        refuse(
+          "additionalProperties",
+          `the member ${JSON.stringify(name)} is not one the schema declares`,
+        );
+      } else if (isRecord(additional)) {
+        this.check(doc, additional, value[name], member, found);
+      }
+    }
+    for (const name of Array.isArray(schema["required"]) ? (schema["required"] as string[]) : []) {
+      if (!Object.hasOwn(value, name)) {
+        refuse("required", `the member ${JSON.stringify(name)} is absent`);
+      }
+    }
+    const fewest = schema["minProperties"];
+    if (typeof fewest === "number" && Object.keys(value).length < fewest) {
+      refuse(
+        "minProperties",
+        `the object holds ${String(Object.keys(value).length)} members, fewer than ${String(fewest)}`,
+      );
+    }
+  }
+
+  private checkArray(
+    doc: string,
+    schema: Schema,
+    value: readonly unknown[],
+    at: string,
+    found: SchemaRefusal[],
+    refuse: (keyword: string, reason: string) => void,
+  ): void {
+    const items = schema["items"];
+    if (isRecord(items)) {
+      value.forEach((item, i) => {
+        this.check(doc, items, item, `${at}/${String(i)}`, found);
+      });
+    }
+    if (typeof schema["minItems"] === "number" && value.length < schema["minItems"]) {
+      refuse(
+        "minItems",
+        `the array holds ${String(value.length)} items, fewer than ${String(schema["minItems"])}`,
+      );
+    }
+    if (typeof schema["maxItems"] === "number" && value.length > schema["maxItems"]) {
+      refuse(
+        "maxItems",
+        `the array holds ${String(value.length)} items, more than ${String(schema["maxItems"])}`,
+      );
+    }
+    if (schema["uniqueItems"] === true && new Set(value.map(canonical)).size !== value.length) {
+      refuse("uniqueItems", "the array lists one value twice");
+    }
+  }
+
+  private checkApplicators(
+    doc: string,
+    schema: Schema,
+    value: unknown,
+    at: string,
+    found: SchemaRefusal[],
+    refuse: (keyword: string, reason: string) => void,
+  ): void {
+    const list = (keyword: string): readonly Schema[] =>
+      Array.isArray(schema[keyword]) ? (schema[keyword] as Schema[]) : [];
+    for (const each of list("allOf")) {
+      this.check(doc, each, value, at, found);
+    }
+    const matching = (keyword: string): number =>
+      list(keyword).filter((each) => this.matches(doc, each, value, at)).length;
+    if (schema["anyOf"] !== undefined && matching("anyOf") === 0) {
+      refuse("anyOf", "the value matches none of the alternatives");
+    }
+    if (schema["oneOf"] !== undefined && matching("oneOf") !== 1) {
+      refuse(
+        "oneOf",
+        `the value matches ${String(matching("oneOf"))} of the alternatives, want exactly one`,
+      );
+    }
+    if (isRecord(schema["not"]) && this.matches(doc, schema["not"], value, at)) {
+      refuse("not", "the value matches a schema it must not match");
+    }
+    if (isRecord(schema["if"])) {
+      const branch = this.matches(doc, schema["if"], value, at) ? schema["then"] : schema["else"];
+      if (isRecord(branch)) {
+        this.check(doc, branch, value, at, found);
+      }
+    }
+  }
+}
+
+/**
+ * A validator over one set of schema documents, each named as a `$ref` names it, rooted
+ * at one of them: what it refuses in a value, none for an instance.
+ */
+export function schemaRefusals(
+  documents: Documents,
+  root: string,
+): (value: unknown) => readonly SchemaRefusal[] {
+  const checker = new Checker(documents);
+  const top = documents[root];
+  if (top === undefined) {
+    throw new Error(`the schema set holds no document ${root}`);
+  }
+  return (value) => {
+    const found: SchemaRefusal[] = [];
+    checker.check(root, top, value, "", found);
+    return found;
+  };
+}
+
+const reportSchema = schemaRefusals(REPORT_SCHEMAS, "report.schema.json");
+
+/**
+ * What the report schema refuses in one report document, none for an instance, and, as
+ * no schema keyword can state it, a components listing that is not one entry per
+ * component a finding or an edge evaluation's finding names.
+ */
+export function reportRefusals(document: unknown): readonly SchemaRefusal[] {
+  const found = reportSchema(document);
+  return found.length > 0 ? found : listingRefusals(document as Report);
+}
+
+/** The components listing held to the components the findings name, once each. */
+function listingRefusals(report: Report): readonly SchemaRefusal[] {
+  if (report.components === undefined) {
+    return [];
+  }
+  const refuse = (pointer: string, reason: string): SchemaRefusal[] => [
+    { pointer, keyword: "components", reason },
+  ];
+  const listed = new Set<string>();
+  for (const [i, entry] of report.components.entries()) {
+    if (listed.has(entry.id)) {
+      return refuse(
+        `/components/${String(i)}`,
+        `the entry lists component ${entry.id} a second time`,
+      );
+    }
+    listed.add(entry.id);
+  }
+  const named = [
+    ...report.findings.map(
+      (finding, i) => [`/findings/${String(i)}`, finding.component.id] as const,
+    ),
+    ...report.edge_evaluations.flatMap((one, i) =>
+      one.finding === undefined
+        ? []
+        : [[`/edge_evaluations/${String(i)}/finding`, one.finding.component.id] as const],
+    ),
+  ];
+  for (const [pointer, id] of named) {
+    if (!listed.has(id)) {
+      return refuse(
+        pointer,
+        `the finding names component ${id}, which the components listing lacks`,
+      );
+    }
+  }
+  const ids = new Set(named.map(([, id]) => id));
+  for (const [i, entry] of report.components.entries()) {
+    if (!ids.has(entry.id)) {
+      return refuse(
+        `/components/${String(i)}`,
+        `the entry lists component ${entry.id}, which no finding names`,
+      );
+    }
+  }
+  return [];
+}