@rtorcato/repo-tooling 3.2.3 → 3.2.5

package/dist/base/checks.js

@@ -0,0 +1,410 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
+export async function checkFile(dir, spec) {
+    for (const candidate of spec.candidates) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        const contents = await fs.readFile(filepath, 'utf-8');
+        if (spec.matcher.test(contents)) {
+            return {
+                check: spec.check,
+                status: 'ok',
+                detail: `${candidate} ${spec.expected}`,
+            };
+        }
+        return {
+            check: spec.check,
+            status: 'drift',
+            detail: `${candidate} found but does not ${spec.expected}`,
+            hint: spec.hint,
+        };
+    }
+    return {
+        check: spec.check,
+        status: spec.optional ? 'optional-missing' : 'missing',
+        detail: `no ${spec.candidates.join(' / ')} found`,
+        hint: spec.hint,
+    };
+}
+export async function checkEditorConfig(dir) {
+    const exists = await fs.pathExists(path.join(dir, '.editorconfig'));
+    return {
+        check: 'EditorConfig',
+        status: exists ? 'ok' : 'optional-missing',
+        detail: exists ? '.editorconfig found' : 'no .editorconfig',
+        hint: exists ? undefined : 'Add an .editorconfig for cross-editor formatting consistency',
+    };
+}
+export async function checkCodeowners(dir) {
+    for (const candidate of ['CODEOWNERS', '.github/CODEOWNERS', 'docs/CODEOWNERS']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'CODEOWNERS',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'CODEOWNERS',
+        status: 'optional-missing',
+        detail: 'no CODEOWNERS file',
+        hint: 'Run `npx @rtorcato/repo-tooling fix codeowners` to scaffold .github/CODEOWNERS',
+    };
+}
+export async function checkCommunityHealth(dir) {
+    const anchors = ['CONTRIBUTING.md', 'SECURITY.md'];
+    const present = await Promise.all(anchors.map((f) => fs.pathExists(path.join(dir, f))));
+    if (present.every(Boolean)) {
+        return {
+            check: 'Community health',
+            status: 'ok',
+            detail: 'CONTRIBUTING.md and SECURITY.md found',
+        };
+    }
+    return {
+        check: 'Community health',
+        status: 'optional-missing',
+        detail: 'missing community-health files (CONTRIBUTING/SECURITY/templates)',
+        hint: 'Run `npx @rtorcato/repo-tooling fix community-health` to scaffold them',
+    };
+}
+export async function checkGitHubActions(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return {
+            check: 'GitHub Actions',
+            status: 'optional-missing',
+            detail: 'no .github/workflows/',
+            hint: 'Run `npx @rtorcato/repo-tooling setup` to scaffold a CI workflow',
+        };
+    }
+    try {
+        const files = await fs.readdir(workflowsDir);
+        const workflows = files.filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        if (workflows.length === 0) {
+            return {
+                check: 'GitHub Actions',
+                status: 'optional-missing',
+                detail: '.github/workflows/ is empty',
+                hint: 'Add a workflow file (e.g. ci.yml) under .github/workflows/',
+            };
+        }
+        return {
+            check: 'GitHub Actions',
+            status: 'ok',
+            detail: `${workflows.length} workflow${workflows.length === 1 ? '' : 's'} in .github/workflows/`,
+        };
+    }
+    catch {
+        return {
+            check: 'GitHub Actions',
+            status: 'optional-missing',
+            detail: 'unable to read .github/workflows/',
+        };
+    }
+}
+export async function checkDependabot(dir) {
+    for (const candidate of ['.github/dependabot.yml', '.github/dependabot.yaml']) {
+        const candidatePath = path.join(dir, candidate);
+        if (await fs.pathExists(candidatePath)) {
+            // The canonical standard (apps/docs/docs/guides/dependabot-strategy.md) is
+            // the safe-tier + major-tier grouping plus the auto-merge workflow that
+            // depends on it. Flag any config that predates it so `fix dependabot` can
+            // bring the pair up to standard.
+            const content = await fs.readFile(candidatePath, 'utf8');
+            const deltas = [];
+            for (const group of ['production-minor', 'dev-minor', 'major-updates']) {
+                if (!new RegExp(`^\\s*${group}:`, 'm').test(content)) {
+                    deltas.push(`missing \`${group}\` group`);
+                }
+            }
+            const automergePath = path.join(dir, '.github', 'workflows', 'dependabot-automerge.yml');
+            if (!(await fs.pathExists(automergePath))) {
+                deltas.push('missing dependabot-automerge workflow');
+            }
+            if (deltas.length > 0) {
+                return {
+                    check: 'Dependabot',
+                    status: 'drift',
+                    detail: `${candidate} drifts from canonical (${deltas.join('; ')})`,
+                    hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` to apply the canonical grouping + auto-merge workflow',
+                };
+            }
+            return {
+                check: 'Dependabot',
+                status: 'ok',
+                detail: `${candidate} + auto-merge workflow`,
+            };
+        }
+    }
+    for (const candidate of [
+        'renovate.json',
+        'renovate.json5',
+        '.github/renovate.json',
+        '.github/renovate.json5',
+        '.renovaterc',
+        '.renovaterc.json',
+    ]) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'Dependabot',
+                status: 'ok',
+                detail: `${candidate} found (Renovate)`,
+            };
+        }
+    }
+    return {
+        check: 'Dependabot',
+        status: 'optional-missing',
+        detail: 'no Dependabot or Renovate config',
+        hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` (or `fix renovate`) to scaffold weekly dep updates',
+    };
+}
+export async function checkCodeQL(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return {
+            check: 'CodeQL',
+            status: 'optional-missing',
+            detail: 'no .github/workflows/',
+            hint: 'Run `npx @rtorcato/repo-tooling fix codeql` to scaffold CodeQL security scanning',
+        };
+    }
+    for (const candidate of ['codeql.yml', 'codeql.yaml']) {
+        if (await fs.pathExists(path.join(workflowsDir, candidate))) {
+            return {
+                check: 'CodeQL',
+                status: 'ok',
+                detail: `.github/workflows/${candidate} found`,
+            };
+        }
+    }
+    try {
+        const files = await fs.readdir(workflowsDir);
+        for (const f of files) {
+            if (!(f.endsWith('.yml') || f.endsWith('.yaml')))
+                continue;
+            const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+            if (/github\/codeql-action/.test(content)) {
+                return {
+                    check: 'CodeQL',
+                    status: 'ok',
+                    detail: `codeql-action referenced in ${f}`,
+                };
+            }
+        }
+    }
+    catch {
+        // fall through to optional-missing
+    }
+    return {
+        check: 'CodeQL',
+        status: 'optional-missing',
+        detail: 'no codeql workflow found',
+        hint: 'Run `npx @rtorcato/repo-tooling fix codeql` to scaffold CodeQL security scanning',
+    };
+}
+// A README that advertises a Codecov badge but a CI that never uploads coverage
+// leaves the badge permanently red. Only flags when the badge is actually present
+// (no badge → nothing to back, so it's not applicable).
+export async function checkCoverageUpload(dir) {
+    const readmePath = path.join(dir, 'README.md');
+    const readme = (await fs.pathExists(readmePath)) ? await fs.readFile(readmePath, 'utf8') : '';
+    if (!/codecov\.io/.test(readme)) {
+        return {
+            check: 'Coverage upload',
+            status: 'ok',
+            detail: 'no coverage badge in README (nothing to back)',
+        };
+    }
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (await fs.pathExists(workflowsDir)) {
+        try {
+            const files = (await fs.readdir(workflowsDir)).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+            for (const f of files) {
+                const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+                if (/codecov\/codecov-action/.test(content)) {
+                    return {
+                        check: 'Coverage upload',
+                        status: 'ok',
+                        detail: `coverage badge backed by codecov-action in .github/workflows/${f}`,
+                    };
+                }
+            }
+        }
+        catch {
+            // fall through to drift
+        }
+    }
+    return {
+        check: 'Coverage upload',
+        status: 'drift',
+        detail: 'README has a Codecov badge but no CI step uploads coverage (badge stays red)',
+        hint: 'Run `npx @rtorcato/repo-tooling fix github-actions` to regenerate ci.yml with a Codecov upload step',
+    };
+}
+export async function checkAiSetup(dir) {
+    // Consider AI setup present if AGENTS.md carries the js-tooling block or the
+    // Claude skill is installed — the two primary markers `fix ai` writes.
+    const agentsPath = path.join(dir, 'AGENTS.md');
+    const hasAgentsBlock = (await fs.pathExists(agentsPath)) &&
+        (await fs.readFile(agentsPath, 'utf8')).includes('<!-- js-tooling:start -->');
+    const hasSkill = (await fs.pathExists(path.join(dir, '.claude', 'skills', 'repo-tooling.md'))) ||
+        // Pre-rename name — still counts as present until `fix` migrates it.
+        (await fs.pathExists(path.join(dir, '.claude', 'skills', 'js-tooling.md')));
+    if (hasAgentsBlock || hasSkill) {
+        return {
+            check: 'AI setup',
+            status: 'ok',
+            detail: hasAgentsBlock ? 'AGENTS.md has the js-tooling block' : '.claude skill installed',
+        };
+    }
+    return {
+        check: 'AI setup',
+        status: 'optional-missing',
+        detail: 'no AI agent files (AGENTS.md, CLAUDE.md, Cursor/Copilot rules, Claude skill)',
+        hint: 'Run `npx @rtorcato/repo-tooling fix ai` to scaffold agent rules for every AI tool',
+    };
+}
+/**
+ * Conventional Commits is a repo convention, not a JavaScript one — the config
+ * file is the same in any repo that has node available to run commitlint, so
+ * the spec lives here rather than in the JS module's FILE_CHECKS (#309).
+ */
+export const COMMITLINT_FILE_CHECK = {
+    check: 'Commitlint',
+    candidates: ['commitlint.config.js', 'commitlint.config.mjs', 'commitlint.config.cjs'],
+    expected: 'exports "@rtorcato/repo-tooling/commitlint/config"',
+    matcher: /@rtorcato\/(?:js|repo)-tooling\/commitlint\/config/,
+    optional: true,
+};
+/**
+ * True when a shell hook has an uncommented line matching `pattern`. A
+ * commented-out line (e.g. `# pnpm verify`) doesn't count — the command never
+ * runs, so it isn't real wiring.
+ */
+export function hookHasUncommented(contents, pattern) {
+    return contents.split('\n').some((line) => {
+        const trimmed = line.trim();
+        return trimmed.length > 0 && !trimmed.startsWith('#') && pattern.test(trimmed);
+    });
+}
+/** `swift test` → /\bswift\s+test\b/, so extra whitespace in a hook still matches. */
+function commandMatcher(command) {
+    const escaped = command.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+    return new RegExp(`\\b${escaped}\\b`);
+}
+export async function checkGitHooks(dir, p) {
+    const check = 'Git hooks';
+    const hint = `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to enable git hooks`;
+    const hooksDir = await fs.pathExists(path.join(dir, p.dir));
+    // With no committed install signal, the hooks directory itself is the whole
+    // answer — there's no second half that can drift out of sync with it.
+    const installed = p.install === null ? hooksDir : p.install.present;
+    if (hooksDir && installed) {
+        return {
+            check,
+            status: 'ok',
+            detail: p.install ? `${p.dir}/ and ${p.install.label} configured` : `${p.dir}/ found`,
+        };
+    }
+    if (hooksDir || installed) {
+        return {
+            check,
+            status: 'drift',
+            detail: hooksDir
+                ? `${p.dir}/ exists but no ${p.install?.label}`
+                : `${p.install?.label} set but no ${p.dir}/ directory`,
+            hint: `${hint} (scaffolds both halves)`,
+        };
+    }
+    return { check, status: 'optional-missing', detail: 'git hooks not configured', hint };
+}
+/**
+ * The pre-push gate. Only asserts that the hook runs the language's verify
+ * command — whether that command itself is well-formed is the language module's
+ * business (JS keeps a `verify script` check for exactly that).
+ */
+export async function checkPrePushHook(dir, p) {
+    const check = 'Pre-push hook';
+    if (!(await fs.pathExists(path.join(dir, p.dir)))) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: 'git hooks not configured',
+            hint: `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to enable git hooks (includes pre-push)`,
+        };
+    }
+    const hookPath = path.join(dir, p.dir, 'pre-push');
+    if (!(await fs.pathExists(hookPath))) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: `no ${p.dir}/pre-push`,
+            hint: `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to scaffold a pre-push hook that runs \`${p.verifyCommand}\``,
+        };
+    }
+    const contents = await fs.readFile(hookPath, 'utf-8');
+    if (hookHasUncommented(contents, commandMatcher(p.verifyCommand))) {
+        return { check, status: 'ok', detail: `${p.dir}/pre-push runs \`${p.verifyCommand}\`` };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `${p.dir}/pre-push exists but does not run \`${p.verifyCommand}\``,
+        hint: `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to align the hook with \`${p.verifyCommand}\``,
+    };
+}
+export async function checkReadmeBadges(dir, audience, 
+/** `fix` target that rebuilds the badge block, or null when the language has none. */
+fixTarget) {
+    const check = 'README badges';
+    const hint = fixTarget
+        ? `Run \`npx @rtorcato/repo-tooling fix ${fixTarget}\` to add CI/npm/coverage/license badges`
+        : 'Add CI and license badges to README.md';
+    const readmePath = path.join(dir, 'README.md');
+    const readme = (await fs.pathExists(readmePath)) ? await fs.readFile(readmePath, 'utf8') : '';
+    if (audience === 'private') {
+        // Only a problem if a private/app repo carries badges that would 404.
+        if (readme && hasPublicOnlyBadges(readme)) {
+            return {
+                check,
+                status: 'drift',
+                detail: 'README has npm/coverage badges but the package is private (they 404)',
+                hint: fixTarget
+                    ? `Run \`npx @rtorcato/repo-tooling fix ${fixTarget}\` to rebuild badges for a private repo`
+                    : 'Remove the npm/coverage badges — they 404 for a private package',
+            };
+        }
+        return { check, status: 'ok', detail: 'not applicable (private package)' };
+    }
+    if (audience === 'not-applicable') {
+        return { check, status: 'ok', detail: 'not applicable (no published exports)' };
+    }
+    const hasBadges = readme.includes(BADGE_START) ||
+        /img\.shields\.io|badge\.svg|badge\.fury\.io|codecov\.io/.test(readme);
+    if (hasBadges) {
+        return { check, status: 'ok', detail: 'README carries status badges' };
+    }
+    return { check, status: 'optional-missing', detail: 'no status badges in README', hint };
+}
+export async function checkGitLabCI(dir) {
+    for (const candidate of ['.gitlab-ci.yml', '.gitlab-ci.yaml']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'GitLab CI',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'GitLab CI',
+        status: 'optional-missing',
+        detail: 'no .gitlab-ci.yml',
+        hint: 'Run `npx @rtorcato/repo-tooling fix gitlab-ci` to scaffold a starter GitLab pipeline',
+    };
+}

package/dist/base/ci.js

@@ -0,0 +1,133 @@
+/**
+ * Language-agnostic CI skeletons (#283).
+ *
+ * The *shell* of a pipeline — triggers, concurrency, the skip gate, job
+ * scaffolding, stage derivation — is identical whether the repo is JS, Swift,
+ * Perl or Python. Only the steps inside each job differ. This module owns the
+ * shell; language modules (`src/languages/<id>/ci.ts`) supply the steps.
+ *
+ * Steps arrive pre-rendered rather than as a YAML AST: the generators' whole
+ * job is emitting text, and a tree we'd immediately flatten buys nothing but a
+ * serializer to maintain.
+ */
+/** Every job is gated on the skip-CI check; extra conditions are ANDed on. */
+const SKIP_GUARD = "needs.check-skip.outputs.should-skip != 'true'";
+/** Header through `jobs:` — triggers and concurrency are language-independent. */
+const WORKFLOW_HEADER = `name: 🚀 CI/CD Pipeline
+
+on:
+  push:
+    branches: [main, release, develop]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+`;
+/**
+ * Honours `[ci skip]` / `[skip ci]` in the head commit message. Pure shell
+ * plumbing — no toolchain involved, so every language shares it verbatim.
+ */
+const CHECK_SKIP_JOB = `  check-skip:
+    runs-on: ubuntu-latest
+    outputs:
+      should-skip: \${{ steps.skip-check.outputs.should-skip }}
+    steps:
+      - name: Check for skip CI
+        id: skip-check
+        run: |
+          if [[ "\${{ github.event.head_commit.message }}" =~ \\[(ci skip|skip ci)\\] ]]; then
+            echo "should-skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "should-skip=false" >> $GITHUB_OUTPUT
+          fi`;
+function renderJob(job) {
+    // A lone dependency stays a scalar (`needs: check-skip`) — that's the form
+    // the hand-written workflows used, and Actions treats both identically.
+    const needs = [...(job.needs ?? []), 'check-skip'];
+    const needsYaml = needs.length === 1 ? needs[0] : `[${needs.join(', ')}]`;
+    const condition = job.if ? `${SKIP_GUARD} && ${job.if}` : SKIP_GUARD;
+    return `  ${job.id}:
+    runs-on: ${job.runsOn ?? 'ubuntu-latest'}
+    needs: ${needsYaml}
+    if: ${condition}
+${job.extra ? `${job.extra}\n` : ''}    steps:
+${job.steps}`;
+}
+/** Wrap language-supplied jobs in the shared workflow shell. */
+export function renderGitHubWorkflow(jobs) {
+    return `${WORKFLOW_HEADER}${[CHECK_SKIP_JOB, ...jobs.map(renderJob)].join('\n\n')}\n`;
+}
+/**
+ * The CodeQL workflow. Only the matrix languages vary, so the whole file lives
+ * here and each language module contributes its `codeqlLanguages`.
+ */
+export function renderCodeQLWorkflow(languages) {
+    return `name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [${languages.join(', ')}]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: \${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:\${{ matrix.language }}"
+`;
+}
+/**
+ * Wrap language-supplied jobs in the shared `.gitlab-ci.yml` shell. Stages are
+ * derived from the jobs in first-appearance order, so a language module never
+ * has to keep a stage list in sync with the jobs it emits.
+ */
+export function renderGitLabCI({ image, preamble, jobs }) {
+    const stages = [...new Set(jobs.map((job) => job.stage))];
+    // A pipeline with no jobs still needs a valid `stages:` key.
+    if (stages.length === 0)
+        stages.push('test');
+    const blocks = jobs.map((job) => `${job.id}:
+  stage: ${job.stage}
+  script:
+${job.script.map((line) => `    - ${line}`).join('\n')}${job.extra ? `\n${job.extra}` : ''}`);
+    return `# .gitlab-ci.yml — generated by @rtorcato/repo-tooling
+# Customize stages and jobs to fit your pipeline.
+
+image: ${image}
+
+stages:
+${stages.map((s) => `  - ${s}`).join('\n')}
+
+${[preamble, ...blocks].join('\n\n')}
+`;
+}