@avi2dg/checks 0.42.0 → 0.44.0

package/src/docs/copy-html.ts

@@ -0,0 +1,110 @@
+import { Effect, Schema } from "effect";
+import { HtmlElement, HtmlValidate, Rule, StaticConfigLoader, TextNode, staticResolver, type DOMReadyEvent, type Plugin } from "html-validate";
+import { collecting, separatorFindings, type Collector, type CopyFinding, type Place } from "./copy-text.ts";
+
+const PLUGIN = "copy";
+const RULE = `${PLUGIN}/separators`;
+
+const UNREAD: ReadonlySet<string> = new Set(["script", "style", "template", "pre"]);
+const CODE: ReadonlySet<string> = new Set(["code", "kbd", "samp", "var"]);
+const TEXT_ATTRIBUTES = ["alt", "title", "placeholder", "aria-label", "aria-description"] as const;
+const BUTTON_TYPES: ReadonlySet<string> = new Set(["submit", "button", "reset"]);
+const LABELLED: ReadonlySet<string> = new Set(["option", "optgroup"]);
+const META_COPY: ReadonlySet<string> = new Set(["description", "og:title", "og:description", "twitter:title", "twitter:description"]);
+
+// Code stands in as one character that is neither a letter nor a space, so a hyphen after it still reads as spaced.
+const HIDDEN = "\0";
+
+const NAMED: Readonly<Record<string, string>> = { mdash: "—", ndash: "–", nbsp: "\u00a0" };
+const ENTITY = /^&(?:#(\d{1,7})|#[xX]([0-9a-fA-F]{1,6})|([A-Za-z][A-Za-z0-9]{1,31}));/;
+const LARGEST_CODE_POINT = 0x10ffff;
+
+function decoded([, decimal, hex, name]: RegExpExecArray): string {
+  const point = decimal === undefined ? (hex === undefined ? undefined : Number.parseInt(hex, 16)) : Number(decimal);
+  if (point === undefined) return NAMED[name ?? ""] ?? HIDDEN;
+  return point > 0 && point <= LARGEST_CODE_POINT ? String.fromCodePoint(point) : HIDDEN;
+}
+
+function addSource(collector: Collector, source: string, from: Place): void {
+  let { line, column } = from;
+  let at = 0;
+  while (at < source.length) {
+    const entity = source.charAt(at) === "&" ? ENTITY.exec(source.slice(at)) : null;
+    const char = entity === null ? source.charAt(at) : decoded(entity);
+    const length = entity === null ? 1 : entity[0].length;
+    collector.add(char, { line, column });
+    if (char === "\n") {
+      line += 1;
+      column = 1;
+    } else column += length;
+    at += length;
+  }
+}
+
+function addAttribute(element: HtmlElement, key: string, attributes: Collector): void {
+  const attribute = element.getAttribute(key);
+  if (attribute === null || typeof attribute.value !== "string" || attribute.valueLocation === null) return;
+  addSource(attributes, attribute.value, attribute.valueLocation);
+  attributes.end();
+}
+
+function readAttributes(element: HtmlElement, attributes: Collector): void {
+  for (const key of TEXT_ATTRIBUTES) addAttribute(element, key, attributes);
+  const named = element.getAttributeValue("name") ?? element.getAttributeValue("property");
+  if (element.tagName === "meta" && named !== null && META_COPY.has(named)) addAttribute(element, "content", attributes);
+  const type = element.getAttributeValue("type")?.toLowerCase();
+  if (element.tagName === "input" && type !== undefined && BUTTON_TYPES.has(type)) addAttribute(element, "value", attributes);
+  if (LABELLED.has(element.tagName)) addAttribute(element, "label", attributes);
+}
+
+function readElement(element: HtmlElement, text: Collector, attributes: Collector): void {
+  readAttributes(element, attributes);
+  const inline = element.meta?.phrasing === true && element.tagName !== "br";
+  if (!inline) text.end();
+  if (CODE.has(element.tagName)) text.add(HIDDEN, element.location);
+  else if (!UNREAD.has(element.tagName)) readChildren(element, text, attributes);
+  if (!inline) text.end();
+}
+
+function readChildren(element: HtmlElement, text: Collector, attributes: Collector): void {
+  for (const child of element.childNodes) {
+    if (child instanceof TextNode) addSource(text, child.textContent, child.location);
+    else if (child instanceof HtmlElement) readElement(child, text, attributes);
+  }
+}
+
+class Separators extends Rule {
+  override setup(): void {
+    this.on("dom:ready", ({ document, source }: DOMReadyEvent) => {
+      const text = collecting();
+      const attributes = collecting();
+      readChildren(document.root, text, attributes);
+      for (const { line, column, message } of separatorFindings([...text.blocks(), ...attributes.blocks()])) {
+        this.report(null, message, { filename: source.filename, line, column, offset: 0, size: 1 });
+      }
+    });
+  }
+}
+
+const plugin: Plugin = { name: PLUGIN, rules: { [RULE]: Separators } };
+
+const validator = new HtmlValidate(
+  new StaticConfigLoader([staticResolver({ plugins: { [PLUGIN]: plugin } })], {
+    root: true,
+    elements: ["html5", { svg: { foreign: false }, math: { foreign: false } }],
+    plugins: [PLUGIN],
+    rules: { [RULE]: "error" },
+  }),
+);
+
+class CopyHtmlError extends Schema.TaggedError<CopyHtmlError>()("CopyHtmlError", { message: Schema.String }) {}
+
+export const htmlFindings = Effect.fn("htmlFindings")(function* (source: string, file: string) {
+  const { results } = yield* Effect.tryPromise({
+    try: () => validator.validateString(source, file),
+    catch: (cause) => new CopyHtmlError({ message: `html-validate cannot read ${file}: ${String(cause)}` }),
+  });
+  return results.flatMap(({ messages }) =>
+    messages.map(({ line, column, message, ruleId }) => ({ line, column, message: ruleId === RULE ? message : `does not parse as HTML: ${message}` })),
+  ) satisfies readonly CopyFinding[];
+});

package/src/docs/copy-text.ts

@@ -0,0 +1,70 @@
+import { bodyOf, carries, continues, scanMarkdown, SEPARATORS, type LineKind } from "./prose-matchers.ts";
+
+export type Place = { readonly line: number; readonly column: number };
+
+export type CopyFinding = Place & { readonly message: string };
+
+// Each place is the source position of the character at the same index in text.
+type Block = { readonly text: string; readonly places: readonly Place[] };
+
+export type Collector = {
+  readonly add: (char: string, place: Place) => void;
+  readonly end: () => void;
+  readonly blocks: () => readonly Block[];
+};
+
+const SPACE = /\s/;
+
+// A reader sees each run of white space as one space, so a hyphen wrapped onto the next line still reads as spaced.
+export function collecting(): Collector {
+  const done: Block[] = [];
+  let text = "";
+  let places: Place[] = [];
+  const add = (char: string, place: Place): void => {
+    const spaced = SPACE.test(char);
+    if (spaced && (text === "" || text.endsWith(" "))) return;
+    text += spaced ? " " : char;
+    places.push(place);
+  };
+  const end = (): void => {
+    if (text.trim() !== "") done.push({ text, places });
+    text = "";
+    places = [];
+  };
+  return {
+    add,
+    end,
+    blocks: () => {
+      end();
+      return done;
+    },
+  };
+}
+
+function blockFindings({ text, places }: Block): readonly CopyFinding[] {
+  return SEPARATORS.flatMap((rule) =>
+    [...text.matchAll(rule.find)].flatMap((match) => {
+      const place = places[match.index + match[0].length - match[0].trimStart().length];
+      return place === undefined ? [] : [{ ...place, message: carries(match[0], rule) }];
+    }),
+  );
+}
+
+export function separatorFindings(blocks: readonly Block[]): readonly CopyFinding[] {
+  return blocks.flatMap(blockFindings).toSorted((a, b) => a.line - b.line || a.column - b.column);
+}
+
+const READ_KINDS: ReadonlySet<LineKind> = new Set(["prose", "heading", "table", "html"]);
+
+export function markdownFindings(text: string): readonly CopyFinding[] {
+  const lines = scanMarkdown(text);
+  const collector = collecting();
+  for (const [index, line] of lines.entries()) {
+    if (!continues(lines[index - 1], line)) collector.end();
+    if (!READ_KINDS.has(line.kind)) continue;
+    const body = bodyOf(line);
+    for (let at = 0; at < body.length; at += 1) collector.add(body.charAt(at), { line: line.line, column: at + 1 });
+    collector.add("\n", { line: line.line, column: body.length + 1 });
+  }
+  return separatorFindings(collector.blocks());
+}

package/src/docs/copy.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { emptyInputs, inputsReport, runDeclaredGate, violationLine, type Declared, type Input, type Violation } from "../core/declared-inputs.ts";
+import { Usage } from "../core/main.ts";
+import { markdownFindings } from "./copy-text.ts";
+
+const DECLARED: Declared = { name: "copy", file: "copy.json", declares: "copy" };
+
+const MARKDOWN = ".md";
+const HTML = ".html";
+
+const OUTSIDE = /(?:^|\/)node_modules\//;
+
+export type Scan = {
+  readonly inputs: readonly Input[];
+  readonly unread: readonly string[];
+  readonly violations: readonly Violation[];
+};
+
+class CopyError extends Schema.TaggedError<CopyError>()("CopyError", {
+  message: Schema.String,
+}) {}
+
+function isCopyFile(file: string): boolean {
+  return file.endsWith(MARKDOWN) || file.endsWith(HTML);
+}
+
+const matched = (root: string, glob: string) =>
+  Effect.tryPromise({
+    try: () => Array.fromAsync(new Bun.Glob(glob).scan({ cwd: root, onlyFiles: true })),
+    catch: (cause) => new CopyError({ message: `cannot expand ${glob}: ${String(cause)}` }),
+  }).pipe(Effect.map((files) => files.filter((file) => !OUTSIDE.test(file)).toSorted()));
+
+const loadHtml = Effect.tryPromise({
+  try: () => import("./copy-html.ts"),
+  catch: () => new Usage({ message: `cannot load html-validate, which a repository that declares HTML in ${DECLARED.file} installs beside the kit as an optional peer` }),
+});
+
+const judge = Effect.fn("judge")(function* (root: string, file: string) {
+  const source = yield* (yield* FileSystem.FileSystem).readFileString((yield* Path.Path).join(root, file));
+  const findings = file.endsWith(HTML) ? yield* (yield* loadHtml).htmlFindings(source, file) : markdownFindings(source);
+  return findings.map(({ line, column, message }) => ({ file, line, column, text: message }) satisfies Violation);
+});
+
+export const scanInputs = Effect.fn("scanInputs")(function* (root: string, globs: readonly string[]) {
+  const inputs: Input[] = [];
+  const unread = new Set<string>();
+  for (const glob of globs) {
+    const files = yield* matched(root, glob);
+    inputs.push({ glob, files: files.filter(isCopyFile) });
+    for (const other of files.filter((file) => !isCopyFile(file))) unread.add(other);
+  }
+  const judged = [...new Set(inputs.flatMap(({ files }) => files))].toSorted();
+  const violations = yield* Effect.forEach(judged, (file) => judge(root, file));
+  return { inputs, unread: [...unread].toSorted(), violations: violations.flat() } satisfies Scan;
+});
+
+export function passes({ inputs, unread, violations }: Scan): boolean {
+  return violations.length === 0 && unread.length === 0 && emptyInputs(inputs).length === 0;
+}
+
+export function report({ inputs, unread, violations }: Scan): string {
+  return inputsReport(DECLARED.name, inputs, [
+    ...emptyInputs(inputs).map(({ glob }) => `${glob}: the declared input matches no Markdown or HTML file`),
+    ...unread.map((file) => `${file}: is neither Markdown nor HTML, so the gate cannot read it`),
+    ...violations.map(violationLine),
+  ]);
+}
+
+if (import.meta.main) runDeclaredGate(DECLARED, scanInputs, { report, passes });

package/src/docs/prose-matchers.ts

@@ -20,7 +20,7 @@ export type ProseRule = {
   readonly instead: string;
 };
 
-type MatchedRule = ProseRule & { readonly find: RegExp };
+export type MatchedRule = ProseRule & { readonly find: RegExp };
 
 export const ADR_DIRECTORY = "docs/adr/";
 export const DOCS_DIRECTORY = "docs/";
@@ -268,9 +268,15 @@ const code = (text: string): string => `\`${text}\``;
 const EVERY_READER: readonly Reader[] = ["people", "agents"];
 const PEOPLE: readonly Reader[] = ["people"];
 
+const EM_DASH: MatchedRule = { readers: EVERY_READER, refuses: "an em dash", example: code("—"), instead: SEPARATOR_INSTEAD, find: /—/g };
+const EN_DASH: MatchedRule = { readers: EVERY_READER, refuses: "an en dash", example: code("–"), instead: SEPARATOR_INSTEAD, find: /–/g };
+const HYPHEN_AS_DASH: MatchedRule = { readers: EVERY_READER, refuses: "a hyphen used as a dash", example: `${code("a - b")} or ${code("a -- b")}`,
+  instead: SEPARATOR_INSTEAD, find: /(?<=[^\s|]) -{1,3} (?=[^\s|])/g };
+export const SEPARATORS: readonly MatchedRule[] = [EM_DASH, EN_DASH, HYPHEN_AS_DASH];
+
 const RULES: readonly MatchedRule[] = [
-  { readers: EVERY_READER, refuses: "an em dash", example: code("—"), instead: SEPARATOR_INSTEAD, find: /—/g },
-  { readers: EVERY_READER, refuses: "an en dash", example: code("–"), instead: SEPARATOR_INSTEAD, find: /–/g },
+  EM_DASH,
+  EN_DASH,
   {
     readers: EVERY_READER,
     refuses: "a parenthesis other than the plural `(s)`",
@@ -278,13 +284,7 @@ const RULES: readonly MatchedRule[] = [
     instead: "Make the aside its own sentence, or set it off with commas",
     find: /\((?!s\))/g,
   },
-  {
-    readers: EVERY_READER,
-    refuses: "a hyphen used as a dash",
-    example: `${code("a - b")} or ${code("a -- b")}`,
-    instead: SEPARATOR_INSTEAD,
-    find: /(?<=[^\s|]) -{1,3} (?=[^\s|])/g,
-  },
+  HYPHEN_AS_DASH,
   { readers: EVERY_READER, refuses: "a semicolon", example: code(";"), instead: "Use two sentences", find: /;/g },
   {
     readers: PEOPLE,
@@ -328,11 +328,11 @@ export const PROSE_RULES: readonly ProseRule[] = [
 
 const JUDGED_KINDS: ReadonlySet<LineKind> = new Set(["prose", "heading", "table", "html"]);
 
+export const carries = (match: string, { refuses, instead }: ProseRule): string => `carries \`${match.trim()}\`, ${refuses}. ${instead}`;
+
 function ruleFindings(line: MarkdownLine, reader: Reader): ProseFinding[] {
   const body = bodyOf(line);
-  return RULES.filter(({ readers }) => readers.includes(reader)).flatMap(({ refuses, instead, find }) =>
-    [...body.matchAll(find)].map(([match]) => ({ line: line.line, message: `carries \`${match.trim()}\`, ${refuses}. ${instead}` })),
-  );
+  return RULES.filter(({ readers }) => readers.includes(reader)).flatMap((rule) => [...body.matchAll(rule.find)].map(([match]) => ({ line: line.line, message: carries(match, rule) })));
 }
 
 const SENTENCE_BREAK = /(?<=[^\s.!?])[.!?]["'”’»)\]*_]*\s+(?=[\p{Lu}"“«*_[\0])/gu;
@@ -364,7 +364,7 @@ function endsMidSentence(line: MarkdownLine, next: MarkdownLine): boolean {
   return !body.endsWith(HIDDEN) || OPENS_LOWERCASE.test(bodyOf(next));
 }
 
-function continues(earlier: MarkdownLine | undefined, later: MarkdownLine | undefined): boolean {
+export function continues(earlier: MarkdownLine | undefined, later: MarkdownLine | undefined): boolean {
   if (earlier?.kind !== "prose" || later?.kind !== "prose" || LIST_ITEM.test(later.raw)) return false;
   return QUOTE_DEPTH.exec(earlier.raw)?.[0].split(">").length === QUOTE_DEPTH.exec(later.raw)?.[0].split(">").length;
 }

package/src/quality/frontend-syntax.ts

@@ -1,11 +1,10 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Effect, Path, Schema } from "effect";
 import type { LintResult } from "stylelint";
-import { runMain, Usage } from "../core/main.ts";
+import { emptyInputs, inputsReport, runDeclaredGate, violationLine, type Declared, type Input, type Violation } from "../core/declared-inputs.ts";
+import { Usage } from "../core/main.ts";
 
-const NAME = "frontend-syntax";
-
-const DECLARATION = "frontend-syntax.json";
+const DECLARED: Declared = { name: "frontend-syntax", file: "frontend-syntax.json", declares: "inputs" };
 
 const TRANSITION_ALL = "declaration-property-value-disallowed-list";
 const BODY_WIDE_USER_SELECT = "rule-selector-property-disallowed-list";
@@ -24,22 +23,6 @@ const ADVICE: Readonly<Record<string, string>> = {
 
 const MARKUP = ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
 
-const Declaration = Schema.Struct({ inputs: Schema.NonEmptyArray(Schema.NonEmptyString) });
-
-const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
-
-export type Violation = {
-  readonly file: string;
-  readonly line: number;
-  readonly column: number;
-  readonly text: string;
-};
-
-export type Input = {
-  readonly glob: string;
-  readonly files: readonly string[];
-};
-
 export type Scan = {
   readonly inputs: readonly Input[];
   readonly violations: readonly Violation[];
@@ -59,20 +42,9 @@ const loadPeer = <A>(name: string, load: () => Promise<A>) =>
   Effect.tryPromise({
     try: load,
     catch: () =>
-      new Usage({ message: `cannot load ${name}, which a repository that declares ${DECLARATION} installs beside the kit as an optional peer` }),
+      new Usage({ message: `cannot load ${name}, which a repository that declares ${DECLARED.file} installs beside the kit as an optional peer` }),
   });
 
-const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const file = (yield* Path.Path).join(root, DECLARATION);
-  if (!(yield* fs.exists(file))) {
-    return yield* new Usage({ message: `${DECLARATION} is missing, and a repository opts in to this gate by declaring its inputs there` });
-  }
-  return yield* decodeDeclaration(yield* fs.readFileString(file)).pipe(
-    Effect.mapError(({ message }) => new Usage({ message: `${DECLARATION} does not decode: ${message}` })),
-  );
-});
-
 function violationsOf(result: LintResult, relative: (file: string) => string): readonly Violation[] {
   const file = relative(result.source ?? "");
   return result.warnings.map(({ line, column, rule, text }) => ({
@@ -112,27 +84,12 @@ export const scanInputs = Effect.fn("scanInputs")(function* (root: string, globs
 });
 
 export function passes({ inputs, violations }: Scan): boolean {
-  return violations.length === 0 && inputs.every(({ files }) => files.length > 0);
+  return violations.length === 0 && emptyInputs(inputs).length === 0;
 }
 
 export function report({ inputs, violations }: Scan): string {
-  const files = new Set(inputs.flatMap((input) => input.files)).size;
-  const scanned = `${files} file(s) from ${inputs.length} declared input(s)`;
-  const empty = inputs.filter((input) => input.files.length === 0);
-  if (violations.length === 0 && empty.length === 0) return `${NAME}: no violation in ${scanned}`;
-  return [
-    `${NAME}: ${violations.length + empty.length} problem(s) in ${scanned}:`,
-    ...empty.map(({ glob }) => `  ${glob}: the declared input matches no file`),
-    ...violations.map(({ file, line, column, text }) => `  ${file}:${line}:${column} ${text}`),
-  ].join("\n");
+  const empty = emptyInputs(inputs).map(({ glob }) => `${glob}: the declared input matches no file`);
+  return inputsReport(DECLARED.name, inputs, [...empty, ...violations.map(violationLine)]);
 }
 
-const gate = Effect.gen(function* () {
-  const root = (yield* Path.Path).resolve(process.argv[2] ?? ".");
-  const { inputs } = yield* readDeclaration(root);
-  const scan = yield* scanInputs(root, inputs);
-  yield* Console.log(report(scan));
-  return passes(scan);
-});
-
-if (import.meta.main) runMain(NAME, gate);
+if (import.meta.main) runDeclaredGate(DECLARED, scanInputs, { report, passes });

package/src/quality/no-plain-js.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+import { Console, Effect, Schema } from "effect";
+import { workingTreeFiles } from "../core/git.ts";
+import { runMain } from "../core/main.ts";
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+const NAME = "no-plain-js";
+
+const PLAIN_SOURCE = /\.m?js$/;
+
+const UNJUDGED_PREFIXES = ["dist/", "node_modules/", "repos/", "public/", "tests/fixtures/"] as const;
+
+const GENERATED_CONFIG = "dependency-cruiser.config.js";
+
+const SHIPPED_PRESET = "stryker.preset.js";
+
+const STRYKER_CONFIG = /^\.?stryker\.(?:conf|config)\.(?:js|mjs|cjs)$/;
+
+function baseNameOf(file: string): string {
+  return file.slice(file.lastIndexOf("/") + 1);
+}
+
+export function isExempt(file: string): boolean {
+  if (UNJUDGED_PREFIXES.some((prefix) => file.startsWith(prefix))) return true;
+  if (file === GENERATED_CONFIG) return true;
+  const base = baseNameOf(file);
+  return base === SHIPPED_PRESET || STRYKER_CONFIG.test(base);
+}
+
+export function violationsOf(files: readonly string[]): readonly Violation[] {
+  return files
+    .filter((file) => PLAIN_SOURCE.test(file) && !isExempt(file))
+    .toSorted()
+    .map((file) => ({
+      file,
+      line: undefined,
+      message: "plain JavaScript source in a TypeScript repository; convert it to TypeScript",
+    }));
+}
+
+class NoPlainJsError extends Schema.TaggedError<NoPlainJsError>()("NoPlainJsError", {
+  message: Schema.String,
+}) {}
+
+export type Result = { readonly files: number; readonly violations: readonly Violation[] };
+
+export const run = Effect.fn("run")(function* (root: string) {
+  const files = yield* workingTreeFiles(root).pipe(
+    Effect.mapError((cause) => new NoPlainJsError({ message: cause.message })),
+  );
+  return { files: files.length, violations: violationsOf(files) } satisfies Result;
+});
+
+export function report({ files, violations }: Result): string {
+  if (violations.length === 0) return `${NAME}: no plain JavaScript sources among ${files} tracked file(s)`;
+  return [`${NAME}: ${violations.length} violation(s)`, ...violations.map(({ file, message }) => `  ${file}: ${message}`)].join("\n");
+}
+
+const noPlainJs = Effect.gen(function* () {
+  const root = process.argv[2] ?? process.cwd();
+  const result = yield* run(root);
+  yield* Console.log(report(result));
+  return result.violations.length === 0;
+});
+
+if (import.meta.main) runMain(NAME, noPlainJs);

package/src/testing/flake-preload.ts

@@ -0,0 +1,4 @@
+import { appendFileSync } from "node:fs";
+
+const log = process.env["CHECKS_FLAKE_WORKER_LOG"];
+if (log !== undefined) appendFileSync(log, `${JSON.stringify({ worker: process.pid, file: Bun.main })}\n`);