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

package/src/exempt-classes.ts

@@ -1,123 +0,0 @@
-/**
- * The exemption classes of the Contract's vocabulary, in its order: each class's name, its
- * languages and, for a TypeScript class, which private members it may retain. The rows are
- * written out, as the fixed severity codes are, and a test holds them equal to the Contract.
- * A class name is a type, so a table or a record naming a class outside the vocabulary, or
- * one of another language only, does not compile.
- */
-
-import type { Language } from "./config.ts";
-
-/**
- * Whether a class may retain a member declared with the `private` modifier, and one
- * declared with a `#private` name. The modifier is a compile-time constraint only, so
- * such a member stays reachable by its name at run time; a private name cannot be
- * named from outside its class body at all.
- */
-export interface TypeScriptVisibility {
-  readonly private: boolean;
-  readonly privateName: boolean;
-}
-
-/** One class of the vocabulary. */
-interface ExemptionClassRow {
-  readonly class: string;
-  readonly languages: readonly Language[];
-  /** Present exactly on a class that runs on TypeScript. */
-  readonly typescriptVisibility?: TypeScriptVisibility;
-}
-
-/** Every class of the vocabulary, in the order the Contract lists them. */
-export const EXEMPTION_CLASSES = [
-  {
-    class: "interface-satisfaction",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: false, privateName: false },
-  },
-  { class: "encoding-reflection", languages: ["go"] },
-  { class: "format-verb-contract", languages: ["go"] },
-  { class: "errors-duck-typing", languages: ["go"] },
-  {
-    class: "enum-group",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: false, privateName: false },
-  },
-  {
-    class: "generated-file",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  { class: "linkname-cgo-asm-plugin", languages: ["go"] },
-  {
-    class: "template-field",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "reflective-lookup",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "decorator",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "injection-container",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "framework-lifecycle",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "serialization-contract",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-] as const satisfies readonly ExemptionClassRow[];
-
-type Row = (typeof EXEMPTION_CLASSES)[number];
-
-/** The name of a class of the vocabulary. */
-export type ExemptionClass = Row["class"];
-
-/** The classes of the rows that list one language. */
-type ClassesOf<R, L extends Language> = R extends {
-  readonly class: infer C;
-  readonly languages: readonly (infer Listed)[];
-}
-  ? L extends Listed
-    ? C
-    : never
-  : never;
-
-/** The name of a class that runs on TypeScript, the only classes this analyzer records. */
-export type TSExemptionClass = ClassesOf<Row, "ts">;
-
-function runsOnTS(row: Row): row is Extract<Row, { readonly class: TSExemptionClass }> {
-  const languages: readonly Language[] = row.languages;
-  return languages.includes("ts");
-}
-
-const TS_ROWS = EXEMPTION_CLASSES.filter(runsOnTS);
-
-/** The classes that run on TypeScript, in the vocabulary's order. */
-export const TS_EXEMPTION_CLASSES: readonly TSExemptionClass[] = TS_ROWS.map((row) => row.class);
-
-const VISIBILITY: ReadonlyMap<TSExemptionClass, TypeScriptVisibility> = new Map(
-  TS_ROWS.map((row) => [row.class, row.typescriptVisibility]),
-);
-
-/** Which private members one class that runs on TypeScript may retain. */
-export function typescriptVisibilityOf(exemptionClass: TSExemptionClass): TypeScriptVisibility {
-  return VISIBILITY.get(exemptionClass) ?? { private: false, privateName: false };
-}
-
-/** Whether one name is a class of the vocabulary, whichever language it runs on. */
-export function isExemptionClass(name: string): name is ExemptionClass {
-  return EXEMPTION_CLASSES.some((row) => row.class === name);
-}

package/src/exempt.ts

@@ -1,323 +0,0 @@
-/**
- * The exemption framework: the classes of reason for which a declaration the reference
- * graph alone would report is live all the same. A class is policy over what one
- * project's checker answers, and its detector names the declarations it holds back;
- * this module runs the detectors, decides which of their records stand, and answers
- * which records held something back. It names no class's detector: the composition
- * hands it the table of the classes it has.
- */
-
-import type { Config, TSSection } from "./config.ts";
-import { ConfigError } from "./config.ts";
-import {
-  EXEMPTION_CLASSES,
-  isExemptionClass,
-  TS_EXEMPTION_CLASSES,
-  typescriptVisibilityOf,
-  type ExemptionClass,
-  type TSExemptionClass,
-  type TypeScriptVisibility,
-} from "./exempt-classes.ts";
-import type { Inventory, InventorySymbol, SymbolKind, Visibility } from "./inventory.ts";
-import type { Matrix } from "./matrix.ts";
-import { byPosition, positionKey, type Position } from "./position.ts";
-import { Unanswerable } from "./query.ts";
-import type { ProjectView } from "./session.ts";
-import type { Templates } from "./template-field.ts";
-import { sweep, type Exemption, type Implementing, type Mode, type SweepInput } from "./sweep.ts";
-
-/** One declaration a detector holds back, and where and why. */
-export interface Evidence {
-  /** The identifier of the declaration held back. */
-  readonly id: string;
-  /** One clause naming the relation, then the thing it relates to. */
-  readonly detail: string;
-  readonly site: Position;
-  /** The component file, below the target root, whose markup holds the evidence. */
-  readonly whileLive?: string;
-  /** Where the evidence is an implementation of interface methods, which and how. */
-  readonly implementing?: Implementing;
-}
-
-/** What a detector reads of one project, while the project's view is open. */
-export interface DetectorInput<Brand> {
-  readonly project: ProjectView<Brand>;
-  readonly held: Inventory;
-  readonly targetRoot: string;
-  /** The configured templates, read once for the run. */
-  readonly templates: Templates;
-  /** The `ts` section, whose declarations the configured classes read. */
-  readonly ts: TSSection;
-  /** The absolute path of each declared consumer, whose modules are part of the analysis. */
-  readonly consumers: readonly string[];
-  /** The project's generated files, by path below the target root, each with the detail its retentions name. */
-  readonly generated?: ReadonlyMap<string, string>;
-}
-
-/**
- * One class's detection over one project. The framework records each piece of evidence
- * under the class the table names the detector by, so a detector names no class.
- */
-export type Detector = <Brand>(input: DetectorInput<Brand>) => readonly Evidence[];
-
-/** The detector of each class one composition implements. */
-export type Detectors = ReadonlyMap<TSExemptionClass, Detector>;
-
-/** What decides which records of one project stand. */
-interface Holding {
-  readonly mode: Mode;
-  /** The paths the reference pass classified as test files. */
-  readonly testFiles: ReadonlySet<string>;
-}
-
-/**
- * The classes `exemptions.disabled` switches off. A name is refused unless the
- * vocabulary holds it; a class that runs on another language only is admitted and
- * switches nothing off here, so one configuration serves every analyzer.
- */
-export function disabledClasses(config: Config): ReadonlySet<ExemptionClass> {
-  const disabled = new Set<ExemptionClass>();
-  for (const name of config.exemptionsDisabled) {
-    if (!isExemptionClass(name)) {
-      const known = EXEMPTION_CLASSES.map((row) => row.class).join(", ");
-      throw new ConfigError(
-        "malformed",
-        "exemptions.disabled",
-        `exemptions.disabled: ${JSON.stringify(name)} is not an exemption class: the classes are ${known}`,
-      );
-    }
-    disabled.add(name);
-  }
-  return disabled;
-}
-
-/**
- * Whether a class whose row states `allowed` may retain a member of one visibility. A
- * declaration the inventory does not hold has no visibility to refuse it by.
- */
-function retainable(allowed: TypeScriptVisibility, visibility: Visibility | undefined): boolean {
-  if (visibility === "private") {
-    return allowed.private;
-  }
-  if (visibility === "private-name") {
-    return allowed.privateName;
-  }
-  return true;
-}
-
-/**
- * The kinds of declaration each class can hold back, which a detector that stops holds
- * back whole. A class with no row here holds back every declaration but a file.
- */
-const RETAINABLE: ReadonlyMap<TSExemptionClass, ReadonlySet<SymbolKind>> = new Map([
-  ["interface-satisfaction", new Set<SymbolKind>(["method", "class-member"])],
-  ["enum-group", new Set<SymbolKind>(["enum-member"])],
-  ["injection-container", new Set<SymbolKind>(["method", "class-member"])],
-  ["framework-lifecycle", new Set<SymbolKind>(["method", "class-member"])],
-  [
-    "serialization-contract",
-    new Set<SymbolKind>(["method", "class-member", "interface-method", "type-member"]),
-  ],
-]);
-
-/** The detail of a record a detector that could not finish holds. */
-const UNANSWERED_DETAIL = "kept live by a question the checker did not answer";
-
-/** Whether one record is held by a detector that could not finish. */
-export function isUnansweredRecord(record: Exemption): boolean {
-  return record.detail === UNANSWERED_DETAIL;
-}
-
-/**
- * What one detector holds back over one project. A detector that stops because the
- * checker left a question it needs unanswered holds back every declaration of the
- * project its class could hold back, each recorded at its own position, so the gap
- * never yields a finding.
- */
-function detected<Brand>(
-  exemptionClass: TSExemptionClass,
-  detect: Detector,
-  input: DetectorInput<Brand>,
-): readonly Evidence[] {
-  try {
-    return detect(input);
-  } catch (error: unknown) {
-    if (!(error instanceof Unanswerable)) {
-      throw error;
-    }
-    const kinds = RETAINABLE.get(exemptionClass);
-    return input.held.symbols
-      .filter((symbol) => (kinds === undefined ? symbol.kind !== "file" : kinds.has(symbol.kind)))
-      .map((symbol) => ({ id: symbol.id, detail: UNANSWERED_DETAIL, site: symbol.position }));
-  }
-}
-
-/** One project's records, and the evidence a production mode found in a test file. */
-interface Detected {
-  readonly records: readonly Exemption[];
-  /**
-   * Under a production mode, each record whose evidence is written in a test file. It
-   * holds nothing, and it is a test reference to its declaration, as a reference the
-   * test file wrote would be.
-   */
-  readonly inTestFiles: readonly Exemption[];
-}
-
-/**
- * Every record one project's detectors found, one per piece of evidence, before the
- * mode decides which of them hold: what {@link heldRecords} reads. Classes run in the
- * vocabulary's order and a switched-off class runs not at all; evidence on a private
- * member the class's row says it cannot retain is dropped, whatever the detector found.
- */
-export function evidenceRecords<Brand>(
-  input: DetectorInput<Brand>,
-  detectors: Detectors,
-  disabled: ReadonlySet<ExemptionClass>,
-): readonly Exemption[] {
-  const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
-  const found: Exemption[] = [];
-  for (const exemptionClass of TS_EXEMPTION_CLASSES) {
-    const detect = detectors.get(exemptionClass);
-    if (detect === undefined || disabled.has(exemptionClass)) {
-      continue;
-    }
-    const allowed = typescriptVisibilityOf(exemptionClass);
-    for (const evidence of detected(exemptionClass, detect, input)) {
-      if (!retainable(allowed, visibility.get(evidence.id))) {
-        continue;
-      }
-      found.push({
-        id: evidence.id,
-        class: exemptionClass,
-        detail: evidence.detail,
-        site: evidence.site,
-        ...(evidence.whileLive === undefined ? {} : { whileLive: evidence.whileLive }),
-        ...(evidence.implementing === undefined ? {} : { implementing: evidence.implementing }),
-      });
-    }
-  }
-  return found;
-}
-
-/** The records that hold under one mode, beside the evidence a production mode found in a test file. */
-export function heldRecords(records: readonly Exemption[], holding: Holding): Detected {
-  const found: Exemption[] = [];
-  const inTestFiles: Exemption[] = [];
-  for (const record of records) {
-    if (holding.mode.production && holding.testFiles.has(record.site.path)) {
-      inTestFiles.push(record);
-    } else {
-      found.push(record);
-    }
-  }
-  return { records: exemptionsOf(found), inTestFiles };
-}
-
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
-/**
- * Records as a run holds them: ordered by site, then class, then declaration, and one
- * per declaration, class, detail and file it holds while live, the one at the first
- * site. A fact found at many sites, or by several projects, is one record.
- */
-export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[] {
-  const ordered = [...found].sort(
-    (a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id),
-  );
-  const seen = new Set<string>();
-  return ordered.filter((record) => {
-    const fact = [record.id, record.class, record.detail, record.whileLive ?? ""].join("\u0000");
-    if (seen.has(fact)) {
-      return false;
-    }
-    seen.add(fact);
-    return true;
-  });
-}
-
-/**
- * The records that hold while the component files at `live` are live: every record that
- * holds whatever is live, and each one a live file's markup holds, as a record of the run.
- */
-export function holdingWhile(
-  records: readonly Exemption[],
-  live: ReadonlySet<string>,
-): readonly Exemption[] {
-  return exemptionsOf(
-    records.flatMap(({ whileLive, ...record }) =>
-      whileLive === undefined || live.has(whileLive) ? [record] : [],
-    ),
-  );
-}
-
-/** The records per declaration, each declaration's in the order given. */
-function byDeclaration(records: readonly Exemption[]): ReadonlyMap<string, readonly Exemption[]> {
-  const grouped = new Map<string, Exemption[]>();
-  for (const record of records) {
-    const held = grouped.get(record.id);
-    if (held === undefined) {
-      grouped.set(record.id, [record]);
-    } else {
-      held.push(record);
-    }
-  }
-  return grouped;
-}
-
-/**
- * The records that held back a declaration: one some configuration's graph, swept
- * again with no exemption and its marks, judges a candidate, whatever another
- * configuration answers, or one in `writeOnly`, which the run would report as written
- * and never read without the record's read. A declaration a relation or a mark holds
- * live in every configuration is held back by no record. The order is the
- * declarations' site order, and for one declaration the input's.
- */
-export function retainedIn(
-  matrix: Matrix,
-  input: SweepInput,
-  writeOnly: ReadonlySet<string> = new Set(),
-): readonly Exemption[] {
-  const exempt = input.exempt ?? [];
-  if (exempt.length === 0) {
-    return [];
-  }
-  const bare: SweepInput = { marked: input.marked, mode: input.mode };
-  const dead = new Set(
-    matrix.graphs.flatMap((graph) =>
-      sweep(graph, bare).candidates.map((candidate) => candidate.id),
-    ),
-  );
-  const held = byDeclaration(
-    exempt.filter((record) => dead.has(record.id) || writeOnly.has(record.id)),
-  );
-  return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
-}
-
-/**
- * One line per held-back declaration, in site order: its reference, then each record's
- * class, site and detail, all separated by tabs.
- */
-export function retainedLines(
-  symbols: readonly InventorySymbol[],
-  retained: readonly Exemption[],
-): readonly string[] {
-  const held = byDeclaration(retained);
-  return symbols.flatMap((symbol) => {
-    const records = held.get(symbol.id);
-    if (records === undefined) {
-      return [];
-    }
-    const fields = records.flatMap((record) => [
-      record.class,
-      positionKey(record.site),
-      record.detail,
-    ]);
-    return [[symbol.ref, ...fields].join("\t")];
-  });
-}

package/src/generated-file.ts

@@ -1,111 +0,0 @@
-/**
- * The generated-file class on TypeScript: every declaration in a file that marks itself
- * generated, or below a directory an applied convention row names as generated, is
- * retained, because a generator owns the file and a deletion there is undone at the next
- * generation.
- */
-
-import type { DetectorInput, Evidence } from "./exempt.ts";
-import type { SourceFiles } from "./source-files.ts";
-
-/** The generated-code header, matched against each line of a leading comment. */
-const HEADER_LINE = /^\/\/ Code generated .* DO NOT EDIT\.$/u;
-
-/** The documentation tag `@generated` as a word of a comment. */
-const GENERATED_TAG = /(?<![\w@$])@generated(?![\w$-])/u;
-
-/** A first comment naming the tool that wrote the file. */
-const GENERATED_BY = /^\/\/ Generated by \S/u;
-
-/** The word a generator's notice holds, beside one of {@link KEEP_OUT}. */
-const GENERATED_WORD = /\bgenerated\b/iu;
-
-/** The phrases a generator's notice asks a reader not to edit the file by. */
-const KEEP_OUT = /\b(?:do not edit|will be overwritten|should not make any changes)\b/iu;
-
-/** The comments before a text's first token, a leading hashbang line skipped. */
-function leadingComments(text: string): readonly string[] {
-  const comments: string[] = [];
-  let at = text.startsWith("\uFEFF") ? 1 : 0;
-  if (text.startsWith("#!", at)) {
-    const end = text.indexOf("\n", at);
-    at = end === -1 ? text.length : end + 1;
-  }
-  for (;;) {
-    while (at < text.length && /\s/u.test(text.charAt(at))) {
-      at++;
-    }
-    if (text.startsWith("//", at)) {
-      const end = text.slice(at).search(/[\r\n\u2028\u2029]/u);
-      const stop = end === -1 ? text.length : at + end;
-      comments.push(text.slice(at, stop));
-      at = stop;
-    } else if (text.startsWith("/*", at)) {
-      const end = text.indexOf("*/", at + 2);
-      if (end === -1) {
-        return comments;
-      }
-      comments.push(text.slice(at, end + 2));
-      at = end + 2;
-    } else {
-      return comments;
-    }
-  }
-}
-
-/** The detail a file's leading comments mark it generated by, or undefined where they mark nothing. */
-export function generatedByComment(text: string): string | undefined {
-  const comments = leadingComments(text);
-  if (comments.some((one) => one.split(/\r?\n/u).some((line) => HEADER_LINE.test(line)))) {
-    return "generated by the header line its leading comments hold";
-  }
-  if (comments.some((one) => GENERATED_TAG.test(one))) {
-    return "generated by the @generated tag its leading comments hold";
-  }
-  const notice = comments.join("\n");
-  if (
-    GENERATED_BY.test(comments[0] ?? "") ||
-    (GENERATED_WORD.test(notice) && KEEP_OUT.test(notice))
-  ) {
-    return "generated by the notice its leading comments hold";
-  }
-  return undefined;
-}
-
-/**
- * Every own file of one project that is generated, by its path below the target root,
- * with the detail a retention in it names: its leading comments' mark, else the row
- * naming its directory as generated.
- */
-export function generatedFilesOf(
-  files: SourceFiles,
-  byRow: ReadonlyMap<string, string>,
-): ReadonlyMap<string, string> {
-  const found = new Map<string, string>();
-  for (const [path, file] of files.byPath) {
-    const row = byRow.get(path);
-    const detail =
-      generatedByComment(file.text) ??
-      (row === undefined
-        ? undefined
-        : `generated below a directory the convention row ${row} names`);
-    if (detail !== undefined) {
-      found.set(path, detail);
-    }
-  }
-  return found;
-}
-
-/** The generated-file detector, recording each file's first line. */
-export function generatedFile<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
-  const generated = input.generated;
-  if (generated === undefined || generated.size === 0) {
-    return [];
-  }
-  return input.held.symbols.flatMap((symbol): Evidence[] => {
-    const detail = generated.get(symbol.position.path);
-    return symbol.kind === "file" || detail === undefined
-      ? []
-      : [{ id: symbol.id, detail, site: { path: symbol.position.path, line: 1, column: 1 } }];
-  });
-}

package/src/glob.ts

@@ -1,67 +0,0 @@
-/**
- * Glob patterns over the paths of the target's own files, as the configuration
- * writes them. Both `ts.test_files` and `ts.entry_files` name files this way, and
- * one grammar answers for both.
- *
- * A configured root is not written in this grammar. It names a symbol reference
- * rather than a path, `*` there spans the solidus and a brace list means nothing,
- * so that rule is written where it is read.
- */
-
-/**
- * One literal run of a pattern, with every character the expression syntax claims
- * escaped.
- *
- * The set is the syntax characters and the solidus, and it is closed: an escape of any
- * other character is refused outright by the expression syntax under the unicode flag,
- * so escaping a hyphen, which needs none outside a character class, would refuse every
- * pattern that names a hyphenated path.
- */
-function quoted(text: string): string {
-  return text.replaceAll(/[.*+?^${}()|[\]\\/]/gu, (character) => `\\${character}`);
-}
-
-/**
- * The expression one glob pattern denotes. `**` spans path separators while `*` and `?`
- * do not, a brace list is an alternation of its members, and every other character
- * stands for itself.
- */
-export function globExpression(pattern: string): RegExp {
-  let source = "^";
-  let at = 0;
-  while (at < pattern.length) {
-    const rest = pattern.slice(at);
-    if (rest.startsWith("**/")) {
-      source += "(?:[^/]*/)*";
-      at += 3;
-      continue;
-    }
-    if (rest.startsWith("**")) {
-      source += ".*";
-      at += 2;
-      continue;
-    }
-    const character = pattern[at] ?? "";
-    at += 1;
-    if (character === "*") {
-      source += "[^/]*";
-      continue;
-    }
-    if (character === "?") {
-      source += "[^/]";
-      continue;
-    }
-    if (character === "{") {
-      const close = pattern.indexOf("}", at);
-      if (close < 0) {
-        source += "\\{";
-        continue;
-      }
-      source += `(?:${pattern.slice(at, close).split(",").map(quoted).join("|")})`;
-      at = close + 1;
-      continue;
-    }
-    source += quoted(character);
-  }
-  return new RegExp(`${source}$`, "u");
-}