@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/knip-check.ts

@@ -0,0 +1,169 @@
+/**
+ * `repo check`'s knip lines: one knip run against the generated config without its ignores, every issue it finds a
+ * problem unless a `knip.ignore` entry covers it, each entry reported with its reason, and an entry that matches
+ * nothing (before or after the run) refused. The config is written beside `knip.json` for the run and named for the
+ * process, so two checks never remove each other's copy.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { findRoot, loadConfig } from "./config.ts";
+import {
+  BINARIES_TYPE,
+  DEPENDENCY_TYPES,
+  EXIT_BAD_CONFIG,
+  FILES_TYPE,
+  MANIFEST_FIELDS,
+  STDERR_LINES,
+  WORDINGS,
+  type Wording,
+} from "./knip-check.constants.ts";
+import type { KnipIgnore } from "./knip-schema.ts";
+import { captureBun, type Captured } from "./scripts/lint.ts";
+import { knipConfig } from "./sync/knip-config.ts";
+import { readWorkspace, type Workspace } from "./sync/workspace.ts";
+
+/** What `repo check` prints of knip: report lines that pass, problem lines that fail it. */
+export type KnipCheck = { report: string[]; problems: string[] };
+/** Runs knip with `args` in `cwd`; the default spawns the knip this package installs. */
+export type KnipRun = (args: string[], cwd: string) => Captured;
+/** The knip runner `checkKnipAt` uses unless a test injects another. */
+export type KnipDeps = { run?: KnipRun };
+/** One knip finding: its file, how its type is worded, name and namespace (an enum's, say). */
+type Issue = { file: string; wording: Wording; name: string; namespace: string | undefined };
+
+const NONE: KnipCheck = { report: [], problems: [] };
+const FIX_CONFIG = "run `bun repo sync` and check knip.json";
+const entrySchema = () => z.object({ name: z.string(), namespace: z.string().optional() });
+const reportSchema = () => z.object({ issues: z.array(z.looseObject({ file: z.string() })) });
+const manifestSchema = () => z.object({ bin: z.object({ knip: z.string() }) });
+
+const unignoredPath = (): string => `knip.unignored-${process.pid}.json`;
+
+/** The path of the knip bin in this package's install. */
+function knipBin(): string {
+  const manifest = Bun.resolveSync("knip/package.json", import.meta.dirname);
+  const { bin } = manifestSchema().parse(JSON.parse(fs.readFileSync(manifest, "utf8")));
+  return path.join(path.dirname(manifest), bin.knip);
+}
+
+/** The knip runner for real: the resolved bin under bun, with no `GIT_*` variable. */
+const runKnip: KnipRun = (args, cwd) => captureBun([knipBin(), ...args], cwd);
+
+/** The issues in knip's json report, in its order; null when `stdout` is not that report. */
+function issuesOf(stdout: string): Issue[] | null {
+  try {
+    const parsed = reportSchema().parse(JSON.parse(stdout));
+    return parsed.issues.flatMap((entry) =>
+      WORDINGS.flatMap(
+        (wording) =>
+          z
+            .array(entrySchema())
+            .optional()
+            .parse(entry[wording.type])
+            ?.map(({ name, namespace }) => ({ file: entry.file, wording, name, namespace })) ?? [],
+      ),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** `knip: <file>: <what is wrong>; <the fix>`. */
+function lineOf({ file, wording, name, namespace }: Issue): string {
+  const { type, label, fix } = wording;
+  const subject = type === FILES_TYPE ? label : `${label} "${namespace === undefined ? name : `${namespace}.${name}`}"`;
+  return `knip: ${file}: ${subject}; ${fix}`;
+}
+
+/** Whether `ignore` covers `issue`. */
+function covers(ignore: KnipIgnore, issue: Issue): boolean {
+  if ("file" in ignore) return new Bun.Glob(ignore.file).match(issue.file);
+  if ("dependency" in ignore) return DEPENDENCY_TYPES.includes(issue.wording.type) && issue.name === ignore.dependency;
+  return issue.wording.type === BINARIES_TYPE && issue.name === ignore.binary;
+}
+
+/** `file "x"`, `dependency "x"` or `binary "x"`. */
+function kindName(ignore: KnipIgnore): [string, string] {
+  if ("file" in ignore) return ["file", ignore.file];
+  if ("dependency" in ignore) return ["dependency", ignore.dependency];
+  return ["binary", ignore.binary];
+}
+
+/** Why `ignore` is stale before knip runs, or null: its file is gone, or no package.json declares its dependency. */
+function staleBefore(workspace: Workspace, ignore: KnipIgnore): string | null {
+  if ("file" in ignore) {
+    const found = fs.globSync(ignore.file, { cwd: workspace.root }).length > 0;
+    return found ? null : `${ignore.file} no longer exists; delete the entry`;
+  }
+  if (!("dependency" in ignore)) return null;
+  const manifests = [workspace.manifest, ...workspace.packages.map((pkg) => pkg.manifest)];
+  const declared = manifests.some((manifest) =>
+    MANIFEST_FIELDS.some((f) => manifest[f]?.[ignore.dependency] !== undefined),
+  );
+  return declared ? null : `dependency "${ignore.dependency}" is in no package.json; delete the entry`;
+}
+
+/** The last lines of knip's stderr, on one line. */
+const tail = (stderr: string): string => stderr.trim().split("\n").slice(-STDERR_LINES).join(" ");
+
+/** Runs knip on the unignored config, written for the run only. */
+function runUnignored(workspace: Workspace, run: KnipRun): Captured {
+  const name = unignoredPath();
+  const file = path.join(workspace.root, name);
+  try {
+    fs.writeFileSync(file, knipConfig(workspace, []));
+    return run(["--config", name, "--no-exit-code", "--reporter", "json"], workspace.root);
+  } finally {
+    fs.rmSync(file, { force: true });
+  }
+}
+
+/** The issues no entry of `ignores` covers, and how many each entry covers (an issue two cover counts for both). */
+function applyIgnores(ignores: readonly KnipIgnore[], issues: readonly Issue[]): { open: Issue[]; hits: number[] } {
+  const hits = ignores.map((ignore) => issues.filter((issue) => covers(ignore, issue)).length);
+  return { open: issues.filter((issue) => !ignores.some((ignore) => covers(ignore, issue))), hits };
+}
+
+/** The report line for the entries that covered something, and a problem for each live entry that covered nothing. */
+function ignoreLines(ignores: readonly KnipIgnore[], hits: readonly number[], stale: readonly (string | null)[]) {
+  const unused = ignores.flatMap((ignore, i) => {
+    const [kind, name] = kindName(ignore);
+    const gone = hits[i] === 0 && stale[i] === null;
+    return gone ? [`knip.ignore[${i}]: ${kind} "${name}" has no knip issue any more; delete the entry`] : [];
+  });
+  const used = ignores.filter((_, i) => hits[i] !== 0);
+  const shown = used.map((ignore) => `${kindName(ignore).join(" ")} (${ignore.reason})`);
+  const line = `knip: ${used.length} ${used.length === 1 ? "ignore" : "ignores"}: ${shown.join(", ")}`;
+  return { report: used.length === 0 ? [] : [line], unused };
+}
+
+/**
+ * Every issue knip finds in `workspace` is a problem unless an entry of `ignores` covers it. Each covering entry is
+ * reported with its reason; one that matches nothing, before or after the run, is a problem.
+ */
+export function checkKnip(workspace: Workspace, ignores: readonly KnipIgnore[], run: KnipRun): KnipCheck {
+  const before = ignores.map((ignore) => staleBefore(workspace, ignore));
+  const stale = before.flatMap((why, i) => (why === null ? [] : [`knip.ignore[${i}]: ${why}`]));
+  const ran = runUnignored(workspace, run);
+  const issues = issuesOf(ran.stdout);
+  if (ran.code === EXIT_BAD_CONFIG || issues === null)
+    return { report: [], problems: [...stale, `knip: exited ${ran.code}: ${tail(ran.stderr)}; ${FIX_CONFIG}`] };
+  const { open, hits } = applyIgnores(ignores, issues);
+  const { report, unused } = ignoreLines(ignores, hits, before);
+  return { report, problems: [...stale, ...open.map(lineOf), ...unused] };
+}
+
+/**
+ * `repo check`'s knip lines for the repo at `cwd`: none without a config, the standards pack or a readable
+ * workspace.
+ */
+export async function checkKnipAt(cwd: string, deps: KnipDeps = {}): Promise<KnipCheck> {
+  const root = findRoot(cwd);
+  if (root === null) return NONE;
+  const loaded = await loadConfig(root);
+  if (!loaded.ok || !loaded.config.packs.includes("standards")) return NONE;
+  // An unreadable manifest is already reported by sync --check.
+  const read = readWorkspace(root);
+  return read.ok ? checkKnip(read.workspace, loaded.config.knip.ignore, deps.run ?? runKnip) : NONE;
+}

package/cli/knip-schema.ts

@@ -0,0 +1,67 @@
+/** The `knip` section of workerstack.config.ts: the sanctioned knip ignores. */
+import { z } from "zod";
+
+/** One `knip.ignore` entry: the file, dependency or binary knip is not to report, and why it cannot see the use. */
+export type KnipIgnore =
+  | { file: string; reason: string }
+  | { dependency: string; reason: string }
+  | { binary: string; reason: string };
+/** A `knip.ignore` entry as written: the schema refuses any that does not name exactly one of the three. */
+export type KnipIgnoreEntry = {
+  reason: string;
+  file?: string | undefined;
+  dependency?: string | undefined;
+  binary?: string | undefined;
+};
+/** What the generated knip config and `repo check` read from `knip`. */
+export type ResolvedKnip = { readonly ignore: readonly KnipIgnore[] };
+
+const REASON_ERROR = "say why knip cannot see the use";
+const ONE_KEY_ERROR = "name exactly one of file, dependency or binary";
+const IGNORE_LIST = "must be a list of { file | dependency | binary, reason } entries";
+
+const name = (error: string): z.ZodOptional<z.ZodString> => z.string({ error }).min(1, { error }).optional();
+
+type EntrySchema = z.ZodPipe<
+  z.ZodObject<
+    {
+      file: z.ZodOptional<z.ZodString>;
+      dependency: z.ZodOptional<z.ZodString>;
+      binary: z.ZodOptional<z.ZodString>;
+      reason: z.ZodString;
+    },
+    z.core.$strict
+  >,
+  z.ZodTransform<KnipIgnore, KnipIgnoreEntry>
+>;
+type KnipSchema = z.ZodObject<{ ignore: z.ZodOptional<z.ZodReadonly<z.ZodArray<EntrySchema>>> }, z.core.$strict>;
+
+/** One ignore: exactly one of `file`, `dependency` or `binary`, and why knip cannot see the use. */
+function entrySchema(): EntrySchema {
+  return z
+    .strictObject(
+      {
+        file: name("file must be a path"),
+        dependency: name("dependency must be a package name"),
+        binary: name("binary must be a command name"),
+        reason: z.string({ error: REASON_ERROR }).min(1, { error: REASON_ERROR }),
+      },
+      { error: 'must be an object like { file: "src/a.ts", reason: "why" }' },
+    )
+    .transform((entry, ctx): KnipIgnore => {
+      const { file, dependency, binary, reason } = entry;
+      if (file !== undefined && dependency === undefined && binary === undefined) return { file, reason };
+      if (dependency !== undefined && file === undefined && binary === undefined) return { dependency, reason };
+      if (binary !== undefined && file === undefined && dependency === undefined) return { binary, reason };
+      ctx.issues.push({ code: "custom", message: ONE_KEY_ERROR, input: entry });
+      return z.NEVER;
+    });
+}
+
+/** `knip`: the ignores, built when the config schema is. */
+export function knipSchema(): KnipSchema {
+  return z.strictObject(
+    { ignore: z.array(entrySchema(), { error: IGNORE_LIST }).readonly().optional() },
+    { error: "must be an object like { ignore: [{ file, reason }] }" },
+  );
+}

package/cli/known-failures.constants.ts

@@ -0,0 +1,22 @@
+/** The names the known-failures list and its check share. */
+
+/** Where the list lives unless the config says otherwise. */
+export const DEFAULT_LIST = "known-failures.json";
+/** Joins the file, the describe titles and the case title into one entry. */
+export const SEPARATOR = " > ";
+/** The modifier that marks a case expected to fail. */
+export const FAILS = "fails";
+/** The suite function whose title joins the names. */
+export const DESCRIBE = "describe";
+/** The test functions that carry `.fails`. */
+export const TEST_ROOTS: readonly string[] = ["it", "test"];
+/** Files worth parsing: ts tsx mts cts js jsx mjs cjs. */
+export const SOURCE: RegExp = /\.(?:[jt]sx?|[cm][jt]s)$/;
+/** The oxc node types the walk reads. */
+export const NODE = {
+  call: "CallExpression",
+  identifier: "Identifier",
+  member: "MemberExpression",
+  literal: "Literal",
+  template: "TemplateLiteral",
+} as const;

package/cli/known-failures.test.ts

@@ -0,0 +1,138 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { knownFailures } from "./known-failures.ts";
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A temp project holding `files` (path → content); the test files are those ending in `.test.ts`. */
+function project(files: Record<string, string>): { root: string; tests: string[] } {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "known-failures-"));
+  dirs.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), content);
+  }
+  return { root, tests: Object.keys(files).filter((rel) => rel.endsWith(".test.ts")) };
+}
+
+const list = (...entries: string[]) => JSON.stringify(entries);
+const run = (files: Record<string, string>) => {
+  const { root, tests } = project(files);
+  return knownFailures(root, tests);
+};
+
+describe("knownFailures, the code against the list", () => {
+  it("fails an it.fails that is not listed, at its line", () => {
+    const problems = run({ "a.test.ts": 'import { it } from "vitest";\n\nit.fails("parses", () => {});\n' });
+    expect(problems).toEqual(['a.test.ts:3: it.fails("parses") is not in known-failures.json; list it or fix it']);
+  });
+
+  it("fails test.fails and it.concurrent.fails the same way", () => {
+    const problems = run({ "a.test.ts": 'test.fails("one", () => {});\nit.concurrent.fails("two", () => {});\n' });
+    expect(problems).toEqual([
+      'a.test.ts:1: test.fails("one") is not in known-failures.json; list it or fix it',
+      'a.test.ts:2: it.concurrent.fails("two") is not in known-failures.json; list it or fix it',
+    ]);
+  });
+});
+
+describe("knownFailures, matching the list", () => {
+  it("passes cases the list names, nested describe titles joined", () => {
+    const problems = run({
+      "known-failures.json": list("a.test.ts > dates > utc > parses", "a.test.ts > top"),
+      "a.test.ts":
+        'describe("dates", () => { describe("utc", () => { it.fails("parses", () => {}); }); });\ntest.fails("top", () => {});\n',
+    });
+    expect(problems).toEqual([]);
+  });
+
+  it("fails a case whose describe path differs from the listed entry", () => {
+    const problems = run({
+      "known-failures.json": list("a.test.ts > parses"),
+      "a.test.ts": 'describe("dates", () => { it.fails("parses", () => {}); });\n',
+    });
+    expect(problems).toEqual([
+      'a.test.ts:1: it.fails("parses") is not in known-failures.json; list it or fix it',
+      'known-failures.json lists "a.test.ts > parses", which has no it.fails; remove it from the list',
+    ]);
+  });
+
+  it("fails a listed entry with no such case", () => {
+    const problems = run({ "known-failures.json": list("a.test.ts > gone"), "a.test.ts": "export {};\n" });
+    expect(problems).toEqual([
+      'known-failures.json lists "a.test.ts > gone", which has no it.fails; remove it from the list',
+    ]);
+  });
+});
+
+describe("knownFailures, titles and files", () => {
+  it("fails a title that is not a literal on its own line, and still lists the others", () => {
+    const problems = run({
+      "known-failures.json": list("a.test.ts > fine"),
+      "a.test.ts": 'const name = "x";\nit.fails("fine", () => {});\nit.fails(name, () => {});\n',
+    });
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toMatch(/^a\.test\.ts:3: it\.fails\(\) title is not a string literal/);
+  });
+
+  it("accepts a template title without placeholders", () => {
+    const problems = run({
+      "known-failures.json": list("a.test.ts > plain"),
+      "a.test.ts": "it.fails(`plain`, () => {});\n",
+    });
+    expect(problems).toEqual([]);
+  });
+});
+
+describe("knownFailures, what it leaves alone", () => {
+  it("ignores plain cases and .fails on other objects", () => {
+    const problems = run({ "a.test.ts": 'it("ok", () => {});\nconst r = { fails: () => 1 };\nr.fails();\n' });
+    expect(problems).toEqual([]);
+  });
+
+  it("passes with no list file and no .fails", () => {
+    expect(run({ "a.test.ts": 'it("ok", () => {});\n' })).toEqual([]);
+  });
+
+  it("reads the list from the path it is given", () => {
+    const { root, tests } = project({
+      "lists/kf.json": list("a.test.ts > x"),
+      "a.test.ts": 'it.fails("x", () => {});\n',
+    });
+    expect(knownFailures(root, tests, "lists/kf.json")).toEqual([]);
+  });
+});
+
+describe("knownFailures, odd shapes", () => {
+  it("names a template with a placeholder, a number title and a non-literal describe as non-literal", () => {
+    const problems = run({
+      "a.test.ts":
+        'it.fails(`a ${1}`, () => {});\nit.fails(5, () => {});\ndescribe(name, () => { it.fails("x", () => {}); });\nit.fails();\n',
+    });
+    expect(problems.map((line) => line.slice(0, "a.test.ts:N".length))).toEqual([
+      "a.test.ts:1",
+      "a.test.ts:2",
+      "a.test.ts:3",
+      "a.test.ts:4",
+    ]);
+  });
+
+  it("ignores callees that are no it or test chain", () => {
+    const problems = run({
+      "a.test.ts": 'it["fails"]("x", () => {});\nmake()("y");\nmake().fails("z");\nthis.fails("w");\nit.fails;\n',
+    });
+    expect(problems).toEqual([]);
+  });
+
+  it("reads an invalid list, a list that is no array and a missing test file as empty", () => {
+    const bad = project({ "known-failures.json": "{", "a.test.ts": "export {};\n" });
+    expect(knownFailures(bad.root, bad.tests)).toEqual([]);
+    const object = project({ "known-failures.json": "{}", "a.test.ts": "export {};\n" });
+    expect(knownFailures(object.root, [...object.tests, "gone.test.ts", "notes.md"])).toEqual([]);
+  });
+});

package/cli/known-failures.ts

@@ -0,0 +1,131 @@
+/**
+ * The known-failures list: every `it.fails` / `test.fails` case named `<file> > <describe titles> > <title>` in a JSON
+ * array, so a case that starts passing is the only way a listed one leaves, and a new one cannot appear unlisted.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseSync } from "oxc-parser";
+import { DEFAULT_LIST, DESCRIBE, FAILS, NODE, SEPARATOR, SOURCE, TEST_ROOTS } from "./known-failures.constants.ts";
+
+/** A `.fails` case found in a file: where, how it was called, and its name, or null for a title that is no literal. */
+type Case = { line: number; call: string; title: string | null; name: string | null };
+
+type Node = Record<string, unknown>;
+
+const isNode = (value: unknown): value is Node => typeof value === "object" && value !== null;
+const isString = (value: unknown): value is string => typeof value === "string";
+const lineOf = (source: string, at: number) => source.slice(0, at).split("\n").length;
+/** `value[key]`, or undefined when `value` is no node. */
+const get = (value: unknown, key: string): unknown => (isNode(value) ? value[key] : undefined);
+
+/** The identifiers of a callee chain `a.b.c`, root first; null when the chain holds anything else. */
+function chainOf(callee: unknown): string[] | null {
+  const type = get(callee, "type");
+  if (type === NODE.identifier) return [String(get(callee, "name"))];
+  if (type !== NODE.member || get(callee, "computed") === true) return null;
+  const head = chainOf(get(callee, "object"));
+  return head === null ? null : [...head, String(get(get(callee, "property"), "name"))];
+}
+
+/** The text of a string literal or a template without expressions, else null. */
+function titleOf(arg: unknown): string | null {
+  if (get(arg, "type") === NODE.literal) {
+    const value = get(arg, "value");
+    return isString(value) ? value : null;
+  }
+  const bare = get(arg, "type") === NODE.template && get(get(arg, "expressions"), "length") === 0;
+  return bare ? String(get(get(get(get(arg, "quasis"), "0"), "value"), "cooked")) : null;
+}
+
+type Scope = (string | null)[];
+
+function caseOf(node: Node, scope: Scope, source: string): Case {
+  const title = titleOf(get(get(node, "arguments"), "0"));
+  const start = Number(get(node, "start"));
+  const end = Number(get(get(node, "callee"), "end"));
+  const named = title === null || scope.includes(null) ? null : [...scope, title].join(SEPARATOR);
+  return { line: lineOf(source, start), call: source.slice(start, end), title, name: named };
+}
+
+/** The scope inside `node`: a `describe` call adds its title (null when it is no literal). */
+function scopeOf(node: Node, chain: string[] | null, scope: Scope): Scope {
+  if (chain?.[0] !== DESCRIBE) return scope;
+  return [...scope, titleOf(get(get(node, "arguments"), "0"))];
+}
+
+const isFailsCall = (chain: string[] | null): chain is string[] =>
+  chain !== null && TEST_ROOTS.includes(String(chain[0])) && chain.includes(FAILS);
+
+/** What a walk carries: the source it reads and the cases it found. */
+type Walk = { source: string; out: Case[] };
+
+/** The cases under `node`, `scope` being the describe titles around it (null for one that is no literal). */
+function collect(node: unknown, scope: Scope, walk: Walk): void {
+  if (Array.isArray(node)) {
+    for (const child of node) collect(child, scope, walk);
+    return;
+  }
+  if (!isNode(node)) return;
+  const chain = node["type"] === NODE.call ? chainOf(node["callee"]) : null;
+  if (isFailsCall(chain)) walk.out.push(caseOf(node, scope, walk.source));
+  const inner = scopeOf(node, chain, scope);
+  for (const child of Object.values(node)) collect(child, inner, walk);
+}
+
+function casesOf(rel: string, source: string): Case[] {
+  if (!source.includes(`.${FAILS}`)) return [];
+  const found: Case[] = [];
+  collect(parseSync(rel, source).program, [], { source, out: found });
+  return found;
+}
+
+function readText(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** The list's entries, or null when the file is absent; a file that is no array of strings is an empty list. */
+function readList(file: string): string[] | null {
+  const text = readText(file);
+  if (text === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed.filter(isString) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The problems between the `.fails` cases of the test `files` (relative to `root`) and the list at `list` (default
+ * `known-failures.json`): a case not listed, a non-literal title, a listed entry with no case. No list file counts as
+ * an empty list.
+ */
+export function knownFailures(root: string, files: readonly string[], list: string = DEFAULT_LIST): string[] {
+  const listed = readList(path.join(root, list)) ?? [];
+  const seen = new Set<string>();
+  const problems: string[] = [];
+  for (const rel of files.filter((f) => SOURCE.test(f))) {
+    const source = readText(path.join(root, rel));
+    if (source === null) continue;
+    for (const found of casesOf(rel, source)) {
+      const at = `${rel}:${found.line}`;
+      if (found.name === null) {
+        problems.push(
+          `${at}: ${found.call}() title is not a string literal; write the title as a literal so ${list} can name it`,
+        );
+        continue;
+      }
+      const name = `${rel}${SEPARATOR}${found.name}`;
+      seen.add(name);
+      if (!listed.includes(name))
+        problems.push(`${at}: ${found.call}("${found.title}") is not in ${list}; list it or fix it`);
+    }
+  }
+  for (const entry of listed)
+    if (!seen.has(entry)) problems.push(`${list} lists "${entry}", which has no it.fails; remove it from the list`);
+  return problems;
+}

package/cli/lint/as-needs-reason.ts

@@ -0,0 +1,41 @@
+import type { Comment, ESTree, CreateRule } from "@oxlint/plugins";
+import { isReason } from "./is-reason.ts";
+
+const AS_KEYWORD = /\bas\b/;
+
+/** `as const` and `as unknown` claim nothing a reader must trust. */
+function claimsNothing(type: ESTree.TSType): boolean {
+  if (type.type === "TSUnknownKeyword") return true;
+  return type.type === "TSTypeReference" && type.typeName.type === "Identifier" && type.typeName.name === "const";
+}
+
+/** Whether a block comment of a reason lies after the expression and before the `as` keyword. */
+function hasReason(text: string, comments: readonly Comment[], node: ESTree.TSAsExpression): boolean {
+  let edge = node.expression.end;
+  for (const comment of comments) {
+    if (comment.start < edge || comment.end > node.typeAnnotation.start) continue;
+    if (AS_KEYWORD.test(text.slice(edge, comment.start))) return false;
+    if (comment.type === "Block" && isReason(comment.value)) return true;
+    edge = comment.end;
+  }
+  return false;
+}
+
+/**
+ * Fails an `as` cast with no reason right before its keyword: `x as Foo` tells the checker to trust it, so the reader
+ * is told why. `as const` and `as unknown` pass; `<Foo>x` is native `typescript/consistent-type-assertions`'.
+ */
+export const asNeedsReason: CreateRule = {
+  create(context) {
+    return {
+      TSAsExpression(node) {
+        if (claimsNothing(node.typeAnnotation)) return;
+        const { text } = context.sourceCode;
+        if (hasReason(text, context.sourceCode.getAllComments(), node)) return;
+        const type = text.slice(node.typeAnnotation.start, node.typeAnnotation.end);
+        const message = `"as ${type}" needs a reason: write x /* why the type holds */ as ${type}, or narrow with a check or a schema parse`;
+        context.report({ message, node });
+      },
+    };
+  },
+};

package/cli/lint/boundaries.ts

@@ -0,0 +1,73 @@
+import { builtinModules } from "node:module";
+import path from "node:path";
+import type { ESTree, CreateRule } from "@oxlint/plugins";
+import { type Manifest, nearestManifest, readManifest } from "./manifest.ts";
+
+/** The file being linted, its package's manifest, and the dir paths in messages are relative to. */
+type Where = { cwd: string; filename: string; own: Manifest };
+type Sourced =
+  | ESTree.ImportDeclaration
+  | ESTree.ExportNamedDeclaration
+  | ESTree.ExportAllDeclaration
+  | ESTree.ImportExpression;
+
+/** `node:fs`, `bun:test`, `virtual:x`: a scheme names no installed package. */
+const SCHEME = /^[a-z][a-z\d+.-]*:/i;
+
+/** `@scope/pkg/sub` → `@scope/pkg`; `pkg/sub` → `pkg`. */
+function packageName(specifier: string): string {
+  const parts = specifier.split("/");
+  return parts.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+}
+
+const exempt = (specifier: string): boolean =>
+  specifier.startsWith("#") ||
+  SCHEME.test(specifier) ||
+  specifier === "bun" ||
+  builtinModules.includes(packageName(specifier));
+
+const shown = (cwd: string, to: string): string => path.relative(cwd, to).replaceAll("\\", "/");
+
+/** The message for a path specifier whose target belongs to another package, or null when it stays home. */
+function reachProblem(where: Where, specifier: string): string | null {
+  const file = nearestManifest(path.resolve(path.dirname(where.filename), specifier));
+  if (file === null || file === where.own.file) return null;
+  const dir = shown(where.cwd, path.dirname(file)) || "the root package";
+  const name = readManifest(file)?.name ?? null;
+  return name === null
+    ? `"${specifier}" reaches into ${dir}; name it in ${shown(where.cwd, file)} and import it by that name`
+    : `"${specifier}" reaches into ${dir}; import it as "${name}"`;
+}
+
+function problemOf(where: Where, specifier: string): string | null {
+  if (specifier.startsWith(".") || path.isAbsolute(specifier)) return reachProblem(where, specifier);
+  const name = packageName(specifier);
+  if (exempt(specifier) || name === where.own.name || where.own.declared.includes(name)) return null;
+  return `"${name}" is not declared in ${shown(where.cwd, where.own.file)}; add it to its dependencies`;
+}
+
+/**
+ * Keeps each file to its own package: a path import stays inside its nearest package.json, and a package import is
+ * the package itself or one its manifest declares. Type-only imports and `import()` count; a file whose manifest
+ * cannot be read is skipped.
+ */
+export const boundaries: CreateRule = {
+  create(context) {
+    const ownFile = nearestManifest(path.dirname(context.filename));
+    const own = ownFile === null ? null : readManifest(ownFile);
+    if (own === null) return {};
+    const where: Where = { cwd: context.cwd, filename: context.filename, own };
+    const check = (node: Sourced): void => {
+      const { source } = node;
+      if (source?.type !== "Literal" || typeof source.value !== "string") return;
+      const message = problemOf(where, source.value);
+      if (message !== null) context.report({ message, node });
+    };
+    return {
+      ImportDeclaration: check,
+      ExportNamedDeclaration: check,
+      ExportAllDeclaration: check,
+      ImportExpression: check,
+    };
+  },
+};