@rtorcato/repo-tooling 3.12.1 → 3.13.0

package/dist/cli/commands/doctor.js

@@ -18,7 +18,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, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, 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
@@ -295,7 +295,10 @@ export async function runDoctor(dir) {
     results.push(await checkNodeVersionPin(targetDir));
     results.push(await checkNodeVersionConsistency(targetDir, pkg));
     for (const spec of FILE_CHECKS) {
-        results.push(await checkFile(targetDir, spec));
+        // Biome is the one spec that needs the directory as well as the file
+        // contents — it compares the `$schema` version against the installed
+        // CLI (#424). Dispatched here so it keeps its place in the output.
+        results.push(spec.check === 'Biome' ? await checkBiome(targetDir) : await checkFile(targetDir, spec));
     }
     results.push(await checkLintStaged(targetDir, pkg));
     results.push(await checkVerifyScript(targetDir, pkg));

package/dist/cli/generators/linting.js

@@ -48,6 +48,18 @@ async function readJsonOrNull(filepath) {
         return null;
     }
 }
+/**
+ * The `@biomejs/biome` actually installed under `targetDir`, or null when
+ * node_modules isn't populated. This is the binary that will parse the config
+ * and emit the schema-mismatch warning, so it is the only version worth
+ * comparing a written `$schema` against — a declared range like `^2.5.0` says
+ * nothing about which 2.x resolved (#424).
+ */
+export async function installedBiomeVersion(targetDir) {
+    const installed = await readJsonOrNull(path.join(targetDir, 'node_modules', '@biomejs', 'biome', 'package.json'));
+    const match = typeof installed?.version === 'string' ? /(\d+\.\d+\.\d+)/.exec(installed.version) : null;
+    return match?.[1] ?? null;
+}
 /**
  * The Biome version the scaffolded `$schema` URL should name (#363).
  *
@@ -59,20 +71,18 @@ async function readJsonOrNull(filepath) {
  * best statement of intent when node_modules isn't populated yet.
  */
 export async function resolveBiomeSchemaVersion(targetDir) {
-    const installed = await readJsonOrNull(path.join(targetDir, 'node_modules', '@biomejs', 'biome', 'package.json'));
+    const installed = await installedBiomeVersion(targetDir);
+    if (installed)
+        return installed;
     const pkg = await readJsonOrNull(path.join(targetDir, 'package.json'));
     const deps = {
         ...(pkg?.dependencies ?? {}),
         ...(pkg?.devDependencies ?? {}),
     };
-    // Both an exact version ("2.5.7") and a range ("^2.5.0") carry the x.y.z we
-    // need, so one pattern covers every source.
-    for (const candidate of [installed?.version, deps['@biomejs/biome']]) {
-        const match = typeof candidate === 'string' ? /(\d+\.\d+\.\d+)/.exec(candidate) : null;
-        if (match?.[1])
-            return match[1];
-    }
-    return BIOME_SCHEMA_FALLBACK;
+    // A range ("^2.5.0") carries the x.y.z we need just as an exact version does.
+    const declared = deps['@biomejs/biome'];
+    const match = typeof declared === 'string' ? /(\d+\.\d+\.\d+)/.exec(declared) : null;
+    return match?.[1] ?? BIOME_SCHEMA_FALLBACK;
 }
 /**
  * The thin pointer config — the same shape this repo dogfoods. `fix biome` used

package/dist/cli/utils/copy-preset.js

@@ -82,6 +82,11 @@ export const PRESETS = {
         desc: 'Claude Code skill for driving the repo-tooling CLI',
         legacyTarget: '.claude/skills/js-tooling.md',
     },
+    'claude-sync-agents': {
+        source: 'tooling/claude/sync-agents.mjs',
+        target: 'scripts/sync-agents.mjs',
+        desc: 'Canonical SKILL.md → AGENTS.md sync script (zero-config; --check mode for CI)',
+    },
     'mcp-example': {
         source: 'tooling/mcp/mcp.json.example',
         target: '.mcp.json.example',

package/dist/languages/js/checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
-import { hookHasUncommented } from '../../base/checks.js';
+import { checkFile, hookHasUncommented } from '../../base/checks.js';
+import { installedBiomeVersion } from '../../cli/generators/linting.js';
 import { CLAUDE_SETTINGS_FILE, readClaudeSettings, workspaceSymlinkDirs, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
 import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
 const PACKAGE = '@rtorcato/repo-tooling';
@@ -152,6 +153,54 @@ function matchesTsConfig(contents) {
         rootDir.includes('${configDir}') &&
         TS_PRESET_STRICTNESS.every((key) => compilerOptions[key] === true));
 }
+export const BIOME_FILE_CHECK = {
+    check: 'Biome',
+    candidates: ['biome.json', 'biome.jsonc'],
+    expected: `extends "${PACKAGE}/biome" or inlines the preset, with the linter on`,
+    matcher: matchesBiomeConfig,
+    optional: true,
+    hint: 'Run `npx @rtorcato/repo-tooling fix biome` to scaffold',
+};
+/**
+ * The Biome check plus the one thing a contents-only matcher can't see: whether
+ * the `$schema` URL still names the Biome that will read it (#424).
+ *
+ * `fix biome` writes the URL from the version resolved at scaffold time, and
+ * nothing re-checked it afterwards — so once the repo's Biome moved on, every
+ * single invocation (the pre-commit hook included) printed "The configuration
+ * schema version does not match the CLI version", while doctor stayed clean.
+ *
+ * Compared against the *installed* package only, never the declared range: an
+ * exact match is what Biome itself demands, and `^2.5.0` doesn't say which 2.x
+ * resolved. With no node_modules there is nothing to be wrong about, so the
+ * check says nothing rather than guessing.
+ */
+export async function checkBiome(dir) {
+    const result = await checkFile(dir, BIOME_FILE_CHECK);
+    if (result.status !== 'ok')
+        return result;
+    const installed = await installedBiomeVersion(dir);
+    if (!installed)
+        return result;
+    // The same candidate checkFile settled on — first one that exists wins.
+    for (const candidate of BIOME_FILE_CHECK.candidates) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        const url = readSchemaUrl(await fs.readFile(filepath, 'utf8'));
+        const targeted = url?.includes('biomejs.dev') ? schemaUrlVersion(url)?.join('.') : null;
+        if (targeted && targeted !== installed) {
+            return {
+                check: BIOME_FILE_CHECK.check,
+                status: 'drift',
+                detail: `${candidate} targets Biome ${targeted} but @biomejs/biome ${installed} is installed`,
+                hint: 'Run `npx @rtorcato/repo-tooling fix biome` to rewrite the $schema URL',
+            };
+        }
+        return result;
+    }
+    return result;
+}
 export const FILE_CHECKS = [
     {
         check: 'TypeScript',
@@ -160,14 +209,7 @@ export const FILE_CHECKS = [
         matcher: matchesTsConfig,
         hint: 'Run `npx @rtorcato/repo-tooling fix tsconfig` to scaffold',
     },
-    {
-        check: 'Biome',
-        candidates: ['biome.json', 'biome.jsonc'],
-        expected: `extends "${PACKAGE}/biome" or inlines the preset, with the linter on`,
-        matcher: matchesBiomeConfig,
-        optional: true,
-        hint: 'Run `npx @rtorcato/repo-tooling fix biome` to scaffold',
-    },
+    BIOME_FILE_CHECK,
     {
         check: 'ESLint',
         candidates: ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'],
@@ -685,6 +727,10 @@ export async function checkSizeLimit(dir, pkg) {
         hint: 'Add `size-limit` to enforce bundle-size budgets in CI for library projects',
     };
 }
+/** Changesets is in use when its config file is present. */
+export function usesChangesets(dir) {
+    return fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+}
 const SEMANTIC_RELEASE_FILES = [
     '.releaserc',
     '.releaserc.json',
@@ -714,7 +760,7 @@ export async function checkSemanticRelease(dir, pkg) {
             break;
         }
     }
-    const hasChangesets = await fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+    const hasChangesets = await usesChangesets(dir);
     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}.
@@ -1205,9 +1251,14 @@ export async function findDocsAppDir(dir) {
 export async function checkDocsSite(dir, docsAppDir) {
     const check = 'Docs site';
     const deltas = [];
+    // sync-changelog pumps a root CHANGELOG.md into the site — a semantic-release
+    // shape. Changesets writes per-package changelogs and leaves the (private)
+    // root package without one, so don't require the script there (#425). If a
+    // Changesets repo keeps the script anyway, it still has to be wired.
     const syncPath = path.join(dir, 'scripts', 'sync-changelog.mjs');
     if (!(await fs.pathExists(syncPath))) {
-        deltas.push('scripts/sync-changelog.mjs missing');
+        if (!(await usesChangesets(dir)))
+            deltas.push('scripts/sync-changelog.mjs missing');
     }
     else {
         const pkgPath = path.join(dir, docsAppDir, 'package.json');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.12.1",
+	"version": "3.13.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -100,6 +100,7 @@
 		"tooling/semantic-release/*.mjs",
 		"tooling/semantic-release/*.d.mts",
 		"tooling/claude/*.md",
+		"tooling/claude/*.mjs",
 		"tooling/mcp/mcp.json.example",
 		"tooling/swift/*.yml",
 		"tooling/swift/*.json",

package/tooling/claude/sync-agents.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Canonical sync-agents for @rtorcato/* repos (shipped by @rtorcato/repo-tooling
+// — copy via `repo-tooling copy claude-sync-agents`).
+//
+// Regenerates AGENTS.md from the repo's SKILL.md body so the two can never
+// drift. SKILL.md (with its YAML frontmatter) is the single source of truth;
+// AGENTS.md is its frontmatter-stripped mirror for non-Claude AI tools.
+//
+//   node scripts/sync-agents.mjs           # write AGENTS.md
+//   node scripts/sync-agents.mjs --check   # exit 1 if AGENTS.md is stale (used by CI)
+//
+// Zero-config: the skill directory is derived from the root package.json `name`
+// with any npm scope stripped — `@rtorcato/js-common` → `skills/js-common/`.
+// That is the convention across the family, so this file is copied unmodified.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const { name } = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const skillRelative = `skills/${name.replace(/^@[^/]+\//, '')}/SKILL.md`
+const SKILL = join(root, skillRelative)
+const AGENTS = join(root, 'AGENTS.md')
+
+const HEADER = `<!-- Generated from ${skillRelative} by scripts/sync-agents.mjs — do not edit by hand; run \`pnpm sync:agents\`. -->\n\n`
+
+// Strip the leading YAML frontmatter block, keep the markdown body.
+const body = readFileSync(SKILL, 'utf8').replace(/^---\n[\s\S]*?\n---\n+/, '')
+const expected = HEADER + body
+
+if (process.argv.includes('--check')) {
+	let current = ''
+	try {
+		current = readFileSync(AGENTS, 'utf8')
+	} catch {
+		// AGENTS.md missing → treat as stale below.
+	}
+	if (current !== expected) {
+		console.error(`AGENTS.md is out of sync with ${skillRelative} — run \`pnpm sync:agents\`.`)
+		process.exit(1)
+	}
+	console.log(`AGENTS.md is in sync with ${skillRelative}.`)
+} else {
+	writeFileSync(AGENTS, expected)
+	console.log(`Wrote AGENTS.md from ${skillRelative}`)
+}