@rtorcato/repo-tooling 2.59.0

package/dist/languages/js/checks.js

@@ -0,0 +1,949 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { hookHasUncommented } from '../../base/checks.js';
+import { WORKSPACE_FILE, dependsOnEsbuild, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
+const PACKAGE = '@rtorcato/repo-tooling';
+const NODE_MIN_MAJOR = 22;
+const NODE_LTS_REQUIREMENTS = {
+    22: { minor: 22, patch: 2 },
+    24: { minor: 15, patch: 0 },
+};
+function parseNodeVersion(version) {
+    const clean = version.replace(/^v/, '').split('-')[0] ?? '';
+    const [maj, min, pat] = clean.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    return [maj ?? 0, min ?? 0, pat ?? 0];
+}
+export function evaluateNodeVersion(version) {
+    const [major, minor, patch] = parseNodeVersion(version);
+    const display = `v${major}.${minor}.${patch}`;
+    if (major < NODE_MIN_MAJOR) {
+        return {
+            check: 'Node',
+            status: 'missing',
+            detail: `${display} is below required Node ${NODE_MIN_MAJOR}+`,
+            hint: `Install Node ${NODE_MIN_MAJOR} LTS or newer (https://nodejs.org)`,
+        };
+    }
+    const lts = NODE_LTS_REQUIREMENTS[major];
+    if (lts) {
+        const meets = minor > lts.minor || (minor === lts.minor && patch >= lts.patch);
+        if (!meets) {
+            return {
+                check: 'Node',
+                status: 'drift',
+                detail: `${display} — npm may emit EBADENGINE warnings from transitive deps`,
+                hint: `Upgrade to Node ${major}.${lts.minor}.${lts.patch}+ (or 26+) to silence transitive engine warnings`,
+            };
+        }
+    }
+    return {
+        check: 'Node',
+        status: 'ok',
+        detail: display,
+    };
+}
+export const FILE_CHECKS = [
+    {
+        check: 'TypeScript',
+        candidates: ['tsconfig.json'],
+        expected: `extends "${PACKAGE}/typescript/*"`,
+        matcher: /@rtorcato\/(?:js|repo)-tooling\/typescript\//,
+        hint: 'Set `"extends": "@rtorcato/repo-tooling/typescript/base"` in tsconfig.json',
+    },
+    {
+        check: 'Biome',
+        candidates: ['biome.json', 'biome.jsonc'],
+        expected: `extends "${PACKAGE}/biome"`,
+        matcher: /@rtorcato\/(?:js|repo)-tooling\/biome/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/repo-tooling copy biome` to scaffold',
+    },
+    {
+        check: 'ESLint',
+        candidates: ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'],
+        expected: `imports "${PACKAGE}/eslint/*"`,
+        matcher: /@rtorcato\/(?:js|repo)-tooling\/eslint\//,
+        optional: true,
+        hint: 'Import from @rtorcato/repo-tooling/eslint/base in eslint.config.mjs',
+    },
+    {
+        check: 'Prettier',
+        candidates: ['prettier.config.js', 'prettier.config.mjs', 'prettier.config.cjs'],
+        expected: `imports "${PACKAGE}/prettier"`,
+        matcher: /@rtorcato\/(?:js|repo)-tooling\/prettier/,
+        optional: true,
+        hint: `Re-export from "${PACKAGE}/prettier" in prettier.config.mjs`,
+    },
+    {
+        check: 'Vitest',
+        candidates: ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mjs'],
+        expected: `imports "${PACKAGE}/vitest/config"`,
+        matcher: /@rtorcato\/(?:js|repo)-tooling\/vitest\/config/,
+        optional: true,
+    },
+    {
+        check: 'Oxlint',
+        candidates: ['.oxlintrc.json', 'oxlintrc.json'],
+        // Oxlint configs are project-owned (extends from npm packages isn't
+        // reliably supported), so any well-formed file counts as ok.
+        expected: 'is a valid Oxlint configuration',
+        matcher: /"(rules|plugins|categories|extends)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/repo-tooling copy oxlint` to scaffold',
+    },
+    {
+        check: 'Changesets',
+        candidates: ['.changeset/config.json'],
+        expected: 'is a valid Changesets configuration',
+        matcher: /"(changelog|access|baseBranch)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/repo-tooling copy changesets` to scaffold',
+    },
+    {
+        check: 'Release Please',
+        candidates: ['release-please-config.json'],
+        expected: 'is a valid Release Please configuration',
+        matcher: /"(packages|release-type|bootstrap-sha)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/repo-tooling fix release-please` to scaffold',
+    },
+];
+/** Merged dependencies + devDependencies of a package.json, for presence checks. */
+export function allDeps(pkg) {
+    if (!pkg)
+        return {};
+    return {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+}
+export async function readPackageJson(dir) {
+    const filepath = path.join(dir, 'package.json');
+    if (!(await fs.pathExists(filepath)))
+        return null;
+    try {
+        return (await fs.readJson(filepath));
+    }
+    catch {
+        return null;
+    }
+}
+export function checkPackageJson(pkg) {
+    if (!pkg) {
+        return {
+            check: 'package.json',
+            status: 'missing',
+            detail: 'no package.json found',
+        };
+    }
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+    if (deps[PACKAGE]) {
+        return {
+            check: 'package.json',
+            status: 'ok',
+            detail: `${PACKAGE}@${deps[PACKAGE]} in dependencies`,
+        };
+    }
+    return {
+        check: 'package.json',
+        status: 'drift',
+        detail: `${PACKAGE} not in dependencies or devDependencies`,
+        hint: `Run \`pnpm add -D ${PACKAGE}\``,
+    };
+}
+export function checkEnginesNode(pkg) {
+    if (!pkg) {
+        return {
+            check: 'engines.node',
+            status: 'missing',
+            detail: 'no package.json',
+        };
+    }
+    const engines = pkg.engines ?? {};
+    if (!engines.node) {
+        return {
+            check: 'engines.node',
+            status: 'drift',
+            detail: 'engines.node not set in package.json',
+            hint: `Add \`"engines": { "node": ">=${NODE_MIN_MAJOR}" }\` to package.json`,
+        };
+    }
+    return {
+        check: 'engines.node',
+        status: 'ok',
+        detail: `engines.node = ${engines.node}`,
+    };
+}
+// Maps a present tool-config file to the VS Code extension that should be
+// recommended for it. Mirrors recommendedExtensions() in the generator, but
+// keyed off files on disk (doctor audits an existing repo, not a config object).
+const EXTENSION_SIGNALS = [
+    { candidates: ['.editorconfig'], ext: 'EditorConfig.EditorConfig' },
+    { candidates: ['biome.json', 'biome.jsonc'], ext: 'biomejs.biome' },
+    {
+        candidates: ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'],
+        ext: 'dbaeumer.vscode-eslint',
+    },
+    {
+        candidates: ['prettier.config.js', 'prettier.config.mjs', 'prettier.config.cjs'],
+        ext: 'esbenp.prettier-vscode',
+    },
+    { candidates: ['.oxlintrc.json', 'oxlintrc.json'], ext: 'oxc.oxc-vscode' },
+    {
+        candidates: ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mjs'],
+        ext: 'vitest.explorer',
+    },
+    { candidates: ['playwright.config.ts', 'playwright.config.js'], ext: 'ms-playwright.playwright' },
+];
+export async function checkVscodeExtensions(dir) {
+    const wanted = [];
+    for (const { candidates, ext } of EXTENSION_SIGNALS) {
+        for (const c of candidates) {
+            if (await fs.pathExists(path.join(dir, c))) {
+                wanted.push(ext);
+                break;
+            }
+        }
+    }
+    if (wanted.length === 0) {
+        return {
+            check: 'VS Code extensions',
+            status: 'ok',
+            detail: 'no tool configs that map to an editor extension',
+        };
+    }
+    let recommended = [];
+    const extPath = path.join(dir, '.vscode', 'extensions.json');
+    if (await fs.pathExists(extPath)) {
+        try {
+            const json = (await fs.readJson(extPath));
+            if (Array.isArray(json.recommendations)) {
+                recommended = json.recommendations.filter((r) => typeof r === 'string');
+            }
+        }
+        catch {
+            recommended = [];
+        }
+    }
+    const missing = wanted.filter((ext) => !recommended.includes(ext));
+    if (missing.length === 0) {
+        return {
+            check: 'VS Code extensions',
+            status: 'ok',
+            detail: '.vscode/extensions.json recommends the matching extensions',
+        };
+    }
+    return {
+        check: 'VS Code extensions',
+        status: 'optional-missing',
+        detail: `enabled tools without a recommended extension: ${missing.join(', ')}`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix vscode-extensions` to recommend matching editor extensions',
+    };
+}
+export async function checkNodeVersionPin(dir) {
+    for (const candidate of ['.nvmrc', '.node-version']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'Node version pin',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'Node version pin',
+        status: 'optional-missing',
+        detail: 'no .nvmrc / .node-version',
+        hint: 'Add .nvmrc to pin Node version per repo (e.g. `echo 22 > .nvmrc`)',
+    };
+}
+/** First integer in an `engines.node` range (the floor major), or null. */
+function enginesFloorMajor(pkg) {
+    const engines = pkg?.engines ?? {};
+    const raw = engines.node;
+    if (!raw)
+        return null;
+    const m = raw.match(/\d+/);
+    return m ? Number.parseInt(m[0], 10) : null;
+}
+async function nvmrcMajor(dir) {
+    for (const candidate of ['.nvmrc', '.node-version']) {
+        const p = path.join(dir, candidate);
+        if (await fs.pathExists(p)) {
+            const m = (await fs.readFile(p, 'utf-8')).trim().match(/\d+/);
+            if (m)
+                return { file: candidate, major: Number.parseInt(m[0], 10) };
+        }
+    }
+    return null;
+}
+// Matches a hardcoded scalar `node-version: <major>` — a leading digit (after
+// an optional quote) is required. This skips matrix arrays (`[22, 24]`),
+// `${{ matrix.node-version }}` expressions, bare `node-version:` input keys, and
+// `node-version-file:` (a different key entirely) — those aren't drift signals.
+const HARDCODED_NODE_VERSION = /node-version:\s*['"]?(\d+)/g;
+async function workflowNodeMajors(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir)))
+        return [];
+    let files;
+    try {
+        files = (await fs.readdir(workflowsDir)).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    }
+    catch {
+        return [];
+    }
+    const signals = [];
+    for (const file of files) {
+        const contents = await fs.readFile(path.join(workflowsDir, file), 'utf-8');
+        const seen = new Set();
+        for (const match of contents.matchAll(HARDCODED_NODE_VERSION)) {
+            const major = Number.parseInt(match[1] ?? '', 10);
+            if (!Number.isNaN(major) && !seen.has(major)) {
+                seen.add(major);
+                signals.push({ source: `.github/workflows/${file}`, major });
+            }
+        }
+    }
+    return signals;
+}
+// Root-cause check for the #94 class: a workflow hardcoding a Node major that
+// disagrees with .nvmrc / engines.node (e.g. ci.yml pinned Node 20 while
+// .nvmrc said 22 → node:sqlite crash under pnpm). Only flags genuine
+// disagreement; a matrix that tests several majors uses arrays/expressions and
+// is not counted.
+export async function checkNodeVersionConsistency(dir, pkg) {
+    const signals = [];
+    const nvmrc = await nvmrcMajor(dir);
+    if (nvmrc)
+        signals.push({ source: nvmrc.file, major: nvmrc.major });
+    const eng = enginesFloorMajor(pkg);
+    if (eng !== null)
+        signals.push({ source: 'engines.node', major: eng });
+    signals.push(...(await workflowNodeMajors(dir)));
+    if (signals.length < 2) {
+        return {
+            check: 'Node version consistency',
+            status: 'ok',
+            detail: signals.length === 0
+                ? 'no Node version pins to cross-check'
+                : `single Node version source (${signals[0]?.source} → ${signals[0]?.major})`,
+        };
+    }
+    const distinct = [...new Set(signals.map((s) => s.major))];
+    if (distinct.length === 1) {
+        return {
+            check: 'Node version consistency',
+            status: 'ok',
+            detail: `Node ${distinct[0]} agrees across ${signals.length} sources`,
+        };
+    }
+    const summary = signals.map((s) => `${s.source}→${s.major}`).join(', ');
+    return {
+        check: 'Node version consistency',
+        status: 'drift',
+        detail: `Node major disagreement: ${summary}`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix node-version` to point workflows at `node-version-file: .nvmrc` (one source of truth)',
+    };
+}
+/**
+ * The JS shape of the base `Git hooks` / `Pre-push hook` checks (#309): husky,
+ * installed by the `prepare` script so a fresh clone wires the hooks on
+ * `pnpm install`.
+ */
+export function jsGitHooksProfile(pkg) {
+    const scripts = pkg?.scripts ?? {};
+    return {
+        dir: '.husky',
+        install: {
+            present: /\bhusky\b/.test(scripts.prepare ?? ''),
+            label: '`prepare: husky` script',
+        },
+        verifyCommand: 'pnpm verify',
+        fixTarget: 'husky',
+    };
+}
+export async function checkVerifyScript(dir, pkg) {
+    if (!pkg) {
+        return {
+            check: 'verify script',
+            status: 'missing',
+            detail: 'no package.json',
+        };
+    }
+    const scripts = pkg.scripts ?? {};
+    const body = scripts.verify;
+    if (!body) {
+        return {
+            check: 'verify script',
+            status: 'optional-missing',
+            detail: 'no `verify` script in package.json',
+            hint: 'Run `npx @rtorcato/repo-tooling fix verify` to add a unified `pnpm verify` script',
+        };
+    }
+    // Lenient: only flag drift when an enabled tool is clearly absent from the script body.
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+    const missing = [];
+    if (scripts.typecheck && !/\btypecheck\b/.test(body))
+        missing.push('typecheck');
+    if ((scripts.check || deps['@biomejs/biome']) && !/\b(check|biome|lint)\b/.test(body)) {
+        missing.push('lint/check');
+    }
+    if ((deps.vitest || scripts.test) && !/(vitest|jest|test:e2e|pnpm\s+test)/.test(body)) {
+        missing.push('tests');
+    }
+    const hasTreeshakeApp = await fs.pathExists(path.join(dir, 'apps', 'treeshake-check', 'check.mjs'));
+    if (hasTreeshakeApp && !/\btreeshake\b/.test(body))
+        missing.push('treeshake');
+    if (missing.length > 0) {
+        return {
+            check: 'verify script',
+            status: 'drift',
+            detail: `\`verify\` script is missing: ${missing.join(', ')}`,
+            hint: 'Run `npx @rtorcato/repo-tooling fix verify` to regenerate the verify chain',
+        };
+    }
+    return {
+        check: 'verify script',
+        status: 'ok',
+        detail: `\`verify\` = ${body}`,
+    };
+}
+const LINT_STAGED_FILES = [
+    '.lintstagedrc',
+    '.lintstagedrc.json',
+    '.lintstagedrc.yaml',
+    '.lintstagedrc.yml',
+    '.lintstagedrc.js',
+    '.lintstagedrc.cjs',
+    '.lintstagedrc.mjs',
+    'lint-staged.config.js',
+    'lint-staged.config.cjs',
+    'lint-staged.config.mjs',
+];
+/**
+ * True when any .husky hook has an uncommented line that invokes lint-staged.
+ * A commented-out `# npx lint-staged` line (react-common's repro) does not
+ * count — lint-staged never actually runs.
+ */
+async function huskyHookCallsLintStaged(dir) {
+    const huskyDir = path.join(dir, '.husky');
+    if (!(await fs.pathExists(huskyDir)))
+        return false;
+    for (const name of await fs.readdir(huskyDir)) {
+        const hookPath = path.join(huskyDir, name);
+        if (!(await fs.stat(hookPath)).isFile())
+            continue;
+        const contents = await fs.readFile(hookPath, 'utf-8');
+        if (hookHasUncommented(contents, /\blint-staged\b/))
+            return true;
+    }
+    return false;
+}
+export async function checkLintStaged(dir, pkg) {
+    const inPkg = pkg ? 'lint-staged' in pkg : false;
+    let inFile = null;
+    for (const candidate of LINT_STAGED_FILES) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            inFile = candidate;
+            break;
+        }
+    }
+    if (inPkg || inFile) {
+        const where = inPkg ? '`lint-staged` field in package.json' : `${inFile} found`;
+        // Config presence isn't enough — verify a husky hook actually runs it.
+        // Only assert wiring when husky is in use; a non-husky setup may invoke
+        // lint-staged another way and shouldn't be flagged.
+        const huskyInUse = await fs.pathExists(path.join(dir, '.husky'));
+        if (huskyInUse && !(await huskyHookCallsLintStaged(dir))) {
+            return {
+                check: 'lint-staged',
+                status: 'drift',
+                detail: `${where} but no husky hook runs it`,
+                hint: 'Run `npx @rtorcato/repo-tooling fix husky` to wire lint-staged into the pre-commit hook',
+            };
+        }
+        return {
+            check: 'lint-staged',
+            status: 'ok',
+            detail: where,
+        };
+    }
+    return {
+        check: 'lint-staged',
+        status: 'optional-missing',
+        detail: 'lint-staged not configured',
+        hint: 'Add a `lint-staged` field to package.json and wire it into the husky pre-commit hook',
+    };
+}
+const KNIP_FILES = [
+    'knip.json',
+    'knip.jsonc',
+    'knip.ts',
+    'knip.config.ts',
+    'knip.config.js',
+    'knip.config.mjs',
+];
+export async function checkKnip(dir, pkg) {
+    const inPkg = pkg ? 'knip' in pkg : false;
+    let inFile = null;
+    for (const candidate of KNIP_FILES) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            inFile = candidate;
+            break;
+        }
+    }
+    if (inPkg || inFile) {
+        return {
+            check: 'knip',
+            status: 'ok',
+            detail: inPkg ? '`knip` field in package.json' : `${inFile} found`,
+        };
+    }
+    return {
+        check: 'knip',
+        status: 'optional-missing',
+        detail: 'knip not configured',
+        hint: 'Add `knip` to detect unused files, deps, and exports',
+    };
+}
+const SIZE_LIMIT_FILES = [
+    '.size-limit.json',
+    '.size-limit.js',
+    '.size-limit.cjs',
+    '.size-limit.mjs',
+    '.size-limit.ts',
+];
+export async function checkSizeLimit(dir, pkg) {
+    const inPkg = pkg ? 'size-limit' in pkg : false;
+    let inFile = null;
+    for (const candidate of SIZE_LIMIT_FILES) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            inFile = candidate;
+            break;
+        }
+    }
+    if (inPkg || inFile) {
+        return {
+            check: 'size-limit',
+            status: 'ok',
+            detail: inPkg ? '`size-limit` field in package.json' : `${inFile} found`,
+        };
+    }
+    return {
+        check: 'size-limit',
+        status: 'optional-missing',
+        detail: 'size-limit not configured',
+        hint: 'Add `size-limit` to enforce bundle-size budgets in CI for library projects',
+    };
+}
+const SEMANTIC_RELEASE_FILES = [
+    '.releaserc',
+    '.releaserc.json',
+    '.releaserc.yaml',
+    '.releaserc.yml',
+    '.releaserc.js',
+    '.releaserc.cjs',
+    'release.config.js',
+    'release.config.cjs',
+    'release.config.mjs',
+];
+export async function checkSemanticRelease(dir, pkg) {
+    const isPrivate = pkg?.private === true;
+    const inPkg = pkg ? 'release' in pkg : false;
+    let configFile = null;
+    let configContent = null;
+    for (const candidate of SEMANTIC_RELEASE_FILES) {
+        const filepath = path.join(dir, candidate);
+        if (await fs.pathExists(filepath)) {
+            configFile = candidate;
+            try {
+                configContent = await fs.readFile(filepath, 'utf-8');
+            }
+            catch {
+                configContent = '';
+            }
+            break;
+        }
+    }
+    const hasChangesets = await fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+    const hasReleasePlease = await fs.pathExists(path.join(dir, 'release-please-config.json'));
+    const hasSemanticRelease = inPkg || !!configFile;
+    // Conflict: more than one of {semantic-release, Changesets, Release Please}.
+    const configured = [
+        hasSemanticRelease && 'semantic-release',
+        hasChangesets && 'Changesets',
+        hasReleasePlease && 'Release Please',
+    ].filter((v) => Boolean(v));
+    if (configured.length >= 2) {
+        return {
+            check: 'semantic-release',
+            status: 'drift',
+            detail: `multiple release tools configured (${configured.join(', ')})`,
+            hint: 'Pick one release tool — remove the extra config(s)',
+        };
+    }
+    if (!hasSemanticRelease) {
+        // Another release tool is present — treat semantic-release as intentionally unused.
+        if (hasChangesets || hasReleasePlease) {
+            return {
+                check: 'semantic-release',
+                status: 'ok',
+                detail: `using ${hasChangesets ? 'Changesets' : 'Release Please'} instead`,
+            };
+        }
+        return {
+            check: 'semantic-release',
+            status: isPrivate ? 'optional-missing' : 'drift',
+            detail: isPrivate
+                ? 'semantic-release not configured (package is private)'
+                : 'semantic-release not configured',
+            hint: isPrivate
+                ? undefined
+                : `Extend "${PACKAGE}/semantic-release" or "${PACKAGE}/semantic-release/github" in a release config`,
+        };
+    }
+    const presetRegex = /@rtorcato\/(?:js|repo)-tooling\/semantic-release/;
+    const pkgReleaseStr = inPkg ? JSON.stringify(pkg?.release ?? '') : '';
+    const usesPreset = (configContent && presetRegex.test(configContent)) || presetRegex.test(pkgReleaseStr);
+    if (usesPreset) {
+        return {
+            check: 'semantic-release',
+            status: 'ok',
+            detail: configFile
+                ? `${configFile} extends ${PACKAGE}/semantic-release`
+                : `release field extends ${PACKAGE}/semantic-release`,
+        };
+    }
+    return {
+        check: 'semantic-release',
+        status: 'drift',
+        detail: configFile
+            ? `${configFile} does not extend ${PACKAGE}/semantic-release`
+            : '`release` field does not extend our preset',
+        hint: `Extend "${PACKAGE}/semantic-release" or "${PACKAGE}/semantic-release/github"`,
+    };
+}
+const TYPEDOC_CONFIGS = [
+    'typedoc.json',
+    'typedoc.config.js',
+    'typedoc.config.mjs',
+    'typedoc.config.cjs',
+    'typedoc.config.ts',
+];
+export async function checkTypedoc(dir, pkg) {
+    if (pkg?.private === true) {
+        return {
+            check: 'TypeDoc',
+            status: 'ok',
+            detail: 'not applicable (package is private)',
+        };
+    }
+    let configFile = null;
+    let configContent = null;
+    for (const candidate of TYPEDOC_CONFIGS) {
+        const fp = path.join(dir, candidate);
+        if (await fs.pathExists(fp)) {
+            configFile = candidate;
+            try {
+                configContent = await fs.readFile(fp, 'utf-8');
+            }
+            catch {
+                configContent = '';
+            }
+            break;
+        }
+    }
+    const deps = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+    };
+    const hasDep = !!deps['typedoc'];
+    const usesPreset = configContent
+        ? /@rtorcato\/(?:js|repo)-tooling\/typedoc/.test(configContent)
+        : false;
+    if (configFile && usesPreset) {
+        return {
+            check: 'TypeDoc',
+            status: 'ok',
+            detail: `${configFile} extends the preset`,
+        };
+    }
+    if (configFile && !usesPreset) {
+        return {
+            check: 'TypeDoc',
+            status: 'drift',
+            detail: `${configFile} found but does not extend @rtorcato/repo-tooling/typedoc`,
+            hint: 'Add `"extends": ["@rtorcato/repo-tooling/typedoc"]` to typedoc.json',
+        };
+    }
+    if (hasDep && !configFile) {
+        return {
+            check: 'TypeDoc',
+            status: 'drift',
+            detail: 'typedoc installed but no typedoc.json found',
+            hint: 'Run `npx @rtorcato/repo-tooling fix typedoc` to scaffold typedoc.json',
+        };
+    }
+    return {
+        check: 'TypeDoc',
+        status: 'optional-missing',
+        detail: 'TypeDoc not configured',
+        hint: 'Run `npx @rtorcato/repo-tooling fix typedoc` to scaffold API docs generation',
+    };
+}
+function isPublishableLibrary(pkg) {
+    if (!pkg || pkg.private === true)
+        return false;
+    return !!(pkg.exports || pkg.main || pkg.module || pkg.files);
+}
+export async function checkAreTheTypesWrong(_dir, pkg) {
+    if (!isPublishableLibrary(pkg)) {
+        return {
+            check: 'are-the-types-wrong',
+            status: 'ok',
+            detail: 'not applicable (private or no published exports)',
+        };
+    }
+    const deps = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+    };
+    const scripts = pkg?.scripts ?? {};
+    const hasDep = !!deps['@arethetypeswrong/cli'];
+    const hasScript = Object.values(scripts).some((s) => /\battw\b/.test(s));
+    if (hasDep && hasScript) {
+        return {
+            check: 'are-the-types-wrong',
+            status: 'ok',
+            detail: '@arethetypeswrong/cli installed and wired into a script',
+        };
+    }
+    if (hasDep) {
+        return {
+            check: 'are-the-types-wrong',
+            status: 'drift',
+            detail: '@arethetypeswrong/cli installed but no script runs it',
+            hint: 'Run `npx @rtorcato/repo-tooling fix attw` to add an `attw` script and wire it into verify',
+        };
+    }
+    return {
+        check: 'are-the-types-wrong',
+        status: 'optional-missing',
+        detail: '@arethetypeswrong/cli not configured',
+        hint: 'Run `npx @rtorcato/repo-tooling fix attw` to validate TypeScript exports before publishing',
+    };
+}
+export async function checkPublint(_dir, pkg) {
+    if (!isPublishableLibrary(pkg)) {
+        return {
+            check: 'publint',
+            status: 'ok',
+            detail: 'not applicable (private or no published exports)',
+        };
+    }
+    const deps = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+    };
+    const scripts = pkg?.scripts ?? {};
+    const hasDep = !!deps['publint'];
+    const hasScript = Object.values(scripts).some((s) => /\bpublint\b/.test(s));
+    if (hasDep && hasScript) {
+        return {
+            check: 'publint',
+            status: 'ok',
+            detail: 'publint installed and wired into a script',
+        };
+    }
+    if (hasDep) {
+        return {
+            check: 'publint',
+            status: 'drift',
+            detail: 'publint installed but no script runs it',
+            hint: 'Run `npx @rtorcato/repo-tooling fix publint` to add a `publint` script and wire it into verify',
+        };
+    }
+    return {
+        check: 'publint',
+        status: 'optional-missing',
+        detail: 'publint not configured',
+        hint: 'Run `npx @rtorcato/repo-tooling fix publint` to lint your package before publishing',
+    };
+}
+/** Who this package's README badges are for — feeds the base badge check (#309). */
+export function jsBadgeAudience(pkg) {
+    if (!pkg || pkg.private === true)
+        return 'private';
+    return isPublishableLibrary(pkg) ? 'public' : 'not-applicable';
+}
+export async function checkTreeshakeSetup(dir, pkg) {
+    const appCheckPath = path.join(dir, 'apps', 'treeshake-check', 'check.mjs');
+    if (await fs.pathExists(appCheckPath)) {
+        return {
+            check: 'Tree-shake check',
+            status: 'ok',
+            detail: 'apps/treeshake-check/check.mjs found',
+        };
+    }
+    // Only nudge libraries that actually claim tree-shaking via multi-subpath exports + sideEffects: false.
+    const exports = pkg?.exports ?? {};
+    const subpaths = Object.keys(exports).filter((k) => k !== '.' && k.startsWith('./') && !k.includes('*'));
+    const sideEffectsFree = pkg?.sideEffects === false;
+    if (subpaths.length < 2 || !sideEffectsFree) {
+        return {
+            check: 'Tree-shake check',
+            status: 'ok',
+            detail: 'not applicable (single-export or has side effects)',
+        };
+    }
+    return {
+        check: 'Tree-shake check',
+        status: 'optional-missing',
+        detail: `package exports ${subpaths.length} subpaths with sideEffects: false but no apps/treeshake-check/`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix treeshake-check` to scaffold an esbuild metafile assertion',
+    };
+}
+export async function checkTurborepo(dir) {
+    const hasTurbo = await fs.pathExists(path.join(dir, 'turbo.json'));
+    const hasNx = await fs.pathExists(path.join(dir, 'nx.json'));
+    if (hasTurbo && hasNx) {
+        return {
+            check: 'Turborepo',
+            status: 'drift',
+            detail: 'both turbo.json and nx.json present',
+            hint: 'Pick one monorepo orchestrator — remove either turbo.json or nx.json',
+        };
+    }
+    if (hasTurbo)
+        return { check: 'Turborepo', status: 'ok', detail: 'turbo.json found' };
+    if (hasNx)
+        return { check: 'Turborepo', status: 'ok', detail: 'nx.json found (using Nx)' };
+    return {
+        check: 'Turborepo',
+        status: 'optional-missing',
+        detail: 'pnpm workspace without a task orchestrator',
+        hint: 'Run `npx @rtorcato/repo-tooling fix turborepo` (or `fix nx`) to scaffold a task pipeline',
+    };
+}
+/**
+ * pnpm settings that would otherwise be hand-copied across the family (#314).
+ * Only reported for pnpm repos — an npm or yarn repo has no use for the file,
+ * and inventing one there would be noise.
+ */
+export async function checkPnpmWorkspace(dir, pkg) {
+    const check = 'pnpm settings';
+    const hint = `Run \`npx ${PACKAGE} fix pnpm-workspace\` to merge them in`;
+    const file = path.join(dir, WORKSPACE_FILE);
+    const exists = await fs.pathExists(file);
+    const usesPnpm = exists ||
+        (await fs.pathExists(path.join(dir, 'pnpm-lock.yaml'))) ||
+        (pkg?.packageManager ?? '').startsWith('pnpm');
+    if (!usesPnpm) {
+        return { check, status: 'ok', detail: 'not a pnpm repo' };
+    }
+    const yaml = exists ? await fs.readFile(file, 'utf-8') : '';
+    const missing = missingPnpmSettings(yaml, dependsOnEsbuild(allDeps(pkg)));
+    if (missing.length === 0) {
+        return { check, status: 'ok', detail: `${WORKSPACE_FILE} carries the managed settings` };
+    }
+    return {
+        check,
+        // A repo with no workspace file at all hasn't drifted — it never opted in.
+        status: exists ? 'drift' : 'optional-missing',
+        detail: `missing ${missing.join(', ')}`,
+        hint,
+    };
+}
+/** The docs app dir (apps/docs or apps/doc) if a Docusaurus config lives there. */
+export async function findDocsAppDir(dir) {
+    for (const app of ['apps/docs', 'apps/doc']) {
+        if (await fs.pathExists(path.join(dir, app, 'docusaurus.config.ts')))
+            return app;
+    }
+    return null;
+}
+// Only surfaced when a Docusaurus site exists (see runDoctor). Verifies the
+// shared-asset wiring #54 standardizes: sync-changelog present + chained into
+// the docs app's build/start, and the deploy artifact path is `build` (not
+// `dist`). Opt-in, so a repo without a docs site never sees this.
+export async function checkDocsSite(dir, docsAppDir) {
+    const check = 'Docs site';
+    const deltas = [];
+    const syncPath = path.join(dir, 'scripts', 'sync-changelog.mjs');
+    if (!(await fs.pathExists(syncPath))) {
+        deltas.push('scripts/sync-changelog.mjs missing');
+    }
+    else {
+        const pkgPath = path.join(dir, docsAppDir, 'package.json');
+        if (await fs.pathExists(pkgPath)) {
+            try {
+                const docsPkg = (await fs.readJson(pkgPath));
+                const scripts = docsPkg.scripts ?? {};
+                const chained = ['build', 'start'].some((s) => typeof scripts[s] === 'string' && /sync-changelog/.test(scripts[s]));
+                // pnpm 8 doesn't run pre* hooks reliably, so build/start must chain it explicitly.
+                if (!chained)
+                    deltas.push(`${docsAppDir} build/start does not chain sync-changelog`);
+            }
+            catch {
+                // Unparseable package.json — a separate check owns that; skip here.
+            }
+        }
+    }
+    // The GitHub Pages deploy must upload `apps/doc*/build` (Docusaurus emits
+    // `build/`, not `dist/`).
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (await fs.pathExists(workflowsDir)) {
+        for (const file of await fs.readdir(workflowsDir)) {
+            if (!/\.ya?ml$/.test(file))
+                continue;
+            const body = await fs.readFile(path.join(workflowsDir, file), 'utf-8').catch(() => '');
+            if (new RegExp(`${docsAppDir}/dist`).test(body)) {
+                deltas.push(`${file} deploys ${docsAppDir}/dist (should be ${docsAppDir}/build)`);
+            }
+        }
+    }
+    if (deltas.length)
+        return {
+            check,
+            status: 'drift',
+            detail: deltas.join('; '),
+            hint: 'Align the docs site with the shared standard (sync-changelog wiring, build/ artifact path)',
+        };
+    return { check, status: 'ok', detail: `${docsAppDir} wired per standard` };
+}
+// Only called when `tailwindcss` is a dependency (see runDoctor) — Tailwind is
+// opt-in per project, so nudging repos that don't use it would be noise. v4 is
+// CSS-first: the wiring is a PostCSS plugin (or the Vite plugin), not a config
+// file, so that's what we look for.
+export async function checkTailwind(dir, pkg) {
+    const hasVitePlugin = '@tailwindcss/vite' in allDeps(pkg);
+    let postcssWired = false;
+    for (const candidate of ['postcss.config.mjs', 'postcss.config.js', 'postcss.config.cjs']) {
+        const p = path.join(dir, candidate);
+        if ((await fs.pathExists(p)) &&
+            (await fs.readFile(p, 'utf8')).includes('@tailwindcss/postcss')) {
+            postcssWired = true;
+            break;
+        }
+    }
+    if (hasVitePlugin || postcssWired) {
+        return {
+            check: 'Tailwind',
+            status: 'ok',
+            detail: hasVitePlugin ? '@tailwindcss/vite configured' : '@tailwindcss/postcss configured',
+        };
+    }
+    return {
+        check: 'Tailwind',
+        status: 'optional-missing',
+        detail: 'tailwindcss installed without a PostCSS (or Vite) plugin',
+        hint: 'Run `npx @rtorcato/repo-tooling fix tailwind` to scaffold the v4 PostCSS wiring',
+    };
+}