@avi2dg/checks 0.56.0 → 0.56.1

package/docs/gates/checks-unused.md

@@ -1,66 +0,0 @@
----
-kind: reference
-audience: consumers
----
-# checks-unused
-
-`checks-unused` is the gate that refuses a TypeScript or Astro file no entry point reaches.
-
-## What it checks
-
-It runs Knip with the repository's own configuration and names each `.ts`, `.tsx` or `.astro` file no entry reaches.
-It reads only the files issue type, so an unused export or dependency never fails it.
-It asks Knip for that issue type itself, so a configuration that narrows `include`, excludes files or turns the files rule off still has its files judged.
-It fails when the repository tracks no `.ts`, `.tsx` or `.astro` file, since an empty scan would pass without judging anything.
-It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead file from an entry point.
-
-## What it reads
-
-It reads the working tree, so an uncommitted file is judged like a committed one.
-It reads the repository's Knip configuration, which names the entries.
-The repository writes `knip.config.ts` with the kit's builder, which requires `entry`, the files nothing imports:
-
-```ts
-import { defineConfig } from "@avi2dg/checks/knip";
-
-export default defineConfig({ entry: ["src/index.ts"] });
-```
-
-The builder sets `include` to unreferenced files alone, and adds `tests/**/*.test.ts`, `dependency-cruiser.config.ts` and `oxlint.config.ts` to the entries.
-In a repository that depends on `astro`, Knip reads `.astro` imports, so a file only an `.astro` entry imports counts as used and an `.astro` file no entry reaches is named.
-The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
-
-## Arguments
-
-It takes none.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | no tracked file is unreferenced |
-| 1 | a tracked file is unreferenced or the repository holds no Knip configuration |
-| 2 | the repository tracks no TypeScript or Astro source, Knip cannot run, or its configuration does not parse |
-
-## Sample output
-
-```
-unused: 1 unreferenced file(s):
-  src/planted-dead.ts
-```
-
-A passing run counts the files it judged:
-
-```
-unused: no unreferenced files among 110 tracked .ts/.tsx/.astro file(s)
-```
-
-## When it runs
-
-`checks-lint` runs it in the full run when the repository tracks a `.ts`, `.tsx` or `.astro` file, and never in the desk run.
-Such a repository names its entries in a Knip configuration.
-
-## Related topics
-
-- [checks-lint](checks-lint.md)
-- [checks-repetition](checks-repetition.md)

package/src/complexity/exports.ts

@@ -1,189 +0,0 @@
-#!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { TYPESCRIPT_SOURCE } from "../core/gates.ts";
-import { checkoutFiles, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
-import { runMain } from "../core/main.ts";
-import { knipReport, scanTree } from "./knip.ts";
-
-const UnusedSymbolSchema = Schema.Struct({
-  file: Schema.String,
-  kind: Schema.Literals(["export", "type"]),
-  name: Schema.String,
-});
-
-export type UnusedSymbol = typeof UnusedSymbolSchema.Type;
-
-export type Baseline = readonly UnusedSymbol[];
-
-export type Held = {
-  readonly reported: readonly UnusedSymbol[];
-  readonly base: Baseline;
-  readonly head: Baseline;
-  readonly unusedAtBase: readonly UnusedSymbol[];
-};
-
-export type Drift = {
-  readonly unlisted: readonly UnusedSymbol[];
-  readonly added: readonly UnusedSymbol[];
-  readonly stale: readonly UnusedSymbol[];
-};
-
-const NAME = "exports";
-export const BASELINE_FILE = "exports-baseline.json";
-const INCLUDED = ["--include", "exports,types"];
-const WRITE = "--write";
-const USAGE = `usage: exports.ts <ref> | <base-ref> <head-ref> | ${WRITE}`;
-
-class ExportsError extends Schema.TaggedError<ExportsError>()("ExportsError", {
-  message: Schema.String,
-}) {}
-
-const KnipSymbol = Schema.Struct({ name: Schema.String });
-
-const decodeKnipReport = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Struct({
-      issues: Schema.Array(
-        Schema.Struct({
-          file: Schema.String,
-          exports: Schema.optional(Schema.Array(KnipSymbol)),
-          types: Schema.optional(Schema.Array(KnipSymbol)),
-        }),
-      ),
-    }),
-  ),
-);
-
-const decodeBaseline = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(UnusedSymbolSchema)));
-
-function byPosition(a: UnusedSymbol, b: UnusedSymbol): number {
-  return a.file.localeCompare(b.file) || a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name);
-}
-
-export const symbolsOf = Effect.fn("symbolsOf")(function* (stdout: string) {
-  const { issues } = yield* decodeKnipReport(stdout).pipe(
-    Effect.mapError((cause) => new ExportsError({ message: `knip's JSON report does not decode: ${cause.message}` })),
-  );
-  return issues
-    .flatMap(({ file, exports = [], types = [] }): readonly UnusedSymbol[] => [
-      ...exports.map(({ name }): UnusedSymbol => ({ file, kind: "export", name })),
-      ...types.map(({ name }): UnusedSymbol => ({ file, kind: "type", name })),
-    ])
-    .toSorted(byPosition);
-});
-
-export const baselineOf = Effect.fn("baselineOf")(function* (text: string, where: string) {
-  return yield* decodeBaseline(text).pipe(
-    Effect.mapError((cause) => new ExportsError({ message: `${where} does not decode: ${cause.message}` })),
-  );
-});
-
-const baselinePath = Effect.fn("baselinePath")(function* (root: string) {
-  return (yield* Path.Path).join(root, BASELINE_FILE);
-});
-
-const baselineInTree = Effect.fn("baselineInTree")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const at = yield* baselinePath(root);
-  if (!(yield* fs.exists(at))) return [] satisfies Baseline;
-  return yield* fs.readFileString(at).pipe(Effect.flatMap((text) => baselineOf(text, BASELINE_FILE)));
-});
-
-const baselineAt = Effect.fn("baselineAt")(function* (treeish: string, root: string) {
-  const blob = (yield* git(["ls-tree", "--object-only", treeish, "--", BASELINE_FILE], root)).trim();
-  if (blob === "") return [] satisfies Baseline;
-  return yield* baselineOf(yield* git(["cat-file", "blob", blob], root), `${BASELINE_FILE} at ${treeish}`);
-});
-
-const keyOf = ({ file, kind, name }: UnusedSymbol): string => `${kind}\0${file}\0${name}`;
-
-function outside(symbols: readonly UnusedSymbol[], others: readonly UnusedSymbol[]): readonly UnusedSymbol[] {
-  const known = new Set(others.map(keyOf));
-  return symbols.filter((symbol) => !known.has(keyOf(symbol))).toSorted(byPosition);
-}
-
-export function driftOf({ reported, base, head, unusedAtBase }: Held): Drift {
-  return {
-    unlisted: outside(reported, head),
-    added: outside(head, [...base, ...unusedAtBase]),
-    stale: outside(head, reported),
-  };
-}
-
-function describe(symbol: UnusedSymbol): string {
-  return `  ${symbol.file}: ${symbol.name} (${symbol.kind})`;
-}
-
-export function report(head: Baseline, { unlisted, added, stale }: Drift): string {
-  const sections = [
-    { symbols: unlisted, what: `unused export(s) not in ${BASELINE_FILE}:` },
-    { symbols: added, what: `${BASELINE_FILE} export(s) the range adds that its base did not leave unused, remove the export instead:` },
-    { symbols: stale, what: `${BASELINE_FILE} export(s) no longer reported, remove them:` },
-  ].filter(({ symbols }) => symbols.length > 0);
-  if (sections.length > 0) {
-    return sections.flatMap(({ symbols, what }) => [`${NAME}: ${symbols.length} ${what}`, ...symbols.map(describe)]).join("\n");
-  }
-  return head.length === 0
-    ? `${NAME}: no unused exports or types`
-    : `${NAME}: ${head.length} unused export(s) in ${BASELINE_FILE}, and no new ones`;
-}
-
-const scan = scanTree(NAME, INCLUDED, TYPESCRIPT_SOURCE).pipe(Effect.mapError((cause) => new ExportsError({ message: cause.message })));
-
-// Knip loads the configuration's imports, such as the kit's knip builder, from a node_modules the checkout lacks.
-const unusedAt = Effect.fn("unusedAt")(
-  function* (rev: string, root: string) {
-    const files = yield* pathsAt(rev, [], root);
-    if (files.length === 0) return [] satisfies readonly UnusedSymbol[];
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const tree = yield* checkoutFiles(rev, files, yield* fs.makeTempDirectoryScoped({ prefix: "checks-exports-" }), root);
-    const modules = path.join(root, "node_modules");
-    if (yield* fs.exists(modules)) yield* fs.symlink(modules, path.join(tree, "node_modules"));
-    const reported = yield* knipReport(tree, INCLUDED).pipe(
-      Effect.mapError((cause) => new ExportsError({ message: `at ${rev}: ${cause.message}` })),
-    );
-    return reported.kind === "unconfigured" ? [] : yield* symbolsOf(reported.stdout);
-  },
-  Effect.scoped,
-);
-
-// Knip scans the checked-out tree, and a pull request's merge checkout holds the base branch tip beside the range head.
-const judgedBase = Effect.fn("judgedBase")(function* (first: string, second: string | undefined, root: string) {
-  const { base } = yield* rangeEnds(first, second, root);
-  if (second === undefined) return base;
-  const head = yield* commitOf(second, root);
-  const parents = (yield* git(["rev-parse", "HEAD^@"], root)).split("\n").filter((line) => line !== "");
-  const [other, ...rest] = parents.filter((parent) => parent !== head);
-  return parents.includes(head) && other !== undefined && rest.length === 0 ? other : base;
-});
-
-const check = Effect.fn("check")(function* (first: string, second: string | undefined) {
-  const { root, reported } = yield* scan;
-  if (reported.kind === "unconfigured") return false;
-  const baseRev = yield* judgedBase(first, second, root);
-  const base = yield* baselineAt(baseRev, root);
-  const head = yield* baselineInTree(root);
-  const unusedAtBase = outside(head, base).length === 0 ? [] : yield* unusedAt(baseRev, root);
-  const drift = driftOf({ reported: yield* symbolsOf(reported.stdout), base, head, unusedAtBase });
-  yield* Console.log(report(head, drift));
-  return drift.unlisted.length === 0 && drift.added.length === 0 && drift.stale.length === 0;
-});
-
-const seed = Effect.gen(function* () {
-  const { root, reported } = yield* scan;
-  if (reported.kind === "unconfigured") return false;
-  const symbols = yield* symbolsOf(reported.stdout);
-  yield* (yield* FileSystem.FileSystem).writeFileString(yield* baselinePath(root), `${JSON.stringify(symbols, null, 2)}\n`);
-  yield* Console.log(`${NAME}: wrote ${symbols.length} unused export(s) to ${BASELINE_FILE}`);
-  return true;
-});
-
-const gate = Effect.gen(function* () {
-  const args = process.argv.slice(2);
-  if (args.length === 1 && args[0] === WRITE) return yield* seed;
-  const { first, second } = yield* refArgs(args, USAGE);
-  return yield* check(first, second);
-});
-
-if (import.meta.main) runMain(NAME, gate);

package/src/complexity/unused.ts

@@ -1,49 +0,0 @@
-#!/usr/bin/env bun
-import { Console, Effect, Schema } from "effect";
-import { LINTED_SOURCE } from "../core/gates.ts";
-import { runMain } from "../core/main.ts";
-import { scanTree } from "./knip.ts";
-
-export type Scan = { readonly tracked: number; readonly files: readonly string[] };
-
-const NAME = "unused";
-const JUDGED = /[.]tsx?$|[.]astro$/;
-
-class UnusedError extends Schema.TaggedError<UnusedError>()("UnusedError", {
-  message: Schema.String,
-}) {}
-
-const decodeKnipReport = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Struct({
-      issues: Schema.Array(Schema.Struct({ files: Schema.optional(Schema.Array(Schema.Struct({ name: Schema.String }))) })),
-    }),
-  ),
-);
-
-export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
-  const { issues } = yield* decodeKnipReport(stdout).pipe(
-    Effect.mapError((cause) => new UnusedError({ message: `knip's JSON report does not decode: ${cause.message}` })),
-  );
-  return issues
-    .flatMap(({ files = [] }) => files.map(({ name }) => name))
-    .filter((file) => JUDGED.test(file))
-    .toSorted();
-});
-
-export function report({ tracked, files }: Scan): string {
-  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx/.astro file(s)`;
-  return [`${NAME}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
-}
-
-const unused = Effect.gen(function* () {
-  const { tracked, reported } = yield* scanTree(NAME, ["--files"], LINTED_SOURCE).pipe(
-    Effect.mapError((cause) => new UnusedError({ message: cause.message })),
-  );
-  if (reported.kind === "unconfigured") return false;
-  const files = yield* filesOf(reported.stdout);
-  yield* Console.log(report({ tracked, files }));
-  return files.length === 0;
-});
-
-if (import.meta.main) runMain(NAME, unused);

package/src/dependencies/imports.ts

@@ -1,94 +0,0 @@
-#!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { collect, git } from "../core/git.ts";
-import { runMain, Usage } from "../core/main.ts";
-
-export const PROJECT_CONFIG = "dependency-cruiser.config.ts";
-
-export const OWN_CONFIGS = [
-  ".dependency-cruiser.json",
-  ".dependency-cruiser.js",
-  ".dependency-cruiser.cjs",
-  ".dependency-cruiser.mjs",
-  ".dependency-cruiser.ts",
-  ".dependency-cruiser.cts",
-  ".dependency-cruiser.mts",
-] as const;
-
-export const CRUISED = ["*.ts", "*.tsx", "*.mts", "*.cts"] as const;
-
-const NAME = "imports";
-const USAGE = "usage: imports.ts";
-const KIT_DEFAULTS = "kit-defaults.ts";
-
-class ImportsError extends Schema.TaggedError<ImportsError>()("ImportsError", {
-  message: Schema.String,
-}) {}
-
-const Violation = Schema.Struct({
-  from: Schema.String,
-  to: Schema.String,
-  rule: Schema.Struct({ name: Schema.String, severity: Schema.String }),
-});
-
-export type Violation = typeof Violation.Type;
-
-const decodeCruise = Schema.decodeUnknownEffect(
-  Schema.fromJsonString(
-    Schema.Struct({
-      summary: Schema.Struct({ violations: Schema.Array(Violation), error: Schema.Int, totalCruised: Schema.Int }),
-    }),
-  ),
-);
-
-export function describeViolation({ from, to, rule }: Violation): string {
-  return from === to ? `  ${rule.severity} ${rule.name}: ${from}` : `  ${rule.severity} ${rule.name}: ${from} → ${to}`;
-}
-
-const configOf = Effect.fn("configOf")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  for (const name of [PROJECT_CONFIG, ...OWN_CONFIGS]) {
-    if (yield* fs.exists(path.join(root, name))) return { file: name, shown: name };
-  }
-  return { file: path.join(import.meta.dir, KIT_DEFAULTS), shown: "the kit's defaults" };
-});
-
-const depcruise = Effect.fn("depcruise")(function* () {
-  const path = yield* Path.Path;
-  const main = yield* Effect.try({
-    try: () => new URL("../../bin/dependency-cruiser.mjs", import.meta.resolve("dependency-cruiser")),
-    catch: () => new ImportsError({ message: "cannot resolve dependency-cruiser, a peer dependency of the kit" }),
-  });
-  return yield* path.fromFileUrl(main);
-});
-
-const trackedInTree = Effect.fn("trackedInTree")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const listed = yield* git(["ls-files", "-z", "--", ...CRUISED], root);
-  return yield* Effect.filter(listed.split("\0").filter(Boolean), (file) => fs.exists(path.join(root, file)), { concurrency: "unbounded" });
-});
-
-const imports = Effect.gen(function* () {
-  if (process.argv.length > 2) return yield* new Usage({ message: USAGE });
-  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const files = yield* trackedInTree(root);
-  if (files.length === 0) return yield* new ImportsError({ message: "no tracked TypeScript to cruise" });
-  const config = yield* configOf(root);
-  const run = yield* collect(process.execPath, [yield* depcruise(), "--config", config.file, "--output-type", "json", ...files], root).pipe(
-    Effect.mapError((cause) => new ImportsError({ message: `cannot run dependency-cruiser: ${cause.message}` })),
-  );
-  const { summary } = yield* decodeCruise(run.stdout).pipe(
-    Effect.mapError(() => new ImportsError({ message: `dependency-cruiser exits ${run.exitCode} with no report: ${(run.stdout + run.stderr).trim()}` })),
-  );
-  const cruised = `${summary.totalCruised} module(s) cruised against ${config.shown}`;
-  if (summary.violations.length === 0) {
-    yield* Console.log(`${NAME}: ${cruised}, no violation`);
-    return true;
-  }
-  yield* Console.error([`${NAME}: ${summary.violations.length} violation(s) in ${cruised}`, ...summary.violations.map(describeViolation)].join("\n"));
-  return summary.error === 0;
-});
-
-if (import.meta.main) runMain(NAME, imports);