@rtorcato/repo-tooling 3.3.0 → 3.5.0

package/dist/base/checks.js

@@ -1,6 +1,29 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
+import { detectNestedLanguages } from '../cli/utils/detect-language.js';
+/**
+ * Root-only detection is the decision (#317), not an oversight — but it used to
+ * be a *silent* one: a Swift repo with a TypeScript docs app audited as Swift
+ * and never mentioned the half it skipped. This says so.
+ *
+ * Always `ok`. Nesting a second language is a legitimate repo shape, so failing
+ * on it would break every monorepo's CI to report a limitation of ours.
+ */
+export async function checkNestedLanguages(dir, rootLanguage) {
+    const check = 'Monorepo';
+    const nested = await detectNestedLanguages(dir, rootLanguage);
+    if (nested.length === 0) {
+        return { check, status: 'ok', detail: 'single-language repo' };
+    }
+    const summary = nested.map((n) => `${n.dir} (${n.language})`).join(', ');
+    return {
+        check,
+        status: 'ok',
+        detail: `auditing the root only — ${summary} ${nested.length === 1 ? 'is' : 'are'} not audited`,
+        hint: 'Run doctor with `--directory <path>` to audit a nested project on its own',
+    };
+}
 export async function checkFile(dir, spec) {
     for (const candidate of spec.candidates) {
         const filepath = path.join(dir, candidate);

package/dist/cli/commands/doctor.js

@@ -12,7 +12,7 @@ import { checkGitHubSettings } from '../../base/github-settings.js';
 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 { checkAiSetup, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/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';
@@ -145,6 +145,7 @@ function demoteDeclined(results, lock) {
 async function runBaseChecks(dir, lock, opts) {
     const results = [];
     results.push(checkLockfile(lock));
+    results.push(await checkNestedLanguages(dir, opts.language));
     results.push(await checkGitIdentity(dir));
     results.push(await checkEditorConfig(dir));
     results.push(await checkFile(dir, COMMITLINT_FILE_CHECK));
@@ -191,6 +192,7 @@ export async function runDoctor(dir) {
                 hooks: null,
                 badges: { audience: 'public', fixTarget: null },
                 presetWorkflow: null,
+                language,
             })),
         ];
         return demoteDeclined(results, lock);
@@ -211,6 +213,7 @@ export async function runDoctor(dir) {
                 // package.json name/repository, which a Swift repo hasn't got.
                 badges: { audience: 'public', fixTarget: null },
                 presetWorkflow: renderSwiftWorkflow(await readSwiftPackage(targetDir)),
+                language,
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
@@ -261,6 +264,7 @@ export async function runDoctor(dir) {
         hooks: jsGitHooksProfile(pkg),
         badges: { audience: jsBadgeAudience(pkg), fixTarget: 'badges' },
         presetWorkflow: renderGitHubWorkflow(githubJobs(inferProjectConfig(pkg))),
+        language,
     })));
     return demoteDeclined(results, lock);
 }

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/cli/utils/detect-language.js

@@ -2,8 +2,9 @@ import path from 'node:path';
 import fs from 'fs-extra';
 /**
  * Marker files that identify a repo's language, checked in order — first match
- * wins. One language per repo root; multi-language monorepos are out of scope
- * for v1 (see #139). A dir with no marker → 'unknown' (base checks only).
+ * wins. One language per repo root; multi-language monorepos stay out of scope
+ * (#139, reaffirmed in #317 — the audit is root-only, but says so via
+ * `detectNestedLanguages`). A dir with no marker → 'unknown' (base checks only).
  */
 const MARKERS = [
     ['js', ['package.json']],
@@ -20,3 +21,44 @@ export async function detectLanguage(dir) {
     }
     return 'unknown';
 }
+/** Never worth descending into, and expensive when we do. */
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'target', 'vendor', '.build']);
+/**
+ * Sub-project dirs whose language marker disagrees with the root's, as
+ * `{ dir, language }` sorted by dir. Depth-2 scan — enough for the shapes that
+ * exist (`apps/docs`, `packages/*`, a top-level `docs/`) and cheap enough to run
+ * on every doctor.
+ *
+ * Deliberately *not* driven by the workspace manifest: the case #317 is about is
+ * a Swift or Perl root with a JS docs app, and such a repo has no
+ * `pnpm-workspace.yaml` to read. Walking the tree finds it either way, and needs
+ * no glob dependency.
+ */
+export async function detectNestedLanguages(dir, rootLanguage) {
+    const found = [];
+    const scan = async (relative, depth) => {
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(dir, relative));
+        }
+        catch {
+            return; // unreadable dir is the caller's problem, not the audit's
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.') || SKIP_DIRS.has(entry))
+                continue;
+            const child = relative ? `${relative}/${entry}` : entry;
+            if (!(await fs.stat(path.join(dir, child)).catch(() => null))?.isDirectory())
+                continue;
+            const language = await detectLanguage(path.join(dir, child));
+            if (language !== 'unknown' && language !== rootLanguage) {
+                found.push({ dir: child, language });
+                continue; // a package's own subdirs belong to it, not to the root
+            }
+            if (depth > 1)
+                await scan(child, depth - 1);
+        }
+    };
+    await scan('', 2);
+    return found.sort((a, b) => a.dir.localeCompare(b.dir));
+}

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.5.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
+}