@rtorcato/repo-tooling 3.3.0 → 3.4.0

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

@@ -58,6 +58,11 @@ const SWIFT_FIX_TARGETS = {
     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]) {

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/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,104 @@ 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
@@ -159,6 +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/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 { 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',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.3.0",
+	"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
+}