bin/family.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1#!/usr/bin/env node
2// The family check: what keeps a repository in step with the shared packages. It fails (exit 1, an ::error:: line each) on
3//
4//   pins       a dependency on one of the shared packages, or a call to devkit's reusable workflows, that is not at that
5//              package's newest release tag (a raw commit counts as behind);
6//   copies     a local definition with the name of something a shared package exports, or text only a shared builder should
7//              write (a robots.txt "User-agent:", a sitemap "<urlset", an IndexNow POST...);
8//   libraries  a direct dependency on a library a shared package wraps (marked, remark, mermaid, sanitize-html...);
9//   features   a family feature the repository's kind of app should have and does not import (robots.txt, security.txt,
10//              IndexNow, the CSP report endpoint, /health...);
11//   spelling   British spelling, read by codespell's en-GB to en-US list (American English everywhere, Dustin 2026-10-25).
12//
13//   npx devkit-family                    the check, against .family.json (no file: one site at the root)
14//   npx devkit-family --fix-spelling     rewrite the British spellings in place, then run the check
15//   npx devkit-family list               the generated list of every shared package's exports and every family feature
16//   --from <dir>                         read the packages from checkouts named by repository (dir/prelum, dir/site-runtime...)
17//                                        instead of node_modules
18//
19// The config, every field optional:
20//
21//   {
22//     "apps": { ".": "site", "mcp": "worker" },          kind per directory: site, static, private, worker or package
23//     "waive": { "indexnow": "why", "mcp:health": "why" }, a feature this repository does not need, and why
24//     "copies": { "app/lib/og.ts": "why" },               a file allowed to hold a copy, and why
25//     "libraries": { "katex": "why" },                    a direct dependency allowed, and why
26//     "spelling": { "ignore": ["word"], "contracts": ["regex"], "skip": ["frame/**"] }
27//                                                         words never checked; text a regex matches (a stored value, a
28//                                                         column) left as it is, while the same word in prose is fixed;
29//                                                         paths not checked
30//   }
31//
32// On a Renovate branch (GITHUB_HEAD_REF renovate/...) the pin findings are warnings: a bump of one package must not fail
33// because another is also behind. A line ending in a codespell:ignore comment is a contract the spelling check leaves.
34
35import { execFileSync, spawnSync } from "node:child_process";
36import { appendFileSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
37import { dirname, join, posix } from "node:path";
38import { pathToFileURL } from "node:url";
39
40/** The shared packages: npm name, repository, and what a session should know them as. */
41export const PACKAGES = [
42  { name: "@drdustinedwards/site-helpers", repo: "prelum", label: "Prelum" },
43  { name: "@dustinedwards/site-runtime", repo: "site-runtime", label: "site-runtime" },
44  { name: "@dustinedwards/site-api", repo: "site-api", label: "site-api" },
45  { name: "@dustinedwards/d1-dump", repo: "d1-dump", label: "d1-dump" },
46  { name: "@dustinedwards/devkit", repo: "devkit", label: "devkit" },
47  { name: "capsomer", repo: "capsomer", label: "Capsomer" },
48  { name: "enarratio", repo: "enarratio", label: "Enarratio" },
49];
50
51const SITE = ["site", "static"];
52const PUBLIC_OR_PRIVATE = ["site", "static", "private"];
53
54/** Every family feature: which kinds of app need it, how its use is found, and what provides it. */
55export const FEATURES = {
56  robots: { kinds: SITE, find: /site-helpers\/robots["']/, use: "Prelum ./robots robotsDocument (/robots.txt)" },
57  aiTxt: { kinds: SITE, find: /\baiTxt\b/, use: "Prelum ./robots aiTxt (/ai.txt)" },
58  tdm: { kinds: SITE, find: /\bTDM_RESERVATION_HEADERS\b/, use: "Prelum ./robots TDM_RESERVATION_HEADERS" },
59  sitemap: { kinds: SITE, find: /site-helpers\/sitemap["']/, use: "Prelum ./sitemap sitemapDocument (/sitemap.xml)" },
60  llms: { kinds: SITE, find: /site-helpers\/llms["']/, use: "Prelum ./llms llmsDocument (/llms.txt)" },
61  head: { kinds: SITE, find: /site-helpers\/head["']/, use: "Prelum ./head headTags (canonical, Open Graph, Twitter)" },
62  schema: { kinds: SITE, find: /site-helpers\/schema["']/, use: "Prelum ./schema (JSON-LD)" },
63  indexnow: { kinds: SITE, find: /site-helpers\/indexnow["']|prelum-indexnow/, use: "Prelum ./indexnow submitIndexNow (site-api onPageChange on a Carrel site; prelum-indexnow after a static deploy)" },
64  securityTxt: { kinds: SITE, find: /site-runtime\/security-txt["']/, use: "site-runtime ./security-txt (/.well-known/security.txt)" },
65  headers: { kinds: [...PUBLIC_OR_PRIVATE, "worker"], find: /site-runtime\/headers["']/, use: "site-runtime ./headers buildSecurityHeaders" },
66  csp: { kinds: PUBLIC_OR_PRIVATE, find: /site-runtime\/csp["']/, use: "site-runtime ./csp buildContentSecurityPolicy" },
67  cspReport: { kinds: PUBLIC_OR_PRIVATE, find: /site-runtime\/csp-report["']/, use: "site-runtime ./csp-report receiveCspReport" },
68  health: { kinds: ["site", "private"], find: /site-runtime\/health["']/, use: "site-runtime ./health healthResponse (/health)" },
69  capsomer: { kinds: PUBLIC_OR_PRIVATE, find: /["']capsomer(\/[^"']*)?["']/, use: "Capsomer (tokens, components, the site layer)" },
70};
71/** A D1 database needs the nightly dump, whatever the kind. */
72const BACKUP = { find: /@dustinedwards\/d1-dump["']/, use: "d1-dump runCheckedBackup and backupHealth" };
73
74/** Text only a shared builder should write. */
75export const FINGERPRINTS = [
76  { find: /User-agent:/, use: "Prelum ./robots robotsDocument" },
77  { find: /<urlset\b/, use: "Prelum ./sitemap sitemapDocument" },
78  { find: /<rss\b|<feed xmlns=/, use: "Prelum ./feeds" },
79  { find: /api\.indexnow\.org/, use: "Prelum ./indexnow submitIndexNow" },
80  { find: /Contact: mailto:/, use: "site-runtime ./security-txt securityTxt" },
81  { find: /property[=:]\s*["']og:/, use: "Prelum ./head headTags" },
82  { find: /["']Strict-Transport-Security["']\s*[:,]/, use: "site-runtime ./headers buildSecurityHeaders" },
83];
84
85/** Libraries a shared package wraps, so a site that lists one is doing that package's job. */
86export const LIBRARIES = [
87  { find: /^(marked|markdown-it|micromark.*|remark.*|rehype.*|unified|mdast-util-.*|hast-util-.*)$/, use: "Prelum ./render" },
88  { find: /^mermaid$/, use: "Prelum ./render/diagram" },
89  { find: /^katex$/, use: "Prelum ./render/math" },
90  { find: /^(shiki|highlight\.js|prismjs)$/, use: "Prelum ./render/highlight" },
91  { find: /^(feed|rss|sitemap|xmlbuilder2?)$/, use: "Prelum ./feeds and ./sitemap" },
92  { find: /^(sanitize-html|dompurify|isomorphic-dompurify)$/, use: "Prelum ./render/safe" },
93  { find: /^jose$/, use: "site-runtime ./access and ./access-login" },
94];
95
96/** Local names for something a shared package exports under another name. */
97export const ALIASES = {
98  xmlEscape: "escapeXml",
99  escXml: "escapeXml",
100  escapeAttr: "escapeHtml",
101  bytesToHex: "toHex",
102  b64url: "base64url",
103  b64urlEncode: "base64url",
104  base64UrlEncode: "base64url",
105  parseThemeCookie: "readThemeCookie",
106  themeFromRequest: "readThemeCookie",
107  getThemeCookie: "readThemeCookie",
108  serializeThemeCookie: "themeCookie",
109  buildSecurityTxt: "securityTxt",
110};
111
112// Single words too common to flag on name alone; compound names (escapeHtml, jsonLd) are distinctive, except these.
113const DISTINCT_SINGLE = new Set(["slugify"]);
114const COMMON_COMPOUND = new Set(["accessToken"]);
115const SOURCE = /\.(m?[jt]sx?|mts|cts)$/;
116const NOT_SOURCE = /(^|\/)(node_modules|dist|build|coverage|test|tests|e2e|__tests__|fixtures)\/|\.(test|spec)\.[mc]?[jt]sx?$|\.d\.m?ts$|worker-configuration\.d\.ts$/;
117
118/**
119 * @typedef {"site" | "static" | "private" | "worker" | "package"} Kind
120 * @typedef {{ apps?: Record<string, Kind>, waive?: Record<string, string>, copies?: Record<string, string>,
121 *   libraries?: Record<string, string>, spelling?: { ignore?: string[], contracts?: string[], skip?: string[] } }} Config
122 * @typedef {{ check: string, file?: string, line?: number, message: string, warn?: boolean }} Finding
123 * @typedef {{ files: string[], read: (file: string) => string }} Tree
124 * @typedef {Record<string, string>} Catalog   export name -> "package subpath"
125 * @typedef {(repo: string) => { tags: string[], commits: Record<string, string> }} TagReader
126 */
127
128/** "v1.2.3" -> [1, 2, 3]; anything else -> null. */
129export function semver(/** @type {string} */ tag) {
130  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(tag);
131  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
132}
133
134/** @param {string} a @param {string} b */
135function compare(a, b) {
136  const [x, y] = [semver(a), semver(b)];
137  if (!x || !y) return 0;
138  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
139  return 0;
140}
141
142/** The newest release tag of a repository. */
143export function newest(/** @type {string[]} */ tags) {
144  return tags.filter((t) => semver(t)).sort(compare).at(-1) ?? null;
145}
146
147/** Tags and the commit each points at, from git ls-remote (peeled for annotated tags). */
148export function lsRemoteTags(/** @type {string} */ repo) {
149  const out = execFileSync("git", ["ls-remote", "--tags", `https://github.com/DrDustinEdwards/${repo}`], { encoding: "utf8" });
150  /** @type {Record<string, string>} */
151  const commits = {};
152  for (const line of out.split("\n")) {
153    const m = /^([0-9a-f]{40})\trefs\/tags\/(.+?)(\^\{\})?$/.exec(line);
154    if (m) commits[m[2]] = m[3] || !commits[m[2]] ? m[1] : commits[m[2]];
155  }
156  return { tags: Object.keys(commits), commits };
157}
158
159/**
160 * Pins behind the newest tag, or on a raw commit.
161 * @param {Tree} tree @param {TagReader} readTags @param {boolean} lenient
162 * @returns {Finding[]}
163 */
164export function checkPins(tree, readTags, lenient = false) {
165  /** @type {Finding[]} */
166  const found = [];
167  /** @type {Record<string, ReturnType<TagReader>>} */
168  const cache = {};
169  const tagsOf = (/** @type {string} */ repo) => (cache[repo] ??= readTags(repo));
170  const judge = (/** @type {string} */ file, /** @type {number} */ line, /** @type {string} */ repo, /** @type {string} */ ref) => {
171    const { tags, commits } = tagsOf(repo);
172    const latest = newest(tags);
173    if (!latest) return;
174    let at = semver(ref) ? (ref.startsWith("v") ? ref : `v${ref}`) : Object.keys(commits).find((t) => commits[t] === ref && semver(t));
175    if (!at) {
176      found.push({ check: "pins", file, line, warn: lenient, message: `${repo} is pinned to ${ref.slice(0, 12)}, which is no release; pin ${latest}` });
177    } else if (compare(at, latest) < 0) {
178      found.push({ check: "pins", file, line, warn: lenient, message: `${repo} is at ${at}; the newest release is ${latest}` });
179    }
180  };
181  for (const file of tree.files) {
182    const text = tree.read(file);
183    const lineOf = (/** @type {number} */ index) => text.slice(0, index).split("\n").length;
184    if (posix.basename(file) === "package.json") {
185      for (const m of text.matchAll(/"([^"]+)":\s*"(?:github:|git\+https:\/\/github\.com\/)DrDustinEdwards\/([\w.-]+?)(?:\.git)?#([^"]+)"/gi)) {
186        judge(file, lineOf(m.index), m[2], m[3]);
187      }
188      for (const m of text.matchAll(/"enarratio":\s*"\^?~?(\d+\.\d+\.\d+)"/g)) judge(file, lineOf(m.index), "enarratio", m[1]);
189    } else if (/^\.github\/workflows\/.+\.ya?ml$/.test(file)) {
190      for (const m of text.matchAll(/DrDustinEdwards\/devkit\/\.github\/workflows\/[\w.-]+@([0-9a-f]{40})/gi)) judge(file, lineOf(m.index), "devkit", m[1]);
191    }
192  }
193  return found;
194}
195
196/** Export names from one module's source or declaration file. */
197export function exportNames(/** @type {string} */ src) {
198  const names = new Set();
199  for (const m of src.matchAll(/export\s+(?:declare\s+)?(?:async\s+)?(?:function\*?|const|let|class)\s+([A-Za-z_$][\w$]*)/g)) names.add(m[1]);
200  for (const m of src.matchAll(/export\s*\{([^}]*)\}/g)) {
201    for (const part of m[1].split(",")) {
202      const name = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/).pop();
203      if (name && !/^type\b/.test(part.trim())) names.add(name);
204    }
205  }
206  return [...names];
207}
208
209/** Whether a name is distinctive enough to flag a local definition of it. */
210export function distinctive(/** @type {string} */ name) {
211  if (COMMON_COMPOUND.has(name)) return false;
212  return DISTINCT_SINGLE.has(name) || (/^[a-z]/.test(name) && /[a-z][A-Z0-9]/.test(name) && name.length >= 6);
213}
214
215/**
216 * Local copies: definitions named like a shared export (or a known alias of one), and builder fingerprints.
217 * @param {Tree} tree @param {Catalog} catalog @param {Config} config @param {string} [self] the package this repository is, if any
218 * @returns {Finding[]}
219 */
220export function checkCopies(tree, catalog, config, self) {
221  /** @type {Finding[]} */
222  const found = [];
223  const names = Object.keys(catalog).filter(distinctive);
224  const aliases = Object.keys(ALIASES).filter((a) => catalog[ALIASES[a]]);
225  const all = [...names, ...aliases];
226  const shared = new RegExp(`from\\s+["'](${PACKAGES.map((p) => p.name.replace(/[/.]/g, "\\$&")).join("|")})(/[^"']*)?["']`);
227  const define = all.length ? new RegExp(`^[ \\t]*(?:export\\s+)?(?:async\\s+)?(?:function\\*?\\s+|(?:const|let|var)\\s+)(${all.join("|")})\\b\\s*[=(<:]`, "gm") : null;
228  for (const file of tree.files) {
229    if (!SOURCE.test(file) || NOT_SOURCE.test(file) || config.copies?.[file]) continue;
230    const text = tree.read(file);
231    const lineOf = (/** @type {number} */ index) => text.slice(0, index).split("\n").length;
232    // A wrapper that imports the shared export it is named after is a use, not a copy.
233    const imported = new Set();
234    for (const m of text.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*["'][^"']+["']/g)) {
235      if (!shared.test(m[0])) continue;
236      for (const part of m[1].split(",")) imported.add(part.trim().split(/\s+as\s+/)[0]);
237    }
238    if (define) {
239      for (const m of text.matchAll(define)) {
240        const target = ALIASES[m[1]] ?? m[1];
241        if (imported.has(target)) continue;
242        found.push({ check: "copies", file, line: lineOf(m.index), message: `${m[1]} is a local copy of ${catalog[target]} ${target}: import it` });
243      }
244    }
245    // Comments may name what a builder writes; only code counts. Blanked, not removed, so line numbers hold.
246    const code = text.replace(/\/\*[\s\S]*?\*\/|(^|[^:"'`])\/\/.*$/gm, (c) => c.replace(/[^\n]/g, " "));
247    for (const { find, use } of FINGERPRINTS) {
248      if (self && use.startsWith(`${self} `)) continue;
249      const m = find.exec(code);
250      if (m) found.push({ check: "copies", file, line: lineOf(m.index), message: `this builds what ${use} builds: use it` });
251    }
252  }
253  return found;
254}
255
256/**
257 * Direct dependencies on libraries a shared package wraps. A library that a shared package the manifest depends on
258 * lists as a peer (Prelum's render packs) is that package's install, not a second job, and passes.
259 * @param {Tree} tree @param {Config} config @param {Record<string, string[]>} [peers] package name -> its peer dependencies
260 * @returns {Finding[]}
261 */
262export function checkLibraries(tree, config, peers = {}) {
263  /** @type {Finding[]} */
264  const found = [];
265  for (const file of tree.files.filter((f) => posix.basename(f) === "package.json")) {
266    const manifest = JSON.parse(tree.read(file));
267    if (PACKAGES.some((p) => p.name === manifest.name)) continue;
268    const deps = { ...manifest.dependencies, ...manifest.devDependencies };
269    const asked = new Set(Object.keys(deps).flatMap((d) => peers[d] ?? []));
270    for (const dep of Object.keys(deps)) {
271      const lib = LIBRARIES.find((l) => l.find.test(dep));
272      if (lib && !asked.has(dep) && !config.libraries?.[dep]) found.push({ check: "libraries", file, message: `${dep} is ${lib.use}'s job: use it, or say why in .family.json "libraries"` });
273    }
274  }
275  return found;
276}
277
278/**
279 * Family features each app is missing for its kind.
280 * @param {Tree} tree @param {Config} config
281 * @returns {Finding[]}
282 */
283export function checkFeatures(tree, config) {
284  /** @type {Finding[]} */
285  const found = [];
286  const apps = Object.entries(config.apps ?? { ".": "site" });
287  // Each file belongs to the deepest app directory that holds it.
288  const owner = (/** @type {string} */ file) =>
289    apps.map(([dir]) => dir).filter((dir) => dir === "." || file === dir || file.startsWith(`${dir}/`)).sort((a, b) => b.length - a.length)[0];
290  for (const [dir, kind] of apps) {
291    const mine = tree.files.filter((f) => owner(f) === dir && !NOT_SOURCE.test(f));
292    const text = mine.filter((f) => SOURCE.test(f) || /\.(css|ya?ml)$/.test(f) || posix.basename(f) === "package.json").map(tree.read).join("\n");
293    const prefix = dir === "." ? "" : `${dir}:`;
294    for (const [feature, { kinds, find, use }] of Object.entries(FEATURES)) {
295      if (!kinds.includes(kind) || config.waive?.[`${prefix}${feature}`] || find.test(text)) continue;
296      found.push({ check: "features", file: dir, message: `${kind} ${dir === "." ? "" : `${dir} `}has no ${feature}: ${use}` });
297    }
298    const d1 = mine.some((f) => /(^|\/)wrangler[^/]*\.jsonc?(\.example)?$/.test(f) && /"d1_databases"/.test(tree.read(f)));
299    if (d1 && kind !== "package" && !config.waive?.[`${prefix}backup`] && !BACKUP.find.test(text)) {
300      found.push({ check: "features", file: dir, message: `${dir} has a D1 database and no nightly dump: ${BACKUP.use}` });
301    }
302  }
303  return found;
304}
305
306/**
307 * British spellings, from codespell's en-GB to en-US list.
308 * @param {string} root @param {Config} config @param {boolean} fix
309 * @returns {Finding[]}
310 */
311export function checkSpelling(root, config, fix = false) {
312  const files = execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" }).split("\0").filter(Boolean);
313  const skip = [...(config.spelling?.skip ?? []), "*.lock", "package-lock.json", "pnpm-lock.yaml", ".family.json"];
314  const targets = files.filter((f) => !skip.some((s) => posix.matchesGlob?.(f, s) ?? f === s) && !/\.(png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|pdf|zip|gz|wasm)$/i.test(f));
315  // Names other tools own: GitHub Actions' cancelled(), Renovate's minimumReleaseAgeBehaviour, and ARIA's labelledby as a
316  // camelCase name (labelledBy, ariaLabelledByElements). codespell:ignore
317  const ignoreRegex = [String.raw`\bcancelled\\?\(|\bminimumReleaseAgeBehaviour\b|[lL]abelledBy`, ...(config.spelling?.contracts ?? [])].join("|"); // codespell:ignore
318  const args = ["--builtin", "en-GB_to_en-US", "--quiet-level", "3", "--check-filenames", "--ignore-regex", ignoreRegex];
319  if (config.spelling?.ignore?.length) args.push("--ignore-words-list", config.spelling.ignore.join(","));
320  // The check reads each part of a camelCase or CONSTANT_CASE name as a word, since a British name is spelling too. The
321  // fix rewrites whole words only: renaming an export breaks every site that imports it, so a name is renamed by hand,
322  // keeping the old one as an alias.
323  args.push(...(fix ? ["--write-changes"] : ["--regex", "[A-Z]?[a-z]+|[A-Z]+(?![a-z])"]));
324  /** @type {Finding[]} */
325  const found = [];
326  for (let i = 0; i < targets.length; i += 400) {
327    const run = codespell([...args, "--", ...targets.slice(i, i + 400)], root);
328    for (const line of run.split("\n")) {
329      const m = /^(.+?):(\d+): (\S+) ==> (\S+)/.exec(line);
330      if (m) found.push({ check: "spelling", file: m[1], line: Number(m[2]), message: `${m[3]} is British; write ${m[4]} (or end the line with a codespell:ignore comment if it is a data contract)` });
331    }
332  }
333  return found;
334}
335
336/** codespell from PATH, else through pipx at a pinned version. Its own exit code says only whether it found something. */
337function codespell(/** @type {string[]} */ args, /** @type {string} */ cwd) {
338  for (const [cmd, pre] of [["codespell", []], ["pipx", ["run", "codespell==2.4.3"]]]) {
339    const run = spawnSync(cmd, [...pre, ...args], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
340    if (run.error) continue;
341    if (run.status !== 0 && run.status !== 65) throw new Error(`codespell failed: ${run.stderr.trim()}`);
342    return run.stdout;
343  }
344  throw new Error("codespell is not installed and pipx is not either: pip install codespell==2.4.3");
345}
346
347/**
348 * The export catalog: every installed shared package's subpaths and the names each exports.
349 * @param {(name: string, repo: string) => string | null} locate the package's directory
350 * @returns {{ catalog: Catalog, packages: { label: string, repo: string, version: string, entries: [string, string[]][], bins: string[] }[] }}
351 */
352export function readCatalog(locate) {
353  /** @type {Catalog} */
354  const catalog = {};
355  const packages = [];
356  for (const { name, repo, label } of PACKAGES) {
357    const dir = locate(name, repo);
358    if (!dir) continue;
359    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
360    /** @type {[string, string[]][]} */
361    const entries = [];
362    const exp = typeof manifest.exports === "string" ? { ".": manifest.exports } : (manifest.exports ?? {});
363    for (const [sub, target] of Object.entries(exp)) {
364      if (sub === "./package.json" || /\.css$|\.json$/.test(sub)) continue;
365      if (sub.includes("*")) {
366        const base = sub.split("/")[1];
367        const comps = existsSync(join(dir, "components")) ? readdirSync(join(dir, "components")).filter((c) => statSync(join(dir, "components", c)).isDirectory()) : [];
368        entries.push([sub, comps.map((c) => `${base}/${c}`)]);
369        continue;
370      }
371      const file = moduleFile(dir, target);
372      const names = file ? exportNames(followReexports(file)) : [];
373      entries.push([sub, names]);
374      // devkit's exports are test helpers, not site code a site could copy.
375      if (repo !== "devkit") for (const n of names) if (!catalog[n] || catalog[n].endsWith(" .")) catalog[n] = `${label} ${sub}`;
376    }
377    packages.push({ label, repo, version: manifest.version, entries, bins: Object.keys(manifest.bin ?? {}) });
378  }
379  return { catalog, packages };
380}
381
382/** The file that declares a subpath's exports: its types, else its source. */
383function moduleFile(/** @type {string} */ dir, /** @type {unknown} */ target) {
384  /** @type {any} */
385  let t = target;
386  while (t && typeof t === "object") t = t.types ?? t.import ?? t.default;
387  if (typeof t !== "string") return null;
388  const f = join(dir, t);
389  const candidates = [f, f.replace(/\.m?js$/, ".d.mts"), f.replace(/\.js$/, ".d.ts"), f.replace(/^(.*)\/dist\/(.*)\.d\.ts$/, "$1/src/$2.ts"), f.replace(/^(.*)\/dist\/(.*)\.js$/, "$1/src/$2.ts")];
390  return candidates.find((c) => existsSync(c) && statSync(c).isFile()) ?? null;
391}
392
393/** The module's text with any `export * from` it makes appended. */
394function followReexports(/** @type {string} */ file) {
395  let src = readFileSync(file, "utf8");
396  for (const m of src.matchAll(/export\s+\*\s+from\s+["'](.+?)["']/g)) {
397    const r = join(dirname(file), m[1]);
398    const hit = [r, r.replace(/\.m?js$/, ".d.mts"), r.replace(/\.js$/, ".ts"), r.replace(/\.js$/, ".d.ts")].find((c) => existsSync(c) && statSync(c).isFile());
399    if (hit) src += `\n${readFileSync(hit, "utf8")}`;
400  }
401  return src;
402}
403
404/** The generated list, as markdown. */
405export function listMarkdown(/** @type {ReturnType<typeof readCatalog>["packages"]} */ packages) {
406  const lines = [
407    "# What the shared packages already do",
408    "",
409    "Generated by `devkit-family list`; do not edit by hand. Before writing anything a site might share, look here: if a package exports it, import it. `npx devkit-family` fails a repository that copies one of these, misses a family feature, or pins an old release.",
410    "",
411    "## Family features",
412    "",
413    "| Feature | Needed by | Provided by |",
414    "| --- | --- | --- |",
415    ...Object.entries(FEATURES).map(([f, { kinds, use }]) => `| ${f} | ${kinds.join(", ")} | ${use} |`),
416    `| backup | any app with a D1 database | ${BACKUP.use} |`,
417  ];
418  for (const p of packages) {
419    lines.push("", `## ${p.label} ${p.version} (DrDustinEdwards/${p.repo})`, "");
420    for (const [sub, names] of p.entries) lines.push(`- \`${sub}\`: ${names.length ? names.map((n) => `\`${n}\``).join(", ") : "(no named exports)"}`);
421    if (p.bins.length) lines.push(`- bins: ${p.bins.map((b) => `\`${b}\``).join(", ")}`);
422  }
423  return `${lines.join("\n")}\n`;
424}
425
426/** Every tracked file, read from disk. */
427function gitTree(/** @type {string} */ root) {
428  const files = execFileSync("git", ["ls-files", "-z"], { cwd: root, encoding: "utf8" }).split("\0").filter(Boolean);
429  /** @type {Record<string, string>} */
430  const cache = {};
431  return {
432    files: files.filter((f) => !f.includes("node_modules/")),
433    read: (/** @type {string} */ f) => (cache[f] ??= existsSync(join(root, f)) && statSync(join(root, f)).isFile() ? readFileSync(join(root, f), "utf8") : ""),
434  };
435}
436
437/** Each located shared package's peer dependencies. @param {(name: string, repo: string) => string | null} locate */
438function peersOf(locate) {
439  /** @type {Record<string, string[]>} */
440  const peers = {};
441  for (const p of PACKAGES) {
442    const dir = locate(p.name, p.repo);
443    if (dir) peers[p.name] = Object.keys(JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).peerDependencies ?? {});
444  }
445  return peers;
446}
447
448function main(/** @type {string[]} */ argv) {
449  const root = process.cwd();
450  const from = argv.includes("--from") ? argv[argv.indexOf("--from") + 1] : null;
451  // Installed packages by default; --from reads checkouts named by repository, for a tree with nothing installed.
452  const locate = (/** @type {string} */ name, /** @type {string} */ repo) => {
453    const dir = from ? join(from, repo) : join(root, "node_modules", name);
454    return existsSync(join(dir, "package.json")) ? dir : null;
455  };
456  if (argv[0] === "list") {
457    process.stdout.write(listMarkdown(readCatalog(locate).packages));
458    return 0;
459  }
460  /** @type {Config} */
461  const config = existsSync(join(root, ".family.json")) ? JSON.parse(readFileSync(join(root, ".family.json"), "utf8")) : {};
462  const tree = gitTree(root);
463  // A shared package defines its own exports; it is checked against the others, as a package, not a site.
464  const self = PACKAGES.find((p) => p.name === JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name);
465  if (self) config.apps ??= { ".": "package" };
466  const { catalog } = readCatalog((name, repo) => (repo === self?.repo ? null : locate(name, repo)));
467  // A name the package exports itself is its own API, even when another package exports a different thing by that name.
468  if (self) for (const name of Object.keys(readCatalog((_, repo) => (repo === self.repo ? root : null)).catalog)) delete catalog[name];
469  const lenient = (process.env.GITHUB_HEAD_REF ?? "").startsWith("renovate/");
470  const findings = [
471    ...checkPins(tree, lsRemoteTags, lenient),
472    ...checkCopies(tree, catalog, config, self?.label),
473    ...checkLibraries(tree, config, peersOf(locate)),
474    ...checkFeatures(tree, config),
475    ...checkSpelling(root, config, argv.includes("--fix-spelling")),
476  ];
477  const errors = findings.filter((f) => !f.warn);
478  for (const f of findings) {
479    const where = f.file ? ` file=${f.file}${f.line ? `,line=${f.line}` : ""}` : "";
480    console.log(`::${f.warn ? "warning" : "error"}${where}::[${f.check}] ${f.message}`);
481  }
482  const counts = ["pins", "copies", "libraries", "features", "spelling"].map((c) => `${c} ${findings.filter((f) => f.check === c).length}`).join(", ");
483  console.log(errors.length ? `devkit-family: ${errors.length} to fix (${counts}). What the packages export: npx devkit-family list` : `devkit-family: in step with the family (${counts}).`);
484  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, `### Family check\n\n${counts}\n`);
485  return errors.length ? 1 : 0;
486}
487
488if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
489  try {
490    process.exitCode = main(process.argv.slice(2));
491  } catch (error) {
492    console.log(`::error::devkit-family could not run: ${error instanceof Error ? error.message : String(error)}`);
493    process.exitCode = 2;
494  }
495}