@rtorcato/repo-tooling 3.2.5 → 3.4.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,12 @@ const SWIFT_FIX_TARGETS = {
     SwiftLint: 'swiftlint',
     Periphery: 'periphery',
     'Swift .gitignore': 'swift-gitignore',
+    'Release automation': 'swift-release',
+    'swift-format': 'swift-format',
+    DocC: 'docc',
+    // `Swift tests` is deliberately absent: when it fails for the manifest half
+    // (no `.testTarget(`) there's nothing to run, and rewriting Package.swift
+    // isn't safe. The check's own hint covers both halves.
 };
 export function getFixTargetForCheck(checkName, language) {
     if (language === 'swift' && SWIFT_FIX_TARGETS[checkName]) {
@@ -97,6 +103,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 +170,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/cli/utils/copy-preset.js

@@ -41,6 +41,11 @@ export const PRESETS = {
         target: '.swiftlint.yml',
         desc: 'SwiftLint configuration (lint + --fix; the standard swift-common runs)',
     },
+    'swift-format': {
+        source: 'tooling/swift/swift-format.json',
+        target: '.swift-format',
+        desc: "Apple swift-format configuration (4-space, 120 columns — matches the module's .editorconfig)",
+    },
     periphery: {
         source: 'tooling/swift/periphery.yml',
         target: '.periphery.yml',

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

@@ -5,8 +5,10 @@
  * (lint + `--fix` in pre-commit, `--strict` in CI) and Periphery for dead code.
  * Deliberately *not* checked:
  *
- * - SwiftFormat — SwiftLint's `--fix` does the formatting; a second formatter
- *   would fight it.
+ * - SwiftFormat (the Nick Lockwood one) — SwiftLint's `--fix` does the
+ *   formatting; a second *rewriting* formatter would fight it. Apple's
+ *   `swift-format` is checked as of #311, but only as an optional slot: a repo
+ *   that opts into it runs it *instead of* `swiftlint --fix`.
  * - `.swift-version` — the toolchain is pinned in CI (`setup-xcode`) and the
  *   package declares `// swift-tools-version:`, so a root file would be a third
  *   place to keep in sync.
@@ -33,6 +35,17 @@ const SWIFT_FILE_CHECKS = [
         optional: true,
         hint: 'Run `npx @rtorcato/repo-tooling fix periphery` to scaffold a dead-code scan config',
     },
+    {
+        // Apple's swift-format, the formatter slot (#311) — not a second linter.
+        // Optional because SwiftLint's `--fix` already formats: a repo runs one,
+        // the other, or both, so its absence is a choice rather than drift.
+        check: 'swift-format',
+        candidates: ['.swift-format', '.swift-format.json'],
+        expected: 'is a valid swift-format configuration',
+        matcher: /"(version|lineLength|indentation|rules)"\s*:/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/repo-tooling fix swift-format` to scaffold one (SwiftLint `--fix` formats without it)',
+    },
 ];
 /**
  * Build artefacts that must never be committed. `.build` and `DerivedData` are
@@ -105,6 +118,140 @@ export async function checkPackageSwift(dir) {
         detail: `Package.swift declares tools ${toolsVersion} and explicit platforms`,
     };
 }
+/**
+ * Directory names under `Sources/`. For a SwiftPM package these are the target
+ * names — a target's sources and its DocC catalogue live in the same folder,
+ * so this is where both the check and the `docc` fixer have to look.
+ */
+export async function swiftSourceTargets(dir) {
+    try {
+        const entries = await fs.readdir(path.join(dir, 'Sources'), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function findDoccCatalogue(dir) {
+    for (const target of await swiftSourceTargets(dir)) {
+        const entries = await fs.readdir(path.join(dir, 'Sources', target));
+        const catalogue = entries.find((e) => e.endsWith('.docc'));
+        if (catalogue)
+            return `Sources/${target}/${catalogue}`;
+    }
+    return null;
+}
+/**
+ * DocC, the Swift shape of the TypeDoc check (#311). Two halves have to line
+ * up: a `.docc` catalogue holds the prose, and `swift-docc-plugin` is what
+ * makes `swift package generate-documentation` exist — either alone is docs
+ * that nobody can build, or a build command with nothing to say.
+ */
+export async function checkDocC(dir) {
+    const check = 'DocC';
+    const hint = 'Run `npx @rtorcato/repo-tooling fix docc` to scaffold a DocC catalogue';
+    const manifest = path.join(dir, 'Package.swift');
+    const contents = (await fs.pathExists(manifest)) ? await fs.readFile(manifest, 'utf-8') : '';
+    const hasPlugin = contents.includes('swift-docc-plugin');
+    const catalogue = await findDoccCatalogue(dir);
+    if (catalogue && hasPlugin) {
+        return { check, status: 'ok', detail: `${catalogue} with swift-docc-plugin declared` };
+    }
+    if (catalogue) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${catalogue} found but Package.swift declares no swift-docc-plugin`,
+            hint: 'Add `.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.0")` to Package.swift',
+        };
+    }
+    if (hasPlugin) {
+        return {
+            check,
+            status: 'drift',
+            detail: 'swift-docc-plugin declared but no .docc catalogue under Sources/',
+            hint,
+        };
+    }
+    return { check, status: 'optional-missing', detail: 'DocC not configured', hint };
+}
+/**
+ * The test setup (#311). SwiftPM has no test-runner config file to check — the
+ * suite is declared in the manifest and run by `swift test` — so the two facts
+ * worth asserting are that a test target exists at all and that CI runs it. A
+ * green pipeline over a package with no `.testTarget(` proves nothing.
+ */
+export async function checkSwiftTests(dir) {
+    const check = 'Swift tests';
+    const manifest = path.join(dir, 'Package.swift');
+    if (!(await fs.pathExists(manifest))) {
+        return { check, status: 'missing', detail: 'no Package.swift' };
+    }
+    if (!/\.testTarget\(/.test(await fs.readFile(manifest, 'utf-8'))) {
+        return {
+            check,
+            status: 'missing',
+            detail: 'Package.swift declares no `.testTarget(`',
+            hint: 'Add a `.testTarget(name: "<Target>Tests", dependencies: ["<Target>"])` to Package.swift',
+        };
+    }
+    const candidates = ['.gitlab-ci.yml', '.gitlab-ci.yaml'];
+    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'));
+        candidates.unshift(...files.map((f) => path.join('.github', 'workflows', f)));
+    }
+    for (const candidate of candidates) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        if (/\bswift\s+test\b/.test(await fs.readFile(filepath, 'utf-8'))) {
+            return { check, status: 'ok', detail: `test target declared and run by ${candidate}` };
+        }
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: 'test target declared but no CI job runs `swift test`',
+        hint: 'Run `npx @rtorcato/repo-tooling fix swift-ci` to regenerate a workflow that runs `swift test`',
+    };
+}
+/**
+ * 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 +270,8 @@ export async function runSwiftChecks(dir) {
         await checkPackageSwift(dir),
         ...(await Promise.all(SWIFT_FILE_CHECKS.map((spec) => checkFile(dir, spec)))),
         await checkSwiftGitignore(dir),
+        await checkSwiftTests(dir),
+        await checkDocC(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,9 +7,33 @@ 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 { swiftSourceTargets } from './checks.js';
+import { readSwiftPackage, renderSwiftGitLabCI, renderSwiftReleaseWorkflow, renderSwiftWorkflow, } from './ci.js';
 import { SWIFT_HOOKS_DIR, installSwiftGitHooks } from './git-hooks.js';
 import { ensureSwiftGitignore } from './gitignore.js';
+/**
+ * A DocC module page. The heading is a symbol link (double backticks) because
+ * that's what binds the article to the module — a plain `# Name` heading makes
+ * DocC treat the file as a standalone article instead.
+ */
+function doccLandingPage(target) {
+    return `# \`\`${target}\`\`
+
+Summary line for ${target} — replace this with what the module is for.
+
+## Overview
+
+Write the prose documentation for ${target} here. Anything else in this
+catalogue (articles, tutorials, resources) is picked up automatically.
+
+Build it with \`swift package generate-documentation\`, or preview it with
+\`swift package --disable-sandbox preview-documentation --target ${target}\`.
+
+## Topics
+
+### Essentials
+`;
+}
 export const SWIFT_FIXERS = [
     {
         target: 'swiftlint',
@@ -33,6 +57,46 @@ export const SWIFT_FIXERS = [
             return { filesWritten: [result.target] };
         },
     },
+    {
+        target: 'swift-format',
+        description: 'Scaffold .swift-format (Apple swift-format, the optional formatter slot)',
+        appliesTo: ['swift-format'],
+        outputs: ['.swift-format'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('swift-format', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'docc',
+        description: 'Scaffold a DocC catalogue (Sources/<Target>/<Target>.docc) for the first target',
+        appliesTo: ['DocC'],
+        // Path depends on the target name, so `fix --dry-run` shows no diff for
+        // this one — the file it writes isn't knowable without reading Sources/.
+        outputs: ['Sources/<Target>/<Target>.docc/<Target>.md'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            // The library product's target first — that's the API consumers read
+            // docs for — falling back to whatever single target the package has.
+            const targets = await swiftSourceTargets(targetDir);
+            const { products } = await readSwiftPackage(targetDir);
+            const target = products.find((p) => targets.includes(p)) ?? targets[0];
+            if (!target) {
+                throw new Error('no Sources/<Target>/ directory to put a DocC catalogue in');
+            }
+            const file = `Sources/${target}/${target}.docc/${target}.md`;
+            // safe-add: the catalogue is prose someone wrote, so a re-run (DocC
+            // also drifts when the manifest lacks the plugin, which this fixer
+            // can't repair) must not overwrite it.
+            if (await fs.pathExists(path.join(targetDir, file)))
+                return { filesWritten: [] };
+            await fs.outputFile(path.join(targetDir, file), doccLandingPage(target));
+            console.log(chalk.yellow('   add swift-docc-plugin to Package.swift to build it: .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.0")'));
+            return { filesWritten: [file] };
+        },
+    },
     {
         target: 'swift-gitignore',
         description: 'Add the Swift/SwiftPM build artefacts (.build, DerivedData, xcuserdata) to .gitignore',
@@ -73,6 +137,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.4.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -102,6 +102,7 @@
 		"tooling/claude/*.md",
 		"tooling/mcp/mcp.json.example",
 		"tooling/swift/*.yml",
+		"tooling/swift/*.json",
 		"tooling/github-actions/workflows/*.yml",
 		"README.md",
 		"AGENTS.md"

package/tooling/swift/swift-format.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "lineLength": 120,
+  "indentation": {
+    "spaces": 4
+  },
+  "respectsExistingLineBreaks": true,
+  "lineBreakBeforeEachArgument": false,
+  "prioritizeKeepingFunctionOutputTogether": true
+}