@homeflare/config 0.1.1 → 0.2.0

package/README.md

@@ -1,12 +1,22 @@
 # @homeflare/config
 
-Shared TypeScript, oxlint and oxfmt configuration. One place to change a rule, rather
-than one copy per repo that drifts.
+The HomeFlare toolchain, as configuration. One place to change a rule, rather than one
+copy per repo that drifts.
 
 ```sh
 bun add -D @homeflare/config
 ```
 
+## What it gives you
+
+| file                 | how to use it                           |
+| -------------------- | --------------------------------------- |
+| `tsconfig.base.json` | `extends` — apps and Workers            |
+| `tsconfig.lib.json`  | `extends` — packages that publish types |
+| `oxlintrc.json`      | `extends` — 36 rules, 6 plugins         |
+| `oxfmtrc.json`       | copy to `.oxfmtrc.json`                 |
+| `bunfig.toml`        | copy to `bunfig.toml`                   |
+
 ## tsconfig
 
 ```jsonc
@@ -17,11 +27,10 @@ bun add -D @homeflare/config
 { "extends": "@homeflare/config/tsconfig.lib.json" }
 ```
 
-`tsconfig.lib.json` adds `isolatedDeclarations` and `declaration` on top of the base.
-⛔ Both are needed together — `isolatedDeclarations` alone is TS5069, even under
-`--noEmit`.
+`tsconfig.lib.json` adds `isolatedDeclarations` and `declaration`. ⛔ Both are needed
+together — `isolatedDeclarations` alone is TS5069, even under `--noEmit`.
 
-The base turns on `strict`, plus the three flags that catch the most runtime bugs:
+The base turns on `strict` plus the flags that catch the most runtime bugs:
 `noUncheckedIndexedAccess` (`arr[0]` is `T | undefined`), `exactOptionalPropertyTypes`,
 and `noFallthroughCasesInSwitch`.
 
@@ -34,14 +43,41 @@ and `noFallthroughCasesInSwitch`.
 ⚠️ oxlint's `extends` takes **file paths**, not package names — there is no
 `eslint-config-*` style resolution, so the path into `node_modules` is written out.
 
-## oxfmt
+36 rules across `typescript`, `unicorn`, `oxc`, `import`, `react` and `jsx-a11y`. The ones
+worth knowing:
+
+- `no-console: error` — ⚠️ except where `console` _is_ the transport, as in a Worker
+  writing JSON for Workers Logs. Override it per file, not globally.
+- `typescript/no-non-null-assertion` — `!` hides exactly what `noUncheckedIndexedAccess`
+  is trying to surface.
+- `react/exhaustive-deps`, `jsx-a11y/click-events-have-key-events` — only bite in React
+  code; a Worker never sees them.
+
+## oxfmt and bunfig
 
 ```sh
 cp node_modules/@homeflare/config/oxfmtrc.json .oxfmtrc.json
+cp node_modules/@homeflare/config/bunfig.toml  bunfig.toml
+```
+
+⚠️ `.oxfmtrc.json` needs the **leading dot**. Without it oxfmt silently uses its defaults,
+and the symptom is a formatter that rewrites your quotes.
+
+⛔ Neither format supports `extends`, so these two are copies. That means they can drift —
+which is what `@homeflare/config/check` exists to catch.
+
+## Keeping a project honest
+
+```ts
+import { checkProject } from '@homeflare/config/check';
+
+const problems = await checkProject(process.cwd());
+if (problems.length > 0) throw new Error(problems.join('\n'));
 ```
 
-⚠️ The file must be named `.oxfmtrc.json` — **with the leading dot**. Without it oxfmt
-silently uses its defaults, and the symptom is a formatter that rewrites your quotes.
+★ Run it from a test. It asserts a project still extends the shared tsconfig and oxlint
+presets, and that its copied `.oxfmtrc.json` and `bunfig.toml` still match — so a project
+that quietly diverges fails its own suite rather than drifting for six months.
 
 ## License
 

package/bunfig.toml

@@ -0,0 +1,22 @@
+# The HomeFlare bun defaults.
+#
+# ★ ADOPTION IS A COPY, NOT AN EXTEND. bunfig.toml has no `extends`, so this is the one
+#   file in the preset that a consumer copies rather than references:
+#       cp node_modules/@homeflare/config/bunfig.toml bunfig.toml
+#   ⚠️ That means it CAN drift. `homeflareConfig()` in @homeflare/config/check asserts a
+#   project's copy still matches, so drift fails a test instead of going unnoticed.
+
+[install]
+# ⛔ EXACT VERSIONS, ALWAYS. A caret in a manifest means two machines resolve different
+#   trees on different days, which is the drift a catalog exists to prevent.
+exact = true
+
+[install.cache]
+# ★ Bun's global cache, shared across every project on the machine.
+disable = false
+
+[test]
+# ⚠️ Coverage is REPORTED by default and gated per project. A repo-wide threshold here
+#   would either be too low to matter or fail every new package on day one.
+coverage = false
+coverageReporter = ["text"]

package/dist/check.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Assert that a project still stands on the shared config.
+ *
+ * ★ WHY THIS EXISTS. Two of the five presets — `.oxfmtrc.json` and `bunfig.toml` — have no
+ *   `extends` mechanism, so adopting them means COPYING them. A copy drifts silently: the
+ *   project keeps building, the rules quietly diverge, and nobody finds out until two
+ *   repos disagree about how the same code should look.
+ *
+ * ⛔ IT REPORTS, IT DOES NOT REPAIR. A checker that rewrites a project's config would
+ *   overwrite a deliberate local exception, and this cannot tell the difference between
+ *   drift and a decision. It names what differs; a human decides which way to move.
+ *
+ * ⚠️ Every file it reads is parsed natively — `Bun.file().json()`, `Bun.TOML.parse`. No
+ *   parsing dependency reaches a consumer.
+ *   ⛔ NOT JSONC. Bun's `.json()` rejects comments (measured 2026-09-15), so a project
+ *     whose tsconfig carries them is reported as unreadable rather than silently skipped.
+ */
+/** One thing a project should fix, in the imperative. */
+export type Problem = string;
+/**
+ * Check a project directory. Returns an empty array when everything is in step.
+ *
+ *     const problems = await checkProject(process.cwd());
+ *     expect(problems).toEqual([]);
+ */
+export declare function checkProject(projectDir: string): Promise<readonly Problem[]>;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,yDAAyD;AACzD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAkH7B;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CASlF"}

package/dist/check.js

@@ -0,0 +1,90 @@
+// @bun
+// src/check.ts
+function stripComments(text) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  for (let i = 0;i < text.length; i += 1) {
+    const ch = text[i] ?? "";
+    const next = text[i + 1] ?? "";
+    if (inString) {
+      out += ch;
+      if (escaped)
+        escaped = false;
+      else if (ch === "\\")
+        escaped = true;
+      else if (ch === '"')
+        inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+    } else if (ch === "/" && next === "/") {
+      while (i < text.length && text[i] !== `
+`)
+        i += 1;
+      out += `
+`;
+    } else if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+        i += 1;
+      i += 1;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+async function readJson(path) {
+  const file = Bun.file(path);
+  if (!await file.exists())
+    return;
+  try {
+    return JSON.parse(stripComments(await file.text()));
+  } catch {
+    return;
+  }
+}
+function presetDir() {
+  return new URL("../", import.meta.url).pathname;
+}
+async function checkExtends(projectDir, file, needle, problems) {
+  const config = await readJson(`${projectDir}/${file}`);
+  if (config === undefined) {
+    problems.push(`${file}: missing or unparseable (JSONC comments are not supported)`);
+    return;
+  }
+  const extended = JSON.stringify(config["extends"] ?? "");
+  const workspacePath = needle.replace("@homeflare/config/", "packages/config/");
+  if (!extended.includes(needle) && !extended.includes(workspacePath)) {
+    problems.push(`${file}: does not extend ${needle} \u2014 it currently extends ${extended}`);
+  }
+}
+async function checkCopy(projectDir, file, parse, problems) {
+  const mine = Bun.file(`${projectDir}/${file}`);
+  if (!await mine.exists()) {
+    problems.push(`${file}: missing \u2014 copy it from @homeflare/config`);
+    return;
+  }
+  const preset = parse(await Bun.file(`${presetDir()}${file.replace(/^\./, "")}`).text());
+  const theirs = parse(await mine.text());
+  if (JSON.stringify(theirs) !== JSON.stringify(preset)) {
+    problems.push(`${file}: differs from @homeflare/config \u2014 re-copy it, or say why it differs`);
+  }
+}
+async function checkProject(projectDir) {
+  const problems = [];
+  await checkExtends(projectDir, "tsconfig.json", "@homeflare/config/tsconfig", problems);
+  await checkExtends(projectDir, ".oxlintrc.json", "@homeflare/config/oxlintrc", problems);
+  await checkCopy(projectDir, ".oxfmtrc.json", (t) => JSON.parse(t), problems);
+  await checkCopy(projectDir, "bunfig.toml", (t) => Bun.TOML.parse(t), problems);
+  return problems;
+}
+export {
+  checkProject
+};
+
+//# debugId=7F6869C495728F5464756E2164756E21
+//# sourceMappingURL=check.js.map

package/dist/check.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/check.ts"],
+  "sourcesContent": [
+    "/**\n * Assert that a project still stands on the shared config.\n *\n * ★ WHY THIS EXISTS. Two of the five presets — `.oxfmtrc.json` and `bunfig.toml` — have no\n *   `extends` mechanism, so adopting them means COPYING them. A copy drifts silently: the\n *   project keeps building, the rules quietly diverge, and nobody finds out until two\n *   repos disagree about how the same code should look.\n *\n * ⛔ IT REPORTS, IT DOES NOT REPAIR. A checker that rewrites a project's config would\n *   overwrite a deliberate local exception, and this cannot tell the difference between\n *   drift and a decision. It names what differs; a human decides which way to move.\n *\n * ⚠️ Every file it reads is parsed natively — `Bun.file().json()`, `Bun.TOML.parse`. No\n *   parsing dependency reaches a consumer.\n *   ⛔ NOT JSONC. Bun's `.json()` rejects comments (measured 2026-09-15), so a project\n *     whose tsconfig carries them is reported as unreadable rather than silently skipped.\n */\n\n/** One thing a project should fix, in the imperative. */\nexport type Problem = string;\n\ntype Json = Record<string, unknown>;\n\n/**\n * ⚠️ A tsconfig LEGITIMATELY carries comments — that is where the reasoning for a strict\n *   flag lives, and stripping them to satisfy a parser would be the wrong trade. Bun's\n *   `.json()` rejects them (measured 2026-09-15), so comments are removed before parsing\n *   rather than treated as a fault.\n * 🔴 A NAIVE REGEX CORRUPTS THE FILE IT IS READING. Measured while writing this: a\n *   `(^|[^:\"])//.*$` strip mangled `\"./node_modules/oxlint/...\"` — the `//` inside a\n *   STRING — turning valid JSON into a parse error reported as \"JSONC not supported\".\n *   So this walks the text and tracks whether it is inside a string, which is the\n *   smallest correct thing; a real JSONC parser would be a dependency every consumer\n *   inherits for one check.\n */\nfunction stripComments(text: string): string {\n  let out = '';\n  let inString = false;\n  let escaped = false;\n\n  for (let i = 0; i < text.length; i += 1) {\n    const ch = text[i] ?? '';\n    const next = text[i + 1] ?? '';\n\n    if (inString) {\n      out += ch;\n      if (escaped) escaped = false;\n      else if (ch === '\\\\') escaped = true;\n      else if (ch === '\"') inString = false;\n      continue;\n    }\n\n    if (ch === '\"') {\n      inString = true;\n      out += ch;\n    } else if (ch === '/' && next === '/') {\n      while (i < text.length && text[i] !== '\\n') i += 1;\n      out += '\\n';\n    } else if (ch === '/' && next === '*') {\n      i += 2;\n      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;\n      i += 1;\n    } else {\n      out += ch;\n    }\n  }\n\n  return out;\n}\n\nasync function readJson(path: string): Promise<Json | undefined> {\n  const file = Bun.file(path);\n  if (!(await file.exists())) return undefined;\n  try {\n    return JSON.parse(stripComments(await file.text())) as Json;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Where this package's own presets live, however it was installed. */\nfunction presetDir(): string {\n  return new URL('../', import.meta.url).pathname;\n}\n\nasync function checkExtends(\n  projectDir: string,\n  file: string,\n  needle: string,\n  problems: Problem[],\n): Promise<void> {\n  const config = await readJson(`${projectDir}/${file}`);\n  if (config === undefined) {\n    problems.push(`${file}: missing or unparseable (JSONC comments are not supported)`);\n    return;\n  }\n\n  const extended = JSON.stringify(config['extends'] ?? '');\n\n  // ⚠️ A WORKSPACE PATH COUNTS. Inside this repo the presets are referenced as\n  //   `./packages/config/...` rather than by package name, and reporting that as drift\n  //   would make the check fail in the one repo that defines the config.\n  const workspacePath = needle.replace('@homeflare/config/', 'packages/config/');\n  if (!extended.includes(needle) && !extended.includes(workspacePath)) {\n    problems.push(`${file}: does not extend ${needle} — it currently extends ${extended}`);\n  }\n}\n\n/**\n * Compare a copied file against the preset, ignoring formatting.\n * ⚠️ Structural comparison, not text: a project that reformats its copy has not drifted,\n *   and reporting that would train people to ignore this check.\n */\nasync function checkCopy(\n  projectDir: string,\n  file: string,\n  parse: (text: string) => unknown,\n  problems: Problem[],\n): Promise<void> {\n  const mine = Bun.file(`${projectDir}/${file}`);\n  if (!(await mine.exists())) {\n    problems.push(`${file}: missing — copy it from @homeflare/config`);\n    return;\n  }\n\n  const preset = parse(await Bun.file(`${presetDir()}${file.replace(/^\\./, '')}`).text());\n  const theirs = parse(await mine.text());\n\n  if (JSON.stringify(theirs) !== JSON.stringify(preset)) {\n    problems.push(`${file}: differs from @homeflare/config — re-copy it, or say why it differs`);\n  }\n}\n\n/**\n * Check a project directory. Returns an empty array when everything is in step.\n *\n *     const problems = await checkProject(process.cwd());\n *     expect(problems).toEqual([]);\n */\nexport async function checkProject(projectDir: string): Promise<readonly Problem[]> {\n  const problems: Problem[] = [];\n\n  await checkExtends(projectDir, 'tsconfig.json', '@homeflare/config/tsconfig', problems);\n  await checkExtends(projectDir, '.oxlintrc.json', '@homeflare/config/oxlintrc', problems);\n  await checkCopy(projectDir, '.oxfmtrc.json', (t) => JSON.parse(t) as unknown, problems);\n  await checkCopy(projectDir, 'bunfig.toml', (t) => Bun.TOML.parse(t), problems);\n\n  return problems;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "7F6869C495728F5464756E2164756E21",
+  "names": []
+}

package/oxlintrc.json

@@ -1,19 +1,75 @@
 {
-  "plugins": ["typescript", "unicorn", "oxc", "import"],
+  "plugins": ["typescript", "unicorn", "oxc", "import", "react", "jsx-a11y"],
   "categories": {
     "correctness": "error",
-    "suspicious": "warn",
-    "perf": "warn"
+    "suspicious": "off",
+    "pedantic": "off",
+    "style": "off",
+    "restriction": "off",
+    "nursery": "off"
   },
   "env": {
-    "builtin": true,
-    "es2024": true
+    "es2024": true,
+    "node": true,
+    "browser": true,
+    "serviceworker": true
   },
   "ignorePatterns": ["dist/**", "coverage/**"],
   "rules": {
+    "no-unused-vars": [
+      "error",
+      {
+        "args": "none",
+        "caughtErrors": "none",
+        "varsIgnorePattern": "^_",
+        "ignoreRestSiblings": true
+      }
+    ],
+    "import/default": "off",
+    "import/no-unassigned-import": "off",
+    "no-underscore-dangle": "off",
+    "unicorn/no-empty-file": "off",
+    "eqeqeq": [
+      "error",
+      "always",
+      {
+        "null": "ignore"
+      }
+    ],
     "no-console": "error",
-    "typescript/consistent-type-imports": "error",
+    "no-control-regex": "error",
+    "no-fallthrough": "error",
+    "no-shadow-restricted-names": "error",
+    "no-template-curly-in-string": "error",
     "typescript/no-explicit-any": "error",
+    "default-param-last": "error",
+    "no-param-reassign": "error",
+    "operator-assignment": "error",
+    "prefer-const": "error",
+    "prefer-template": "error",
+    "typescript/no-non-null-assertion": "error",
+    "typescript/no-extraneous-class": "error",
+    "typescript/no-this-alias": "error",
+    "unicorn/no-array-for-each": "warn",
+    "unicorn/prefer-array-flat-map": "error",
+    "oxc/no-accumulating-spread": "error",
+    "react/no-danger": "error",
+    "react/button-has-type": "error",
+    "react/exhaustive-deps": "error",
+    "react/react-in-jsx-scope": "off",
+    "jsx-a11y/click-events-have-key-events": "error",
+    "jsx-a11y/prefer-tag-over-role": "off",
+    "react/set-state-in-effect": "off",
+    "typescript/dot-notation": "off",
+    "no-shadow": "off",
+    "unicorn/consistent-function-scoping": "off",
+    "typescript/consistent-type-imports": "error",
+    "sort-imports": [
+      "error",
+      {
+        "ignoreDeclarationSort": true
+      }
+    ],
     "import/no-default-export": "error"
   },
   "overrides": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/config",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Shared tsconfig, oxlint and oxfmt configuration for HomeFlare projects.",
   "license": "MIT",
   "author": "Timothy Schneider",
@@ -10,10 +10,13 @@
     "directory": "packages/config"
   },
   "files": [
+    "dist",
+    "src",
     "tsconfig.base.json",
     "tsconfig.lib.json",
     "oxlintrc.json",
     "oxfmtrc.json",
+    "bunfig.toml",
     "README.md",
     "LICENSE"
   ],
@@ -23,13 +26,14 @@
     "./tsconfig.lib.json": "./tsconfig.lib.json",
     "./oxlintrc.json": "./oxlintrc.json",
     "./oxfmtrc.json": "./oxfmtrc.json",
+    "./bunfig.toml": "./bunfig.toml",
+    "./check": {
+      "types": "./dist/check.d.ts",
+      "default": "./dist/check.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "echo 'config: nothing to build'",
-    "clean": "echo 'config: nothing to clean'"
   }
 }

package/src/check.ts

@@ -0,0 +1,149 @@
+/**
+ * Assert that a project still stands on the shared config.
+ *
+ * ★ WHY THIS EXISTS. Two of the five presets — `.oxfmtrc.json` and `bunfig.toml` — have no
+ *   `extends` mechanism, so adopting them means COPYING them. A copy drifts silently: the
+ *   project keeps building, the rules quietly diverge, and nobody finds out until two
+ *   repos disagree about how the same code should look.
+ *
+ * ⛔ IT REPORTS, IT DOES NOT REPAIR. A checker that rewrites a project's config would
+ *   overwrite a deliberate local exception, and this cannot tell the difference between
+ *   drift and a decision. It names what differs; a human decides which way to move.
+ *
+ * ⚠️ Every file it reads is parsed natively — `Bun.file().json()`, `Bun.TOML.parse`. No
+ *   parsing dependency reaches a consumer.
+ *   ⛔ NOT JSONC. Bun's `.json()` rejects comments (measured 2026-09-15), so a project
+ *     whose tsconfig carries them is reported as unreadable rather than silently skipped.
+ */
+
+/** One thing a project should fix, in the imperative. */
+export type Problem = string;
+
+type Json = Record<string, unknown>;
+
+/**
+ * ⚠️ A tsconfig LEGITIMATELY carries comments — that is where the reasoning for a strict
+ *   flag lives, and stripping them to satisfy a parser would be the wrong trade. Bun's
+ *   `.json()` rejects them (measured 2026-09-15), so comments are removed before parsing
+ *   rather than treated as a fault.
+ * 🔴 A NAIVE REGEX CORRUPTS THE FILE IT IS READING. Measured while writing this: a
+ *   `(^|[^:"])//.*$` strip mangled `"./node_modules/oxlint/..."` — the `//` inside a
+ *   STRING — turning valid JSON into a parse error reported as "JSONC not supported".
+ *   So this walks the text and tracks whether it is inside a string, which is the
+ *   smallest correct thing; a real JSONC parser would be a dependency every consumer
+ *   inherits for one check.
+ */
+function stripComments(text: string): string {
+  let out = '';
+  let inString = false;
+  let escaped = false;
+
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] ?? '';
+    const next = text[i + 1] ?? '';
+
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+    } else if (ch === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1;
+      out += '\n';
+    } else if (ch === '/' && next === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i += 1;
+    } else {
+      out += ch;
+    }
+  }
+
+  return out;
+}
+
+async function readJson(path: string): Promise<Json | undefined> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  try {
+    return JSON.parse(stripComments(await file.text())) as Json;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Where this package's own presets live, however it was installed. */
+function presetDir(): string {
+  return new URL('../', import.meta.url).pathname;
+}
+
+async function checkExtends(
+  projectDir: string,
+  file: string,
+  needle: string,
+  problems: Problem[],
+): Promise<void> {
+  const config = await readJson(`${projectDir}/${file}`);
+  if (config === undefined) {
+    problems.push(`${file}: missing or unparseable (JSONC comments are not supported)`);
+    return;
+  }
+
+  const extended = JSON.stringify(config['extends'] ?? '');
+
+  // ⚠️ A WORKSPACE PATH COUNTS. Inside this repo the presets are referenced as
+  //   `./packages/config/...` rather than by package name, and reporting that as drift
+  //   would make the check fail in the one repo that defines the config.
+  const workspacePath = needle.replace('@homeflare/config/', 'packages/config/');
+  if (!extended.includes(needle) && !extended.includes(workspacePath)) {
+    problems.push(`${file}: does not extend ${needle} — it currently extends ${extended}`);
+  }
+}
+
+/**
+ * Compare a copied file against the preset, ignoring formatting.
+ * ⚠️ Structural comparison, not text: a project that reformats its copy has not drifted,
+ *   and reporting that would train people to ignore this check.
+ */
+async function checkCopy(
+  projectDir: string,
+  file: string,
+  parse: (text: string) => unknown,
+  problems: Problem[],
+): Promise<void> {
+  const mine = Bun.file(`${projectDir}/${file}`);
+  if (!(await mine.exists())) {
+    problems.push(`${file}: missing — copy it from @homeflare/config`);
+    return;
+  }
+
+  const preset = parse(await Bun.file(`${presetDir()}${file.replace(/^\./, '')}`).text());
+  const theirs = parse(await mine.text());
+
+  if (JSON.stringify(theirs) !== JSON.stringify(preset)) {
+    problems.push(`${file}: differs from @homeflare/config — re-copy it, or say why it differs`);
+  }
+}
+
+/**
+ * Check a project directory. Returns an empty array when everything is in step.
+ *
+ *     const problems = await checkProject(process.cwd());
+ *     expect(problems).toEqual([]);
+ */
+export async function checkProject(projectDir: string): Promise<readonly Problem[]> {
+  const problems: Problem[] = [];
+
+  await checkExtends(projectDir, 'tsconfig.json', '@homeflare/config/tsconfig', problems);
+  await checkExtends(projectDir, '.oxlintrc.json', '@homeflare/config/oxlintrc', problems);
+  await checkCopy(projectDir, '.oxfmtrc.json', (t) => JSON.parse(t) as unknown, problems);
+  await checkCopy(projectDir, 'bunfig.toml', (t) => Bun.TOML.parse(t), problems);
+
+  return problems;
+}