@rtorcato/repo-tooling 3.32.0 → 3.34.0

package/dist/cli/commands/doctor.js

@@ -22,7 +22,7 @@ import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { compareRulesWithReference } from '../utils/reference-rules.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, checkRecommendedMcp, checkRequiredSkills, COMMITLINT_FILE_CHECK, } from '../../base/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';
+import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkExportsBuildable, 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
@@ -385,6 +385,8 @@ export async function runDoctor(dir, skillsDir) {
     results.push(await checkTypedoc(targetDir, pkg));
     results.push(await checkAreTheTypesWrong(targetDir, pkg));
     results.push(await checkPublint(targetDir, pkg));
+    // The setup/doctor-time half of what publint catches at release time (#578).
+    results.push(await checkExportsBuildable(targetDir, pkg));
     results.push(await checkTreeshakeSetup(targetDir, pkg));
     results.push(await checkPnpmWorkspace(targetDir, pkg));
     results.push(await checkBuildApprovals(targetDir, pkg));

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

@@ -76,6 +76,8 @@ const SWIFT_FIX_TARGETS = {
     // `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.
+    // `Swift targets` too (#575): the repair is either adding a target or
+    // deleting the directory, and only the project knows which.
 };
 /** The same shadowing for the Python module (#290). */
 const PYTHON_FIX_TARGETS = {

package/dist/languages/js/checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { checkFile, hookHasUncommented } from '../../base/checks.js';
+import { realGitExec } from '../../base/git-identity.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';
@@ -964,6 +965,202 @@ export async function checkPublint(_dir, pkg) {
         hint: 'Run `npx @rtorcato/repo-tooling fix publint` to lint your package before publishing',
     };
 }
+/**
+ * The file extensions each recognised build command drops in the output
+ * directory. Inferring this from an arbitrary shell command is inherently
+ * partial, so the table is deliberately small and anything missing from it
+ * makes the whole check stand down (see `emittedExtensions`) — a doctor check
+ * that cries wolf on a valid config is worse than one with a stated blind spot.
+ */
+const BUILD_EMITS = {
+    // tsc mirrors its input extension: .ts → .js + .d.ts. It reaches .cjs/.d.cts
+    // only from .cts sources, which is why a repo that has any stands the check
+    // down below.
+    tsc: ['.js', '.d.ts'],
+    // tsup's real set is whatever `format`/`dts` say in a config file this does
+    // not parse, so it claims the broadest set tsup could emit. A tsup build is
+    // therefore passed rather than guessed at, while `rimraf dist && tsup` still
+    // resolves instead of standing the check down.
+    tsup: ['.js', '.cjs', '.mjs', '.d.ts', '.d.cts', '.d.mts'],
+    // Cleaners emit nothing. Recognised only so the very common
+    // `rimraf dist && tsc` is still judged on its tsc half.
+    rimraf: [],
+    rm: [],
+    del: [],
+};
+/** Package-manager noise to strip before the command name: `pnpm exec tsup`. */
+const RUNNER_TOKENS = new Set([
+    'npx',
+    'npm',
+    'pnpm',
+    'yarn',
+    'bun',
+    'exec',
+    'dlx',
+    'run',
+    'x',
+    '-s',
+    '--silent',
+]);
+/**
+ * Extensions this check will judge, longest suffix first. Anything else — a
+ * package publishing `./src/index.ts` directly, a `./dist/style.css` from a
+ * non-JS step — is left alone rather than measured against a JS emit table.
+ */
+const ARTEFACT_EXTENSIONS = ['.d.cts', '.d.mts', '.d.ts', '.cjs', '.mjs', '.js'];
+function artefactExtension(p) {
+    return ARTEFACT_EXTENSIONS.find((ext) => p.endsWith(ext)) ?? null;
+}
+/**
+ * Every file path the publish contract names. Shared with the #570 regression
+ * test so doctor and that test agree on what the contract is.
+ */
+export function declaredEntryPoints(pkg) {
+    const found = [];
+    const walk = (node) => {
+        if (typeof node === 'string')
+            found.push(node);
+        else if (node && typeof node === 'object')
+            Object.values(node).forEach(walk);
+    };
+    walk(pkg.exports);
+    for (const field of ['main', 'module', 'types']) {
+        const value = pkg[field];
+        if (typeof value === 'string')
+            found.push(value);
+    }
+    return [...new Set(found)];
+}
+/**
+ * What `command` puts in the output directory, or null when any part of it is
+ * absent from BUILD_EMITS. Null means "don't know", and every caller stands
+ * down on it rather than guessing.
+ */
+function emittedExtensions(scripts, command, seen = new Set()) {
+    // Only a plain `a && b` chain is read. Pipes, `||`, subshells and redirects
+    // are not something to infer an output set from.
+    if (/[|;`<>]|\$\(/.test(command))
+        return null;
+    const emitted = new Set();
+    for (const segment of command.split('&&')) {
+        const tokens = segment.trim().split(/\s+/).filter(Boolean);
+        const before = tokens.length;
+        while (tokens.length > 0 && RUNNER_TOKENS.has(tokens[0]))
+            tokens.shift();
+        const name = tokens[0];
+        if (!name)
+            return null;
+        // `"build": "pnpm build-cli"` — one script delegating to another. Followed
+        // only when a runner was actually stripped, because a bare `tsc` runs the
+        // binary even in a repo that also happens to have a script by that name.
+        const nested = tokens.length < before ? scripts[name] : undefined;
+        if (nested !== undefined) {
+            if (seen.has(name))
+                return null;
+            seen.add(name);
+            const inner = emittedExtensions(scripts, nested, seen);
+            if (!inner)
+                return null;
+            for (const ext of inner)
+                emitted.add(ext);
+            continue;
+        }
+        const known = BUILD_EMITS[name];
+        if (!known)
+            return null;
+        for (const ext of known)
+            emitted.add(ext);
+    }
+    return [...emitted];
+}
+/**
+ * Catches a publish contract naming files the repo's own `build` cannot produce
+ * (#578) — the class of bug that shipped `main: ./dist/index.cjs` alongside
+ * `build: tsc`, which emits only .js and .d.ts, so every CJS consumer of the
+ * published package got a 404 (#570). #577 fixed the preset that wrote that
+ * pair; this catches it however else it arises, e.g. a repo editing `build` or
+ * the contract by hand afterwards.
+ *
+ * Judged from the build *script*, never from `dist/` on disk: a clean checkout
+ * has no dist/ and a stale one has whatever the last build left, so neither
+ * answers the question. Git is what separates the two kinds of path a contract
+ * may name — a tracked `./tooling/preset.mjs` ships as committed source and
+ * needs no build, while an untracked `./dist/index.cjs` has to come out of
+ * `build` or it will not exist at publish time.
+ *
+ * This overlaps publint, which the generated `verify` already runs — but not in
+ * time. publint fires at release, against a dist/ just built on a machine where
+ * it happens to work; this fires at setup/doctor time, on a checkout, before
+ * anything is built.
+ */
+export async function checkExportsBuildable(dir, pkg, exec) {
+    const check = 'Exports buildable';
+    if (!pkg || !isPublishableLibrary(pkg)) {
+        return { check, status: 'ok', detail: 'not applicable (private or no published exports)' };
+    }
+    const scripts = pkg.scripts ?? {};
+    const build = scripts.build;
+    if (!build) {
+        return { check, status: 'ok', detail: 'no build script — nothing is expected to be generated' };
+    }
+    const emitted = emittedExtensions(scripts, build);
+    if (!emitted) {
+        return {
+            check,
+            status: 'ok',
+            detail: `not checked — cannot infer what \`${build}\` emits (recognised: ${Object.keys(BUILD_EMITS).join(', ')})`,
+        };
+    }
+    const declared = declaredEntryPoints(pkg).filter((p) => artefactExtension(p));
+    if (declared.length === 0) {
+        return { check, status: 'ok', detail: 'no JS entry points named in main/module/types/exports' };
+    }
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        return {
+            check,
+            status: 'ok',
+            detail: 'not checked — not a git repository, so committed assets and build output are indistinguishable',
+        };
+    }
+    // Declared paths are `./dist/index.js`; git speaks `dist/index.js`.
+    const declaredByPath = new Map(declared.map((p) => [p.replace(/^\.\//, ''), p]));
+    const git = exec ?? ((args) => realGitExec(args, dir));
+    // One call answers both questions: which declared paths are committed, and
+    // whether the repo has .cts/.mts sources. Every argument is a pathspec behind
+    // `--`, so a package.json path beginning with `-` cannot become a flag.
+    const listed = await git(['ls-files', '-z', '--', ...declaredByPath.keys(), '*.cts', '*.mts']);
+    if (listed === null) {
+        return { check, status: 'ok', detail: 'not checked — `git ls-files` is unavailable here' };
+    }
+    const tracked = new Set(listed.split('\0').filter(Boolean));
+    const unbuildable = [...declaredByPath]
+        .filter(([bare]) => !tracked.has(bare))
+        .map(([, declaredPath]) => declaredPath)
+        .filter((p) => !emitted.includes(artefactExtension(p)));
+    if (unbuildable.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `every declared entry point is committed or emitted by \`${build}\``,
+        };
+    }
+    // tsc emits .cjs/.d.cts from a .cts input, so its narrow BUILD_EMITS entry is
+    // wrong for a repo that has any. Checked last, and only when there is
+    // something to report, so the common repo pays nothing for it.
+    if ([...tracked].some((p) => !declaredByPath.has(p) && /\.[cm]ts$/.test(p))) {
+        return {
+            check,
+            status: 'ok',
+            detail: 'not checked — repo has .cts/.mts sources, whose emitted extensions this cannot infer',
+        };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `\`${build}\` emits ${emitted.join(', ')}; package.json names ${unbuildable.length} entry point(s) nothing produces: ${unbuildable.join(', ')}`,
+        hint: 'The published package will 404 on those paths. Either point `build` at a bundler that emits those formats (tsup with `format: ["cjs", "esm"]`), or narrow main/module/exports to the formats the current build produces. No autofix — both directions are valid and only the package author knows which one it promises.',
+    };
+}
 /** Who this package's README badges are for — feeds the base badge check (#309). */
 export function jsBadgeAudience(pkg) {
     if (!pkg || pkg.private === true)

package/dist/languages/swift/checks.js

@@ -16,6 +16,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { checkFile } from '../../base/checks.js';
+import { parsePackageSwift } from './ci.js';
 import { SWIFT_HOOKS_DIR } from './git-hooks.js';
 const SWIFT_FILE_CHECKS = [
     {
@@ -118,19 +119,82 @@ export async function checkPackageSwift(dir) {
         detail: `Package.swift declares tools ${toolsVersion} and explicit platforms`,
     };
 }
+/** Subdirectory names of `<dir>/<root>`, or none when that root doesn't exist. */
+async function subdirectories(dir, root) {
+    try {
+        const entries = await fs.readdir(path.join(dir, root), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * 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);
+    return subdirectories(dir, 'Sources');
+}
+/** Where SwiftPM looks for a target's sources when the manifest gives no `path:`. */
+const TARGET_ROOTS = ['Sources', 'Tests'];
+/**
+ * Sources that belong to no declared target (#575). SwiftPM silently ignores a
+ * directory under `Sources/` that no `.target(` names — so `swift build` and
+ * `swift test` both exit 0 while the code in it is never compiled and the tests
+ * in it are never run. There is no red X anywhere, which is the whole reason
+ * this check exists: a renamed target, a dropped `.target(...)` line, or a
+ * generator that rewrote the manifest all leave the same invisible hole.
+ *
+ * No fixer: repairing it means either adding a target or deleting the
+ * directory, and nothing outside the project can tell which.
+ */
+export async function checkSwiftTargets(dir) {
+    const check = 'Swift targets';
+    const filepath = path.join(dir, 'Package.swift');
+    if (!(await fs.pathExists(filepath))) {
+        return { check, status: 'missing', detail: 'no Package.swift' };
     }
-    catch {
-        return [];
+    const contents = await fs.readFile(filepath, 'utf-8');
+    // A custom `path:` puts a target's sources anywhere, so directory names stop
+    // meaning target names and every comparison below becomes a guess. Bail out
+    // rather than report something we can't stand behind. Deliberately crude:
+    // `.package(path:)` for a local dependency trips this too, which costs a
+    // skipped check on repos that use one — cheaper than a false accusation.
+    if (/\bpath:\s*"/.test(contents)) {
+        return {
+            check,
+            status: 'ok',
+            detail: 'not checked — Package.swift uses a custom `path:`, so directories need not match targets',
+        };
     }
+    const declared = new Set(parsePackageSwift(contents).targets);
+    const orphans = [];
+    let scanned = 0;
+    for (const root of TARGET_ROOTS) {
+        for (const name of await subdirectories(dir, root)) {
+            scanned++;
+            if (!declared.has(name))
+                orphans.push(`${root}/${name}`);
+        }
+    }
+    if (scanned === 0) {
+        return { check, status: 'ok', detail: 'no directories under Sources/ or Tests/' };
+    }
+    if (orphans.length > 0) {
+        return {
+            check,
+            status: 'drift',
+            detail: `no target declares ${orphans.join(', ')} — SwiftPM ignores them, so \`swift build\` passes without building them`,
+            hint: `Add a target named after each directory to Package.swift, or delete the directory: ${orphans.join(', ')}`,
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `all ${scanned} source directories are declared as targets`,
+    };
 }
 async function findDoccCatalogue(dir) {
     for (const target of await swiftSourceTargets(dir)) {
@@ -270,6 +334,7 @@ export async function runSwiftChecks(dir) {
         await checkPackageSwift(dir),
         ...(await Promise.all(SWIFT_FILE_CHECKS.map((spec) => checkFile(dir, spec)))),
         await checkSwiftGitignore(dir),
+        await checkSwiftTargets(dir),
         await checkSwiftTests(dir),
         await checkDocC(dir),
         await checkSwiftRelease(dir),

package/dist/languages/swift/ci.js

@@ -13,23 +13,38 @@ import { renderGitHubWorkflow, renderGitLabCI } from '../../base/ci.js';
 /** SwiftPM runs on macOS runners — Xcode isn't available anywhere else. */
 const MACOS = 'macos-latest';
 /**
- * Pull the two facts CI needs out of a Package.swift. A regex rather than a
- * SwiftPM invocation: `swift package dump-package` would need a Swift toolchain
- * on the machine running `repo-tooling`, which is usually a Node environment.
+ * Every SwiftPM target factory. `name:` is their first parameter and Swift
+ * enforces argument order, so a literal name always follows the open paren.
+ * `binaryTarget` owns no source directory but is matched anyway: the only
+ * consumer uses this set to *suppress* a report, so over-matching costs a
+ * missed finding while under-matching costs a false one.
+ */
+const TARGET_DECL = /\.(?:target|executableTarget|testTarget|macro|plugin|systemLibrary|binaryTarget)\(\s*name:\s*"([^"]+)"/g;
+/**
+ * Pull the facts doctor and CI need out of a Package.swift. A regex rather than
+ * a SwiftPM invocation: `swift package dump-package` would need a Swift
+ * toolchain on the machine running `repo-tooling`, which is usually a Node
+ * environment.
+ *
+ * ponytail: literal string arguments only. A manifest that builds its target
+ * list in a loop, behind `#if`, or from a variable parses as fewer targets than
+ * it declares — callers that act on the result must fail open. Upgrade path is
+ * `swift package dump-package` on a machine that has Swift.
  */
 export function parsePackageSwift(contents) {
     const products = [...contents.matchAll(/\.library\(\s*name:\s*"([^"]+)"/g)].map((m) => m[1]);
+    const targets = [...contents.matchAll(TARGET_DECL)].map((m) => m[1]);
     // Only the `platforms:` array declares deployment targets — matching
     // `.iOS(` across the whole manifest would also catch `.iOS` in target
     // conditionals.
     const platformsClause = contents.match(/platforms:\s*\[([^\]]*)\]/s)?.[1] ?? '';
     const platforms = [...platformsClause.matchAll(/\.(iOS|macOS|tvOS|watchOS|visionOS)\s*\(/g)].map((m) => m[1]);
-    return { products, platforms: [...new Set(platforms)] };
+    return { products, platforms: [...new Set(platforms)], targets };
 }
 export async function readSwiftPackage(dir) {
     const filepath = path.join(dir, 'Package.swift');
     if (!(await fs.pathExists(filepath)))
-        return { products: [], platforms: [] };
+        return { products: [], platforms: [], targets: [] };
     return parsePackageSwift(await fs.readFile(filepath, 'utf-8'));
 }
 /** Checkout + pin Xcode. Every Swift job needs both before it can do anything. */

package/package.json

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