@rtorcato/repo-tooling 3.2.5 → 3.3.0

package/README.md

@@ -72,6 +72,14 @@ See the [Getting Started guide](https://rtorcato.github.io/repo-tooling/guides/g
 | `doctor` | Diagnose an existing project for missing or drifted tooling. | `npx @rtorcato/repo-tooling doctor` |
 | `fix [target]` | Apply scaffolders for what `doctor` flagged (`--yes`, `--dry-run`, `--diff`). | `npx @rtorcato/repo-tooling fix` |
 
+Prefer to run the audit in CI? `doctor` also ships as a GitHub Action:
+
+```yaml
+- uses: rtorcato/repo-tooling@v3.2.5
+```
+
+See the [GitHub Actions reference](https://rtorcato.github.io/repo-tooling/reference/github-actions/#run-doctor-as-a-github-action) for its inputs and outputs.
+
 Every command takes `-d, --directory <path>`; run any with `--help` for its full flags. Run `list` (or `list --json`) for the full set of `fix` targets — it's the source of truth. Notable ones include `fix docs-site` (scaffold a [Docusaurus docs site](https://rtorcato.github.io/repo-tooling/guides/docs-site/)) and `fix bun` (Bun runtime config).
 
 ## The `.repo-tooling.json` lockfile

package/dist/base/checks.js

@@ -71,7 +71,27 @@ export async function checkCommunityHealth(dir) {
         hint: 'Run `npx @rtorcato/repo-tooling fix community-health` to scaffold them',
     };
 }
-export async function checkGitHubActions(dir) {
+/**
+ * `org/action@vN`, the only form the generators emit. Same shape as the scan in
+ * tests/cli/generators/action-pins.test.ts — major-only, because that's the
+ * granularity every emitted pin uses.
+ */
+const ACTION_PIN = /\b([a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*)@v(\d+)/g;
+function actionPins(yaml) {
+    const pins = new Map();
+    for (const [, action, major] of yaml.matchAll(ACTION_PIN)) {
+        if (action && major)
+            pins.set(action, major);
+    }
+    return pins;
+}
+/**
+ * @param preset the ci.yml this repo's generator would render right now, or null
+ * for a language whose CI generator isn't wired up. Supplied by the caller
+ * rather than rendered here: the JS preset needs a ProjectConfig and the Swift
+ * one needs Package.swift, neither of which belongs in a base check.
+ */
+export async function checkGitHubActions(dir, preset = null) {
     const workflowsDir = path.join(dir, '.github', 'workflows');
     if (!(await fs.pathExists(workflowsDir))) {
         return {
@@ -92,6 +112,33 @@ export async function checkGitHubActions(dir) {
                 hint: 'Add a workflow file (e.g. ci.yml) under .github/workflows/',
             };
         }
+        // "A workflow exists" said nothing about whether it still matches the preset,
+        // so doctor reported ok on a ci.yml that had drifted arbitrarily far — the
+        // blind half of #349/#340. Compare action pins rather than the whole file: a
+        // consuming repo is *expected* to add jobs and steps, so a byte diff is noise
+        // on every customized repo, while a pin major that disagrees with the preset
+        // is exactly the drift that loops (a bump here, a sync there, forever).
+        const ciPath = path.join(workflowsDir, 'ci.yml');
+        if (preset && (await fs.pathExists(ciPath))) {
+            const ours = actionPins(preset);
+            const deltas = [];
+            for (const [action, major] of actionPins(await fs.readFile(ciPath, 'utf-8'))) {
+                const expected = ours.get(action);
+                // Only the intersection is comparable — an action the repo runs but the
+                // preset never emits is the consumer's own business.
+                if (expected && expected !== major) {
+                    deltas.push(`${action}@v${major} (preset emits @v${expected})`);
+                }
+            }
+            if (deltas.length > 0) {
+                return {
+                    check: 'GitHub Actions',
+                    status: 'drift',
+                    detail: `ci.yml action pins disagree with the preset: ${deltas.join('; ')}`,
+                    hint: 'Run `npx @rtorcato/repo-tooling fix github-actions --diff` to see the delta before overwriting — a pin *ahead* of the preset means regenerating would downgrade it',
+                };
+            }
+        }
         return {
             check: 'GitHub Actions',
             status: 'ok',

package/dist/cli/commands/doctor.js

@@ -1,8 +1,12 @@
 import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
+import { renderGitHubWorkflow } from '../../base/ci.js';
+import { githubJobs } from '../../languages/js/ci.js';
+import { inferProjectConfig } from '../../languages/js/fixers.js';
 import { resolveLanguageModule } from '../../languages/registry.js';
 import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js';
+import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
 import { detectLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
 import { checkGitIdentity } from '../../base/git-identity.js';
@@ -148,7 +152,7 @@ async function runBaseChecks(dir, lock, opts) {
         results.push(await checkGitHooks(dir, opts.hooks));
         results.push(await checkPrePushHook(dir, opts.hooks));
     }
-    results.push(await checkGitHubActions(dir));
+    results.push(await checkGitHubActions(dir, opts.presetWorkflow));
     results.push(await checkDependabot(dir));
     results.push(await checkCodeQL(dir));
     // GitHub repo-settings drift (branch protection, merge settings, workflow
@@ -186,6 +190,7 @@ export async function runDoctor(dir) {
             ...(await runBaseChecks(targetDir, lock, {
                 hooks: null,
                 badges: { audience: 'public', fixTarget: null },
+                presetWorkflow: null,
             })),
         ];
         return demoteDeclined(results, lock);
@@ -205,6 +210,7 @@ export async function runDoctor(dir) {
                 // badges always apply. No fixer: `fix badges` derives the block from
                 // package.json name/repository, which a Swift repo hasn't got.
                 badges: { audience: 'public', fixTarget: null },
+                presetWorkflow: renderSwiftWorkflow(await readSwiftPackage(targetDir)),
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
@@ -254,6 +260,7 @@ export async function runDoctor(dir) {
     results.push(...(await runBaseChecks(targetDir, lock, {
         hooks: jsGitHooksProfile(pkg),
         badges: { audience: jsBadgeAudience(pkg), fixTarget: 'badges' },
+        presetWorkflow: renderGitHubWorkflow(githubJobs(inferProjectConfig(pkg))),
     })));
     return demoteDeclined(results, lock);
 }

package/dist/cli/commands/fix-targets.js

@@ -57,6 +57,7 @@ const SWIFT_FIX_TARGETS = {
     SwiftLint: 'swiftlint',
     Periphery: 'periphery',
     'Swift .gitignore': 'swift-gitignore',
+    'Release automation': 'swift-release',
 };
 export function getFixTargetForCheck(checkName, language) {
     if (language === 'swift' && SWIFT_FIX_TARGETS[checkName]) {
@@ -97,6 +98,10 @@ export function declinedInLock(lock, checkName) {
                 c.linting?.tool === 'none' &&
                 c.testing?.framework === 'none');
         case 'semantic-release':
+        // The Swift shape of the same recorded choice (#310): `semanticRelease`
+        // is the config's release-automation flag, and on a SwiftPM repo that
+        // means a tag-triggered workflow rather than an npm publish.
+        case 'Release automation':
             return c.semanticRelease === false;
         case 'Dependabot':
         case 'CodeQL':
@@ -160,6 +165,7 @@ export function lockfilePatchForTarget(target, lock) {
         case 'swift-git-hooks':
             return c.gitHooks ? null : { gitHooks: true };
         case 'semantic-release':
+        case 'swift-release':
             return c.semanticRelease ? null : { semanticRelease: true };
         case 'dependabot':
         case 'renovate':

package/dist/cli/commands/setup-presets.js

@@ -89,8 +89,10 @@ export function buildPresetConfig(name, projectName) {
                 // commitlint *is* an npm package and needs node on PATH to run, so
                 // the Swift hooks deliberately wire no commit-msg hook.
                 commitLint: false,
-                // semantic-release publishes to npm. SwiftPM consumes git tags.
-                semanticRelease: false,
+                // The release-automation flag, not the npm tool: semantic-release
+                // publishes to npm, and SwiftPM consumes git tags, so on this path it
+                // means a tag-triggered release workflow instead (#310).
+                semanticRelease: true,
                 securityAutomation: true,
                 bundler: 'none',
                 // Every badge URL is derived from package.json (name + repository),

package/dist/cli/generators/github-actions.js

@@ -16,7 +16,19 @@ const CODECOV_YML = `coverage:
         target: auto
         threshold: 1%
 `;
-export async function generateGitHubActions(config, targetDir) {
+/** Matches the fixer's declared output, so `fix` reports the same path it lists. */
+export const CI_WORKFLOW = '.github/workflows/ci.yml';
+/**
+ * @param overwrite Replace a ci.yml that no longer matches the preset. Off by
+ * default: this used to write unconditionally, so a consuming repo's customized
+ * workflow — an extra job, a Dependabot-bumped action pin — was reverted on
+ * every sync with no diff, no prompt and no backup (#349, the mechanism behind
+ * #340). Same self-enforced safe-add as github-workflows.ts, widened to "or is
+ * byte-identical anyway" so a no-op regeneration still reports honestly. Only a
+ * caller that has told the user this workflow itself is drifting passes true.
+ * @returns the files actually written, relative to targetDir.
+ */
+export async function generateGitHubActions(config, targetDir, { overwrite = false } = {}) {
     const workflowsDir = path.join(targetDir, '.github', 'workflows');
     await fs.ensureDir(workflowsDir);
     // This is the JS path specifically. Swift (#287) renders its own workflow
@@ -26,10 +38,18 @@ export async function generateGitHubActions(config, targetDir) {
     // paths meet at renderGitHubWorkflow() in src/base/ci.ts, which is the seam
     // that actually matters.
     const workflow = renderGitHubWorkflow(githubJobs(config));
-    await fs.writeFile(path.join(workflowsDir, 'ci.yml'), workflow);
+    const ciPath = path.join(workflowsDir, 'ci.yml');
+    const existing = (await fs.pathExists(ciPath)) ? await fs.readFile(ciPath, 'utf-8') : null;
+    const filesWritten = [];
+    if (overwrite || existing === null || existing === workflow) {
+        await fs.writeFile(ciPath, workflow);
+        filesWritten.push(CI_WORKFLOW);
+    }
     // codecov.yml is the CI's coverage-upload companion — emit it alongside ci.yml
     // whenever the workflow uploads coverage, so the codecov badge isn't red.
     if (usesCoverage(config)) {
         await fs.writeFile(path.join(targetDir, 'codecov.yml'), CODECOV_YML);
+        filesWritten.push('codecov.yml');
     }
+    return filesWritten;
 }

package/dist/languages/js/fixers.js

@@ -4,7 +4,7 @@ import fs from 'fs-extra';
 import { buildBadgeBlock, parseRepository, upsertBadges } from '../../cli/generators/badges.js';
 import { generateReleasePleaseConfig, generateRolldownConfig, generateRollupConfig, generateSemanticReleaseConfig, } from '../../cli/generators/build.js';
 import { generateHuskyConfig, generatePrePushHook } from '../../cli/generators/git.js';
-import { generateGitHubActions } from '../../cli/generators/github-actions.js';
+import { CI_WORKFLOW, generateGitHubActions } from '../../cli/generators/github-actions.js';
 import { generateGitLabCI } from '../../cli/generators/gitlab-ci.js';
 import { GH_WORKFLOWS, generateGhWorkflow } from '../../cli/generators/github-workflows.js';
 import { generateESLintConfig, generatePrettierConfig } from '../../cli/generators/linting.js';
@@ -22,7 +22,8 @@ import { generateDocsSite } from '../../cli/generators/docs-site.js';
 import { generateTypedocConfig, generateTypedocWorkflow } from '../../cli/generators/typedoc.js';
 import { copyPreset } from '../../cli/utils/copy-preset.js';
 import { LOCKFILE_NAME, writeLockfile } from '../../cli/utils/lockfile.js';
-function inferProjectConfig(pkg) {
+/** Exported so doctor can render the preset ci.yml it compares against (#349). */
+export function inferProjectConfig(pkg) {
     const deps = {
         ...(pkg?.dependencies ?? {}),
         ...(pkg?.devDependencies ?? {}),
@@ -303,13 +304,19 @@ export const FIXERS = [
         target: 'github-actions',
         description: 'Scaffold .github/workflows/ci.yml (+ codecov.yml when tests run)',
         appliesTo: ['GitHub Actions', 'Coverage upload', 'npm OIDC publish'],
-        outputs: ['.github/workflows/ci.yml', 'codecov.yml'],
+        outputs: [CI_WORKFLOW, 'codecov.yml'],
         canFixDrift: true,
-        async run({ targetDir, pkg }) {
-            await generateGitHubActions(inferProjectConfig(pkg), targetDir);
-            const filesWritten = ['.github/workflows/ci.yml'];
-            if (await fs.pathExists(path.join(targetDir, 'codecov.yml')))
-                filesWritten.push('codecov.yml');
+        async run({ targetDir, pkg, result }) {
+            // Only a `GitHub Actions` finding means the user was shown that the
+            // workflow itself is wrong (and got the destructive-overwrite prompt).
+            // A sibling finding — Coverage upload, npm OIDC publish — must not take a
+            // customized ci.yml down with it (#349).
+            const filesWritten = await generateGitHubActions(inferProjectConfig(pkg), targetDir, {
+                overwrite: result.check === 'GitHub Actions',
+            });
+            if (!filesWritten.includes(CI_WORKFLOW)) {
+                console.log(chalk.yellow(`   ${CI_WORKFLOW} differs from the preset — left as-is; run \`fix github-actions --diff\` to see the delta`));
+            }
             return { filesWritten };
         },
     },

package/dist/languages/swift/checks.js

@@ -105,6 +105,42 @@ export async function checkPackageSwift(dir) {
         detail: `Package.swift declares tools ${toolsVersion} and explicit platforms`,
     };
 }
+/**
+ * Release automation for a SwiftPM package (#310). There is no publish step to
+ * look for — a release *is* a semver git tag consumers resolve with
+ * `.package(url:from:)` — so "configured" means a workflow that fires on a tag
+ * push. semantic-release is deliberately not accepted as evidence: its pipeline
+ * is npm end to end, and a Swift repo running it is publishing the wrong thing.
+ *
+ * Only the trigger section is searched (everything above `jobs:`), because
+ * `tags:` also appears inside job steps — docker/metadata-action emits one — and
+ * a step that mentions tags is not a release trigger.
+ */
+export async function checkSwiftRelease(dir) {
+    const check = 'Release automation';
+    const hint = 'Run `npx @rtorcato/repo-tooling fix swift-release` to scaffold a tag-triggered release workflow';
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (await fs.pathExists(workflowsDir)) {
+        const files = (await fs.readdir(workflowsDir)).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const file of files) {
+            const contents = await fs.readFile(path.join(workflowsDir, file), 'utf-8');
+            const triggers = contents.split(/^jobs:/m)[0] ?? '';
+            if (/^\s+tags:/m.test(triggers)) {
+                return {
+                    check,
+                    status: 'ok',
+                    detail: `.github/workflows/${file} releases on a tag push`,
+                };
+            }
+        }
+    }
+    return {
+        check,
+        status: 'optional-missing',
+        detail: 'no workflow triggered by a version tag',
+        hint,
+    };
+}
 /**
  * The Swift shape of the base `Git hooks` / `Pre-push hook` checks (#309).
  * `install` is null because the wiring — `git config core.hooksPath` — is
@@ -123,5 +159,6 @@ export async function runSwiftChecks(dir) {
         await checkPackageSwift(dir),
         ...(await Promise.all(SWIFT_FILE_CHECKS.map((spec) => checkFile(dir, spec)))),
         await checkSwiftGitignore(dir),
+        await checkSwiftRelease(dir),
     ];
 }

package/dist/languages/swift/ci.js

@@ -140,6 +140,49 @@ ${pkg.platforms.map((p) => `          - ${p}`).join('\n')}`,
 export function renderSwiftWorkflow(pkg) {
     return renderGitHubWorkflow(swiftGithubJobs(pkg));
 }
+/**
+ * The release pipeline (#310). SwiftPM has no registry publish step — a release
+ * *is* a semver git tag that consumers resolve with `.package(url:from:)` — so
+ * the workflow fires on the tag rather than on a merge, and its only output is
+ * a GitHub Release with generated notes.
+ *
+ * The build/test gate runs before the release is cut because a tag is
+ * effectively permanent: SwiftPM caches resolved tags, so re-pointing a bad one
+ * doesn't reliably reach consumers who already resolved it.
+ *
+ * `gh` (preinstalled on the runner) rather than a release action: one fewer
+ * third-party pin to track, and `--verify-tag` refuses to invent a tag that
+ * isn't actually pushed.
+ */
+export function renderSwiftReleaseWorkflow() {
+    return `name: 🏷️  Release
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  release:
+    runs-on: ${MACOS}
+    permissions:
+      contents: write
+    steps:
+${XCODE_SETUP}
+
+      - name: 🏗️  swift build
+        run: swift build
+
+      - name: 🧪 swift test
+        run: swift test
+
+      - name: 🏷️  Publish GitHub Release
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: gh release create "\${{ github.ref_name }}" --generate-notes --verify-tag
+`;
+}
 /**
  * GitLab runs Swift in the official Linux image. That rules out Xcode — so no
  * platform matrix and no SwiftLint (a Homebrew/macOS tool in practice); the

package/dist/languages/swift/fixers.js

@@ -7,7 +7,7 @@ import fs from 'fs-extra';
 import { buildPresetConfig } from '../../cli/commands/setup-presets.js';
 import { copyPreset } from '../../cli/utils/copy-preset.js';
 import { LOCKFILE_NAME, writeLockfile } from '../../cli/utils/lockfile.js';
-import { readSwiftPackage, renderSwiftGitLabCI, renderSwiftWorkflow } from './ci.js';
+import { readSwiftPackage, renderSwiftGitLabCI, renderSwiftReleaseWorkflow, renderSwiftWorkflow, } from './ci.js';
 import { SWIFT_HOOKS_DIR, installSwiftGitHooks } from './git-hooks.js';
 import { ensureSwiftGitignore } from './gitignore.js';
 export const SWIFT_FIXERS = [
@@ -73,6 +73,19 @@ export const SWIFT_FIXERS = [
             return { filesWritten: ['.github/workflows/ci.yml'] };
         },
     },
+    {
+        target: 'swift-release',
+        description: 'Scaffold .github/workflows/release.yml (build + test on a version tag, then publish a GitHub Release)',
+        appliesTo: ['Release automation'],
+        outputs: ['.github/workflows/release.yml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const workflowsDir = path.join(targetDir, '.github', 'workflows');
+            await fs.ensureDir(workflowsDir);
+            await fs.writeFile(path.join(workflowsDir, 'release.yml'), renderSwiftReleaseWorkflow());
+            return { filesWritten: ['.github/workflows/release.yml'] };
+        },
+    },
     {
         target: 'swift-gitlab-ci',
         description: 'Scaffold .gitlab-ci.yml for Swift (swift build + test on the Linux Swift image)',

package/dist/languages/swift/scaffold.js

@@ -18,7 +18,7 @@ import { generateEditorConfig } from '../../cli/generators/misc.js';
 import { generateCodeQLWorkflow, generateDependabotConfig } from '../../cli/generators/security.js';
 import { copyPreset } from '../../cli/utils/copy-preset.js';
 import { LANGUAGES } from '../registry.js';
-import { readSwiftPackage, renderSwiftWorkflow } from './ci.js';
+import { readSwiftPackage, renderSwiftReleaseWorkflow, renderSwiftWorkflow } from './ci.js';
 import { SWIFT_HOOKS_DIR, installSwiftGitHooks } from './git-hooks.js';
 import { ensureSwiftGitignore } from './gitignore.js';
 /**
@@ -168,7 +168,18 @@ ${config.projectName}/
 - **GitHub Actions** — \`swift build\`/\`swift test\` on macOS, plus \`xcodebuild\` per declared platform
 
 Run \`npx @rtorcato/repo-tooling doctor\` any time to audit this repo against the standard.
+${config.semanticRelease
+        ? `
+## Releasing
 
+SwiftPM has no registry: a release is a semver git tag. Pushing one runs the
+build/test gate and publishes a GitHub Release from it.
+
+\`\`\`bash
+git tag 1.0.0 && git push origin 1.0.0
+\`\`\`
+`
+        : ''}
 ## Contributing
 
 1. Fork the repository
@@ -199,6 +210,9 @@ export function swiftFileList(config) {
         '.editorconfig',
         '.github/workflows/ci.yml',
     ];
+    if (config.semanticRelease) {
+        files.push('.github/workflows/release.yml');
+    }
     if (config.gitHooks) {
         files.push(`${SWIFT_HOOKS_DIR}/pre-commit`, `${SWIFT_HOOKS_DIR}/pre-push`);
     }
@@ -227,6 +241,10 @@ export async function generateSwiftProject(config, targetDir) {
     const workflowsDir = path.join(targetDir, '.github', 'workflows');
     await fs.ensureDir(workflowsDir);
     await fs.writeFile(path.join(workflowsDir, 'ci.yml'), renderSwiftWorkflow(await readSwiftPackage(targetDir)));
+    // A tag-triggered release, not an npm publish (#310) — see the preset.
+    if (config.semanticRelease) {
+        await fs.writeFile(path.join(workflowsDir, 'release.yml'), renderSwiftReleaseWorkflow());
+    }
     // `core.hooksPath` won't stick here — `setup` scaffolds into a directory that
     // isn't a git repo yet — so the hooks land as files and the README tells you
     // the one-line config to run after `git init`.

package/package.json

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