typescript-bedrock 0.1.3 → 0.1.5

package/files/base/.markdownlint.jsonc

@@ -2,6 +2,10 @@
 	"default": true,
 	// Lines wrap where the writer breaks them; prose is not reflowed.
 	"line-length": false,
+	// A changelog repeats Added, Changed, and Fixed under each version.
+	"no-duplicate-heading": {
+		"siblings_only": true,
+	},
 	"table-column-style": {
 		"style": "compact",
 	},

package/markdownlint.jsonc

@@ -2,6 +2,10 @@
 	"default": true,
 	// Lines wrap where the writer breaks them; prose is not reflowed.
 	"line-length": false,
+	// A changelog repeats Added, Changed, and Fixed under each version.
+	"no-duplicate-heading": {
+		"siblings_only": true,
+	},
 	"table-column-style": {
 		"style": "compact",
 	},

package/oxlintrc.json

@@ -345,6 +345,14 @@
 				"import/no-default-export": "off"
 			}
 		},
+		{
+			"files": ["**/hooks/**"],
+			"rules": {
+				"eslint/func-style": "off",
+				"promise/prefer-await-to-then": "off",
+				"promise/no-callback-in-promise": "off"
+			}
+		},
 		{
 			"files": ["**/*.d.{ts,mts,cts}"],
 			"rules": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "typescript-bedrock",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"description": "Strictest Bun + TypeScript 7 tooling: shared configs, git hooks, a guard, and an adopt command.",
 	"license": "MIT",
 	"author": "xsyetopz",

package/src/adopt/adopt.ts

@@ -1,8 +1,8 @@
 import { realpath } from "node:fs/promises";
 import { basename, join } from "node:path";
 
-import { mergeBunfig } from "./bunfig.ts";
-import { asRecord, exists, type Json, readJsonc, toJson } from "./json.ts";
+import { copies, existing, planBunfig } from "./copies.ts";
+import { asRecord, type Json, readJsonc, toJson } from "./json.ts";
 import { migrateManifest } from "./manifest.ts";
 import { sharedSteps } from "./shared.ts";
 import { pending, type Step } from "./steps.ts";
@@ -100,7 +100,8 @@ export const BASE_FILES = [
 	".markdownlint.jsonc",
 	"justfile",
 ];
-/** Thin files that point at typescript-bedrock. A changed copy is backed up, then replaced. */
+/** Thin files that point at typescript-bedrock. A changed copy is backed up, then replaced,
+ * except the entries a repo adds to the ignore list of `.oxlintrc.json` or `.markdownlint-cli2.jsonc`, which stay. */
 const TOOL_FILES = [
 	".bun-version",
 	".github/workflows/typescript.yml",
@@ -114,46 +115,6 @@ const STARTER_FILES = [".vscode/extensions.json", ".vscode/settings.json"];
 const OLD_CI = ".github/workflows/ci.yml";
 const OLD_CI_COMMAND = /\b(?:npm|npx|pnpm|yarn)\b|bun run verify/u;
 
-const existing = async (
-	root: string,
-	paths: readonly string[],
-): Promise<string[]> => {
-	const found = await Promise.all(
-		paths.map((path) => exists(join(root, path))),
-	);
-	return paths.filter((_, index) => found[index] === true);
-};
-
-/** npm packs drop `bunfig.toml`, and linters read nested configs, so these keep a suffix. */
-const STORED_WITH_SUFFIX = new Set([
-	".markdownlint-cli2.jsonc",
-	".oxlintrc.json",
-	"bunfig.toml",
-]);
-const storedPath = (path: string): string =>
-	STORED_WITH_SUFFIX.has(path) ? `${path}.template` : path;
-
-const copyFile = async (dir: string, path: string): Promise<Step> => ({
-	kind: "write",
-	path,
-	content: await Bun.file(join(dir, storedPath(path))).text(),
-	executable: path.startsWith(".githooks/"),
-});
-
-const copies = async (
-	dir: string,
-	target: string,
-	paths: readonly string[],
-	overwrite: boolean,
-): Promise<Step[]> => {
-	const present = new Set(overwrite ? [] : await existing(target, paths));
-	return Promise.all(
-		paths
-			.filter((path) => !present.has(path))
-			.map((path) => copyFile(dir, path)),
-	);
-};
-
 const planManifest = async (
 	packageRoot: string,
 	target: string,
@@ -176,21 +137,6 @@ const planManifest = async (
 	);
 };
 
-const planBunfig = async (
-	filesRoot: string,
-	target: string,
-): Promise<{ steps: Step[]; notes: string[] }> => {
-	const file = Bun.file(join(target, "bunfig.toml"));
-	const merged = mergeBunfig(
-		await Bun.file(join(filesRoot, storedPath("bunfig.toml"))).text(),
-		(await file.exists()) ? await file.text() : undefined,
-	);
-	return {
-		steps: [{ kind: "write", path: "bunfig.toml", content: merged.content }],
-		notes: merged.notes,
-	};
-};
-
 const planTsconfig = async (
 	packageRoot: string,
 	target: string,

package/src/adopt/copies.ts

@@ -0,0 +1,92 @@
+import { join } from "node:path";
+
+import { mergeBunfig } from "./bunfig.ts";
+import { IGNORE_KEYS, mergeIgnoreList } from "./ignore-lists.ts";
+import { exists, readJsonc } from "./json.ts";
+import type { Step } from "./steps.ts";
+
+/** The paths under `root` that exist. */
+export const existing = async (
+	root: string,
+	paths: readonly string[],
+): Promise<string[]> => {
+	const found = await Promise.all(
+		paths.map((path) => exists(join(root, path))),
+	);
+	return paths.filter((_, index) => found[index] === true);
+};
+
+/** npm packs drop `bunfig.toml`, and linters read nested configs, so these keep a suffix. */
+const STORED_WITH_SUFFIX = new Set([
+	".markdownlint-cli2.jsonc",
+	".oxlintrc.json",
+	"bunfig.toml",
+]);
+export const storedPath = (path: string): string =>
+	STORED_WITH_SUFFIX.has(path) ? `${path}.template` : path;
+
+/** The template's text, plus the ignore entries the repo's copy adds to it. */
+const contentOf = async (
+	dir: string,
+	target: string,
+	path: string,
+): Promise<string> => {
+	const template = await Bun.file(join(dir, storedPath(path))).text();
+	const key = IGNORE_KEYS[path];
+	return key === undefined
+		? template
+		: mergeIgnoreList(template, await readJsonc(join(target, path)), key);
+};
+
+const copyFile = async (
+	dir: string,
+	target: string,
+	path: string,
+): Promise<Step[]> => {
+	const content = await contentOf(dir, target, path);
+	// A repo's own layout of its ignore list stays when the data matches.
+	if (
+		path in IGNORE_KEYS &&
+		Bun.deepEquals(
+			Bun.JSONC.parse(content),
+			await readJsonc(join(target, path)),
+		)
+	) {
+		return [];
+	}
+	return [
+		{ kind: "write", path, content, executable: path.startsWith(".githooks/") },
+	];
+};
+
+/** Writes each of `paths` from `dir`; with `overwrite` off, only the ones `target` lacks. */
+export const copies = async (
+	dir: string,
+	target: string,
+	paths: readonly string[],
+	overwrite: boolean,
+): Promise<Step[]> => {
+	const present = new Set(overwrite ? [] : await existing(target, paths));
+	const steps = await Promise.all(
+		paths
+			.filter((path) => !present.has(path))
+			.map((path) => copyFile(dir, target, path)),
+	);
+	return steps.flat();
+};
+
+/** The template's `bunfig.toml` plus the settings the repo's copy adds. */
+export const planBunfig = async (
+	filesRoot: string,
+	target: string,
+): Promise<{ steps: Step[]; notes: string[] }> => {
+	const file = Bun.file(join(target, "bunfig.toml"));
+	const merged = mergeBunfig(
+		await Bun.file(join(filesRoot, storedPath("bunfig.toml"))).text(),
+		(await file.exists()) ? await file.text() : undefined,
+	);
+	return {
+		steps: [{ kind: "write", path: "bunfig.toml", content: merged.content }],
+		notes: merged.notes,
+	};
+};

package/src/adopt/ignore-lists.ts

@@ -0,0 +1,41 @@
+import { asRecord, asStrings } from "./json.ts";
+
+/** The ignore list each tool config keeps, which a repo may extend. */
+export const IGNORE_KEYS: Readonly<Record<string, string>> = {
+	".markdownlint-cli2.jsonc": "ignores",
+	".oxlintrc.json": "ignorePatterns",
+};
+
+const arrayOf = (key: string): RegExp =>
+	new RegExp(`("${key}"\\s*:\\s*)\\[([^\\]]*)\\]`, "u");
+
+/**
+ * Writes the template's config with the entries `current` lists under `key`
+ * and the template lacks added after the template's own, in the template's
+ * layout and with its comments.
+ */
+export const mergeIgnoreList = (
+	template: string,
+	current: unknown,
+	key: string,
+): string => {
+	const found = arrayOf(key).exec(template);
+	if (found === null) {
+		return template;
+	}
+	const have = new Set(asStrings(Bun.JSONC.parse(`[${found[2] ?? ""}]`)));
+	const extra = [
+		...new Set(asStrings(asRecord(current)[key]).filter((e) => !have.has(e))),
+	];
+	if (extra.length === 0) {
+		return template;
+	}
+	const items = [...have, ...extra].map((entry) => JSON.stringify(entry));
+	const body = (found[2] ?? "").includes("\n")
+		? `\n${items.map((item) => `\t\t${item}`).join(",\n")}\n\t`
+		: items.join(", ");
+	return template.replace(
+		arrayOf(key),
+		(_, head: string) => `${head}[${body}]`,
+	);
+};

package/src/adopt/tests.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 
 import { listFiles } from "../files.ts";
+import { readBunfigTestIgnores } from "../ignores.ts";
 import type { Step } from "./steps.ts";
 
 const TEST_FILES = new Bun.Glob(
@@ -40,9 +41,16 @@ export const migrateTestFile = (text: string): string => {
 		: text;
 };
 
-/** Rewrites each test file outside node_modules and git's ignored files that is not on bun:test yet. */
+/**
+ * Rewrites each test file that is not on bun:test yet, except those in node_modules,
+ * those git ignores, and those bunfig.toml keeps `bun test` from running.
+ */
 export const testSteps = async (target: string): Promise<Step[]> => {
-	const paths = await listFiles(target, TEST_FILES);
+	const paths = await listFiles(
+		target,
+		TEST_FILES,
+		await readBunfigTestIgnores(target),
+	);
 	const texts = await Promise.all(
 		paths.map((path) => Bun.file(join(target, path)).text()),
 	);

package/src/files.ts

@@ -2,8 +2,17 @@ import { join } from "node:path";
 
 import { $, type Glob } from "bun";
 
-/** The files under `cwd` that match `glob`, without the ones git ignores and without node_modules. */
-export const listFiles = async (cwd: string, glob: Glob): Promise<string[]> => {
+import { isIgnored } from "./ignores.ts";
+
+/**
+ * The files under `cwd` that match `glob`, without the ones git ignores, the
+ * ones `ignore` matches, and node_modules.
+ */
+export const listFiles = async (
+	cwd: string,
+	glob: Glob,
+	ignore: readonly string[] = [],
+): Promise<string[]> => {
 	const git = await $`git ls-files --cached --others --exclude-standard`
 		.cwd(cwd)
 		.nothrow()
@@ -13,7 +22,10 @@ export const listFiles = async (cwd: string, glob: Glob): Promise<string[]> => {
 			? git.stdout.toString().split("\n")
 			: await Array.fromAsync(glob.scan({ cwd }))
 	).filter(
-		(path) => glob.match(path) && !path.split("/").includes("node_modules"),
+		(path) =>
+			glob.match(path) &&
+			!path.split("/").includes("node_modules") &&
+			!isIgnored(path, ignore),
 	);
 	// The index still lists a file deleted since the last commit.
 	const present = await Promise.all(

package/src/guard.ts

@@ -5,6 +5,7 @@ import { $, Glob } from "bun";
 
 import { planAdoption, PROJECT_FILES } from "./adopt/adopt.ts";
 import { listFiles } from "./files.ts";
+import { readOxlintIgnores } from "./ignores.ts";
 
 // Written as alternations so this file does not match itself.
 const SUPPRESSION =
@@ -181,9 +182,12 @@ const reExported = (
  * The tracked source files each package exposes: its entry points and, through
  * relative re-exports, the files they re-export from.
  */
-const listApiFiles = async (cwd: string): Promise<string[]> => {
-	const sources = new Set(await listFiles(cwd, SOURCE));
-	const manifests = await listFiles(cwd, MANIFEST);
+const listApiFiles = async (
+	cwd: string,
+	ignore: readonly string[],
+): Promise<string[]> => {
+	const sources = new Set(await listFiles(cwd, SOURCE, ignore));
+	const manifests = await listFiles(cwd, MANIFEST, ignore);
 	const entries = await Promise.all(
 		manifests.map(async (path) => {
 			const manifest: unknown = await Bun.file(join(cwd, path)).json();
@@ -215,8 +219,11 @@ const listApiFiles = async (cwd: string): Promise<string[]> => {
 };
 
 /** Exported declarations in the package API that lack a JSDoc comment. */
-const findUndocumentedApi = async (cwd: string): Promise<string[]> => {
-	const files = await listApiFiles(cwd);
+const findUndocumentedApi = async (
+	cwd: string,
+	ignore: readonly string[],
+): Promise<string[]> => {
+	const files = await listApiFiles(cwd, ignore);
 	if (files.length === 0) {
 		return [];
 	}
@@ -255,15 +262,18 @@ const findDrift = async (cwd: string): Promise<string[]> => {
 		);
 };
 
-export const findProblems = async (cwd: string): Promise<string[]> => [
-	...(await findSuppressions(cwd, await listFiles(cwd, SOURCE))),
-	...(await findUndocumentedApi(cwd)),
-	...(await findForeignFiles(cwd)),
-	...(await findForeignScripts(cwd)),
-	...(await findTypescriptDrift(cwd)),
-	...findUnsortedCatalogs(await Bun.file(join(cwd, "package.json")).json()),
-	...(await findDrift(cwd)),
-];
+export const findProblems = async (cwd: string): Promise<string[]> => {
+	const ignore = await readOxlintIgnores(cwd);
+	return [
+		...(await findSuppressions(cwd, await listFiles(cwd, SOURCE, ignore))),
+		...(await findUndocumentedApi(cwd, ignore)),
+		...(await findForeignFiles(cwd)),
+		...(await findForeignScripts(cwd)),
+		...(await findTypescriptDrift(cwd)),
+		...findUnsortedCatalogs(await Bun.file(join(cwd, "package.json")).json()),
+		...(await findDrift(cwd)),
+	];
+};
 
 export const guard = async (cwd: string): Promise<number> => {
 	const problems = await findProblems(cwd);

package/src/ignores.ts

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+
+import { Glob } from "bun";
+
+import { asRecord, asStrings, readJsonc } from "./adopt/json.ts";
+
+/** The globs a gitignore-style `pattern` stands for: the path itself and what is under it. */
+const globsOf = (pattern: string): string[] => {
+	const dir = pattern.replace(/\/+$/u, "");
+	const anchored = dir.startsWith("/") || dir.includes("/", 1);
+	const base = dir.replace(/^\//u, "");
+	const glob = anchored ? base : `**/${base}`;
+	return [glob, `${glob}/**`];
+};
+
+/**
+ * Whether `path`, relative to the repo root, matches `patterns`: gitignore-style
+ * entries (a bare name matches at any depth, `dir/` matches a directory, a
+ * later `!entry` re-includes) that Bun's glob syntax can read.
+ */
+export const isIgnored = (
+	path: string,
+	patterns: readonly string[],
+): boolean => {
+	let ignored = false;
+	for (const entry of patterns) {
+		const negated = entry.startsWith("!");
+		const pattern = negated ? entry.slice(1) : entry;
+		if (
+			pattern !== "" &&
+			globsOf(pattern).some((glob) => new Glob(glob).match(path))
+		) {
+			ignored = !negated;
+		}
+	}
+	return ignored;
+};
+
+/** The `ignorePatterns` of the repo's `.oxlintrc.json`, which the repo may extend. */
+export const readOxlintIgnores = async (cwd: string): Promise<string[]> =>
+	asStrings(
+		asRecord(await readJsonc(join(cwd, ".oxlintrc.json")))["ignorePatterns"],
+	);
+
+/** The `[test] pathIgnorePatterns` of the repo's `bunfig.toml`: the paths `bun test` skips. */
+export const readBunfigTestIgnores = async (cwd: string): Promise<string[]> => {
+	const file = Bun.file(join(cwd, "bunfig.toml"));
+	if (!(await file.exists())) {
+		return [];
+	}
+	const patterns = asRecord(
+		asRecord(Bun.TOML.parse(await file.text()))["test"],
+	)["pathIgnorePatterns"];
+	return typeof patterns === "string" ? [patterns] : asStrings(patterns);
+};