@cplieger/deadset-ts 3.2.0 → 3.3.1

package/src/template-field.ts

@@ -0,0 +1,214 @@
+/**
+ * The template-field class: a member is held back, at the lowest confidence, when a
+ * template under a configured template directory writes its name inside an action,
+ * because a template engine reads the member by that name at run time.
+ *
+ * Every file under a configured directory is a template. An action runs from an
+ * opening delimiter to the first closing one after it, at the pair
+ * `analysis.template_delimiters` sets, `{{` and `}}` by default, and each identifier
+ * it writes outside a quoted string is a name it reads: `{{ user.name }}` names `user`
+ * and `name`. A file holding an unclosed action names nothing. A name reaches the
+ * instance members of classes and the members of interfaces and object types, on any
+ * type, because nothing ties the name to a type.
+ */
+
+import { ConfigError, type Analysis, type TemplateDelimiters } from "./config.ts";
+import type { DetectorInput, Evidence } from "./exempt.ts";
+import type { Host } from "./host.ts";
+import type { SymbolKind } from "./inventory.ts";
+import { memberNames } from "./member-names.ts";
+import { isAbsolutePath, joinPath, normalizePath } from "./paths.ts";
+import type { Position } from "./position.ts";
+
+/** One template, by its path below the target root. */
+export interface TemplateFile {
+  readonly path: string;
+  readonly text: string;
+}
+
+/** The templates one run scans, and the pair their actions are written with. */
+export interface Templates {
+  readonly delimiters: TemplateDelimiters;
+  readonly files: readonly TemplateFile[];
+}
+
+/** The kinds of declaration an action can name. */
+const READ_BY_A_TEMPLATE: ReadonlySet<SymbolKind> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+]);
+
+/** One identifier, as the grammar of the analyzed language spells one. */
+const IDENTIFIER = /[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*/uy;
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Every template under the configured directories, read once for the run, in path
+ * order and each file once. A directory is named relative to the target root, and
+ * one the target does not hold refuses the run as a usage error: the class would
+ * scan nothing, so a name that no longer matches the tree would silently switch the
+ * exemption it was configured for off. A symbolic link to a directory is not
+ * followed.
+ */
+export function readTemplates(host: Host, targetRoot: string, analysis: Analysis): Templates {
+  const files = new Map<string, string>();
+  const read = (dir: string): void => {
+    const entries = [...host.readDirectory(joinPath(targetRoot, dir))].sort((a, b) =>
+      compare(a.name, b.name),
+    );
+    for (const entry of entries) {
+      const path = joinPath(dir, entry.name);
+      if (entry.directory) {
+        read(path);
+        continue;
+      }
+      const absolute = joinPath(targetRoot, path);
+      if (!files.has(path) && host.kindOf(absolute) === "file") {
+        files.set(path, host.readFile(absolute));
+      }
+    }
+  };
+  for (const configured of analysis.templateDirs) {
+    const dir = normalizePath(configured);
+    if (
+      isAbsolutePath(dir) ||
+      dir === ".." ||
+      dir.startsWith("../") ||
+      host.kindOf(joinPath(targetRoot, dir)) !== "directory"
+    ) {
+      throw new ConfigError(
+        "malformed",
+        "analysis.template_dirs",
+        `analysis.template_dirs: ${JSON.stringify(configured)} is not a directory below the target root`,
+      );
+    }
+    read(dir);
+  }
+  return {
+    delimiters: analysis.templateDelimiters,
+    files: [...files]
+      .map(([path, text]) => ({ path, text }))
+      .sort((a, b) => compare(a.path, b.path)),
+  };
+}
+
+/** One identifier an action writes, where it is written, and the action that writes it. */
+interface Named {
+  readonly name: string;
+  readonly offset: number;
+  readonly action: string;
+}
+
+/** The end of the quoted string that opens at `from`, past its closing quote. */
+function stringEnd(text: string, from: number): number {
+  const quote = text[from];
+  let at = from + 1;
+  while (at < text.length && text[at] !== quote) {
+    at += text[at] === "\\" ? 2 : 1;
+  }
+  return at + 1;
+}
+
+/** The identifiers one action's inner text writes outside a quoted string, with their offsets in it. */
+function identifiersOf(inner: string): readonly { name: string; offset: number }[] {
+  const found: { name: string; offset: number }[] = [];
+  let at = 0;
+  while (at < inner.length) {
+    const char = inner[at] ?? "";
+    if (char === '"' || char === "'" || char === "`") {
+      at = stringEnd(inner, at);
+      continue;
+    }
+    if (/[0-9]/u.test(char)) {
+      // A number's letters are part of the number: `1e3` names nothing.
+      while (at < inner.length && /[0-9A-Za-z_.]/u.test(inner[at] ?? "")) {
+        at += 1;
+      }
+      continue;
+    }
+    IDENTIFIER.lastIndex = at;
+    const match = IDENTIFIER.exec(inner);
+    if (match !== null) {
+      found.push({ name: match[0], offset: at });
+      at += match[0].length;
+      continue;
+    }
+    at += 1;
+  }
+  return found;
+}
+
+/**
+ * Every identifier one template's actions write, in the order the file writes them,
+ * or none where an action is not closed.
+ */
+function namesOf(text: string, delimiters: TemplateDelimiters): readonly Named[] {
+  const found: Named[] = [];
+  let from = 0;
+  for (;;) {
+    const open = text.indexOf(delimiters.left, from);
+    if (open < 0) {
+      return found;
+    }
+    const start = open + delimiters.left.length;
+    const close = text.indexOf(delimiters.right, start);
+    if (close < 0) {
+      return [];
+    }
+    const inner = text.slice(start, close);
+    const action = `${delimiters.left}${inner.trim().replace(/\s+/gu, " ")}${delimiters.right}`;
+    for (const { name, offset } of identifiersOf(inner)) {
+      found.push({ name, offset: start + offset, action });
+    }
+    from = close + delimiters.right.length;
+  }
+}
+
+/** Where one offset of a template is, its column counted in UTF-16 code units. */
+function positionIn(file: TemplateFile, offset: number): Position {
+  const before = file.text.slice(0, offset);
+  const lineStart = before.lastIndexOf("\n") + 1;
+  return {
+    path: file.path,
+    line: before.split("\n").length,
+    column: offset - lineStart + 1,
+  };
+}
+
+/**
+ * The template-field detector: every instance member of a class and every member of
+ * an interface or an object type whose name an action of a configured template
+ * writes, recorded at the identifier.
+ */
+export function templateField<Brand>(input: DetectorInput<Brand>): readonly Evidence[] {
+  const { templates } = input;
+  if (templates.files.length === 0) {
+    return [];
+  }
+  const members = memberNames(input.project.ownSourceFiles(), input.held);
+  const found: Evidence[] = [];
+  for (const file of templates.files) {
+    for (const named of namesOf(file.text, templates.delimiters)) {
+      for (const member of members.get(named.name) ?? []) {
+        if (!READ_BY_A_TEMPLATE.has(member.kind) || member.static) {
+          continue;
+        }
+        found.push({
+          id: member.id,
+          detail: `named by ${named.action}`,
+          site: positionIn(file, named.offset),
+        });
+      }
+    }
+  }
+  return found;
+}

package/src/verbs/print-config.ts

@@ -0,0 +1,10 @@
+import { printConfig } from "../print.ts";
+import { resolve } from "../resolve.ts";
+import { EXIT_CLEAN, type Verb } from "./verb.ts";
+
+/** Writes the resolved configuration with the source of every setting. */
+export const printConfigVerb: Verb = ({ out, inputs }) => {
+  const { config, provenance } = resolve(inputs());
+  out.write(printConfig(config, provenance));
+  return EXIT_CLEAN;
+};

package/src/verbs/print-projects.ts

@@ -0,0 +1,35 @@
+import { diagnosticErrors, discoverProjects, renderDiagnostic } from "../discover.ts";
+import { resolveMatrix } from "../resolve.ts";
+import { diagnosticsOf, runSession } from "../session.ts";
+import { EXIT_CLEAN, EXIT_FAILURE, type Verb } from "./verb.ts";
+
+/**
+ * Writes the name of every project one run analyzes, one per line, having read each
+ * project's diagnostics first: the identifier the build matrix declares for it, or,
+ * where discovery derived the project, its configuration file's path below the
+ * target root.
+ */
+export const printProjectsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
+  const matrix = resolveMatrix(inputs());
+  const scoped = scope();
+  const engine = openClient(false);
+  const discovered = discoverProjects(engine, host, scoped, matrix);
+  const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+  const failures: string[] = [];
+  const { projects } = runSession(engine, discovered.configFiles, (project) => {
+    const errors = diagnosticErrors(diagnosticsOf(project));
+    failures.push(...errors.map(renderDiagnostic));
+    return ids.get(project.configFile) ?? project.configFile;
+  });
+  if (failures.length > 0) {
+    for (const line of failures) {
+      err.write(`${line}\n`);
+    }
+    err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
+    return EXIT_FAILURE;
+  }
+  for (const id of projects) {
+    out.write(`${id}\n`);
+  }
+  return EXIT_CLEAN;
+};

package/src/verbs/print-retained.ts

@@ -0,0 +1,24 @@
+import { runSweep } from "../analysis.ts";
+import { retainedLines } from "../exempt.ts";
+import { resolve } from "../resolve.ts";
+import { EXIT_CLEAN, type Verb } from "./verb.ts";
+
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+export const printRetainedVerb: Verb = ({ out, host, inputs, scope, openClient }) => {
+  const { config } = resolve(inputs());
+  const scoped = scope();
+  const swept = runSweep(openClient(false), host, scoped, config, {
+    marked: [],
+    mode: { production: true },
+  });
+  for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+    out.write(`${line}\n`);
+  }
+  return EXIT_CLEAN;
+};

package/src/verbs/print-roots.ts

@@ -0,0 +1,38 @@
+import { runRoots, type RunRoot } from "../analysis.ts";
+import { resolve } from "../resolve.ts";
+import { EXIT_CLEAN, EXIT_FINDINGS, type Verb } from "./verb.ts";
+
+/**
+ * One root as a line: the declaration's reference, why it is a root, and the string
+ * that named it, separated by tabs. A run of several configurations adds the ones
+ * whose project holds the root as a fourth field, and writes the third present and
+ * empty where no string named the root, so every line of one run holds the same
+ * fields.
+ */
+function rootLine(root: RunRoot, several: boolean): string {
+  const line = `${root.ref}\t${root.kind}`;
+  if (several) {
+    return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
+  }
+  return root.source === "" ? line : `${line}\t${root.source}`;
+}
+
+/**
+ * Writes the root set of the run, one root per line, and then names on the error
+ * stream, by its issue kind, every configured root or pattern that named nothing;
+ * one such string fails the run. The line shape is this command's own rather than a
+ * Contract format, so that sort and cut read it.
+ */
+export const printRootsVerb: Verb = ({ out, err, host, inputs, scope, openClient }) => {
+  const { config, provenance } = resolve(inputs());
+  const scoped = scope();
+  const answer = runRoots(openClient(false), host, scoped, config, provenance);
+  const several = answer.configurations.length > 1;
+  for (const root of answer.roots) {
+    out.write(`${rootLine(root, several)}\n`);
+  }
+  for (const finding of answer.findings) {
+    err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
+  }
+  return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
+};

package/src/verbs/verb.ts

@@ -0,0 +1,38 @@
+import type { Inputs } from "../config.ts";
+import type { Emitters } from "../findings/emitter.ts";
+import type { Host } from "../host.ts";
+import type { Writer } from "../run.ts";
+import type { Scope } from "../scope.ts";
+import type { Engine } from "../session.ts";
+
+/** The exit codes the Contract's exit-code table names. */
+export const EXIT_CLEAN = 0;
+export const EXIT_FINDINGS = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_FAILURE = 3;
+
+/**
+ * What one verb is handed: the streams it writes, the platform it reads, and the
+ * options that follow its name, read only when the verb asks for what they name, so
+ * a verb that asks for nothing refuses no option.
+ */
+export interface Invocation {
+  readonly out: Writer;
+  readonly err: Writer;
+  readonly host: Host;
+  /** The configuration documents the options name, and the settings they supply. */
+  readonly inputs: () => Inputs;
+  /** The scope the options name: the document `--scope` names, or the target. */
+  readonly scope: () => Scope;
+  /** Opens the compiler client. A client the verb opened is closed if the verb throws. */
+  readonly openClient: (collectTiming: boolean) => Engine;
+  /** The emitter of every kind family, which a verb that reports findings runs. */
+  readonly emitters: Emitters;
+}
+
+/**
+ * One verb of the command line. It returns the exit code, and refuses by throwing a
+ * configuration, discovery or scope error, which the command line writes and turns
+ * into the code the Contract's table gives it.
+ */
+export type Verb = (invocation: Invocation) => number;

package/src/verbs/version.ts

@@ -0,0 +1,8 @@
+import { CONTRACT_VERSION } from "../version.ts";
+import { EXIT_CLEAN, type Verb } from "./verb.ts";
+
+/** Writes the version the host reports and the Contract version this analyzer implements. */
+export const versionVerb: Verb = ({ out, host }) => {
+  out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
+  return EXIT_CLEAN;
+};