@avi2dg/checks 0.21.0 → 0.23.0

package/scripts/repetition.ts

@@ -2,7 +2,6 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { changedPaths, checkoutFiles, collect, git, pathsAt, rangeFromArgs } from "./git.ts";
 import { runMain } from "./main.ts";
-import { readQuality } from "./quality-file.ts";
 
 export type Fragment = {
   readonly file: string;
@@ -34,19 +33,29 @@ const USAGE = "usage: repetition.ts <ref> | <base-ref> <head-ref>";
 const MIN_TOKENS = 50;
 const MIN_LINES = 5;
 const MEASURE = `at ${MIN_TOKENS} tokens and ${MIN_LINES} lines`;
-const DECLARATIONS = ":(exclude,glob)**/*.d.ts";
-const TYPESCRIPT = [":(glob)**/*.ts", ":(glob)**/*.tsx", DECLARATIONS];
+const CONFIG = ".jscpd.json";
 const JSCPD_FINISHED = 0;
 const REPORT = "jscpd-report.json";
 
 const Location = Schema.Struct({ name: Schema.String, start: Schema.Int, end: Schema.Int });
 
 const decodeReport = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(Schema.Struct({ duplicates: Schema.Array(Schema.Struct({ firstFile: Location, secondFile: Location })) })),
+  Schema.fromJsonString(
+    Schema.Struct({
+      duplicates: Schema.Array(Schema.Struct({ firstFile: Location, secondFile: Location })),
+      statistics: Schema.Struct({ total: Schema.Struct({ sources: Schema.Int }) }),
+    }),
+  ),
 );
 
-function fragmentOf({ name, start, end }: typeof Location.Type): Fragment {
-  return { file: name, start, end };
+const decodeConfigPaths = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(Schema.Struct({ path: Schema.optional(Schema.Array(Schema.String)) })),
+);
+
+type Scan = { readonly sources: number; readonly clones: readonly Clone[] };
+
+function fragmentOf(file: (name: string) => string, { name, start, end }: typeof Location.Type): Fragment {
+  return { file: file(name), start, end };
 }
 
 export function repeatedLines(clones: readonly Clone[]): ReadonlyMap<string, number> {
@@ -60,28 +69,40 @@ export function repeatedLines(clones: readonly Clone[]): ReadonlyMap<string, num
 }
 
 // jscpd reads files from disk, and the working tree need not hold the revision: a merge checkout or an uncommitted edit.
+// Both ends scan under the head's config, so a changed file set never reads as a change in repetition.
+// jscpd refuses a missing path, so a path in `emptied` the revision lacks is created empty.
 const scan = Effect.fn("scan")(
-  function* (root: string, rev: string, files: readonly string[]) {
-    if (files.length === 0) return [];
+  function* (root: string, rev: string, config: string, emptied: readonly string[]) {
+    const files = yield* pathsAt(rev, [], root);
+    if (files.length === 0) return { sources: 0, clones: [] } satisfies Scan;
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const scratch = yield* fs.makeTempDirectoryScoped({ prefix: "checks-repetition-" });
     const tree = yield* checkoutFiles(rev, files, scratch, root);
+    yield* fs.writeFileString(path.join(tree, CONFIG), config);
+    for (const absent of emptied.map((entry) => path.join(tree, entry))) {
+      if (!(yield* fs.exists(absent))) yield* fs.makeDirectory(absent, { recursive: true });
+    }
     const output = path.join(scratch, "report");
-    const flags = ["--silent", "--no-tips", "--no-gitignore", "--reporters", "json", "--output", output];
+    const flags = ["--silent", "--no-tips", "--no-gitignore", "--absolute", "--reporters", "json", "--output", output];
     const thresholds = ["--min-tokens", `${MIN_TOKENS}`, "--min-lines", `${MIN_LINES}`];
 
-    const run = yield* collect("jscpd", [...flags, ...thresholds, "."], tree).pipe(
+    const run = yield* collect("jscpd", [...flags, ...thresholds], tree).pipe(
       Effect.mapError((cause) => new JscpdUnreadable({ message: `cannot run jscpd: ${cause.message}` })),
     );
-    if (run.exitCode !== JSCPD_FINISHED) {
+    const reportPath = path.join(output, REPORT);
+    // A threshold, exitCode or failOnEmpty in the repository's config fails jscpd after the report is written.
+    if (run.exitCode !== JSCPD_FINISHED && !(yield* fs.exists(reportPath))) {
       return yield* new JscpdUnreadable({ message: `jscpd exited ${run.exitCode}: ${run.stderr.trim() || run.stdout.trim()}` });
     }
-    const { duplicates } = yield* fs.readFileString(path.join(output, REPORT)).pipe(
+    const { duplicates, statistics } = yield* fs.readFileString(reportPath).pipe(
       Effect.flatMap(decodeReport),
       Effect.mapError((cause) => new JscpdUnreadable({ message: `cannot read jscpd's report: ${cause.message}` })),
     );
-    return duplicates.map(({ firstFile, secondFile }): Clone => [fragmentOf(firstFile), fragmentOf(secondFile)]);
+    const scanned = yield* fs.realPath(tree);
+    const file = (name: string): string => path.relative(scanned, name);
+    const clones = duplicates.map(({ firstFile, secondFile }): Clone => [fragmentOf(file, firstFile), fragmentOf(file, secondFile)]);
+    return { sources: statistics.total.sources, clones } satisfies Scan;
   },
   Effect.scoped,
 );
@@ -113,33 +134,25 @@ export function risesOf(
     .toSorted((a, b) => a.file.localeCompare(b.file));
 }
 
-// Tallies every held file that did not rise, plus every file outside the held set, as advisory.
-export function heldOf(
-  measured: number,
-  rises: readonly Rise[],
-  after: ReadonlyMap<string, number>,
-  othersRepeated: ReadonlyMap<string, number>,
-): Held {
+// Tallies every repeating file that did not rise as advisory.
+export function heldOf(measured: number, rises: readonly Rise[], after: ReadonlyMap<string, number>): Held {
   const risen = new Set(rises.map((rise) => rise.file));
-  const advisory = [...after].filter(([file]) => !risen.has(file)).concat([...othersRepeated]);
+  const advisory = [...after].filter(([file]) => !risen.has(file));
   return { measured, rises, advisory: new Map(advisory.toSorted(([a], [b]) => a.localeCompare(b))) };
 }
 
-const runHold = Effect.fn("runHold")(function* (root: string, production: readonly string[], base: string, head: string) {
-  const pathspecs = [...production.map((glob) => `:(glob)${glob}`), DECLARATIONS];
-  const held = yield* pathsAt(head, pathspecs, root);
-  const holds = new Set(held);
-  const others = (yield* pathsAt(head, TYPESCRIPT, root)).filter((file) => !holds.has(file));
+const runHold = Effect.fn("runHold")(function* (root: string, config: string, base: string, head: string) {
   const formerPath = new Map(
-    (yield* changedPaths(base, head, pathspecs, root)).flatMap((change) => (change.kind === "renamed" ? [[change.path, change.from]] : [])),
+    (yield* changedPaths(base, head, [], root)).flatMap((change) => (change.kind === "renamed" ? [[change.path, change.from]] : [])),
   );
-
-  const before = repeatedLines(yield* scan(root, base, yield* pathsAt(base, pathspecs, root)));
-  const clones = yield* scan(root, head, held);
+  const { path: configPaths = [] } = yield* decodeConfigPaths(config).pipe(
+    Effect.mapError((cause) => new JscpdUnreadable({ message: `cannot read ${CONFIG}: ${cause.message}` })),
+  );
+  const before = repeatedLines((yield* scan(root, base, config, configPaths)).clones);
+  const { sources, clones } = yield* scan(root, head, config, []);
   const after = repeatedLines(clones);
-  const rises = risesOf(held, before, after, formerPath, clones);
-  const othersRepeated = repeatedLines(yield* scan(root, head, others));
-  return heldOf(held.length, rises, after, othersRepeated) satisfies Held;
+  const rises = risesOf([...after.keys()], before, after, formerPath, clones);
+  return heldOf(sources, rises, after) satisfies Held;
 });
 
 export function describe({ file, before, after, clones }: Rise): readonly string[] {
@@ -152,8 +165,8 @@ export function describe({ file, before, after, clones }: Rise): readonly string
 export function report({ measured, rises, advisory }: Held): string {
   const verdict =
     rises.length === 0
-      ? [`${NAME}: ${measured} production file(s) repeat no more lines than where the range starts, ${MEASURE}`]
-      : [`${NAME}: ${rises.length} production file(s) repeat more lines than where the range starts, ${MEASURE}:`, ...rises.flatMap(describe)];
+      ? [`${NAME}: ${measured} file(s) ${CONFIG} holds repeat no more lines than where the range starts, ${MEASURE}`]
+      : [`${NAME}: ${rises.length} file(s) ${CONFIG} holds repeat more lines than where the range starts, ${MEASURE}:`, ...rises.flatMap(describe)];
   const notice =
     advisory.size === 0
       ? []
@@ -167,13 +180,11 @@ export function report({ measured, rises, advisory }: Held): string {
 const hold = Effect.gen(function* () {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
   const { base, head } = yield* rangeFromArgs(process.argv.slice(2), USAGE, root);
-  const { source, quality } = yield* readQuality(root);
-  const production = quality.sources?.production ?? [];
-  if (production.length === 0) {
-    yield* Console.log(`${NAME}: ${source} declares no sources.production`);
+  if ((yield* pathsAt(head, [`:(literal)${CONFIG}`], root)).length === 0) {
+    yield* Console.log(`${NAME}: the head holds no ${CONFIG}, so no file is measured`);
     return true;
   }
-  const held = yield* runHold(root, production, base, head);
+  const held = yield* runHold(root, yield* git(["show", `${head}:${CONFIG}`], root), base, head);
 
   yield* Console.log(report(held));
   return held.rises.length === 0;

package/scripts/shell-command.ts

@@ -64,8 +64,14 @@ export function plainCommand(script: string): Command | undefined {
   return words.length === 0 ? undefined : words;
 }
 
+// bun run resolves any other word, even one holding a slash, to a package.json script of that name first.
+const FILE_PATH = /^\.{0,2}\//;
+
 export function invokes(command: Command | undefined, gate: Command): boolean {
-  return command !== undefined && gate.length <= command.length && gate.every((word, index) => command[index] === word);
+  if (command === undefined) return false;
+  const begins = (words: Command) => gate.length <= words.length && gate.every((word, index) => words[index] === word);
+  const bunRunsFile = command[0] === "bun" && command[1] === "run" && FILE_PATH.test(gate[0] ?? "");
+  return begins(command) || (bunRunsFile && begins(command.slice(2)));
 }
 
 export function mentions(script: string, gate: Command): boolean {

package/scripts/swc.ts

@@ -0,0 +1,46 @@
+import { parse } from "@swc/core";
+import { Effect, Schema } from "effect";
+
+export class TypeScriptParseError extends Schema.TaggedError<TypeScriptParseError>()("TypeScriptParseError", {
+  message: Schema.String,
+}) {}
+
+export const parseTypeScript = Effect.fn("parseTypeScript")(function* (file: string, source: string) {
+  return yield* Effect.tryPromise({
+    try: () => parse(source, { syntax: "typescript", tsx: file.endsWith(".tsx"), target: "esnext" }),
+    catch: (cause) => new TypeScriptParseError({ message: `cannot parse ${file}: ${String(cause)}` }),
+  });
+});
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function identifierName(node: unknown): string | undefined {
+  if (!isRecord(node) || node["type"] !== "Identifier") return undefined;
+  const value = node["value"];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function stringValue(node: unknown): string | undefined {
+  if (!isRecord(node) || node["type"] !== "StringLiteral") return undefined;
+  const value = node["value"];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function spanStart(node: Record<string, unknown>): number {
+  const span = node["span"];
+  if (!isRecord(span)) return 0;
+  const start = span["start"];
+  return typeof start === "number" ? start : 0;
+}
+
+export function lineOf(source: string, start: number): number {
+  const bytes = Buffer.from(source, "utf8");
+  const offset = Math.max(0, Math.min(bytes.length, start - 1));
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (bytes[index] === 0x0a) line += 1;
+  }
+  return line;
+}

package/scripts/test-layout.ts

@@ -1,10 +1,9 @@
 #!/usr/bin/env bun
-import { parse } from "@swc/core";
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { git } from "./git.ts";
 import { runMain } from "./main.ts";
-import { ENTRY_POINT, QUALITY_FILE, TEST_ENTRY_POINT } from "./gates.ts";
-import { readQuality } from "./quality-file.ts";
+import { ENTRY_POINT, TEST_ENTRY_POINT } from "./gates.ts";
+import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "./swc.ts";
 
 export type Violation = {
   readonly file: string;
@@ -42,12 +41,15 @@ const BANNED_GLOBAL_CALLS: readonly string[] = ["fetch"];
 
 const IGNORES_KEY = "pathIgnorePatterns";
 const QUARANTINE = "**/tests/quarantine/**";
+const LIVE_TESTS = "**/tests/live/**";
+const PIXEL_TESTS = "**/tests/pixel/**";
 const VENDORED = "repos/**";
-const PRESET_IGNORES: readonly string[] = [QUARANTINE, VENDORED];
-
-function acceptedIgnores(vendors: boolean): readonly (readonly string[])[] {
-  return vendors ? [PRESET_IGNORES] : [PRESET_IGNORES, [QUARANTINE]];
-}
+const TEST_TIERS = ["live", "pixel"] as const;
+const OUT_OF_PROCESS: readonly string[] = [E2E, ...TEST_TIERS.map((tier) => `${TESTS}${tier}/`)];
+const ACCEPTED_IGNORES: readonly (readonly string[])[] = [
+  [QUARANTINE, LIVE_TESTS, PIXEL_TESTS, VENDORED],
+  [QUARANTINE, LIVE_TESTS, PIXEL_TESTS],
+];
 export const LAYOUT_CHECK_MARK = "scripts/test-layout.ts";
 export const LAYOUT_CHECK_BIN = "checks-test-layout";
 const OWN_ENTRY_POINT = `scripts/${ENTRY_POINT.script}`;
@@ -57,10 +59,6 @@ export class LayoutError extends Schema.TaggedError<LayoutError>()("LayoutError"
   message: Schema.String,
 }) {}
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
 function runsLayoutCheck(lint: string): boolean {
   if (lint.includes(LAYOUT_CHECK_MARK) || lint.includes(LAYOUT_CHECK_BIN)) return true;
   return lint.split(/[\s|&;()]+/).some((word) => word === ENTRY_POINT.bin || word === OWN_ENTRY_POINT);
@@ -104,40 +102,11 @@ export function placementViolations(files: readonly string[]): readonly Violatio
   return violations;
 }
 
-function lineOf(source: string, start: number): number {
-  const bytes = Buffer.from(source, "utf8");
-  const offset = Math.max(0, Math.min(bytes.length, start - 1));
-  let line = 1;
-  for (let index = 0; index < offset; index += 1) {
-    if (bytes[index] === 0x0a) line += 1;
-  }
-  return line;
-}
-
 function bannedModule(specifier: string): string | undefined {
   const bare = specifier.startsWith("node:") ? specifier.slice("node:".length) : specifier;
   return BANNED_MODULES.includes(bare) ? bare : undefined;
 }
 
-function identifierName(node: unknown): string | undefined {
-  if (!isRecord(node) || node["type"] !== "Identifier") return undefined;
-  const value = node["value"];
-  return typeof value === "string" ? value : undefined;
-}
-
-function stringValue(node: unknown): string | undefined {
-  if (!isRecord(node) || node["type"] !== "StringLiteral") return undefined;
-  const value = node["value"];
-  return typeof value === "string" ? value : undefined;
-}
-
-function spanStart(node: Record<string, unknown>): number {
-  const span = node["span"];
-  if (!isRecord(span)) return 0;
-  const start = span["start"];
-  return typeof start === "number" ? start : 0;
-}
-
 function importedNames(node: Record<string, unknown>): readonly string[] {
   const specifiers = node["specifiers"];
   if (!Array.isArray(specifiers)) return [];
@@ -197,10 +166,9 @@ function outOfProcessUse(node: Record<string, unknown>): string | undefined {
 }
 
 export const isolationViolations = Effect.fn("isolationViolations")(function* (file: string, source: string) {
-  const module = yield* Effect.tryPromise({
-    try: () => parse(source, { syntax: "typescript", tsx: file.endsWith(".tsx"), target: "esnext" }),
-    catch: (error) => new LayoutError({ message: `cannot parse ${file}: ${String(error)}` }),
-  });
+  const module = yield* parseTypeScript(file, source).pipe(
+    Effect.mapError((error) => new LayoutError({ message: error.message })),
+  );
   const violations: Violation[] = [];
   const seen = new Set<unknown>();
 
@@ -228,7 +196,22 @@ export const isolationViolations = Effect.fn("isolationViolations")(function* (f
   return violations;
 });
 
-export function scriptViolations(manifest: unknown): readonly Violation[] {
+function tierScriptViolation(scripts: unknown, files: readonly string[], tier: (typeof TEST_TIERS)[number]): Violation | undefined {
+  const file = "package.json";
+  const key = `test:${tier}`;
+  const found = isRecord(scripts) ? scripts[key] : undefined;
+  const expected = `${TEST_ENTRY_POINT.bin} --tier=${tier}`;
+  const hasTests = files.some((candidate) => candidate.startsWith(`tests/${tier}/`) && TEST_FILE.test(candidate));
+  if (!hasTests && found === undefined) return undefined;
+  if (found === expected) return undefined;
+  return {
+    file,
+    line: undefined,
+    message: `${key} must be "${expected}"${hasTests ? " when its test tier has files" : " when declared"}, found ${JSON.stringify(found ?? null)}`,
+  };
+}
+
+export function scriptViolations(manifest: unknown, files: readonly string[] = []): readonly Violation[] {
   const file = "package.json";
   const scripts = isRecord(manifest) ? manifest["scripts"] : undefined;
   const test = isRecord(scripts) ? scripts["test"] : undefined;
@@ -248,10 +231,14 @@ export function scriptViolations(manifest: unknown): readonly Violation[] {
       message: `scripts.lint must run the layout check: add "${ENTRY_POINT.bin}"`,
     });
   }
+  for (const tier of TEST_TIERS) {
+    const violation = tierScriptViolation(scripts, files, tier);
+    if (violation !== undefined) violations.push(violation);
+  }
   return violations;
 }
 
-export function bunfigViolations(consumer: unknown, preset: unknown, vendors: boolean): readonly Violation[] {
+export function bunfigViolations(consumer: unknown, preset: unknown): readonly Violation[] {
   const file = "bunfig.toml";
   const copy = "bun has no bunfig extends, so copy node_modules/@avi2dg/checks/bunfig.toml";
   if (consumer === undefined) {
@@ -272,10 +259,9 @@ export function bunfigViolations(consumer: unknown, preset: unknown, vendors: bo
   for (const [key, value] of Object.entries(presetTest)) {
     if (key !== IGNORES_KEY && !Bun.deepEquals(found(key), value)) violations.push(drifted(key, JSON.stringify(value), copy));
   }
-  const accepted = acceptedIgnores(vendors);
-  if (!accepted.some((ignores) => Bun.deepEquals(found(IGNORES_KEY), ignores))) {
-    const wanted = accepted.map((ignores) => JSON.stringify(ignores)).join(" or ");
-    violations.push(drifted(IGNORES_KEY, wanted, `the check pins it, requiring ${VENDORED} where ${QUALITY_FILE} declares sources.libraries`));
+  if (!ACCEPTED_IGNORES.some((ignores) => Bun.deepEquals(found(IGNORES_KEY), ignores))) {
+    const wanted = ACCEPTED_IGNORES.map((ignores) => JSON.stringify(ignores)).join(" or ");
+    violations.push(drifted(IGNORES_KEY, wanted, `the check pins it, and a repository that links libraries under repos/ keeps ${VENDORED}`));
   }
   return violations;
 }
@@ -318,7 +304,7 @@ export const run = Effect.fn("run")(function* (root: string, presetPath: string)
     (file) =>
       file.startsWith(TESTS) &&
       TYPESCRIPT.test(file) &&
-      !file.startsWith(E2E) &&
+      !startsWithAny(file, OUT_OF_PROCESS) &&
       !file.startsWith(DATA_DIR),
   );
   for (const file of inProcess) {
@@ -326,13 +312,11 @@ export const run = Effect.fn("run")(function* (root: string, presetPath: string)
     violations.push(...(yield* isolationViolations(file, source)));
   }
 
-  violations.push(...scriptViolations(yield* readManifest(path.join(root, "package.json"))));
+  violations.push(...scriptViolations(yield* readManifest(path.join(root, "package.json")), files));
 
   const bunfig = path.join(root, "bunfig.toml");
   const consumerBunfig = (yield* fs.exists(bunfig)) ? yield* parsedToml(bunfig) : undefined;
-  const { quality } = yield* readQuality(root);
-  const vendors = (quality.sources?.libraries ?? []).length > 0;
-  violations.push(...bunfigViolations(consumerBunfig, yield* parsedToml(presetPath), vendors));
+  violations.push(...bunfigViolations(consumerBunfig, yield* parsedToml(presetPath)));
 
   return { files: files.length, violations };
 });

package/scripts/test-skips.ts

@@ -0,0 +1,180 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "./swc.ts";
+
+export type Environment = "ci" | "local";
+export type TestTier = "live" | "pixel";
+export type SkipDeclaration = {
+  readonly file: string;
+  readonly line: number;
+  readonly name: string;
+  readonly reason: string;
+  readonly when?: Environment;
+};
+
+export class SkipDeclarationError extends Schema.TaggedError<SkipDeclarationError>()("SkipDeclarationError", {
+  message: Schema.String,
+}) {}
+
+const TEST_FILES = ["tests/**/*.test.ts", "tests/**/*.test.tsx"] as const;
+const SKIP_HELPER_MODULE = "test-skips.ts";
+const whenSchema = Schema.Literals(["ci", "local"]);
+
+export function skipReason(_reason: string, label: string, _when?: Environment): string {
+  return label;
+}
+
+function expressionOf(argument: unknown): unknown {
+  return isRecord(argument) ? argument["expression"] : undefined;
+}
+
+function argumentsOf(node: Record<string, unknown>): readonly unknown[] {
+  const args = node["arguments"];
+  return Array.isArray(args) ? args : [];
+}
+
+function skipReasonAliases(statement: unknown): readonly string[] {
+  if (!isRecord(statement) || statement["type"] !== "ImportDeclaration") return [];
+  const source = stringValue(statement["source"]);
+  const specifiers = statement["specifiers"];
+  if (source === undefined || !source.endsWith(SKIP_HELPER_MODULE) || !Array.isArray(specifiers)) return [];
+  return specifiers.flatMap((specifier) => {
+    if (!isRecord(specifier) || specifier["type"] !== "ImportSpecifier") return [];
+    const imported = identifierName(specifier["imported"]) ?? identifierName(specifier["local"]);
+    const local = identifierName(specifier["local"]);
+    return imported === "skipReason" && local !== undefined ? [local] : [];
+  });
+}
+
+function importedSkipReasonNames(module: unknown): ReadonlySet<string> {
+  if (!isRecord(module) || !Array.isArray(module["body"])) return new Set();
+  return new Set(module["body"].flatMap(skipReasonAliases));
+}
+
+type Member = { readonly object: string | undefined; readonly property: string | undefined };
+
+function memberOf(node: unknown): Member | undefined {
+  if (!isRecord(node) || node["type"] !== "MemberExpression") return undefined;
+  return { object: identifierName(node["object"]), property: identifierName(node["property"]) };
+}
+
+type SkipReasonScan =
+  | { readonly kind: "none" }
+  | { readonly kind: "invalid"; readonly message: string }
+  | { readonly kind: "valid"; readonly name: string; readonly reason: string; readonly when?: Environment };
+
+function skipReasonCall(node: unknown, aliases: ReadonlySet<string>): SkipReasonScan {
+  if (!isRecord(node) || node["type"] !== "CallExpression") return { kind: "none" };
+  if (!aliases.has(identifierName(node["callee"]) ?? "")) return { kind: "none" };
+  const [reasonArgument, labelArgument, whenArgument] = argumentsOf(node);
+  const reason = stringValue(expressionOf(reasonArgument));
+  const label = stringValue(expressionOf(labelArgument));
+  if (reason === undefined || reason.trim() === "" || label === undefined || label.trim() === "") {
+    return { kind: "invalid", message: "skipReason needs a non-empty literal reason and a literal test name" };
+  }
+  const when = whenArgument === undefined ? undefined : stringValue(expressionOf(whenArgument));
+  if (whenArgument !== undefined && when === undefined) {
+    return { kind: "invalid", message: "skipReason's when value must be \"ci\" or \"local\"" };
+  }
+  if (when !== undefined && !Schema.is(whenSchema)(when)) {
+    return {
+      kind: "invalid",
+      message: `skipReason's when value must be "ci" or "local", found ${JSON.stringify(when)}`,
+    };
+  }
+  return { kind: "valid", name: label, reason, ...(when === undefined ? {} : { when }) };
+}
+
+type RegisteredSkip = { readonly onDescribe: boolean; readonly first: unknown };
+
+function registeredSkip(node: Record<string, unknown>): RegisteredSkip | undefined {
+  if (node["type"] !== "CallExpression") return undefined;
+  const callee = node["callee"];
+  const curried = isRecord(callee) && callee["type"] === "CallExpression";
+  const member = memberOf(curried ? callee["callee"] : callee);
+  const methods = curried ? ["skipIf", "if"] : ["skip", "todo"];
+  if (member === undefined || !methods.includes(member.property ?? "")) return undefined;
+  return { onDescribe: member.object === "describe", first: expressionOf(argumentsOf(node)[0]) };
+}
+
+function registeredSkips(module: unknown): readonly RegisteredSkip[] {
+  const found: RegisteredSkip[] = [];
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    if (!isRecord(node)) return;
+    const registered = registeredSkip(node);
+    if (registered !== undefined) found.push(registered);
+    for (const value of Object.values(node)) visit(value);
+  };
+  visit(module);
+  return found;
+}
+
+type DeclarationsRead =
+  | { readonly kind: "valid"; readonly declarations: readonly SkipDeclaration[] }
+  | { readonly kind: "invalid"; readonly message: string };
+
+function declarationsIn(source: string, file: string, module: unknown): DeclarationsRead {
+  const aliases = importedSkipReasonNames(module);
+  if (aliases.size === 0) return { kind: "valid", declarations: [] };
+  const declarations: SkipDeclaration[] = [];
+  for (const { onDescribe, first } of registeredSkips(module)) {
+    if (!isRecord(first)) continue;
+    const metadata = skipReasonCall(first, aliases);
+    if (metadata.kind === "none") continue;
+    const line = lineOf(source, spanStart(first));
+    if (onDescribe) {
+      return {
+        kind: "invalid",
+        message: `line ${line}: skipReason cannot declare a describe; declare each test inside it with its own skipReason`,
+      };
+    }
+    if (metadata.kind === "invalid") return metadata;
+    const { name, reason, when } = metadata;
+    declarations.push({ file, line, name, reason, ...(when === undefined ? {} : { when }) });
+  }
+  return { kind: "valid", declarations };
+}
+
+function selectedTierFile(file: string, tier: TestTier | undefined): boolean {
+  if (file.startsWith("tests/quarantine/")) return false;
+  if (tier === undefined) return !file.startsWith("tests/live/") && !file.startsWith("tests/pixel/");
+  return file.startsWith(`tests/${tier}/`);
+}
+
+export const readSkipDeclarations = Effect.fn("readSkipDeclarations")(function* (
+  root: string,
+  tier: TestTier | undefined,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const files = yield* Effect.tryPromise({
+    try: () =>
+      Promise.all(
+        TEST_FILES.map((pattern) =>
+          Array.fromAsync(new Bun.Glob(pattern).scan({ cwd: root, onlyFiles: true })),
+        ),
+      ).then((groups) => groups.flat().filter((file) => selectedTierFile(file, tier)).sort()),
+    catch: (cause) => new SkipDeclarationError({ message: `cannot find test files: ${String(cause)}` }),
+  });
+  const declarations: SkipDeclaration[] = [];
+  for (const file of files) {
+    const source = yield* fs.readFileString(path.join(root, file)).pipe(
+      Effect.mapError((cause) => new SkipDeclarationError({ message: `cannot read ${file}: ${cause.message}` })),
+    );
+    const module = yield* parseTypeScript(file, source).pipe(
+      Effect.mapError((error) => new SkipDeclarationError({ message: error.message })),
+    );
+    const parsed = yield* Effect.try({
+      try: () => declarationsIn(source, file, module),
+      catch: (cause) => new SkipDeclarationError({ message: `cannot read skip declarations in ${file}: ${String(cause)}` }),
+    });
+    if (parsed.kind === "invalid") {
+      return yield* new SkipDeclarationError({ message: `${file}: ${parsed.message}` });
+    }
+    declarations.push(...parsed.declarations);
+  }
+  return declarations;
+});