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

package/src/report-schema.ts

@@ -1,309 +1,11 @@
 /**
  * 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.
+ * this analyzer never writes a document a reader refuses.
  */
 
 import { REPORT_SCHEMAS, type Report } from "./contract/report.generated.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 isObject(value: unknown): value is Readonly<Record<string, unknown>> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-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 (isObject(value)) {
-    return `{${Object.keys(value)
-      .sort()
-      .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 = isObject(schema)
-        ? schema[token.replaceAll("~1", "/").replaceAll("~0", "~")]
-        : undefined;
-    }
-    if (!isObject(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 (isObject(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 = isObject(schema["properties"]) ? schema["properties"] : {};
-    const additional = schema["additionalProperties"];
-    for (const name of Object.keys(value).sort()) {
-      const member = `${at}/${escape(name)}`;
-      const declared = properties[name];
-      if (isObject(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 (isObject(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 (isObject(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 (isObject(schema["not"]) && this.matches(doc, schema["not"], value, at)) {
-      refuse("not", "the value matches a schema it must not match");
-    }
-    if (isObject(schema["if"])) {
-      const branch = this.matches(doc, schema["if"], value, at) ? schema["then"] : schema["else"];
-      if (isObject(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;
-  };
-}
+import { schemaRefusals, type SchemaRefusal } from "./schema.ts";
 
 const reportSchema = schemaRefusals(REPORT_SCHEMAS, "report.schema.json");
 
@@ -323,7 +25,7 @@ function listingRefusals(report: Report): readonly SchemaRefusal[] {
     return [];
   }
   const refuse = (pointer: string, reason: string): SchemaRefusal[] => [
-    { pointer, keyword: "components", reason },
+    { pointer, keyword: "components", reason, member: "" },
   ];
   const listed = new Set<string>();
   for (const [i, entry] of report.components.entries()) {

package/src/report.ts

@@ -19,12 +19,8 @@ import type { AppliedConvention } from "./conventions.ts";
 import type { PassResult } from "./findings-pass.ts";
 import type { StaleSuppression } from "./findings/self-check.ts";
 import type { TestFileRule } from "./references.ts";
-
-/** The name this analyzer writes every document under and mints every identifier with. */
-export const ANALYZER_NAME = "deadset-ts";
-
-/** The language this analyzer claims. */
-export const LANGUAGE = "ts";
+import { bytewise } from "./text/compare.ts";
+import { LANGUAGE, PRODUCT } from "./product.ts";
 
 /** One project configuration of the matrix a run analyzed. */
 export interface ReportConfiguration {
@@ -131,14 +127,6 @@ function componentsOf(
   return [...listed.values()];
 }
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 function wirePosition(position: FindingPosition): wire.Position {
   return {
     path: position.path,
@@ -257,22 +245,22 @@ function wireStale(stale: StaleSuppression): wire.StaleSuppressionsEntry {
 /** The canonical key over two findings: path, line, column, code, then the symbol reference. */
 function canonical(a: wire.Finding, b: wire.Finding): number {
   return (
-    compare(a.position.path, b.position.path) ||
+    bytewise(a.position.path, b.position.path) ||
     a.position.line - b.position.line ||
     a.position.column - b.position.column ||
-    compare(a.code, b.code) ||
-    compare(a.symbol.ref, b.symbol.ref)
+    bytewise(a.code, b.code) ||
+    bytewise(a.symbol.ref, b.symbol.ref)
   );
 }
 
 /** The canonical key over two stale suppressions, each component from the record's own member. */
 function canonicalStale(a: wire.StaleSuppressionsEntry, b: wire.StaleSuppressionsEntry): number {
   return (
-    compare(a.position.path, b.position.path) ||
+    bytewise(a.position.path, b.position.path) ||
     a.position.line - b.position.line ||
     a.position.column - b.position.column ||
-    compare(a.code, b.code) ||
-    compare(a.symbol, b.symbol)
+    bytewise(a.code, b.code) ||
+    bytewise(a.symbol, b.symbol)
   );
 }
 
@@ -289,9 +277,9 @@ function wireGap(gap: DeclaredGap): wire.DeclaredGapsEntry {
 /** Edge evaluations by edge, then side, then their compact encodings. */
 function byEdge(a: wire.EdgeEvaluationsEntry, b: wire.EdgeEvaluationsEntry): number {
   return (
-    compare(a.edge, b.edge) ||
-    compare(a.side, b.side) ||
-    compare(JSON.stringify(a), JSON.stringify(b))
+    bytewise(a.edge, b.edge) ||
+    bytewise(a.side, b.side) ||
+    bytewise(JSON.stringify(a), JSON.stringify(b))
   );
 }
 
@@ -346,16 +334,16 @@ export function buildReport(input: ReportInput): wire.Report {
     one.finding === undefined ? [] : [[wireFinding(one.finding), one.finding] as const],
   );
   const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
-    .sort((a, b) => compare(a.id, b.id))
+    .sort((a, b) => bytewise(a.id, b.id))
     .map((one) => ({ id: one.id, role: "consumer" as const, reason: one.reason }));
   const loaded = [...input.loaded]
-    .sort((a, b) => compare(a.id, b.id) || compare(a.path, b.path))
+    .sort((a, b) => bytewise(a.id, b.id) || bytewise(a.path, b.path))
     .map((one) => ({ id: one.id, role: "consumer" as const, path: one.path }));
   return {
     schema_version: SCHEMA_VERSION,
     contract_version: input.contractVersion,
     analyzer: {
-      name: ANALYZER_NAME,
+      name: PRODUCT,
       version: input.version,
       languages: [LANGUAGE],
       schema_versions_accepted: SCHEMA_VERSIONS,
@@ -367,10 +355,10 @@ export function buildReport(input: ReportInput): wire.Report {
     },
     target: { kind: input.target.kind, root: input.target.root, identity: input.target.identity },
     configurations: [...input.configurations]
-      .sort((a, b) => compare(a.id, b.id))
+      .sort((a, b) => bytewise(a.id, b.id))
       .map((one) => ({ id: one.id, project: one.project })),
     configurations_not_built: [...input.notBuilt]
-      .sort((a, b) => compare(a.id, b.id))
+      .sort((a, b) => bytewise(a.id, b.id))
       .map((one) => ({ id: one.id, project: one.project, error: one.error })),
     consumers: { declared: loaded.length + unavailable.length, loaded, unavailable },
     findings,
@@ -383,10 +371,10 @@ export function buildReport(input: ReportInput): wire.Report {
     // name, so the compact encodings alone order them.
     declared_gaps: input.declaredGaps
       .map(wireGap)
-      .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))),
+      .sort((a, b) => bytewise(JSON.stringify(a), JSON.stringify(b))),
     excluded_by_cgo: [],
     test_file_rules: [...input.testFileRules]
-      .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)
+      .sort((a, b) => bytewise(a.rule, b.rule) || a.matched - b.matched)
       .map((one) => ({ rule: one.rule, matched: one.matched })),
     type_error_skips: [
       ...new Map(
@@ -396,16 +384,18 @@ export function buildReport(input: ReportInput): wire.Report {
         }),
       ),
     ]
-      .sort(([a, x], [b, y]) => compare(x.path, y.path) || x.line - y.line || compare(a, b))
+      .sort(([a, x], [b, y]) => bytewise(x.path, y.path) || x.line - y.line || bytewise(a, b))
       .map(([, skip]) => skip),
     notes: [...new Map((input.notes ?? []).map((one) => [JSON.stringify(one), one])).entries()]
-      .sort(([a, x], [b, y]) => compare(x.kind, y.kind) || compare(x.path, y.path) || compare(a, b))
+      .sort(
+        ([a, x], [b, y]) => bytewise(x.kind, y.kind) || bytewise(x.path, y.path) || bytewise(a, b),
+      )
       .map(([, note]) => note),
     unanswered_questions: [...input.unanswered]
       .sort(
         (a, b) =>
-          compare(a.configuration, b.configuration) ||
-          compare(JSON.stringify(a), JSON.stringify(b)),
+          bytewise(a.configuration, b.configuration) ||
+          bytewise(JSON.stringify(a), JSON.stringify(b)),
       )
       .map((one) => ({
         configuration: one.configuration,

package/src/reporters/sarif.ts

@@ -12,6 +12,8 @@ import { lineHashes, symbolFingerprint } from "./fingerprint.ts";
 import { RenderError, type RenderOptions } from "./reporter.ts";
 import { utf8Bytes } from "./sha256.ts";
 import { withheldLine } from "./text.ts";
+import { bytewise } from "../text/compare.ts";
+import { message } from "../product.ts";
 
 const SCHEMA =
   "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json";
@@ -133,9 +135,7 @@ function lineHashCache(read: (path: string) => string): (at: Located) => string
       try {
         text = read(at.path);
       } catch (error: unknown) {
-        throw new RenderError(
-          `read ${at.path} for its line fingerprint: ${error instanceof Error ? error.message : String(error)}`,
-        );
+        throw new RenderError(`read ${at.path} for its line fingerprint: ${message(error)}`);
       }
       hashes = lineHashes(text);
       held.set(at.path, hashes);
@@ -292,7 +292,7 @@ export function sarif(report: Report, options: RenderOptions): Iterable<string>
     ...report.findings.map((found) => findingResult(found, index, hashOf, members)),
     ...report.stale_suppressions.map((stale) => staleResult(stale, index, hashOf)),
   ];
-  const languages = [...report.analyzer.languages].sort().join("+");
+  const languages = [...report.analyzer.languages].sort(bytewise).join("+");
   const withheld = withheldLine(report.totals);
   const log = {
     $schema: SCHEMA,

package/src/reporters/template.ts

@@ -10,6 +10,7 @@
 import { CHUNK_LENGTH } from "../json-chunks.ts";
 import { RenderError } from "./reporter.ts";
 import { utf8Bytes } from "./sha256.ts";
+import { bytewise } from "../text/compare.ts";
 
 /** A template that does not parse, which refuses the invocation before any analysis. */
 export class TemplateError extends Error {
@@ -618,7 +619,7 @@ function formatted(value: Value, nested: boolean): string {
   }
   const object: ValueObject = value;
   const entries = Object.keys(object)
-    .sort()
+    .sort(bytewise)
     .map((key) => `${key}:${formatted(object[key] ?? null, true)}`);
   return `map[${entries.join(" ")}]`;
 }
@@ -647,28 +648,11 @@ function compareBasic(name: string, a: Value, b: Value): number {
     return Number.NaN;
   }
   if (kind === "string") {
-    return byCodePoints(a as string, b as string);
+    return bytewise(a as string, b as string);
   }
   return (a as number) < (b as number) ? -1 : 1;
 }
 
-/**
- * Two strings ordered by the bytes of their UTF-8 encodings, which is the order of their
- * code points: the order of their UTF-16 code units differs above U+FFFF.
- */
-function byCodePoints(a: string, b: string): number {
-  let at = 0;
-  while (at < a.length && at < b.length) {
-    const x = a.codePointAt(at) ?? 0;
-    const y = b.codePointAt(at) ?? 0;
-    if (x !== y) {
-      return x < y ? -1 : 1;
-    }
-    at += x > 0xffff ? 2 : 1;
-  }
-  return a.length - b.length;
-}
-
 /** The escapes `%q` writes for the control characters that have one of their own. */
 const QUOTED_ESCAPES: Readonly<Record<string, string>> = {
   '"': '\\"',
@@ -1022,7 +1006,7 @@ class Execution {
         entries = value.map((one, i) => [i, one]);
       } else if (isObject(value)) {
         entries = Object.keys(value)
-          .sort()
+          .sort(bytewise)
           .map((key) => [key, value[key] ?? null]);
       } else {
         throw new RenderError(`range cannot iterate over a ${kindOf(value)}`);