@rtorcato/repo-tooling 3.1.0 → 3.2.1

package/dist/cli/commands/doctor.js

@@ -9,7 +9,7 @@ import { checkGitIdentity } from '../../base/git-identity.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
 import { checkAiSetup, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkDocsSite, checkEnginesNode, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
 // Detects the broken-release-on-protected-main footgun: a workflow that runs
@@ -218,6 +218,8 @@ export async function runDoctor(dir) {
     results.push(evaluateNodeVersion(process.version));
     results.push(checkPackageJson(pkg));
     results.push(checkEnginesNode(pkg));
+    results.push(await checkConfigSchemaVersions(targetDir, pkg));
+    results.push(checkGitDependencies(pkg));
     results.push(await checkVscodeExtensions(targetDir));
     results.push(await checkNodeVersionPin(targetDir));
     results.push(await checkNodeVersionConsistency(targetDir, pkg));

package/dist/cli/generators/index.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { generateSwiftProject } from '../../languages/swift/scaffold.js';
 import { installAiSetup } from './agent-rules.js';
 import { bundlerNeedsEsbuild, ensureBuildApprovals, generateBuildConfigs } from './build.js';
-import { ensurePnpmSettings } from './pnpm-workspace.js';
+import { ensurePnpmSettings, familyGlob } from './pnpm-workspace.js';
 import { generateGitConfigs } from './git.js';
 import { generateGitHubActions } from './github-actions.js';
 import { generateLintingConfigs } from './linting.js';
@@ -84,7 +84,7 @@ export async function generateConfigs(config, targetDir) {
     await ensureBuildApprovals(config, targetDir);
     // Family-wide pnpm settings (#314). Runs last of the workspace writers so it
     // merges into whatever they wrote rather than racing them for the file.
-    await ensurePnpmSettings(targetDir, bundlerNeedsEsbuild(config));
+    await ensurePnpmSettings(targetDir, bundlerNeedsEsbuild(config), familyGlob(config.projectName));
     // Turborepo task pipeline (pnpm-workspace monorepos, when opted-in)
     if (config.turborepo) {
         await generateTurborepo(targetDir);

package/dist/cli/generators/pnpm-workspace.js

@@ -12,12 +12,24 @@ import fs from 'fs-extra';
 export const WORKSPACE_FILE = 'pnpm-workspace.yaml';
 /**
  * pnpm's `minimumReleaseAge` cutoff holds back freshly published versions —
- * good against a typosquat-hijack, but it also stalls every consumer of a
- * same-day `@rtorcato/*` fix for 24h. One glob covers the whole family: pnpm
- * matches these entries with `@pnpm/config.matcher`, so there's no package list
- * to keep in sync with `@rtorcato/shared-docs`'s `FAMILY`.
+ * good against a typosquat or a hijacked account, but it also stalls every
+ * consumer of a same-day fix in a sibling package for 24h. Exempting the
+ * repo's *own* scope trades that off only for packages it already publishes.
+ *
+ * Derived from the consuming package's name rather than hardcoded: this is a
+ * public CLI, and writing one organisation's scope into a stranger's config
+ * would loosen a supply-chain guard for packages they neither use nor chose.
+ * An unscoped package gets no such setting at all — there is no "family" to
+ * infer, and guessing one would be worse than leaving it alone.
+ *
+ * One glob covers a whole scope: pnpm matches these entries with
+ * `@pnpm/config.matcher`, so there's no package list to keep in sync.
  */
-const FAMILY_GLOB = '@rtorcato/*';
+export function familyGlob(packageName) {
+    const name = typeof packageName === 'string' ? packageName : '';
+    const scope = /^(@[^/]+)\//.exec(name)?.[1];
+    return scope ? `${scope}/*` : null;
+}
 /** Bundlers that pull in esbuild, whose install script pnpm 11 refuses to run unapproved. */
 const ESBUILD_BUNDLERS = ['esbuild', 'tsup', 'vite'];
 /** True when the repo depends on a bundler that drags esbuild in. */
@@ -43,7 +55,29 @@ function section(yaml, key) {
     }
     return body;
 }
-const SETTINGS = [
+/**
+ * The managed settings for one repo. A function rather than a constant because
+ * the release-age exemption is scope-derived, and a repo with no scope to
+ * derive doesn't get that setting at all.
+ */
+function settingsFor(glob) {
+    return glob ? [...BASE_SETTINGS, releaseAgeSetting(glob)] : BASE_SETTINGS;
+}
+function releaseAgeSetting(glob) {
+    return {
+        label: `minimumReleaseAgeExclude: ${glob}`,
+        applies: () => true,
+        satisfied: (yaml) => (section(yaml, 'minimumReleaseAgeExclude') ?? []).some((l) => l.includes(glob)),
+        key: 'minimumReleaseAgeExclude',
+        block: `# Exempt this package's own scope from pnpm's minimumReleaseAge cutoff, so a
+# same-day fix in a sibling package is installable today rather than tomorrow.
+minimumReleaseAgeExclude:
+  - '${glob}'
+`,
+        item: `  - '${glob}'`,
+    };
+}
+const BASE_SETTINGS = [
     {
         label: 'verifyDepsBeforeRun: false',
         applies: () => true,
@@ -57,18 +91,6 @@ verifyDepsBeforeRun: false
 `,
         item: '',
     },
-    {
-        label: `minimumReleaseAgeExclude: ${FAMILY_GLOB}`,
-        applies: () => true,
-        satisfied: (yaml) => (section(yaml, 'minimumReleaseAgeExclude') ?? []).some(hasFamilyGlob),
-        key: 'minimumReleaseAgeExclude',
-        block: `# Exempt the @rtorcato family from pnpm's minimumReleaseAge cutoff, so a
-# same-day fix in a sibling package is installable today rather than tomorrow.
-minimumReleaseAgeExclude:
-  - '${FAMILY_GLOB}'
-`,
-        item: `  - '${FAMILY_GLOB}'`,
-    },
     {
         label: 'allowBuilds: esbuild',
         applies: (needsEsbuild) => needsEsbuild,
@@ -82,12 +104,11 @@ allowBuilds:
         item: '  esbuild: true',
     },
 ];
-function hasFamilyGlob(line) {
-    return line.includes(FAMILY_GLOB);
-}
 /** Managed settings absent from `yaml`, named as doctor reports them. */
-export function missingPnpmSettings(yaml, needsEsbuild) {
-    return SETTINGS.filter((s) => s.applies(needsEsbuild) && !s.satisfied(yaml)).map((s) => s.label);
+export function missingPnpmSettings(yaml, needsEsbuild, glob) {
+    return settingsFor(glob)
+        .filter((s) => s.applies(needsEsbuild) && !s.satisfied(yaml))
+        .map((s) => s.label);
 }
 /** Insert `item` directly under an existing `key:` line, keeping the rest untouched. */
 function insertUnder(yaml, key, item) {
@@ -97,9 +118,9 @@ function insertUnder(yaml, key, item) {
     return lines.join('\n');
 }
 /** Merge every missing managed setting into `yaml` and return the new contents. */
-export function upsertPnpmSettings(yaml, needsEsbuild) {
+export function upsertPnpmSettings(yaml, needsEsbuild, glob) {
     let next = yaml;
-    for (const setting of SETTINGS) {
+    for (const setting of settingsFor(glob)) {
         if (!setting.applies(needsEsbuild) || setting.satisfied(next))
             continue;
         if (setting.item && section(next, setting.key)) {
@@ -115,10 +136,10 @@ export function upsertPnpmSettings(yaml, needsEsbuild) {
  * Merge the managed pnpm settings into `pnpm-workspace.yaml`, creating it when
  * absent. Returns the relative path if anything changed, else null.
  */
-export async function ensurePnpmSettings(targetDir, needsEsbuild) {
+export async function ensurePnpmSettings(targetDir, needsEsbuild, glob) {
     const file = path.join(targetDir, WORKSPACE_FILE);
     const current = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf-8') : '';
-    const next = upsertPnpmSettings(current, needsEsbuild);
+    const next = upsertPnpmSettings(current, needsEsbuild, glob);
     if (next === current)
         return null;
     await fs.writeFile(file, next.replace(/^\n+/, ''));

package/dist/languages/js/checks.js

@@ -1,7 +1,7 @@
 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';
+import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
 const PACKAGE = '@rtorcato/repo-tooling';
 const NODE_MIN_MAJOR = 22;
 const NODE_LTS_REQUIREMENTS = {
@@ -849,7 +849,7 @@ export async function checkPnpmWorkspace(dir, pkg) {
         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)));
+    const missing = missingPnpmSettings(yaml, dependsOnEsbuild(allDeps(pkg)), familyGlob(pkg?.name));
     if (missing.length === 0) {
         return { check, status: 'ok', detail: `${WORKSPACE_FILE} carries the managed settings` };
     }
@@ -947,3 +947,161 @@ export async function checkTailwind(dir, pkg) {
         hint: 'Run `npx @rtorcato/repo-tooling fix tailwind` to scaffold the v4 PostCSS wiring',
     };
 }
+/**
+ * Both checks below read `package.json` alone — no network, no lockfile. They
+ * report `optional-missing` rather than `drift`: each is a policy call a repo
+ * can legitimately decide against, so they surface in doctor's output and can
+ * be declined in `.repo-tooling.json`, but neither fails a build.
+ */
+/** `[major, minor, patch]` floor of a range, or null when it hasn't got one. */
+export function rangeFloor(range) {
+    const m = /^[\s^~>=<v]*(\d+)\.(\d+)\.(\d+)/.exec(range);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+/**
+ * Major.minor only — patch is deliberately ignored. New config keys and new
+ * behaviour arrive in minors; a dev floor five patches above the peer floor
+ * (`^2.5.0` vs `^2.5.5`) is just a routine bump and flagging it would make
+ * this check fire on almost every package.
+ */
+function compareFloor(a, b) {
+    return a[0] - b[0] || a[1] - b[1];
+}
+/**
+ * Config files whose `$schema` URL carries the tool version the config is
+ * written for, and the package that reads them. One entry per tool; adding
+ * another is a line here.
+ */
+const SCHEMA_CONFIGS = [
+    { files: ['biome.json', 'biome.jsonc'], host: 'biomejs.dev', pkg: '@biomejs/biome' },
+];
+/** The version out of `https://biomejs.dev/schemas/2.5.0/schema.json`. */
+export function schemaUrlVersion(url) {
+    const m = /\/(\d+\.\d+\.\d+)\//.exec(url);
+    return m?.[1] ? rangeFloor(m[1]) : null;
+}
+/**
+ * `"$schema": "..."` without parsing the file. Biome configs may be JSONC, and
+ * a comment is enough to break `JSON.parse` — the one field this needs is
+ * cheaper and safer to read directly.
+ */
+function readSchemaUrl(contents) {
+    return /"\$schema"\s*:\s*"([^"]+)"/.exec(contents)?.[1] ?? null;
+}
+/**
+ * A shipped config written for a newer tool version than the package claims to
+ * support (#330). The `$schema` URL is an explicit, machine-readable statement
+ * of which version the config targets, so comparing it against the declared
+ * dependency floor is exact — no heuristics, no false positives.
+ *
+ * This is the #330 defect precisely: `tooling/biome/biome.json` carries
+ * `$schema` 2.5.0 and uses `linter.rules.preset`, a 2.5 key, while
+ * `peerDependencies` advertised `@biomejs/biome: ^2.0.0`. Consumers on 2.0–2.4
+ * got `Found an unknown key \`preset\`` with nothing pointing at the range.
+ *
+ * It reads the same way in a consuming repo: a `biome.json` targeting 2.5.0
+ * with `@biomejs/biome: ^2.3.0` in devDependencies is the identical failure,
+ * one level down.
+ *
+ * The floor is what matters, not the ceiling — `^2.0.0` resolves to the newest
+ * 2.x today, so the repo's own install works and only consumers pinned lower
+ * break. That is exactly why this goes unnoticed.
+ */
+export async function checkConfigSchemaVersions(dir, pkg) {
+    const check = 'Config schema versions';
+    // peerDependencies is the contract a publisher offers; devDependencies is
+    // what a leaf repo actually installs. Prefer the former when present.
+    const declared = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+        ...(pkg?.peerDependencies ?? {}),
+    };
+    const mismatches = [];
+    let checked = 0;
+    for (const spec of SCHEMA_CONFIGS) {
+        for (const file of spec.files) {
+            const filepath = path.join(dir, file);
+            if (!(await fs.pathExists(filepath)))
+                continue;
+            const url = readSchemaUrl(await fs.readFile(filepath, 'utf8'));
+            if (!url?.includes(spec.host))
+                continue;
+            const schemaVersion = schemaUrlVersion(url);
+            const range = declared[spec.pkg];
+            if (!schemaVersion || !range)
+                continue;
+            const floor = rangeFloor(range);
+            if (!floor)
+                continue;
+            checked++;
+            if (compareFloor(schemaVersion, floor) > 0) {
+                const v = schemaVersion.join('.');
+                mismatches.push(`${file} targets ${spec.pkg} ${v} but the range is ${range}`);
+            }
+        }
+    }
+    if (checked === 0) {
+        return { check, status: 'ok', detail: 'no versioned config schemas to compare' };
+    }
+    if (mismatches.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `${checked} config schema${checked === 1 ? '' : 's'} within the declared version range`,
+        };
+    }
+    return {
+        check,
+        status: 'optional-missing',
+        detail: `${mismatches.length} config${mismatches.length === 1 ? '' : 's'} written for a newer tool than declared: ${mismatches.join('; ')}`,
+        hint: 'Raise the dependency floor to the version the config targets, or rewrite the config for the oldest version supported. Anyone resolving below the schema version gets a config-parse error that never mentions the version range.',
+    };
+}
+/** npm git specifiers, including the bare `owner/repo` GitHub shorthand. */
+const GIT_PROTOCOL = /^(?:github|gitlab|bitbucket|gist):|^git\+|^git:\/\//;
+const GITHUB_SHORTHAND = /^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*(?:#.*)?$/;
+export function isGitSpecifier(spec) {
+    return GIT_PROTOCOL.test(spec) || GITHUB_SHORTHAND.test(spec);
+}
+/**
+ * A git dependency with no `#ref` (#332). The package manager resolves it once
+ * and pins the commit in the lockfile, so it never moves again until somebody
+ * re-resolves by hand — with no version mismatch, no Dependabot PR, and no
+ * signal of any kind that it has gone stale.
+ *
+ * This is how the docs homepage kept advertising `@rtorcato/js-tooling` for
+ * days after the rename: `github:rtorcato/shared-docs` had been pinned to a
+ * pre-rename commit and nothing could tell.
+ */
+export function checkGitDependencies(pkg) {
+    const check = 'Git dependencies';
+    const fields = ['dependencies', 'devDependencies', 'optionalDependencies'];
+    const refless = [];
+    let total = 0;
+    for (const field of fields) {
+        const deps = pkg?.[field] ?? {};
+        for (const [name, spec] of Object.entries(deps)) {
+            if (typeof spec !== 'string' || !isGitSpecifier(spec))
+                continue;
+            total++;
+            if (!spec.includes('#'))
+                refless.push(`${name} (${spec})`);
+        }
+    }
+    if (total === 0) {
+        return { check, status: 'ok', detail: 'no git dependencies' };
+    }
+    if (refless.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `${total} git dependenc${total === 1 ? 'y' : 'ies'}, all with an explicit ref`,
+        };
+    }
+    return {
+        check,
+        status: 'optional-missing',
+        detail: `${refless.length} git dependenc${refless.length === 1 ? 'y' : 'ies'} with no ref — pinned to whatever commit was current at install time: ${refless.join('; ')}`,
+        hint: 'Prefer publishing to a registry and depending on a semver range. Failing that, add an explicit ref — `#semver:^1.2.0` is strongest, `#main` at least makes the intent legible and `pnpm update` meaningful.',
+    };
+}

package/dist/languages/js/fixers.js

@@ -10,7 +10,7 @@ import { GH_WORKFLOWS, generateGhWorkflow } from '../../cli/generators/github-wo
 import { generateESLintConfig, generatePrettierConfig } from '../../cli/generators/linting.js';
 import { alignNodeVersion, ensureEnginesNode, generateKnipConfig, generateNvmrc, generateSizeLimitConfig, generateVscodeExtensions, } from '../../cli/generators/misc.js';
 import { composeVerifyScriptFromPkg } from '../../cli/generators/package-json.js';
-import { WORKSPACE_FILE, dependsOnEsbuild, ensurePnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
+import { WORKSPACE_FILE, dependsOnEsbuild, ensurePnpmSettings, familyGlob, } from '../../cli/generators/pnpm-workspace.js';
 import { generatePostcss } from '../../cli/generators/postcss.js';
 import { generateCypressConfig, generateVitestConfig } from '../../cli/generators/testing.js';
 import { generateTreeshakeCheck, inferSubpathsFromExports } from '../../cli/generators/treeshake.js';
@@ -351,7 +351,7 @@ export const FIXERS = [
                 ...(pkg?.dependencies ?? {}),
                 ...(pkg?.devDependencies ?? {}),
             };
-            const written = await ensurePnpmSettings(targetDir, dependsOnEsbuild(deps));
+            const written = await ensurePnpmSettings(targetDir, dependsOnEsbuild(deps), familyGlob(pkg?.name));
             return { filesWritten: written ? [written] : [] };
         },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.1.0",
+	"version": "3.2.1",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [