@avi2dg/checks 0.43.0 → 0.45.0

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/comment-matchers.ts

@@ -40,6 +40,7 @@ const SQL: Syntax = { line: DASHES, block: SLASHES, quotes: STRINGS, regexLitera
 const LUA: Syntax = { line: DASHES, block: [["--[[", "]]"]], quotes: STRINGS, regexLiterals: false };
 const HASKELL: Syntax = { line: DASHES, block: [["{-", "-}"]], quotes: [escaping('"')], regexLiterals: false };
 const ML: Syntax = { line: [], block: [["(*", "*)"]], quotes: [escaping('"')], regexLiterals: false };
+const CSS: Syntax = { line: [], block: SLASHES, quotes: STRINGS, regexLiterals: false };
 
 export const SYNTAXES: Readonly<Record<string, Syntax>> = {
   ts: JS,
@@ -78,6 +79,7 @@ export const SYNTAXES: Readonly<Record<string, Syntax>> = {
   yml: YAML,
   toml: HASH,
   ml: ML,
+  css: CSS,
 };
 
 const extensionOf = (path: string): string => path.slice(path.lastIndexOf(".") + 1);
@@ -247,13 +249,14 @@ export const REFUSED_DIRECTIVES = [
   "biome-ignore",
   "eslint-disable",
   "prettier-ignore",
+  "stylelint-disable",
 ] as const satisfies readonly string[];
 
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 const directiveSource = (name: string): string => {
   const escaped = escapeRegExp(name);
-  if (name === "eslint-disable") return `\\b${escaped}[\\w-]*`;
+  if (name.endsWith("-disable")) return `\\b${escaped}[\\w-]*`;
   return /^[\w]/.test(name) ? `\\b${escaped}\\b` : escaped;
 };
 

package/src/quality/frontend-syntax.ts

@@ -1,43 +1,36 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import type { LintResult } from "stylelint";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import type { Config, LinterOptions, LintResult } from "stylelint";
+import { declaredGate, emptyInputs, inputsReport, violationLine, type Declared, type Input, type Violation } from "../core/declared-inputs.ts";
 import { runMain, Usage } from "../core/main.ts";
+import { MARKUP } from "./presets/stylelint.ts";
 
-const NAME = "frontend-syntax";
+const DECLARED: Declared = { name: "frontend-syntax", file: "frontend-syntax.json", declares: "inputs" };
 
-const DECLARATION = "frontend-syntax.json";
+const STYLELINT_CONFIG = "stylelint.config.ts";
+
+const USAGE = "usage: frontend-syntax.ts [--fix] [--suppress] [<directory>]";
 
 const TRANSITION_ALL = "declaration-property-value-disallowed-list";
 const BODY_WIDE_USER_SELECT = "rule-selector-property-disallowed-list";
 const UNPARSED = "CssSyntaxError";
+const UNPARSED_PART = "parseError";
 
 const RULES = {
   [TRANSITION_ALL]: [{ "/^(?:-[a-z]+-)?transition(?:-property)?$/": ["/(?:^|[\\s,])all(?:[\\s,]|$)/i"] }],
   [BODY_WIDE_USER_SELECT]: [{ "/(?:^|,)\\s*(?:html|body|:root|\\*|:global\\(\\s*(?:html|body|:root|\\*)\\s*\\))\\s*(?:,|$)/": ["/^(?:-[a-z]+-)?user-select$/"] }],
 } as const;
 
-const ADVICE: Readonly<Record<string, string>> = {
-  [TRANSITION_ALL]: "Name the properties the transition animates.",
-  [BODY_WIDE_USER_SELECT]: "Leave text selectable across the page, and turn selection off only on the control that needs it.",
-  [UNPARSED]: "The gate judges only what parses.",
-};
-
-const MARKUP = ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
+type Advice = Readonly<Record<string, string>>;
 
-const Declaration = Schema.Struct({ inputs: Schema.NonEmptyArray(Schema.NonEmptyString) });
+const JUDGES_ONLY_WHAT_PARSES = "The gate judges only what parses.";
 
-const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
+const UNPARSED_ADVICE: Advice = { [UNPARSED]: JUDGES_ONLY_WHAT_PARSES, [UNPARSED_PART]: JUDGES_ONLY_WHAT_PARSES };
 
-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[];
+const KIT_ADVICE: Advice = {
+  [TRANSITION_ALL]: "Name the properties the transition animates.",
+  [BODY_WIDE_USER_SELECT]: "Leave text selectable across the page, and turn selection off only on the control that needs it.",
+  ...UNPARSED_ADVICE,
 };
 
 export type Scan = {
@@ -45,6 +38,10 @@ export type Scan = {
   readonly violations: readonly Violation[];
 };
 
+type Options = { readonly fix: boolean; readonly suppress: boolean };
+
+type Pass = { readonly config: Config; readonly advice: Advice; readonly refuses: string };
+
 class FrontendSyntaxError extends Schema.TaggedError<FrontendSyntaxError>()("FrontendSyntaxError", {
   message: Schema.String,
 }) {}
@@ -59,80 +56,126 @@ 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 ConfigModule = Schema.Struct({ default: Schema.Record(Schema.String, Schema.Unknown) });
+
+const decodeConfigModule = Schema.decodeUnknownEffect(ConfigModule);
+
+const loadRepositoryConfig = Effect.fn("loadRepositoryConfig")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
-  const file = (yield* Path.Path).join(root, DECLARATION);
+  const file = (yield* Path.Path).join(root, STYLELINT_CONFIG);
   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* new Usage({
+      message: `${STYLELINT_CONFIG} is missing, and a repository that declares ${DECLARED.file} writes it with defineConfig from @avi2dg/checks/stylelint`,
+    });
   }
-  return yield* decodeDeclaration(yield* fs.readFileString(file)).pipe(
-    Effect.mapError(({ message }) => new Usage({ message: `${DECLARATION} does not decode: ${message}` })),
+  const loaded: unknown = yield* Effect.tryPromise({
+    try: () => import(file),
+    catch: (cause) => new Usage({ message: `${STYLELINT_CONFIG} does not load: ${String(cause)}` }),
+  });
+  const module = yield* decodeConfigModule(loaded).pipe(
+    Effect.mapError(() => new Usage({ message: `${STYLELINT_CONFIG} has no default export of a stylelint config object` })),
   );
+  return module.default;
 });
 
-function violationsOf(result: LintResult, relative: (file: string) => string): readonly Violation[] {
+function violationsOf(result: LintResult, relative: (file: string) => string, advice: Advice): readonly Violation[] {
   const file = relative(result.source ?? "");
-  return result.warnings.map(({ line, column, rule, text }) => ({
-    file,
-    line,
-    column,
-    text: `${text.replace(` (${rule})`, "")}. ${ADVICE[rule] ?? ""}`.trim(),
-  }));
+  const unparsed = result.parseErrors.map(({ line, column, stylelintType, text }) => ({ line, column, rule: stylelintType, text }));
+  return [...result.warnings, ...unparsed].map(({ line, column, rule, text }) => {
+    const advised = advice[rule];
+    return { file, line, column, text: advised === undefined ? text : `${text.replace(` (${rule})`, "")}. ${advised}` };
+  });
 }
 
-export const scanInputs = Effect.fn("scanInputs")(function* (root: string, globs: readonly string[]) {
-  const path = yield* Path.Path;
-  const stylelint = (yield* loadPeer("stylelint", () => import("stylelint"))).default;
-  const html = (yield* loadPeer("postcss-html", () => import("postcss-html"))).default;
-  const config = { rules: RULES, overrides: [{ files: MARKUP, customSyntax: html }] };
-  const relative = (file: string): string => path.relative(root, file);
-  const inputs: Input[] = [];
-  const violations = new Map<string, Violation>();
-  for (const glob of globs) {
+const lintWith = (root: string, pass: Pass, options: Partial<LinterOptions>) =>
+  Effect.gen(function* () {
+    const stylelint = (yield* loadPeer("stylelint", () => import("stylelint"))).default;
+    const files = options.files ?? [];
     const linted: readonly LintResult[] = yield* Effect.tryPromise({
-      try: () => stylelint.lint({ files: glob, cwd: root, config }),
-      catch: (cause) => (isNoFilesFound(cause) ? new NoFilesFound() : new FrontendSyntaxError({ message: `stylelint fails on ${glob}: ${String(cause)}` })),
+      try: () => stylelint.lint({ ...options, cwd: root, configBasedir: root, config: pass.config, ignoreDisables: true }),
+      catch: (cause) => (isNoFilesFound(cause) ? new NoFilesFound() : new FrontendSyntaxError({ message: `stylelint fails on ${String(files)}: ${String(cause)}` })),
     }).pipe(
       Effect.map(({ results }) => results),
       Effect.catchTag("NoFilesFound", () => Effect.succeed([])),
     );
-    const results = linted.filter(({ ignored }) => ignored !== true);
-    const invalid = results.flatMap(({ invalidOptionWarnings }) => invalidOptionWarnings.map(({ text }) => text));
-    if (invalid.length > 0) return yield* new FrontendSyntaxError({ message: `stylelint refuses the kit's rule options: ${invalid.join("; ")}` });
-    inputs.push({ glob, files: results.map((result) => relative(result.source ?? "")).toSorted() });
-    for (const violation of results.flatMap((result) => violationsOf(result, relative))) {
-      violations.set(`${violation.file}:${violation.line}:${violation.column}:${violation.text}`, violation);
-    }
+    const invalid = linted.flatMap(({ invalidOptionWarnings }) => invalidOptionWarnings.map(({ text }) => text));
+    if (invalid.length > 0) return yield* new FrontendSyntaxError({ message: `stylelint refuses ${pass.refuses}: ${[...new Set(invalid)].join("; ")}` });
+    return linted;
+  });
+
+// stylelint applies stylelint-suppressions.json to every file it reads itself, and to no code it is handed.
+const lintUnsuppressed = (root: string, pass: Pass, files: readonly string[]) =>
+  Effect.forEach(files, (file) =>
+    Effect.gen(function* () {
+      const code = yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(
+        Effect.mapError((cause) => new FrontendSyntaxError({ message: `cannot read ${file}: ${String(cause)}` })),
+      );
+      return yield* lintWith(root, pass, { code, codeFilename: file });
+    }),
+  ).pipe(Effect.map((results) => results.flat()));
+
+function isJudged({ ignored }: LintResult): boolean {
+  return ignored !== true;
+}
+
+const passesFor = Effect.fn("passesFor")(function* (root: string) {
+  const html = (yield* loadPeer("postcss-html", () => import("postcss-html"))).default;
+  const kit: Pass = { config: { rules: RULES, overrides: [{ files: [...MARKUP], customSyntax: html }] }, advice: KIT_ADVICE, refuses: "the kit's rule options" };
+  const repository: Pass = {
+    config: { ...(yield* loadRepositoryConfig(root)), quiet: false },
+    advice: UNPARSED_ADVICE,
+    refuses: `an option in ${STYLELINT_CONFIG}`,
+  };
+  return { kit, repository };
+});
+
+export const scanInputs = Effect.fn("scanInputs")(function* (root: string, globs: readonly string[], { fix, suppress }: Options) {
+  const path = yield* Path.Path;
+  // stylelint keys its suppressions file on the process directory rather than on its cwd option.
+  yield* Effect.sync(() => process.chdir(root));
+  const { kit, repository } = yield* passesFor(root);
+  if (suppress) yield* lintWith(root, repository, { files: [...globs], fix, suppressAll: true, allowEmptyInput: true });
+  const relative = (file: string): string => path.relative(root, file);
+  const inputs: Input[] = [];
+  const violations = new Map<string, Violation>();
+  for (const glob of globs) {
+    const matched = yield* lintWith(root, repository, { files: glob, fix });
+    const judged = matched.filter(isJudged);
+    const ruled = yield* lintUnsuppressed(root, kit, matched.flatMap(({ source }) => (source === undefined ? [] : [source])));
+    const files = new Set([...judged, ...ruled.filter(isJudged)].map((result) => relative(result.source ?? "")));
+    inputs.push({ glob, files: [...files].toSorted() });
+    const found = [...ruled.flatMap((result) => violationsOf(result, relative, kit.advice)), ...judged.flatMap((result) => violationsOf(result, relative, repository.advice))];
+    for (const violation of found) violations.set(`${violation.file}:${violation.line}:${violation.column}:${violation.text}`, violation);
   }
-  const byPlace = (a: Violation, b: Violation): number => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column;
+  const byPlace = (a: Violation, b: Violation): number => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.text.localeCompare(b.text);
   return { inputs, violations: [...violations.values()].toSorted(byPlace) } satisfies Scan;
 });
 
 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)]);
 }
 
+type Arguments = Options & { readonly directory: string | undefined };
+
+export const parseArguments = Effect.fn("parseArguments")(function* (args: readonly string[]) {
+  const flags = new Set(args.filter((arg) => arg.startsWith("--")));
+  const directories = args.filter((arg) => !arg.startsWith("--"));
+  const unknown = [...flags].filter((flag) => flag !== "--fix" && flag !== "--suppress");
+  if (unknown.length > 0 || directories.length > 1) return yield* new Usage({ message: USAGE });
+  return { fix: flags.has("--fix"), suppress: flags.has("--suppress"), directory: directories[0] } satisfies Arguments;
+});
+
 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);
+  const { directory, ...options } = yield* parseArguments(process.argv.slice(2));
+  return yield* declaredGate(DECLARED, (root, globs) => scanInputs(root, globs, options), { report, passes }, directory);
 });
 
-if (import.meta.main) runMain(NAME, gate);
+if (import.meta.main) runMain(DECLARED.name, gate);

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/quality/presets/stylelint.ts

@@ -0,0 +1,91 @@
+import { fileURLToPath } from "node:url";
+import type { Config } from "stylelint";
+
+type Globs = readonly [string, ...string[]];
+
+export type BaselineTarget = "widely" | "newly" | number;
+
+export type ChecksStylelintConfig = Omit<Config, "extends" | "plugins"> & {
+  readonly baseline: BaselineTarget;
+  readonly tokens: Globs | false;
+};
+
+type Rules = NonNullable<Config["rules"]>;
+
+const HTML_AND_ASTRO = ["**/*.html", "**/*.astro"] as const;
+
+export const MARKUP = [...HTML_AND_ASTRO, "**/*.vue", "**/*.svelte"] as const;
+
+// stylelint resolves a name from the repository, and the kit's peers sit beside the kit rather than under every repository it lints.
+function peer(name: string): string {
+  return fileURLToPath(import.meta.resolve(name));
+}
+
+const CONVENTION_CHANGES = {
+  "no-descending-specificity": null,
+  "property-no-vendor-prefix": [true, { disableFix: true, ignoreProperties: ["-webkit-user-select"] }],
+} as const satisfies Rules;
+
+const SELECTOR_COMPLEXITY = {
+  "selector-max-specificity": "0,3,2",
+  "selector-max-compound-selectors": 3,
+} as const satisfies Rules;
+
+const COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"] as const;
+
+const DESIGN_TOKENS = {
+  "color-no-hex": true,
+  "color-named": "never",
+  "function-disallowed-list": COLOUR_FUNCTIONS.map((name) => `/^${name}$/i`),
+  "declaration-property-value-allowed-list": { "/^font-size$/i": ["/^var\\(\\s*--[^\\s,()]+\\s*\\)$/i", "/^inherit$/i"] },
+} as const satisfies Rules;
+
+const REFUSED_BASELINE = '@avi2dg/checks/stylelint: set baseline to "widely", "newly" or a year such as 2024';
+
+const REFUSED_TOKENS = "@avi2dg/checks/stylelint: set tokens to the globs of the token files, or false to leave the design token rules off";
+
+function baselineTarget(baseline: unknown): BaselineTarget {
+  if (baseline === "widely" || baseline === "newly") return baseline;
+  if (typeof baseline === "number" && Number.isInteger(baseline)) return baseline;
+  throw new TypeError(REFUSED_BASELINE);
+}
+
+function isGlobList(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((glob) => typeof glob === "string" && glob !== "");
+}
+
+function tokenFiles(tokens: unknown): readonly string[] {
+  if (tokens === false) return [];
+  if (isGlobList(tokens) && tokens.length > 0) return tokens;
+  throw new TypeError(REFUSED_TOKENS);
+}
+
+function designTokens(files: readonly string[]): Required<Pick<Config, "rules" | "overrides">> {
+  if (files.length === 0) return { rules: {}, overrides: [] };
+  const off = Object.fromEntries(Object.keys(DESIGN_TOKENS).map((rule) => [rule, null]));
+  return { rules: DESIGN_TOKENS, overrides: [{ files: [...files], rules: off }] };
+}
+
+// The types refuse a missing or malformed baseline or tokens, and the guards repeat it for a config no typecheck reads.
+export function defineConfig({ baseline, tokens, rules, overrides = [], ...rest }: ChecksStylelintConfig): Config {
+  const available = baselineTarget(baseline);
+  const tokenRules = designTokens(tokenFiles(tokens));
+  return {
+    ...rest,
+    extends: [peer("stylelint-config-standard")],
+    plugins: [peer("stylelint-plugin-use-baseline")],
+    rules: {
+      ...CONVENTION_CHANGES,
+      ...SELECTOR_COMPLEXITY,
+      "plugin/use-baseline": [true, { available }],
+      ...tokenRules.rules,
+      ...rules,
+    },
+    overrides: [
+      { files: [...MARKUP], customSyntax: peer("postcss-html") },
+      { files: [...HTML_AND_ASTRO], rules: { "declaration-block-single-line-max-declarations": null } },
+      ...tokenRules.overrides,
+      ...overrides,
+    ],
+  };
+}

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`);