@rtorcato/repo-tooling 3.5.0 → 3.7.0

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' \\)`;