@rtorcato/repo-tooling 3.2.3 → 3.2.5

package/dist/base/fixers.js

@@ -0,0 +1,207 @@
+/**
+ * The fixer contract plus the language-agnostic fixers (#286, #303).
+ *
+ * These are the fixers for the checks in ./checks.ts — repo hygiene, security
+ * automation, community health, AI agent files, GitHub repo settings. Nothing
+ * here reads a package.json or emits a toolchain-specific step, so every
+ * language module gets them for free; `fix` concatenates them with the module's
+ * own set.
+ *
+ * Not here: `github-actions` / `gitlab-ci` / `lockfile`. Their *content* is
+ * language-shaped (CI steps, recorded tool choices), so each module ships its
+ * own — see src/base/ci.ts for the shell they share.
+ */
+import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
+import { generateCommunityHealth } from '../cli/generators/community-health.js';
+import { generateCommitlintConfig } from '../cli/generators/git.js';
+import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
+import { generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../cli/generators/security.js';
+import { copyPreset } from '../cli/utils/copy-preset.js';
+import { detectLanguage } from '../cli/utils/detect-language.js';
+import { resolveLanguageModule } from '../languages/registry.js';
+import { applyGithubSettings } from './github-settings.js';
+/** The repo's language module, resolved from its marker files. */
+async function moduleFor(targetDir) {
+    return resolveLanguageModule(await detectLanguage(targetDir));
+}
+export const BASE_FIXERS = [
+    {
+        target: 'editorconfig',
+        description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
+        appliesTo: ['EditorConfig'],
+        outputs: ['.editorconfig'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateEditorConfig(targetDir);
+            return { filesWritten: ['.editorconfig'] };
+        },
+    },
+    {
+        target: 'commitlint',
+        description: 'Scaffold commitlint.config.mjs exporting the preset',
+        // Conventional Commits is a repo convention, not a JS one (#309) — the
+        // config is identical in any repo. Running commitlint still needs node on
+        // PATH, which is why the Swift hooks don't wire a commit-msg hook.
+        appliesTo: ['Commitlint'],
+        outputs: ['commitlint.config.mjs'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateCommitlintConfig(targetDir);
+            return { filesWritten: ['commitlint.config.mjs'] };
+        },
+    },
+    {
+        target: 'dependabot',
+        description: 'Scaffold the canonical .github/dependabot.yml (monthly, grouped: production-minor/dev-minor/major-updates) + the dependabot-automerge workflow',
+        appliesTo: ['Dependabot'],
+        outputs: ['.github/dependabot.yml', '.github/workflows/dependabot-automerge.yml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const { dependabotEcosystem } = await moduleFor(targetDir);
+            return { filesWritten: await generateDependabotConfig(targetDir, dependabotEcosystem) };
+        },
+    },
+    {
+        target: 'renovate',
+        description: 'Scaffold renovate.json (weekly schedule; alternative to Dependabot)',
+        appliesTo: ['Dependabot'],
+        outputs: ['renovate.json'],
+        riskLevel: 'safe-add',
+        async run({ targetDir }) {
+            await generateRenovateConfig(targetDir);
+            return { filesWritten: ['renovate.json'] };
+        },
+    },
+    {
+        target: 'codeql',
+        description: 'Scaffold .github/workflows/codeql.yml (security scanning)',
+        appliesTo: ['CodeQL'],
+        outputs: ['.github/workflows/codeql.yml'],
+        async run({ targetDir }) {
+            const { codeqlLanguages } = await moduleFor(targetDir);
+            return { filesWritten: await generateCodeQLWorkflow(targetDir, codeqlLanguages) };
+        },
+    },
+    {
+        target: 'github-settings',
+        description: 'Apply branch protection + auto-merge + workflow permissions + code-scanning ruleset on GitHub via gh api (mutates the remote repo, not files)',
+        appliesTo: [
+            'Branch protection',
+            'Merge settings',
+            'Workflow permissions',
+            'Code-scanning gate',
+        ],
+        outputs: ['GitHub repo settings (remote, via gh api)'],
+        // safe-add is load-bearing: it exempts this fixer from the `--diff` shadow-run
+        // (previewFixer copies to tmp and *executes* run(), which would fire real
+        // `gh api` PUTs during a mere preview).
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await applyGithubSettings(targetDir) };
+        },
+    },
+    {
+        target: 'codeowners',
+        description: 'Scaffold .github/CODEOWNERS with commented examples',
+        appliesTo: ['CODEOWNERS'],
+        outputs: ['.github/CODEOWNERS'],
+        riskLevel: 'safe-add',
+        canFixDrift: false,
+        async run({ targetDir }) {
+            const written = await generateCodeowners(targetDir);
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'community-health',
+        description: 'Scaffold CONTRIBUTING.md, SECURITY.md, PR + issue templates',
+        appliesTo: ['Community health'],
+        outputs: [
+            'CONTRIBUTING.md',
+            'SECURITY.md',
+            '.github/PULL_REQUEST_TEMPLATE.md',
+            '.github/ISSUE_TEMPLATE/bug_report.md',
+            '.github/ISSUE_TEMPLATE/feature_request.md',
+        ],
+        riskLevel: 'safe-add',
+        canFixDrift: false,
+        async run({ targetDir }) {
+            const filesWritten = await generateCommunityHealth(targetDir);
+            return { filesWritten };
+        },
+    },
+    {
+        target: 'ai',
+        description: 'Install all AI agent files at once (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill, MCP example)',
+        appliesTo: ['AI setup'],
+        outputs: [
+            'AGENTS.md',
+            'CLAUDE.md',
+            '.cursor/rules/repo-tooling.mdc',
+            '.github/copilot-instructions.md',
+            '.claude/skills/repo-tooling.md',
+            '.mcp.json.example',
+            // Only written when the repo ships its own skills/<name>/SKILL.md.
+            'README.md',
+        ],
+        // Every output is a delimited-block upsert or a `.example` file — existing
+        // user content is never clobbered.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const filesWritten = await installAiSetup(targetDir);
+            return { filesWritten };
+        },
+    },
+    {
+        target: 'claude-skill',
+        description: 'Install the repo-tooling Claude Code skill into .claude/skills/',
+        appliesTo: ['Claude skill'],
+        outputs: ['.claude/skills/repo-tooling.md'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('claude-skill', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'cursor-rules',
+        description: 'Install the repo-tooling rules for Cursor (.cursor/rules/repo-tooling.mdc)',
+        appliesTo: ['Cursor rules'],
+        outputs: ['.cursor/rules/repo-tooling.mdc'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'cursor');
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'copilot-instructions',
+        description: 'Install the repo-tooling rules for GitHub Copilot (.github/copilot-instructions.md)',
+        appliesTo: ['Copilot instructions'],
+        outputs: ['.github/copilot-instructions.md'],
+        // Upserts a delimited block — never clobbers the consumer's own instructions.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'copilot');
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'agents-md',
+        description: 'Install the repo-tooling rules into AGENTS.md (universal agent instructions)',
+        appliesTo: ['AGENTS.md rules'],
+        outputs: ['AGENTS.md'],
+        // Upserts a delimited block — never clobbers existing AGENTS.md content.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'agents-md');
+            return { filesWritten: [written] };
+        },
+    },
+];

package/dist/base/git-identity.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * IANA-reserved domains that can never receive mail. This is what made #327
+ * unrecoverable: an address at one of these can never be verified as a
+ * secondary email, so the commits can never be re-linked without a history
+ * rewrite.
+ */
+const PLACEHOLDER_DOMAINS = ['example.com', 'example.org', 'example.net', 'invalid', 'test'];
+/**
+ * Suffixes of a machine-derived hostname. `.local` is mDNS (macOS default),
+ * `.matrix` is this user's LAN — both produced real commits in the #327 set.
+ */
+const HOSTNAME_SUFFIXES = ['.local', '.matrix', '.localhost', '.lan', '.home', '.internal'];
+/** Pure so the rules are testable without a git repo or a spawn. */
+export function classifyGitEmail(raw) {
+    const email = (raw ?? '').trim().toLowerCase();
+    if (email === '')
+        return 'unset';
+    // lastIndexOf: a quoted local part may legally contain '@'.
+    const at = email.lastIndexOf('@');
+    const domain = at === -1 ? '' : email.slice(at + 1);
+    // No '@' at all, or nothing either side of it — not an address.
+    if (domain === '' || at === 0)
+        return 'generated';
+    if (PLACEHOLDER_DOMAINS.some((d) => domain === d || domain.endsWith(`.${d}`))) {
+        return 'placeholder';
+    }
+    // A bare hostname has no dot at all (`richard@laptop`); the suffixes catch
+    // the ones that do (`richard@Richards-Mini.matrix`).
+    if (!domain.includes('.') || HOSTNAME_SUFFIXES.some((s) => domain.endsWith(s))) {
+        return 'generated';
+    }
+    return 'ok';
+}
+const DETAIL = {
+    unset: () => 'git user.email is not set — git will invent one from the hostname at commit time',
+    placeholder: (e) => `git user.email is a placeholder that can never receive mail: ${e}`,
+    generated: (e) => `git user.email looks machine-derived, not a real address: ${e}`,
+};
+const HINT = 'Commits made with this identity will not link to your forge account, and the address cannot be added as a verified secondary email to fix them retroactively (#327). Set a real one: `git config --global user.email you@yourdomain.com` — or per-repo, drop `--global`.';
+const CHECK = 'Git identity';
+const GIT_TIMEOUT_MS = 5_000;
+/** Never rejects; a missing or failing git resolves to null. */
+export const realGitExec = (args, cwd) => new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(v);
+    };
+    // Args are internal constants, never user free-text — shell:false keeps
+    // this injection-safe.
+    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    let stdout = '';
+    const timer = setTimeout(() => {
+        child.kill();
+        done(null);
+    }, GIT_TIMEOUT_MS);
+    child.stdout?.on('data', (d) => {
+        stdout += d;
+    });
+    child.on('close', (code) => done(code === 0 ? stdout.trim() : null));
+    child.on('error', () => done(null));
+});
+/**
+ * STATUS: a bad identity is never `drift` or `missing`, both of which exit 1.
+ * The identity belongs to whoever is running doctor, not to the repo — failing
+ * CI over the runner's git config would be noise the repo's author cannot fix
+ * by changing the repo. `optional-missing` reports it in gray and leaves the
+ * exit code alone.
+ */
+export async function checkGitIdentity(dir, exec) {
+    // Cheap gate: no .git → no commits to mis-attribute, and no spawn.
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        return { check: CHECK, status: 'ok', detail: 'not a git repository' };
+    }
+    // On a runner the identity is the bot's, so there is nothing to warn about
+    // and the warning would be permanent.
+    if (process.env.CI) {
+        return { check: CHECK, status: 'ok', detail: 'skipped on CI (identity is the runner’s)' };
+    }
+    const git = exec ?? ((args) => realGitExec(args, dir));
+    const email = await git(['config', '--get', 'user.email']);
+    const verdict = classifyGitEmail(email);
+    if (verdict === 'ok') {
+        return { check: CHECK, status: 'ok', detail: `git user.email is ${email}` };
+    }
+    return {
+        check: CHECK,
+        status: 'optional-missing',
+        detail: DETAIL[verdict](email ?? ''),
+        hint: HINT,
+    };
+}