@rtorcato/repo-tooling 3.6.0 → 3.7.0

package/AGENTS.md

@@ -6,7 +6,7 @@ Orientation for coding agents working with `@rtorcato/repo-tooling`. Human-reada
 
 A one-package JavaScript / TypeScript tooling distribution. Ships every preset (TypeScript, Biome, ESLint, Prettier, Vitest, Jest, Commitlint, semantic-release, tsup, esbuild, Vite, Playwright) plus a CLI to scaffold and audit projects. Consumers get one install.
 
-**Swift** repos (detected via `Package.swift`) are covered end to end: `setup --preset swift-library` scaffolds a SwiftPM package, and `doctor`/`fix` run the language-agnostic checks plus SwiftLint / Periphery / `.gitignore` / `Package.swift`. **Python** repos (detected via `pyproject.toml` / `setup.py`) get `doctor`/`fix` — Ruff / mypy / pytest / `.gitignore` / CI / git hooks — but no `setup` preset yet. Perl is audit-only for now. See `src/languages/` — one directory per language module, `src/base/` for what's shared.
+**Swift** repos (detected via `Package.swift`) are covered end to end: `setup --preset swift-library` scaffolds a SwiftPM package, and `doctor`/`fix` run the language-agnostic checks plus SwiftLint / Periphery / `.gitignore` / `Package.swift`. **Python** repos (detected via `pyproject.toml` / `setup.py`) get `doctor`/`fix` — Ruff / mypy / pytest / `.gitignore` / CI / git hooks — but no `setup` preset yet. **Perl** distributions (detected via `cpanfile` / `Makefile.PL` / `dist.ini`) get the same deal: Perl::Critic / perltidy / `.gitignore` / CI / git hooks, no `setup` preset. See `src/languages/` — one directory per language module, `src/base/` for what's shared.
 
 ## CLI surface (agent-friendly)
 

package/dist/base/checks.js

@@ -233,7 +233,21 @@ export async function checkDependabot(dir) {
         hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` (or `fix renovate`) to scaffold weekly dep updates',
     };
 }
-export async function checkCodeQL(dir) {
+/**
+ * `languages` is the detected module's `codeqlLanguages`. An empty list means
+ * CodeQL ships no analyzer for this language at all (Perl, #289) — reporting it
+ * as missing would send the user to `fix codeql`, whose generator correctly
+ * writes nothing for an empty matrix, so they'd get a silent no-op and a check
+ * that never goes green.
+ */
+export async function checkCodeQL(dir, languages) {
+    if (languages.length === 0) {
+        return {
+            check: 'CodeQL',
+            status: 'ok',
+            detail: 'not applicable — CodeQL has no analyzer for this language',
+        };
+    }
     const workflowsDir = path.join(dir, '.github', 'workflows');
     if (!(await fs.pathExists(workflowsDir))) {
         return {

package/dist/base/fixers.js

@@ -11,6 +11,7 @@
  * language-shaped (CI steps, recorded tool choices), so each module ships its
  * own — see src/base/ci.ts for the shell they share.
  */
+import chalk from 'chalk';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
@@ -78,7 +79,14 @@ export const BASE_FIXERS = [
         appliesTo: ['CodeQL'],
         outputs: ['.github/workflows/codeql.yml'],
         async run({ targetDir }) {
-            const { codeqlLanguages } = await moduleFor(targetDir);
+            const { codeqlLanguages, label } = await moduleFor(targetDir);
+            // Say so rather than reporting a successful fix that wrote nothing: the
+            // generator correctly emits no workflow for an empty matrix (Perl, #289),
+            // and a silent no-op reads as "done".
+            if (codeqlLanguages.length === 0) {
+                console.error(chalk.yellow(`   skipped — CodeQL has no ${label} analyzer`));
+                return { filesWritten: [] };
+            }
             return { filesWritten: await generateCodeQLWorkflow(targetDir, codeqlLanguages) };
         },
     },

package/dist/cli/commands/doctor.js

@@ -4,6 +4,8 @@ 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 { PERL_GIT_HOOKS, runPerlChecks } from '../../languages/perl/checks.js';
+import { readPerlProject, renderPerlWorkflow } from '../../languages/perl/ci.js';
 import { PYTHON_GIT_HOOKS, runPythonChecks } from '../../languages/python/checks.js';
 import { readPyproject, renderPythonWorkflow } from '../../languages/python/ci.js';
 import { resolveLanguageModule } from '../../languages/registry.js';
@@ -157,7 +159,7 @@ async function runBaseChecks(dir, lock, opts) {
     }
     results.push(await checkGitHubActions(dir, opts.presetWorkflow));
     results.push(await checkDependabot(dir));
-    results.push(await checkCodeQL(dir));
+    results.push(await checkCodeQL(dir, opts.codeqlLanguages));
     // GitHub repo-settings drift (branch protection, merge settings, workflow
     // permissions). Read-only; self-skips as `ok` outside a live GitHub repo.
     results.push(...(await checkGitHubSettings(dir)));
@@ -174,12 +176,14 @@ export async function runDoctor(dir) {
     const lock = await readLockfile(targetDir);
     // Per-module dispatch (#285): the base checks (repo hygiene, CI, security,
     // GitHub settings) apply to any repo and run for every language. A supported
-    // module layers its own checks on top; an unsupported one (Perl, until #289)
-    // still gets the full base suite instead of the old wholesale skip.
-    // 'unknown' (bare dir mid-setup) resolves to JS so a fresh repo runs the
-    // full suite.
+    // module layers its own checks on top. 'unknown' (bare dir mid-setup)
+    // resolves to JS so a fresh repo runs the full suite.
     const language = await detectLanguage(targetDir);
     const languageModule = resolveLanguageModule(language);
+    // Every language in the registry has a module as of #289, so nothing reaches
+    // this today. It stays as the on-ramp: a language is added to the registry
+    // with `supported: false` first, and until its module lands its repos get the
+    // full base suite rather than the wholesale skip this replaced.
     if (!languageModule.supported) {
         const results = [
             {
@@ -187,14 +191,14 @@ export async function runDoctor(dir) {
                 status: 'ok',
                 detail: `detected ${languageModule.label} — running language-agnostic checks; ${languageModule.label}-specific checks land with its module (#139)`,
             },
-            // hooks: null — nothing here encodes a Perl hook convention yet, and
-            // guessing one would nag every repo with a fix target that doesn't
-            // exist. #289 fills it in.
+            // hooks: null — guessing a hook convention would nag every repo with a
+            // fix target that doesn't exist.
             ...(await runBaseChecks(targetDir, lock, {
                 hooks: null,
                 badges: { audience: 'public', fixTarget: null },
                 presetWorkflow: null,
                 language,
+                codeqlLanguages: languageModule.codeqlLanguages,
             })),
         ];
         return demoteDeclined(results, lock);
@@ -216,6 +220,7 @@ export async function runDoctor(dir) {
                 badges: { audience: 'public', fixTarget: null },
                 presetWorkflow: renderSwiftWorkflow(await readSwiftPackage(targetDir)),
                 language,
+                codeqlLanguages: languageModule.codeqlLanguages,
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
@@ -238,11 +243,37 @@ export async function runDoctor(dir) {
                 badges: { audience: 'public', fixTarget: null },
                 presetWorkflow: renderPythonWorkflow(await readPyproject(targetDir)),
                 language,
+                codeqlLanguages: languageModule.codeqlLanguages,
             })),
             ...(await runPythonChecks(targetDir)),
         ];
         return demoteDeclined(results, lock);
     }
+    // Perl suite (#289): same shape as Swift and Python — base checks plus the
+    // module's own, and nothing JS-shaped, because a distribution has no
+    // package.json. CodeQL self-reports as not applicable: it ships no Perl
+    // analyzer, which `codeqlLanguages: []` in the registry encodes.
+    if (languageModule.id === 'perl') {
+        const results = [
+            {
+                check: 'language',
+                status: 'ok',
+                detail: 'detected Perl (cpanfile / Makefile.PL / dist.ini)',
+            },
+            ...(await runBaseChecks(targetDir, lock, {
+                hooks: PERL_GIT_HOOKS,
+                // A distribution released to CPAN is public by definition, so badges
+                // apply. No fixer: `fix badges` derives the block from package.json
+                // name and repository, which a Perl repo hasn't got.
+                badges: { audience: 'public', fixTarget: null },
+                presetWorkflow: renderPerlWorkflow(await readPerlProject(targetDir)),
+                language,
+                codeqlLanguages: languageModule.codeqlLanguages,
+            })),
+            ...(await runPerlChecks(targetDir)),
+        ];
+        return demoteDeclined(results, lock);
+    }
     // JS suite: the module's own checks, then the shared base ones. Only the
     // JS-shaped checks are listed here — re-listing the base suite is what made
     // any new base check silently skip JS repos (#309).
@@ -289,6 +320,7 @@ export async function runDoctor(dir) {
         badges: { audience: jsBadgeAudience(pkg), fixTarget: 'badges' },
         presetWorkflow: renderGitHubWorkflow(githubJobs(inferProjectConfig(pkg))),
         language,
+        codeqlLanguages: languageModule.codeqlLanguages,
     })));
     return demoteDeclined(results, lock);
 }

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

@@ -79,9 +79,24 @@ const PYTHON_FIX_TARGETS = {
     // (package metadata, actual tests). Their own hints say what to add.
     // `lockfile` too — see the note at the top of src/languages/python/fixers.ts.
 };
+/** The same shadowing for the Perl module (#289). */
+const PERL_FIX_TARGETS = {
+    'Git hooks': 'perl-git-hooks',
+    'Pre-push hook': 'perl-git-hooks',
+    'GitHub Actions': 'perl-ci',
+    'GitLab CI': 'perl-gitlab-ci',
+    'Perl::Critic': 'perlcritic',
+    perltidy: 'perltidy',
+    'Perl .gitignore': 'perl-gitignore',
+    // `Perl distribution` and `Perl tests` are deliberately absent, for the same
+    // reason `Swift tests` is: the fix is content only the project can write
+    // (dependency metadata, actual tests). Their own hints say what to add.
+    // `lockfile` too — see the note at the top of src/languages/perl/fixers.ts.
+};
 const FIX_TARGETS_BY_LANGUAGE = {
     swift: SWIFT_FIX_TARGETS,
     python: PYTHON_FIX_TARGETS,
+    perl: PERL_FIX_TARGETS,
 };
 export function getFixTargetForCheck(checkName, language) {
     const overrides = language ? FIX_TARGETS_BY_LANGUAGE[language] : undefined;
@@ -186,6 +201,7 @@ export function lockfilePatchForTarget(target, lock) {
         case 'husky':
         case 'swift-git-hooks':
         case 'python-git-hooks':
+        case 'perl-git-hooks':
             return c.gitHooks ? null : { gitHooks: true };
         case 'semantic-release':
         case 'swift-release':

package/dist/cli/commands/fix.js

@@ -11,13 +11,15 @@ import { declinedInLock, lockfilePatchForTarget } from './fix-targets.js';
 import { computeFileList } from './setup-presets.js';
 import { BASE_FIXERS } from '../../base/fixers.js';
 import { FIXERS, readPackageJson } from '../../languages/js/fixers.js';
+import { PERL_FIXERS } from '../../languages/perl/fixers.js';
 import { PYTHON_FIXERS } from '../../languages/python/fixers.js';
 import { SWIFT_FIXERS } from '../../languages/swift/fixers.js';
 import { detectLanguage } from '../utils/detect-language.js';
-/** The module-specific fixer set per detected language (#286, #290, #303). */
+/** The module-specific fixer set per detected language (#286, #289, #290, #303). */
 const LANGUAGE_FIXERS = {
     swift: SWIFT_FIXERS,
     python: PYTHON_FIXERS,
+    perl: PERL_FIXERS,
 };
 /**
  * The fixers that apply to a repo, by detected language: the language-agnostic
@@ -28,7 +30,13 @@ function fixersForLanguage(language) {
     return [...BASE_FIXERS, ...(LANGUAGE_FIXERS[language] ?? FIXERS)];
 }
 /** Every fixer across every language — for `--list` and the unknown-target hint. */
-const ALL_FIXERS = [...BASE_FIXERS, ...FIXERS, ...SWIFT_FIXERS, ...PYTHON_FIXERS];
+const ALL_FIXERS = [
+    ...BASE_FIXERS,
+    ...FIXERS,
+    ...SWIFT_FIXERS,
+    ...PYTHON_FIXERS,
+    ...PERL_FIXERS,
+];
 export function getFixers() {
     return ALL_FIXERS;
 }

package/dist/cli/index.js

@@ -269,6 +269,18 @@ const TOOL_CATALOG = [
         exports: [],
         fixTarget: 'pytest',
     },
+    {
+        name: 'Perl::Critic',
+        description: 'Perl linter configuration (severity 3, with the family rule exceptions)',
+        exports: [],
+        fixTarget: 'perlcritic',
+    },
+    {
+        name: 'perltidy',
+        description: 'Perl formatter configuration (Perl Best Practices layout at 100 columns)',
+        exports: [],
+        fixTarget: 'perltidy',
+    },
     {
         name: 'AI Agent Setup',
         description: 'Scaffold AGENTS.md, CLAUDE.md, Cursor/Copilot rules, Claude skill, MCP example',

package/dist/cli/utils/copy-preset.js

@@ -66,6 +66,16 @@ export const PRESETS = {
         target: 'pytest.ini',
         desc: 'pytest configuration (strict markers and config, warnings as errors)',
     },
+    perlcritic: {
+        source: 'tooling/perl/perlcriticrc',
+        target: '.perlcriticrc',
+        desc: 'Perl::Critic configuration (severity 3, with the family rule exceptions)',
+    },
+    perltidy: {
+        source: 'tooling/perl/perltidyrc',
+        target: '.perltidyrc',
+        desc: 'perltidy configuration (Perl Best Practices layout at 100 columns)',
+    },
     'claude-skill': {
         source: 'tooling/claude/repo-tooling.md',
         target: '.claude/skills/repo-tooling.md',

package/dist/languages/perl/checks.js

@@ -0,0 +1,177 @@
+/**
+ * Perl language module — checks (#289), on the same template as Swift (#286)
+ * and Python (#290).
+ *
+ * The standard encoded here is Perl::Critic (lint) and perltidy (format), with
+ * prove/Test::More as the runner. Deliberately *not* checked:
+ *
+ * - **A `pre-commit` framework config** — the hooks in `./git-hooks.ts` call
+ *   the tools directly, exactly as CI does, rather than adding a second config
+ *   file and a second pinned-tool source to keep in sync.
+ * - **`Perl::Tidy` as a lint rule** (`CodeLayout::RequireTidyCode`) — running
+ *   the formatter from inside the linter reports "this file is untidy" without
+ *   saying how, and it makes a perlcritic run depend on perltidy being
+ *   installed. The CI job runs perltidy directly and shows the diff instead.
+ * - **A pinned interpreter file** — the floor is declared once in the
+ *   distribution's metadata, and CI derives its matrix from that. A root file
+ *   would be a second place to keep in sync.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { checkFile } from '../../base/checks.js';
+import { PERL_METADATA_FILES, declaredPerlFloor, readPerlMetadata } from './ci.js';
+import { PERL_HOOKS_DIR } from './git-hooks.js';
+import { PERL_GITIGNORE_SENTINELS } from './gitignore.js';
+const PERL_FILE_CHECKS = [
+    {
+        check: 'Perl::Critic',
+        // Both spellings are read by perlcritic; the dotted one is conventional.
+        candidates: ['.perlcriticrc', 'perlcriticrc'],
+        expected: 'is a valid Perl::Critic configuration',
+        // A `severity`/`verbose`-style setting, or a `[Policy::Name]` block.
+        matcher: /^\s*(severity|verbose|theme|only|include|exclude|profile-strictness)\s*=|^\s*\[[-\w:]+\]/m,
+        hint: 'Run `npx @rtorcato/repo-tooling fix perlcritic` to scaffold',
+    },
+    {
+        check: 'perltidy',
+        candidates: ['.perltidyrc', 'perltidyrc'],
+        expected: 'is a valid perltidy configuration',
+        // perltidyrc is a list of command-line switches, one per line.
+        matcher: /^\s*-{1,2}[a-zA-Z]/m,
+        hint: 'Run `npx @rtorcato/repo-tooling fix perltidy` to scaffold',
+    },
+];
+/**
+ * Distribution metadata, the Perl shape of the `Package.swift` and
+ * `pyproject.toml` checks. Both signals are things no tool infers for you:
+ * without a metadata file there is nothing for cpanm to resolve dependencies
+ * from, and without a declared perl floor cpanm installs the distribution on
+ * an interpreter that cannot compile it — the failure lands on the user, at
+ * `use` time, as a syntax error rather than a version complaint.
+ */
+export async function checkPerlDistribution(dir) {
+    const check = 'Perl distribution';
+    const metadata = await readPerlMetadata(dir);
+    if (!metadata) {
+        return {
+            check,
+            status: 'missing',
+            detail: `no ${PERL_METADATA_FILES.join(' / ')}`,
+            hint: "Add a `cpanfile` declaring the distribution's dependencies — `requires 'perl', '5.036';` at minimum",
+        };
+    }
+    const floor = declaredPerlFloor(metadata.contents);
+    if (!floor) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${metadata.file} declares no minimum perl version`,
+            hint: metadata.file === 'cpanfile'
+                ? "Add `requires 'perl', '5.036';` — without it cpanm installs on interpreters that cannot compile the code"
+                : 'Declare a minimum perl (`MIN_PERL_VERSION` in Makefile.PL, `perl` under [Prereqs] in dist.ini) — without it cpanm installs on interpreters that cannot compile the code',
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `${metadata.file} declares a minimum perl of ${floor}`,
+    };
+}
+export async function checkPerlGitignore(dir) {
+    const check = 'Perl .gitignore';
+    const filepath = path.join(dir, '.gitignore');
+    if (!(await fs.pathExists(filepath))) {
+        return {
+            check,
+            status: 'missing',
+            detail: 'no .gitignore',
+            hint: 'Run `npx @rtorcato/repo-tooling fix perl-gitignore` to scaffold the Perl template',
+        };
+    }
+    const contents = await fs.readFile(filepath, 'utf-8');
+    const missing = PERL_GITIGNORE_SENTINELS.filter((entry) => !contents.includes(entry));
+    if (missing.length > 0) {
+        return {
+            check,
+            status: 'drift',
+            detail: `.gitignore missing Perl build artefacts: ${missing.join(', ')}`,
+            hint: 'Run `npx @rtorcato/repo-tooling fix perl-gitignore` to append the missing entries',
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `.gitignore covers ${PERL_GITIGNORE_SENTINELS.join(', ')}`,
+    };
+}
+/** CI files that could be running the test suite, most likely first. */
+async function ciFiles(dir) {
+    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)));
+    }
+    return candidates;
+}
+/**
+ * The test setup. Same two halves as the Swift and Python versions: a suite has
+ * to exist, and CI has to run it. `t/` is the universal convention — prove and
+ * every build system default to it — so unlike Python there is no second layout
+ * to look for. `xt/` counts too: author tests are still tests.
+ */
+export async function checkPerlTests(dir) {
+    const check = 'Perl tests';
+    let tests = null;
+    for (const candidate of ['t', 'xt']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            tests = `${candidate}/`;
+            break;
+        }
+    }
+    if (!tests) {
+        return {
+            check,
+            status: 'missing',
+            detail: 'no t/ directory',
+            hint: 'Add a `t/` directory of `.t` files — `prove -lr t` is what CI runs',
+        };
+    }
+    for (const candidate of await ciFiles(dir)) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        // `prove` is the harness; `make test` / `dzil test` are the build systems'
+        // wrappers around the same thing, and all three count as running the suite.
+        if (/\b(prove|make test|dzil test)\b/.test(await fs.readFile(filepath, 'utf-8'))) {
+            return { check, status: 'ok', detail: `${tests} found and run by ${candidate}` };
+        }
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `${tests} found but no CI job runs the test suite`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix perl-ci` to regenerate a workflow that runs `prove`',
+    };
+}
+/**
+ * The Perl shape of the base `Git hooks` / `Pre-push hook` checks (#309).
+ * `install` is null for the same reason Swift's and Python's are: the wiring —
+ * `git config core.hooksPath` — is per-clone local state that nothing commits,
+ * so flagging its absence would fail every fresh CI checkout.
+ */
+export const PERL_GIT_HOOKS = {
+    dir: PERL_HOOKS_DIR,
+    install: null,
+    verifyCommand: 'prove -lr t',
+    fixTarget: 'perl-git-hooks',
+};
+/** The Perl module's suite, layered on top of the base checks by doctor. */
+export async function runPerlChecks(dir) {
+    return [
+        await checkPerlDistribution(dir),
+        ...(await Promise.all(PERL_FILE_CHECKS.map((spec) => checkFile(dir, spec)))),
+        await checkPerlGitignore(dir),
+        await checkPerlTests(dir),
+    ];
+}

package/dist/languages/perl/ci.js

@@ -0,0 +1,191 @@
+/**
+ * Perl CI generation (#289), built on the language-agnostic skeleton in
+ * `src/base/ci.ts`. No `setup-node`, no `pnpm` — the Perl path runs on Linux
+ * with `shogo82148/actions-setup-perl` and cpanm.
+ *
+ * Like the Swift and Python paths there's no `ProjectConfig` to read: the one
+ * fact CI needs beyond the fixed job shapes — which interpreters to test on —
+ * is declared in the distribution's own metadata, so the matrix is derived
+ * from the repo itself.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { renderGitHubWorkflow, renderGitLabCI } from '../../base/ci.js';
+import { FIND_PERL_SOURCES } from './sources.js';
+/**
+ * The newest interpreter the emitted matrix tests against, and the one the
+ * single-interpreter lint job runs on.
+ *
+ * ponytail: a constant, bumped by hand when perl ships a stable minor (they
+ * land roughly annually, even minors only). Resolving "latest" at generation
+ * time would need a network call from a generator whose whole job is emitting
+ * text.
+ */
+const LATEST_PERL = '5.42';
+/**
+ * The oldest interpreter to assume when the distribution declares no floor.
+ * Debian stable's perl — the oldest one a consumer is actually likely to be
+ * running, as opposed to the oldest one still theoretically supported.
+ */
+const DEFAULT_FLOOR = '5.36';
+const minorOf = (version) => Number.parseInt(version.split('.')[1] ?? '0', 10);
+/**
+ * Normalise any of the forms a perl version is written in to `major.minor`.
+ *
+ * Perl has three spellings of the same thing and metadata files use all of
+ * them: `5.36`, the v-string `v5.36.0`, and the *packed decimal* `5.036000`,
+ * where the minor is the first three digits after the point. Parsed naively,
+ * that last one reads as minor 36000 — which would emit a matrix entry for a
+ * perl that does not exist and fail every run.
+ */
+export function normalizePerlVersion(raw) {
+    const match = /^v?(\d+)\.(\d+)/.exec(raw.trim());
+    if (!match?.[1] || !match[2])
+        return null;
+    const [, major, fraction] = match;
+    // 3+ digits means the packed form (5.036000 → 5.36); fewer is already plain.
+    const minor = fraction.length >= 3 ? Number.parseInt(fraction.slice(0, 3), 10) : Number.parseInt(fraction, 10);
+    return `${major}.${minor}`;
+}
+/**
+ * The declared minimum perl, or null when the distribution names none.
+ *
+ * A regex rather than parsing Perl: `cpanfile`, `Makefile.PL` and `Build.PL`
+ * are all *executable Perl*, so reading them properly means running arbitrary
+ * code from the audited repo — which `doctor` must never do. This is one key.
+ */
+export function declaredPerlFloor(contents) {
+    const raw = 
+    // cpanfile: `requires 'perl', '5.036';` / `requires 'perl' => '5.036000';`
+    /requires\s*\(?\s*['"]perl['"]\s*(?:,|=>)\s*['"]?v?([\d._]+)/.exec(contents)?.[1] ??
+        // Makefile.PL: `MIN_PERL_VERSION => '5.036'`
+        /MIN_PERL_VERSION\s*=>\s*['"]?v?([\d._]+)/.exec(contents)?.[1] ??
+        // Build.PL: `requires => { perl => '5.036' }`
+        /\bperl\s*=>\s*['"]?v?([\d._]+)/.exec(contents)?.[1] ??
+        // dist.ini: `perl = 5.036` under [Prereqs]
+        /^\s*perl\s*=\s*['"]?v?([\d._]+)/m.exec(contents)?.[1];
+    return raw ? normalizePerlVersion(raw) : null;
+}
+export function parsePerlProject(contents) {
+    const floor = declaredPerlFloor(contents) ?? DEFAULT_FLOOR;
+    // A floor at or above the newest release we know about collapses the matrix
+    // to one entry rather than emitting a version that doesn't exist yet.
+    const versions = minorOf(floor) >= minorOf(LATEST_PERL) ? [floor] : [floor, LATEST_PERL];
+    return { perlVersions: versions };
+}
+/**
+ * Files that can carry a distribution's metadata, most authoritative first.
+ * `cpanfile` is the modern one; the `.PL` scripts are the older build systems,
+ * and `dist.ini` is Dist::Zilla, which generates the others at release time.
+ */
+export const PERL_METADATA_FILES = ['cpanfile', 'Makefile.PL', 'Build.PL', 'dist.ini'];
+/** The first metadata file present, with its contents. Null when none exists. */
+export async function readPerlMetadata(dir) {
+    for (const file of PERL_METADATA_FILES) {
+        const filepath = path.join(dir, file);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        return { file, contents: await fs.readFile(filepath, 'utf-8') };
+    }
+    return null;
+}
+export async function readPerlProject(dir) {
+    const metadata = await readPerlMetadata(dir);
+    if (!metadata)
+        return { perlVersions: [DEFAULT_FLOOR, LATEST_PERL] };
+    return parsePerlProject(metadata.contents);
+}
+/** Checkout + interpreter. cpanm comes from the setup action, not a separate step. */
+function perlSetup(version) {
+    return `      - name: 📦 Checkout repository
+        uses: actions/checkout@v7
+
+      - name: 🐪 Set up Perl ${version}
+        uses: shogo82148/actions-setup-perl@v1
+        with:
+          perl-version: '${version}'
+          install-modules-with: cpanm`;
+}
+export function perlGithubJobs(project) {
+    return [
+        {
+            id: 'lint',
+            // Perl::Critic is static, so the distribution's own dependencies are not
+            // installed here — the lint job stays fast and can't fail on a CPAN
+            // mirror hiccup that has nothing to do with the code.
+            steps: `${perlSetup(LATEST_PERL)}
+
+      - name: 📦 Install Perl::Critic and Perl::Tidy
+        run: cpanm --notest Perl::Critic Perl::Tidy
+
+      - name: 🔍 perlcritic
+        # A block scalar, not a plain one: the find expression carries quotes,
+        # parentheses and braces that a plain YAML scalar would make fragile.
+        run: |
+          ${FIND_PERL_SOURCES} -exec perlcritic {} +
+
+      - name: 🎨 perltidy --check
+        # perltidy has no non-rewriting check mode that reports *which* files
+        # are untidy, so this tidies in place and lets git report the delta.
+        # The diff in the log is the fix, ready to apply.
+        run: |
+          ${FIND_PERL_SOURCES} -exec perltidy -b -bext='/' {} +
+          git diff --exit-code`,
+        },
+        {
+            id: 'test',
+            extra: `    name: prove \${{ matrix.perl-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        perl-version:
+${project.perlVersions.map((v) => `          - '${v}'`).join('\n')}`,
+            steps: `      - name: 📦 Checkout repository
+        uses: actions/checkout@v7
+
+      - name: 🐪 Set up Perl \${{ matrix.perl-version }}
+        uses: shogo82148/actions-setup-perl@v1
+        with:
+          perl-version: \${{ matrix.perl-version }}
+          install-modules-with: cpanm
+
+      - name: 📦 Install dependencies
+        run: cpanm --installdeps --notest .
+
+      - name: 🧪 prove
+        run: prove -lr t`,
+        },
+    ];
+}
+export function renderPerlWorkflow(project) {
+    return renderGitHubWorkflow(perlGithubJobs(project));
+}
+/**
+ * GitLab runs the same commands in the official Perl image. The matrix is
+ * dropped for the same reason Python's is: GitLab's `parallel:matrix` would
+ * need a per-job image override, and a mirrored repo is a secondary pipeline —
+ * the version sweep lives on the GitHub side.
+ */
+function perlGitlabSpec(project) {
+    const image = `perl:${project.perlVersions.at(-1) ?? LATEST_PERL}`;
+    return {
+        image,
+        preamble: `variables:
+  PERL_CPANM_OPT: "--notest"`,
+        jobs: [
+            {
+                id: 'lint',
+                stage: 'lint',
+                script: ['cpanm --notest Perl::Critic', `${FIND_PERL_SOURCES} -exec perlcritic {} +`],
+            },
+            {
+                id: 'test',
+                stage: 'test',
+                script: ['cpanm --installdeps --notest .', 'prove -lr t'],
+            },
+        ],
+    };
+}
+export function renderPerlGitLabCI(project) {
+    return renderGitLabCI(perlGitlabSpec(project));
+}

package/dist/languages/perl/fixers.js

@@ -0,0 +1,93 @@
+/**
+ * Perl language module — fixers (#289). One per check in ./checks.ts.
+ *
+ * ponytail: no `perl-lockfile` fixer, for the same reason the Python module has
+ * none (#290). Swift's writes the config `setup --preset swift-library` would
+ * have produced, and there is no `perl-library` preset. Inventing a
+ * ProjectConfig here would put a fabricated set of JS tool choices in a Perl
+ * distribution's lockfile — worse than doctor reporting it absent, which is
+ * true.
+ */
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { copyPreset } from '../../cli/utils/copy-preset.js';
+import { readPerlProject, renderPerlGitLabCI, renderPerlWorkflow } from './ci.js';
+import { PERL_HOOKS_DIR, installPerlGitHooks } from './git-hooks.js';
+import { ensurePerlGitignore } from './gitignore.js';
+export const PERL_FIXERS = [
+    {
+        target: 'perlcritic',
+        description: 'Scaffold .perlcriticrc (Perl::Critic at severity 3, with the family exceptions)',
+        appliesTo: ['Perl::Critic'],
+        outputs: ['.perlcriticrc'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('perlcritic', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'perltidy',
+        description: 'Scaffold .perltidyrc (Perl Best Practices layout at 100 columns)',
+        appliesTo: ['perltidy'],
+        outputs: ['.perltidyrc'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('perltidy', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'perl-gitignore',
+        description: 'Add the Perl build artefacts (blib, MYMETA.*, pm_to_blib, local/) to .gitignore',
+        appliesTo: ['Perl .gitignore'],
+        // Appends what's missing; never clobbers a project's own entries.
+        riskLevel: 'safe-merge',
+        outputs: ['.gitignore'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await ensurePerlGitignore(targetDir) };
+        },
+    },
+    {
+        target: 'perl-git-hooks',
+        description: `Scaffold ${PERL_HOOKS_DIR}/pre-commit + pre-push (perltidy, perlcritic, prove) and point git at them via core.hooksPath`,
+        appliesTo: ['Git hooks', 'Pre-push hook'],
+        outputs: [`${PERL_HOOKS_DIR}/pre-commit`, `${PERL_HOOKS_DIR}/pre-push`],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const { filesWritten, hooksPathSet } = await installPerlGitHooks(targetDir);
+            console.error(hooksPathSet
+                ? chalk.dim(`   git config core.hooksPath ${PERL_HOOKS_DIR}`)
+                : chalk.yellow(`   run \`git config core.hooksPath ${PERL_HOOKS_DIR}\` once per clone — it's local git config, not a committed file`));
+            return { filesWritten };
+        },
+    },
+    {
+        target: 'perl-ci',
+        description: 'Scaffold .github/workflows/ci.yml for Perl (perlcritic, perltidy, prove across the supported interpreters)',
+        appliesTo: ['GitHub Actions'],
+        outputs: ['.github/workflows/ci.yml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const workflowsDir = path.join(targetDir, '.github', 'workflows');
+            await fs.ensureDir(workflowsDir);
+            const workflow = renderPerlWorkflow(await readPerlProject(targetDir));
+            await fs.writeFile(path.join(workflowsDir, 'ci.yml'), workflow);
+            return { filesWritten: ['.github/workflows/ci.yml'] };
+        },
+    },
+    {
+        target: 'perl-gitlab-ci',
+        description: 'Scaffold .gitlab-ci.yml for Perl (perlcritic + prove on the official Perl image)',
+        appliesTo: ['GitLab CI'],
+        outputs: ['.gitlab-ci.yml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const ci = renderPerlGitLabCI(await readPerlProject(targetDir));
+            await fs.writeFile(path.join(targetDir, '.gitlab-ci.yml'), ci);
+            return { filesWritten: ['.gitlab-ci.yml'] };
+        },
+    },
+];

package/dist/languages/perl/git-hooks.js

@@ -0,0 +1,53 @@
+/**
+ * Perl git hooks (#289). Same shape as the Swift (#309) and Python (#290) ones
+ * and for the same reason: Husky is an npm package, and a Perl distribution has
+ * no node on the path to run it. The committed `.githooks/` directory plus
+ * `core.hooksPath` is the node-free equivalent; the mechanics live in
+ * `src/base/git-hooks.ts`.
+ *
+ * The hooks call perltidy/perlcritic/prove directly rather than going through
+ * `dzil` or a `Makefile` target — those exist only in some distributions, and a
+ * hook that assumes the wrong build system fails on every commit.
+ */
+import { installGitHooks } from '../../base/git-hooks.js';
+import { FIND_PERL_SOURCES } from './sources.js';
+export const PERL_HOOKS_DIR = '.githooks';
+/** Wraps the shared find expression so each hook can name the action once. */
+const FIND_PERL_FN = `# Every Perl source file in the distribution, minus build output and deps.
+find_perl() {
+  ${FIND_PERL_SOURCES} "$@"
+}`;
+// perltidy before perlcritic so the lint pass sees the final layout. The two
+// never fight, unlike SwiftLint/SwiftFormat or ruff/black: Perl::Critic only
+// reports, it never rewrites.
+//
+// `-b -bext='/'` means in-place with no backup file. Both flags are passed here
+// rather than baked into the shipped .perltidyrc, so a human running `perltidy
+// lib/Foo.pm` by hand still gets Foo.pm.tdy instead of a silent overwrite.
+const PERL_PRE_COMMIT = `#!/bin/sh
+set -e
+
+${FIND_PERL_FN}
+
+find_perl -exec perltidy -b -bext='/' {} +
+find_perl -exec perlcritic {} +
+`;
+// perlcritic before prove: a lint violation is cheaper to surface than a full
+// test run. `prove -lr t` puts ./lib on @INC and recurses into subdirectories,
+// which is what a distribution's t/ tree needs.
+const PERL_PRE_PUSH = `#!/bin/sh
+set -e
+echo "🔍 Running pre-push verify..."
+
+${FIND_PERL_FN}
+
+find_perl -exec perlcritic {} +
+prove -lr t
+echo "✅ Verify passed — pushing."
+`;
+export function installPerlGitHooks(targetDir) {
+    return installGitHooks(targetDir, PERL_HOOKS_DIR, {
+        preCommit: PERL_PRE_COMMIT,
+        prePush: PERL_PRE_PUSH,
+    });
+}

package/dist/languages/perl/gitignore.js

@@ -0,0 +1,65 @@
+/**
+ * The Perl .gitignore block, shared by the `perl-gitignore` fixer and the check
+ * that reports it. Its own module for the same reason Swift's and Python's are
+ * (#286, #290): nothing else in the module has to import from `fixers.ts`.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * The Perl build artefacts that must stay out of git. Appended to an existing
+ * .gitignore rather than replacing it — a Perl distribution's ignore file
+ * usually carries project-specific entries worth keeping.
+ */
+const PERL_GITIGNORE_BLOCK = `# Perl build output
+/blib/
+/_build/
+/Build
+/Build.bat
+pm_to_blib
+MYMETA.*
+Makefile
+Makefile.old
+/_eumm/
+
+# Distribution tarballs
+/*.tar.gz
+/*.zip
+
+# Dependencies (Carton / local::lib)
+/local/
+/.carton/
+
+# Test and profiling output
+/cover_db/
+nytprof.out
+/tmon.out
+
+# Compiled XS
+*.o
+*.bs
+*.c.tmp
+`;
+/**
+ * Entries whose presence means the block (or an equivalent) is already there.
+ * All three are produced by any Makefile.PL/Build.PL build, so they are the
+ * ones a repo accidentally commits. `local/` is deliberately not a sentinel:
+ * only Carton users have it, and demanding it would nag every other repo.
+ */
+export const PERL_GITIGNORE_SENTINELS = ['blib', 'MYMETA', 'pm_to_blib'];
+export async function ensurePerlGitignore(targetDir) {
+    const filepath = path.join(targetDir, '.gitignore');
+    if (!(await fs.pathExists(filepath))) {
+        await fs.writeFile(filepath, PERL_GITIGNORE_BLOCK);
+        return ['.gitignore'];
+    }
+    const existing = await fs.readFile(filepath, 'utf-8');
+    const missing = PERL_GITIGNORE_SENTINELS.filter((entry) => !existing.includes(entry));
+    if (missing.length === 0)
+        return [];
+    // Append only what's absent, so a repo that already ignores blib doesn't get
+    // a duplicate entry for it.
+    const additions = PERL_GITIGNORE_BLOCK.split('\n').filter((line) => line.length > 0 && !existing.includes(line));
+    const separator = existing.endsWith('\n') ? '' : '\n';
+    await fs.writeFile(filepath, `${existing}${separator}\n${additions.join('\n')}\n`);
+    return ['.gitignore'];
+}

package/dist/languages/perl/sources.js

@@ -0,0 +1,22 @@
+/**
+ * How this module enumerates a distribution's Perl source files.
+ *
+ * One definition, because the pre-commit hook and both CI lint jobs have to
+ * cover the *same* set: if they drift, a commit passes the hook and then fails
+ * CI over a file one of them never looked at.
+ *
+ * Rather than `lib t`, which assumes the standard CPAN layout — plenty of
+ * distributions keep scripts in `bin/` or `script/`, and a repo with no `lib/`
+ * would make perlcritic exit non-zero for a missing path rather than a real
+ * violation.
+ *
+ * The caller appends the action, always as `-exec … +` and never a pipe into
+ * xargs. With no matches `-exec … +` runs nothing at all, while *GNU* xargs —
+ * which is what the Linux CI runners have — runs the command once with no
+ * arguments unless given `-r`. perltidy with no file arguments reads stdin, so
+ * that lands as a lint job hanging until the job timeout with no output.
+ * (BSD/macOS xargs already declines to run on empty input, which is exactly
+ * how the bug would survive local testing and only show up in CI.) `-exec … +`
+ * is POSIX and behaves the same everywhere, with no flag to remember.
+ */
+export const FIND_PERL_SOURCES = `find . \\( -name blib -o -name local -o -name _build -o -name .git \\) -prune -o -type f \\( -name '*.pm' -o -name '*.pl' -o -name '*.t' \\)`;

package/dist/languages/python/fixers.js

@@ -69,7 +69,7 @@ export const PYTHON_FIXERS = [
         canFixDrift: true,
         async run({ targetDir }) {
             const { filesWritten, hooksPathSet } = await installPythonGitHooks(targetDir);
-            console.log(hooksPathSet
+            console.error(hooksPathSet
                 ? chalk.dim(`   git config core.hooksPath ${PYTHON_HOOKS_DIR}`)
                 : chalk.yellow(`   run \`git config core.hooksPath ${PYTHON_HOOKS_DIR}\` once per clone — it's local git config, not a committed file`));
             return { filesWritten };

package/dist/languages/registry.js

@@ -25,7 +25,7 @@ export const LANGUAGES = {
         label: 'Perl',
         codeqlLanguages: [],
         dependabotEcosystem: null,
-        supported: false,
+        supported: true,
     },
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.6.0",
+	"version": "3.7.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -105,6 +105,8 @@
 		"tooling/swift/*.json",
 		"tooling/python/*.toml",
 		"tooling/python/*.ini",
+		"tooling/perl/perlcriticrc",
+		"tooling/perl/perltidyrc",
 		"tooling/github-actions/workflows/*.yml",
 		"README.md",
 		"AGENTS.md"

package/tooling/perl/perlcriticrc

@@ -0,0 +1,35 @@
+# .perlcriticrc — @rtorcato/repo-tooling Perl preset
+#
+# Perl::Critic is the linter; perltidy (see .perltidyrc) is the formatter.
+# They do not overlap: Perl::Critic never rewrites source, so unlike the
+# SwiftLint/SwiftFormat and ruff/black pairings there is no second rewriting
+# tool to fight — see src/languages/perl/checks.ts.
+
+# Severity 3 ("harsh") and above. Severity 1 turns on the whole Perl Best
+# Practices book, including rules modern code deliberately breaks; 4-5 catch
+# so little they stop functioning as a gate.
+severity = 3
+
+# One violation per line with a file:line:column prefix, which both an editor
+# and a CI log annotator can parse.
+verbose = %f:%l:%c %m (%p, severity %s)\n
+
+# --- Rule adjustments -------------------------------------------------------
+
+# RequireVersionVar wants a $VERSION in every .pm. Distributions that carry the
+# version in their metadata (Dist::Zilla) or in the main module alone would
+# have to repeat it in every file to satisfy it.
+[-Modules::RequireVersionVar]
+
+# RequirePodSections enforces a fixed POD skeleton in every file, including
+# private modules that have no public interface to document. The POD that
+# matters is on the distribution's entry points, which this cannot tell apart.
+[-Documentation::RequirePodSections]
+
+# These modules enable strict and warnings for you, so requiring the explicit
+# pragma alongside them is a false positive.
+[TestingAndDebugging::RequireUseStrict]
+equivalent_modules = Moose Moo Mojo::Base Test2::V0
+
+[TestingAndDebugging::RequireUseWarnings]
+equivalent_modules = Moose Moo Mojo::Base Test2::V0

package/tooling/perl/perltidyrc

@@ -0,0 +1,23 @@
+# .perltidyrc — @rtorcato/repo-tooling Perl preset
+#
+# perltidy is the formatter; Perl::Critic (see .perlcriticrc) is the linter.
+#
+# Order matters in this file: -pbp is a bundle that sets many options at once,
+# so every deviation from it has to come afterwards to win.
+
+# Perl Best Practices as the base: 4-column indents, no cuddled else,
+# consistent operator spacing.
+-pbp
+
+# 100 columns rather than PBP's 78 — the same width the JavaScript and Swift
+# presets in this distribution use, so a polyglot repo wraps consistently.
+-l=100
+
+# Keep up to two consecutive blank lines instead of collapsing to one:
+# deliberate vertical grouping inside a long sub is worth preserving.
+-mbl=2
+
+# Deliberately NOT set here: -b (in-place edit) and -bext. They change what a
+# bare `perltidy lib/Foo.pm` does for a human running it by hand — it would
+# silently rewrite the file instead of producing Foo.pm.tdy. The pre-commit
+# hook and the CI job pass those flags explicitly, where in-place is the point.