@rtorcato/repo-tooling 3.5.0 → 3.6.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 and Perl are 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 is audit-only for now. See `src/languages/` — one directory per language module, `src/base/` for what's shared.
 
 ## CLI surface (agent-friendly)
 

package/dist/base/git-hooks.js

@@ -0,0 +1,43 @@
+/**
+ * Committed git hooks for languages that can't use Husky (#309).
+ *
+ * Husky is an npm package, so a repo whose toolchain has no node can't use it.
+ * The node-free equivalent is a committed hooks directory that git is pointed at
+ * with `core.hooksPath` — identical mechanics whatever the language; only the
+ * hook bodies differ. Swift and Python both land here rather than each carrying
+ * their own copy of the write-then-chmod-then-git-config dance.
+ */
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import fs from 'fs-extra';
+/** Best-effort `git config` — a missing git or a non-repo dir is not a failure. */
+function gitConfig(cwd, key, value) {
+    return new Promise((resolve) => {
+        execFile('git', ['-C', cwd, 'config', key, value], (err) => resolve(!err));
+    });
+}
+/**
+ * Writes both hooks and points git at them. Returns the files written —
+ * `core.hooksPath` is per-clone local config, not a file, so it's reported
+ * separately rather than pretending to be a repo change.
+ */
+export async function installGitHooks(targetDir, hooksDirName, scripts) {
+    const hooksDir = path.join(targetDir, hooksDirName);
+    await fs.ensureDir(hooksDir);
+    const filesWritten = [];
+    for (const [name, content] of [
+        ['pre-commit', scripts.preCommit],
+        ['pre-push', scripts.prePush],
+    ]) {
+        const hookPath = path.join(hooksDir, name);
+        await fs.writeFile(hookPath, content);
+        await fs.chmod(hookPath, 0o755);
+        filesWritten.push(`${hooksDirName}/${name}`);
+    }
+    // Guard on .git: `fix --diff` shadow-runs fixers in a temp copy that excludes
+    // .git, and that copy can land inside another repo — an unguarded `git config`
+    // there would rewrite the *parent* repo's hooksPath during a mere preview.
+    const isRepo = await fs.pathExists(path.join(targetDir, '.git'));
+    const hooksPathSet = isRepo ? await gitConfig(targetDir, 'core.hooksPath', hooksDirName) : false;
+    return { filesWritten, hooksPathSet };
+}

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 { PYTHON_GIT_HOOKS, runPythonChecks } from '../../languages/python/checks.js';
+import { readPyproject, renderPythonWorkflow } from '../../languages/python/ci.js';
 import { resolveLanguageModule } from '../../languages/registry.js';
 import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js';
 import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
@@ -172,10 +174,10 @@ 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 (Swift/Perl/Python
-    // until their modules land) 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; 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.
     const language = await detectLanguage(targetDir);
     const languageModule = resolveLanguageModule(language);
     if (!languageModule.supported) {
@@ -185,9 +187,9 @@ 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 Python/Perl hook convention yet,
-            // and guessing one would nag every repo with a fix target that doesn't
-            // exist. #289/#290 fill it in.
+            // 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.
             ...(await runBaseChecks(targetDir, lock, {
                 hooks: null,
                 badges: { audience: 'public', fixTarget: null },
@@ -219,6 +221,28 @@ export async function runDoctor(dir) {
         ];
         return demoteDeclined(results, lock);
     }
+    // Python suite (#290): same shape as Swift — base checks plus the module's
+    // own, and nothing JS-shaped, because a Python repo has no package.json.
+    if (languageModule.id === 'python') {
+        const results = [
+            {
+                check: 'language',
+                status: 'ok',
+                detail: 'detected Python (pyproject.toml / setup.py)',
+            },
+            ...(await runBaseChecks(targetDir, lock, {
+                hooks: PYTHON_GIT_HOOKS,
+                // A Python package on PyPI is public by default, so badges apply. No
+                // fixer: `fix badges` derives the block from package.json name and
+                // repository, which a Python repo hasn't got.
+                badges: { audience: 'public', fixTarget: null },
+                presetWorkflow: renderPythonWorkflow(await readPyproject(targetDir)),
+                language,
+            })),
+            ...(await runPythonChecks(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).

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

@@ -64,11 +64,28 @@ const SWIFT_FIX_TARGETS = {
     // (no `.testTarget(`) there's nothing to run, and rewriting Package.swift
     // isn't safe. The check's own hint covers both halves.
 };
+/** The same shadowing for the Python module (#290). */
+const PYTHON_FIX_TARGETS = {
+    'Git hooks': 'python-git-hooks',
+    'Pre-push hook': 'python-git-hooks',
+    'GitHub Actions': 'python-ci',
+    'GitLab CI': 'python-gitlab-ci',
+    Ruff: 'ruff',
+    mypy: 'mypy',
+    pytest: 'pytest',
+    'Python .gitignore': 'python-gitignore',
+    // `pyproject.toml` and `Python tests` are deliberately absent, for the same
+    // reason `Swift tests` is: the fix is content only the project can write
+    // (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.
+};
+const FIX_TARGETS_BY_LANGUAGE = {
+    swift: SWIFT_FIX_TARGETS,
+    python: PYTHON_FIX_TARGETS,
+};
 export function getFixTargetForCheck(checkName, language) {
-    if (language === 'swift' && SWIFT_FIX_TARGETS[checkName]) {
-        return SWIFT_FIX_TARGETS[checkName];
-    }
-    return FIX_TARGETS[checkName] ?? null;
+    const overrides = language ? FIX_TARGETS_BY_LANGUAGE[language] : undefined;
+    return overrides?.[checkName] ?? FIX_TARGETS[checkName] ?? null;
 }
 /**
  * For a given doctor check name, returns true when the lockfile records that
@@ -168,6 +185,7 @@ export function lockfilePatchForTarget(target, lock) {
             return c.commitLint ? null : { commitLint: true };
         case 'husky':
         case 'swift-git-hooks':
+        case 'python-git-hooks':
             return c.gitHooks ? null : { gitHooks: true };
         case 'semantic-release':
         case 'swift-release':

package/dist/cli/commands/fix.js

@@ -11,19 +11,24 @@ 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 { 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). */
+const LANGUAGE_FIXERS = {
+    swift: SWIFT_FIXERS,
+    python: PYTHON_FIXERS,
+};
 /**
- * The fixers that apply to a repo, by detected language (#286, #303): the
- * language-agnostic base set plus the module's own. Swift repos get the Swift
- * module; everything else (including a bare dir mid-setup) gets JS, the
- * historical default.
+ * The fixers that apply to a repo, by detected language: the language-agnostic
+ * base set plus the module's own. Anything without a module of its own
+ * (including a bare dir mid-setup) gets JS, the historical default.
  */
 function fixersForLanguage(language) {
-    return [...BASE_FIXERS, ...(language === 'swift' ? SWIFT_FIXERS : FIXERS)];
+    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];
+const ALL_FIXERS = [...BASE_FIXERS, ...FIXERS, ...SWIFT_FIXERS, ...PYTHON_FIXERS];
 export function getFixers() {
     return ALL_FIXERS;
 }

package/dist/cli/index.js

@@ -251,6 +251,24 @@ const TOOL_CATALOG = [
         exports: [],
         fixTarget: 'periphery',
     },
+    {
+        name: 'Ruff',
+        description: 'Python linter and formatter in one tool (replaces flake8, isort, pyupgrade, black)',
+        exports: [],
+        fixTarget: 'ruff',
+    },
+    {
+        name: 'mypy',
+        description: 'Python static type checker configuration (strict on your code, lenient on untyped deps)',
+        exports: [],
+        fixTarget: 'mypy',
+    },
+    {
+        name: 'pytest',
+        description: 'Python test runner configuration (strict markers and config, warnings as errors)',
+        exports: [],
+        fixTarget: 'pytest',
+    },
     {
         name: 'AI Agent Setup',
         description: 'Scaffold AGENTS.md, CLAUDE.md, Cursor/Copilot rules, Claude skill, MCP example',

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

@@ -51,6 +51,21 @@ export const PRESETS = {
         target: '.periphery.yml',
         desc: 'Periphery dead-code scan configuration (retains public API)',
     },
+    ruff: {
+        source: 'tooling/python/ruff.toml',
+        target: 'ruff.toml',
+        desc: 'Ruff configuration (lint + format — replaces flake8, isort, pyupgrade and black)',
+    },
+    mypy: {
+        source: 'tooling/python/mypy.ini',
+        target: 'mypy.ini',
+        desc: 'mypy configuration (strict on your code, lenient on untyped dependencies)',
+    },
+    pytest: {
+        source: 'tooling/python/pytest.ini',
+        target: 'pytest.ini',
+        desc: 'pytest configuration (strict markers and config, warnings as errors)',
+    },
     'claude-skill': {
         source: 'tooling/claude/repo-tooling.md',
         target: '.claude/skills/repo-tooling.md',

package/dist/languages/js/fixers.js

@@ -225,13 +225,13 @@ export const FIXERS = [
         async run({ targetDir, pkg }) {
             const pkgPath = path.join(targetDir, 'package.json');
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const includeTreeshake = await fs.pathExists(path.join(targetDir, 'apps', 'treeshake-check', 'check.mjs'));
             const verify = composeVerifyScriptFromPkg(pkg, { includeTreeshake });
             if (!verify) {
-                console.log(chalk.gray('   not enough tools enabled to compose a verify chain — skipping (need 2+ of typecheck/lint/tests)'));
+                console.error(chalk.gray('   not enough tools enabled to compose a verify chain — skipping (need 2+ of typecheck/lint/tests)'));
                 return { filesWritten: [] };
             }
             const updated = { ...pkg };
@@ -256,7 +256,7 @@ export const FIXERS = [
         canFixDrift: true,
         async run({ targetDir, pkg }) {
             if (pkg?.private === true) {
-                console.log(chalk.gray('   skipping — package is private'));
+                console.error(chalk.gray('   skipping — package is private'));
                 return { filesWritten: [] };
             }
             const filesWritten = await generateSemanticReleaseConfig(targetDir);
@@ -315,7 +315,7 @@ export const FIXERS = [
                 overwrite: result.check === 'GitHub Actions',
             });
             if (!filesWritten.includes(CI_WORKFLOW)) {
-                console.log(chalk.yellow(`   ${CI_WORKFLOW} differs from the preset — left as-is; run \`fix github-actions --diff\` to see the delta`));
+                console.error(chalk.yellow(`   ${CI_WORKFLOW} differs from the preset — left as-is; run \`fix github-actions --diff\` to see the delta`));
             }
             return { filesWritten };
         },
@@ -518,17 +518,17 @@ export const FIXERS = [
         canFixDrift: false,
         async run({ targetDir, pkg }) {
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const workspaceName = pkg.name ?? null;
             if (!workspaceName) {
-                console.log(chalk.yellow('   package.json has no `name` — skipping'));
+                console.error(chalk.yellow('   package.json has no `name` — skipping'));
                 return { filesWritten: [] };
             }
             const { allCandidates, defaultAllowed } = inferSubpathsFromExports(pkg);
             if (allCandidates.length < 2 || !defaultAllowed) {
-                console.log(chalk.yellow('   package.json does not expose ≥2 subpath exports — tree-shake check needs multiple subpaths to be meaningful. Skipping.'));
+                console.error(chalk.yellow('   package.json does not expose ≥2 subpath exports — tree-shake check needs multiple subpaths to be meaningful. Skipping.'));
                 return { filesWritten: [] };
             }
             const allowedSubpath = defaultAllowed;
@@ -538,7 +538,7 @@ export const FIXERS = [
                 allowedSubpath,
                 forbiddenSubpaths,
             });
-            console.log(chalk.dim(`   Wired '${allowedSubpath}' as allowed; forbidden = [${forbiddenSubpaths.join(', ')}]. Edit apps/treeshake-check/check.mjs to tune.`));
+            console.error(chalk.dim(`   Wired '${allowedSubpath}' as allowed; forbidden = [${forbiddenSubpaths.join(', ')}]. Edit apps/treeshake-check/check.mjs to tune.`));
             return { filesWritten: written };
         },
     },
@@ -615,7 +615,7 @@ export const FIXERS = [
         async run({ targetDir, pkg }) {
             const pkgPath = path.join(targetDir, 'package.json');
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const updated = { ...pkg };
@@ -645,7 +645,7 @@ export const FIXERS = [
         async run({ targetDir, pkg }) {
             const pkgPath = path.join(targetDir, 'package.json');
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const updated = { ...pkg };
@@ -674,7 +674,7 @@ export const FIXERS = [
         canFixDrift: true,
         async run({ targetDir, pkg }) {
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const p = pkg;
@@ -687,7 +687,7 @@ export const FIXERS = [
                 isPrivate: p.private === true,
             });
             if (!block) {
-                console.log(chalk.yellow('   package.json has no name/repository to build badges from — skipping'));
+                console.error(chalk.yellow('   package.json has no name/repository to build badges from — skipping'));
                 return { filesWritten: [] };
             }
             const readmePath = path.join(targetDir, 'README.md');
@@ -708,7 +708,7 @@ export const FIXERS = [
         async run({ targetDir, pkg }) {
             const pkgPath = path.join(targetDir, 'package.json');
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const updated = { ...pkg };
@@ -718,7 +718,7 @@ export const FIXERS = [
             devDeps['@rtorcato/repo-tooling'] = 'latest';
             updated.devDependencies = devDeps;
             await fs.writeJson(pkgPath, updated, { spaces: 2 });
-            console.log(chalk.dim('   reminder: run `pnpm install` to install the new dep'));
+            console.error(chalk.dim('   reminder: run `pnpm install` to install the new dep'));
             return { filesWritten: ['package.json'] };
         },
     },
@@ -731,7 +731,7 @@ export const FIXERS = [
         canFixDrift: false,
         async run({ targetDir, pkg }) {
             if (!pkg) {
-                console.log(chalk.yellow('   no package.json found — skipping'));
+                console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
             const config = inferProjectConfig(pkg);

package/dist/languages/python/checks.js

@@ -0,0 +1,234 @@
+/**
+ * Python language module — checks (#290), on the same template as Swift (#286).
+ *
+ * The standard encoded here is ruff (lint *and* format), mypy and pytest.
+ * Deliberately *not* checked:
+ *
+ * - **black** — ruff's formatter is black-compatible and already runs in the
+ *   pre-commit hook and the lint job. A second *rewriting* formatter fights the
+ *   first, which is the same reason the Swift module checks SwiftLint's `--fix`
+ *   rather than SwiftFormat. If a repo wants black instead, it configures black
+ *   in its own pyproject.toml — nothing here objects.
+ * - **flake8 / isort / pyupgrade** — the `select` list in the shipped ruff.toml
+ *   covers all three (E/W, I, UP), so a separate config would be a second place
+ *   to keep the same rules.
+ * - **A pinned interpreter file** (`.python-version`) — the supported range is
+ *   declared once in pyproject's `requires-python`, and CI derives its matrix
+ *   from that. A root file would be a second thing to keep in sync.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { checkFile } from '../../base/checks.js';
+import { PYTHON_GITIGNORE_SENTINELS } from './gitignore.js';
+import { PYTHON_HOOKS_DIR } from './git-hooks.js';
+const PYTHON_TOOL_CHECKS = [
+    {
+        dedicated: {
+            check: 'Ruff',
+            candidates: ['ruff.toml', '.ruff.toml'],
+            expected: 'is a valid Ruff configuration',
+            // `[tool.ruff...]` is the pyproject form; the rest are ruff.toml's own
+            // top-level keys and sections.
+            matcher: /^\[tool\.ruff|^\[(lint|format)\]|^(line-length|target-version)\s*=/m,
+            hint: 'Run `npx @rtorcato/repo-tooling fix ruff` to scaffold (or add a `[tool.ruff]` table to pyproject.toml)',
+        },
+        shared: ['pyproject.toml'],
+    },
+    {
+        dedicated: {
+            check: 'mypy',
+            candidates: ['mypy.ini', '.mypy.ini'],
+            expected: 'is a valid mypy configuration',
+            // `[mypy]` in mypy.ini/setup.cfg, `[tool.mypy]` in pyproject.
+            matcher: /^\[(tool\.)?mypy\]/m,
+            hint: 'Run `npx @rtorcato/repo-tooling fix mypy` to scaffold (or add a `[tool.mypy]` table to pyproject.toml)',
+        },
+        shared: ['setup.cfg', 'pyproject.toml'],
+    },
+    {
+        dedicated: {
+            check: 'pytest',
+            candidates: ['pytest.ini'],
+            expected: 'is a valid pytest configuration',
+            // `[pytest]` in pytest.ini/tox.ini, `[tool:pytest]` in setup.cfg,
+            // `[tool.pytest.ini_options]` in pyproject.
+            matcher: /^\[(pytest|tool:pytest|tool\.pytest\.ini_options)\]/m,
+            hint: 'Run `npx @rtorcato/repo-tooling fix pytest` to scaffold (or add a `[tool.pytest.ini_options]` table to pyproject.toml)',
+        },
+        shared: ['tox.ini', 'setup.cfg', 'pyproject.toml'],
+    },
+];
+async function checkPythonTool(dir, spec) {
+    const result = await checkFile(dir, spec.dedicated);
+    // A dedicated file that exists takes precedence over any shared table — all
+    // three tools read it first — so `ok` and `drift` are both final answers.
+    if (result.status !== 'missing')
+        return result;
+    for (const candidate of spec.shared) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        if (spec.dedicated.matcher.test(await fs.readFile(filepath, 'utf-8'))) {
+            return {
+                check: spec.dedicated.check,
+                status: 'ok',
+                detail: `${candidate} ${spec.dedicated.expected}`,
+            };
+        }
+    }
+    return result;
+}
+export async function checkPythonGitignore(dir) {
+    const check = 'Python .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 python-gitignore` to scaffold the Python template',
+        };
+    }
+    const contents = await fs.readFile(filepath, 'utf-8');
+    const missing = PYTHON_GITIGNORE_SENTINELS.filter((entry) => !contents.includes(entry));
+    if (missing.length > 0) {
+        return {
+            check,
+            status: 'drift',
+            detail: `.gitignore missing Python artefacts: ${missing.join(', ')}`,
+            hint: 'Run `npx @rtorcato/repo-tooling fix python-gitignore` to append the missing entries',
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `.gitignore covers ${PYTHON_GITIGNORE_SENTINELS.join(', ')}`,
+    };
+}
+/**
+ * pyproject.toml hygiene, the Python shape of the `Package.swift` check. Both
+ * signals are things no tool infers for you: without a metadata table there is
+ * nothing to build or publish, and without a `requires-python` floor pip will
+ * happily install the package on an interpreter it cannot run on — the failure
+ * lands on the user, at import time.
+ */
+export async function checkPyproject(dir) {
+    const check = 'pyproject.toml';
+    const filepath = path.join(dir, 'pyproject.toml');
+    if (!(await fs.pathExists(filepath))) {
+        // detect-language also accepts setup.py, so a repo can reach this module
+        // without a pyproject at all. That's drift rather than "not a Python repo".
+        const legacy = await fs.pathExists(path.join(dir, 'setup.py'));
+        return {
+            check,
+            status: 'missing',
+            detail: legacy ? 'setup.py only — no pyproject.toml' : 'no pyproject.toml',
+            hint: 'Add a PEP 621 pyproject.toml with a `[project]` table — setup.py is legacy and no longer the packaging standard',
+        };
+    }
+    const contents = await fs.readFile(filepath, 'utf-8');
+    // PEP 621 `[project]` or Poetry's `[tool.poetry]` — the two forms in the wild.
+    const poetry = /^\[tool\.poetry\]/m.test(contents);
+    if (!/^\[project\]/m.test(contents) && !poetry) {
+        return {
+            check,
+            status: 'drift',
+            detail: 'pyproject.toml declares no `[project]` (or `[tool.poetry]`) metadata',
+            hint: 'Add a `[project]` table with `name`, `version` and `requires-python` — see PEP 621',
+        };
+    }
+    // Poetry spells the same constraint `python = "^3.11"` under its dependencies.
+    const hasFloor = poetry
+        ? /^\s*python\s*=/m.test(contents)
+        : /^requires-python\s*=/m.test(contents);
+    if (!hasFloor) {
+        return {
+            check,
+            status: 'drift',
+            detail: `pyproject.toml declares no ${poetry ? '`python` constraint' : '`requires-python`'}`,
+            hint: 'Add `requires-python = ">=3.10"` — without it pip installs the package on interpreters it cannot run on',
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `pyproject.toml declares ${poetry ? 'Poetry' : 'PEP 621'} metadata and a Python floor`,
+    };
+}
+/** 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;
+}
+/** `tests/`, `test/`, or a root-level `test_*.py` — the three layouts pytest finds. */
+async function hasTestFiles(dir) {
+    for (const candidate of ['tests', 'test']) {
+        if (await fs.pathExists(path.join(dir, candidate)))
+            return `${candidate}/`;
+    }
+    try {
+        const found = (await fs.readdir(dir)).find((f) => /^test_.*\.py$/.test(f));
+        return found ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The test setup. Same two halves as the Swift version: a suite has to exist,
+ * and CI has to run it. A green pipeline over a repo with no tests proves
+ * nothing, and a tests/ directory nothing executes is worse than none at all —
+ * it reads as covered.
+ */
+export async function checkPythonTests(dir) {
+    const check = 'Python tests';
+    const tests = await hasTestFiles(dir);
+    if (!tests) {
+        return {
+            check,
+            status: 'missing',
+            detail: 'no tests/ directory or test_*.py files',
+            hint: 'Add a `tests/` directory — the shipped pytest.ini sets `testpaths = tests`',
+        };
+    }
+    for (const candidate of await ciFiles(dir)) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        if (/\bpytest\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 pytest`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix python-ci` to regenerate a workflow that runs pytest',
+    };
+}
+/**
+ * The Python shape of the base `Git hooks` / `Pre-push hook` checks (#309).
+ * `install` is null for the same reason Swift's is: 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 PYTHON_GIT_HOOKS = {
+    dir: PYTHON_HOOKS_DIR,
+    install: null,
+    verifyCommand: 'pytest',
+    fixTarget: 'python-git-hooks',
+};
+/** The Python module's suite, layered on top of the base checks by doctor. */
+export async function runPythonChecks(dir) {
+    return [
+        await checkPyproject(dir),
+        ...(await Promise.all(PYTHON_TOOL_CHECKS.map((spec) => checkPythonTool(dir, spec)))),
+        await checkPythonGitignore(dir),
+        await checkPythonTests(dir),
+    ];
+}

package/dist/languages/python/ci.js

@@ -0,0 +1,153 @@
+/**
+ * Python CI generation (#290), built on the language-agnostic skeleton in
+ * `src/base/ci.ts`. No `setup-node`, no `pnpm` — the Python path runs on Linux
+ * with `actions/setup-python` and pip.
+ *
+ * Like the Swift path there's no `ProjectConfig` to read: the one fact CI needs
+ * beyond the fixed job shapes — which interpreters to test on — is declared in
+ * pyproject.toml, 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';
+/**
+ * The newest interpreter the emitted matrix tests against, and the one the
+ * single-interpreter jobs (lint, typecheck) run on.
+ *
+ * ponytail: a constant, bumped by hand once a year when CPython ships a minor.
+ * Resolving "latest" at generation time would need a network call from a
+ * generator whose whole job is emitting text.
+ */
+const LATEST_PYTHON = '3.13';
+/** The oldest interpreter to assume when pyproject declares no floor. */
+const DEFAULT_FLOOR = '3.10';
+const minorOf = (version) => Number.parseInt(version.split('.')[1] ?? '0', 10);
+/**
+ * Pull the supported-Python floor out of a pyproject.toml. A regex rather than
+ * a TOML parser: this is one key, and a parser is a dependency the CLI would
+ * carry solely to read it.
+ */
+export function parsePyproject(contents) {
+    // PEP 621 `requires-python = ">=3.10"`, or Poetry's
+    // `python = "^3.11"` under [tool.poetry.dependencies].
+    const constraint = contents.match(/^requires-python\s*=\s*["']([^"']+)["']/m)?.[1] ??
+        contents.match(/^\s*python\s*=\s*["']([^"']+)["']/m)?.[1] ??
+        '';
+    const floor = constraint.match(/(\d+\.\d+)/)?.[1] ?? 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_PYTHON) ? [floor] : [floor, LATEST_PYTHON];
+    return { pythonVersions: versions };
+}
+export async function readPyproject(dir) {
+    const filepath = path.join(dir, 'pyproject.toml');
+    if (!(await fs.pathExists(filepath)))
+        return { pythonVersions: [DEFAULT_FLOOR, LATEST_PYTHON] };
+    return parsePyproject(await fs.readFile(filepath, 'utf-8'));
+}
+/** Checkout + interpreter. `cache: pip` keys off the manifests pip resolves from. */
+function pythonSetup(version) {
+    return `      - name: 📦 Checkout repository
+        uses: actions/checkout@v7
+
+      - name: 🐍 Set up Python ${version}
+        uses: actions/setup-python@v6
+        with:
+          python-version: '${version}'
+          cache: pip`;
+}
+export function pythonGithubJobs(project) {
+    return [
+        {
+            id: 'lint',
+            steps: `${pythonSetup(LATEST_PYTHON)}
+
+      - name: 📦 Install Ruff
+        run: pip install ruff
+
+      - name: 🔍 ruff check
+        run: ruff check --output-format=github
+
+      - name: 🎨 ruff format --check
+        run: ruff format --check`,
+        },
+        {
+            id: 'typecheck',
+            // mypy needs the package's own dependencies importable to resolve their
+            // types — running it against bare source reports every third-party import
+            // as missing.
+            steps: `${pythonSetup(LATEST_PYTHON)}
+
+      - name: 📦 Install project and mypy
+        run: |
+          pip install --upgrade pip
+          pip install -e .
+          pip install mypy
+
+      - name: 🔎 mypy
+        run: mypy .`,
+        },
+        {
+            id: 'test',
+            extra: `    name: pytest \${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+${project.pythonVersions.map((v) => `          - '${v}'`).join('\n')}`,
+            steps: `      - name: 📦 Checkout repository
+        uses: actions/checkout@v7
+
+      - name: 🐍 Set up Python \${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: \${{ matrix.python-version }}
+          cache: pip
+
+      - name: 📦 Install project and pytest
+        run: |
+          pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+
+      - name: 🧪 pytest
+        run: pytest`,
+        },
+    ];
+}
+export function renderPythonWorkflow(project) {
+    return renderGitHubWorkflow(pythonGithubJobs(project));
+}
+/**
+ * GitLab runs the same three commands in the official Python image. The matrix
+ * is dropped: 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 pythonGitlabSpec(project) {
+    const image = `python:${project.pythonVersions.at(-1) ?? LATEST_PYTHON}`;
+    return {
+        image,
+        preamble: `variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip`,
+        jobs: [
+            {
+                id: 'lint',
+                stage: 'lint',
+                script: ['pip install ruff', 'ruff check', 'ruff format --check'],
+            },
+            {
+                id: 'test',
+                stage: 'test',
+                script: ['pip install -e .', 'pip install pytest', 'pytest'],
+            },
+        ],
+    };
+}
+export function renderPythonGitLabCI(project) {
+    return renderGitLabCI(pythonGitlabSpec(project));
+}

package/dist/languages/python/fixers.js

@@ -0,0 +1,104 @@
+/**
+ * Python language module — fixers (#290). One per check in ./checks.ts.
+ *
+ * ponytail: no `python-lockfile` fixer. Swift's writes the config that
+ * `setup --preset swift-library` would have produced, and there is no
+ * `python-library` preset yet (the Swift one landed in its own issue, #288).
+ * Inventing a ProjectConfig here just to have something to record would put a
+ * fabricated set of JS tool choices in a Python repo's lockfile — worse than
+ * doctor saying the lockfile is 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 { readPyproject, renderPythonGitLabCI, renderPythonWorkflow } from './ci.js';
+import { PYTHON_HOOKS_DIR, installPythonGitHooks } from './git-hooks.js';
+import { ensurePythonGitignore } from './gitignore.js';
+export const PYTHON_FIXERS = [
+    {
+        target: 'ruff',
+        description: 'Scaffold ruff.toml (lint + format — the linter and the formatter in one tool)',
+        appliesTo: ['Ruff'],
+        outputs: ['ruff.toml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('ruff', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'mypy',
+        description: 'Scaffold mypy.ini (strict on your code, lenient on untyped dependencies)',
+        appliesTo: ['mypy'],
+        outputs: ['mypy.ini'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('mypy', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'pytest',
+        description: 'Scaffold pytest.ini (strict markers and config, warnings as errors)',
+        appliesTo: ['pytest'],
+        outputs: ['pytest.ini'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('pytest', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'python-gitignore',
+        description: 'Add the Python artefacts (__pycache__, .venv, tool caches, build output) to .gitignore',
+        appliesTo: ['Python .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 ensurePythonGitignore(targetDir) };
+        },
+    },
+    {
+        target: 'python-git-hooks',
+        description: `Scaffold ${PYTHON_HOOKS_DIR}/pre-commit + pre-push (ruff, mypy, pytest) and point git at them via core.hooksPath`,
+        appliesTo: ['Git hooks', 'Pre-push hook'],
+        outputs: [`${PYTHON_HOOKS_DIR}/pre-commit`, `${PYTHON_HOOKS_DIR}/pre-push`],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const { filesWritten, hooksPathSet } = await installPythonGitHooks(targetDir);
+            console.log(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 };
+        },
+    },
+    {
+        target: 'python-ci',
+        description: 'Scaffold .github/workflows/ci.yml for Python (ruff, mypy, pytest 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 = renderPythonWorkflow(await readPyproject(targetDir));
+            await fs.writeFile(path.join(workflowsDir, 'ci.yml'), workflow);
+            return { filesWritten: ['.github/workflows/ci.yml'] };
+        },
+    },
+    {
+        target: 'python-gitlab-ci',
+        description: 'Scaffold .gitlab-ci.yml for Python (ruff + pytest on the official Python image)',
+        appliesTo: ['GitLab CI'],
+        outputs: ['.gitlab-ci.yml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const ci = renderPythonGitLabCI(await readPyproject(targetDir));
+            await fs.writeFile(path.join(targetDir, '.gitlab-ci.yml'), ci);
+            return { filesWritten: ['.gitlab-ci.yml'] };
+        },
+    },
+];

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

@@ -0,0 +1,35 @@
+/**
+ * Python git hooks (#290). Same shape as the Swift ones (#309) and for the same
+ * reason: Husky is an npm package, and a Python repo 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`.
+ *
+ * Deliberately *not* `pre-commit` (the Python framework of that name): it is a
+ * second config file, a second pinned-tool source, and a second place the CI
+ * commands have to be kept in sync with. The hooks run ruff/mypy/pytest
+ * directly, exactly as CI does.
+ */
+import { installGitHooks } from '../../base/git-hooks.js';
+export const PYTHON_HOOKS_DIR = '.githooks';
+// `ruff format` before `ruff check --fix` so the lint pass sees final layout.
+// Neither rewrites anything the other undoes — one tool owns both jobs.
+const PYTHON_PRE_COMMIT = `#!/bin/sh
+set -e
+ruff format
+ruff check --fix
+`;
+// mypy before pytest: a type error is cheaper to surface than a test run.
+const PYTHON_PRE_PUSH = `#!/bin/sh
+set -e
+echo "🔍 Running pre-push verify..."
+ruff check
+mypy .
+pytest
+echo "✅ Verify passed — pushing."
+`;
+export function installPythonGitHooks(targetDir) {
+    return installGitHooks(targetDir, PYTHON_HOOKS_DIR, {
+        preCommit: PYTHON_PRE_COMMIT,
+        prePush: PYTHON_PRE_PUSH,
+    });
+}

package/dist/languages/python/gitignore.js

@@ -0,0 +1,55 @@
+/**
+ * The Python .gitignore block, shared by the `python-gitignore` fixer and the
+ * check that reports it. Its own module for the same reason Swift's is (#286):
+ * nothing else in the module has to import from `fixers.ts` to reuse it.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * The Python artefacts that must stay out of git. Appended to an existing
+ * .gitignore rather than replacing it — a Python repo's ignore file usually
+ * carries project-specific entries worth keeping.
+ */
+const PYTHON_GITIGNORE_BLOCK = `# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+`;
+/**
+ * Entries whose presence means the block (or an equivalent) is already there.
+ * `__pycache__` and `.venv` are the expensive ones — either committed by
+ * accident buries the diff — and a tool cache stands in for the rest.
+ */
+export const PYTHON_GITIGNORE_SENTINELS = ['__pycache__', '.venv', '.pytest_cache'];
+export async function ensurePythonGitignore(targetDir) {
+    const filepath = path.join(targetDir, '.gitignore');
+    if (!(await fs.pathExists(filepath))) {
+        await fs.writeFile(filepath, PYTHON_GITIGNORE_BLOCK);
+        return ['.gitignore'];
+    }
+    const existing = await fs.readFile(filepath, 'utf-8');
+    const missing = PYTHON_GITIGNORE_SENTINELS.filter((entry) => !existing.includes(entry));
+    if (missing.length === 0)
+        return [];
+    // Append only what's absent, so a repo that already ignores __pycache__
+    // doesn't get a duplicate entry for it.
+    const additions = PYTHON_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/registry.js

@@ -18,7 +18,7 @@ export const LANGUAGES = {
         label: 'Python',
         codeqlLanguages: ['python'],
         dependabotEcosystem: 'pip',
-        supported: false,
+        supported: true,
     },
     perl: {
         id: 'perl',

package/dist/languages/swift/fixers.js

@@ -93,7 +93,7 @@ export const SWIFT_FIXERS = [
             if (await fs.pathExists(path.join(targetDir, file)))
                 return { filesWritten: [] };
             await fs.outputFile(path.join(targetDir, file), doccLandingPage(target));
-            console.log(chalk.yellow('   add swift-docc-plugin to Package.swift to build it: .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.0")'));
+            console.error(chalk.yellow('   add swift-docc-plugin to Package.swift to build it: .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.0")'));
             return { filesWritten: [file] };
         },
     },
@@ -117,7 +117,7 @@ export const SWIFT_FIXERS = [
         canFixDrift: true,
         async run({ targetDir }) {
             const { filesWritten, hooksPathSet } = await installSwiftGitHooks(targetDir);
-            console.log(hooksPathSet
+            console.error(hooksPathSet
                 ? chalk.dim(`   git config core.hooksPath ${SWIFT_HOOKS_DIR}`)
                 : chalk.yellow(`   run \`git config core.hooksPath ${SWIFT_HOOKS_DIR}\` once per clone — it's local git config, not a committed file`));
             return { filesWritten };

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

@@ -2,16 +2,15 @@
  * Swift git hooks (#309). Husky is an npm package, so a SwiftPM repo can't use
  * it without dragging node into a toolchain that otherwise has none. The
  * node-free equivalent is a committed `.githooks/` directory that git is pointed
- * at with `core.hooksPath`.
+ * at with `core.hooksPath` — the mechanics live in `src/base/git-hooks.ts`; only
+ * the hook bodies are Swift's.
  *
  * The hooks run the tools directly rather than a `verify` indirection: SwiftPM
  * has no scripts field, and inventing a Makefile target would be a third place
  * to keep the CI commands in sync (they already live in .github/workflows/ci.yml
  * and .swiftlint.yml).
  */
-import { execFile } from 'node:child_process';
-import path from 'node:path';
-import fs from 'fs-extra';
+import { installGitHooks } from '../../base/git-hooks.js';
 export const SWIFT_HOOKS_DIR = '.githooks';
 // SwiftLint's --fix is the formatter (see ./checks.ts), so pre-commit formats
 // then lints. --quiet keeps a clean commit from printing a wall of nothing.
@@ -28,36 +27,9 @@ swift test
 swiftlint lint --strict
 echo "✅ Verify passed — pushing."
 `;
-/** Best-effort `git config` — a missing git or a non-repo dir is not a failure. */
-function gitConfig(cwd, key, value) {
-    return new Promise((resolve) => {
-        execFile('git', ['-C', cwd, 'config', key, value], (err) => resolve(!err));
+export function installSwiftGitHooks(targetDir) {
+    return installGitHooks(targetDir, SWIFT_HOOKS_DIR, {
+        preCommit: SWIFT_PRE_COMMIT,
+        prePush: SWIFT_PRE_PUSH,
     });
 }
-/**
- * Writes both hooks and points git at them. Returns the files written —
- * `core.hooksPath` is per-clone local config, not a file, so it's reported
- * separately rather than pretending to be a repo change.
- */
-export async function installSwiftGitHooks(targetDir) {
-    const hooksDir = path.join(targetDir, SWIFT_HOOKS_DIR);
-    await fs.ensureDir(hooksDir);
-    const filesWritten = [];
-    for (const [name, content] of [
-        ['pre-commit', SWIFT_PRE_COMMIT],
-        ['pre-push', SWIFT_PRE_PUSH],
-    ]) {
-        const hookPath = path.join(hooksDir, name);
-        await fs.writeFile(hookPath, content);
-        await fs.chmod(hookPath, 0o755);
-        filesWritten.push(`${SWIFT_HOOKS_DIR}/${name}`);
-    }
-    // Guard on .git: `fix --diff` shadow-runs fixers in a temp copy that excludes
-    // .git, and that copy can land inside another repo — an unguarded `git config`
-    // there would rewrite the *parent* repo's hooksPath during a mere preview.
-    const isRepo = await fs.pathExists(path.join(targetDir, '.git'));
-    const hooksPathSet = isRepo
-        ? await gitConfig(targetDir, 'core.hooksPath', SWIFT_HOOKS_DIR)
-        : false;
-    return { filesWritten, hooksPathSet };
-}

package/package.json

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

package/tooling/python/mypy.ini

@@ -0,0 +1,21 @@
+; mypy.ini — @rtorcato/repo-tooling Python preset
+;
+; Strict-by-default on your own code, lenient on third-party packages that ship
+; no type information. Without the second half, a single untyped dependency
+; turns every import into an error and the whole run gets ignored.
+
+[mypy]
+python_version = 3.10
+strict = True
+warn_unused_configs = True
+warn_unreachable = True
+show_error_codes = True
+exclude = (^|/)(build|dist|\.venv)/
+
+; Tests exercise deliberately-wrong inputs, so full strictness there costs more
+; than it catches.
+[mypy-tests.*]
+disallow_untyped_defs = False
+
+[mypy-tests.*.*]
+disallow_untyped_defs = False

package/tooling/python/pytest.ini

@@ -0,0 +1,15 @@
+; pytest.ini — @rtorcato/repo-tooling Python preset
+;
+; A standalone file rather than [tool.pytest.ini_options] in pyproject.toml:
+; pyproject is the project's own metadata, and merging a table into it needs a
+; TOML round-tripper this CLI does not carry. pytest reads pytest.ini first.
+
+[pytest]
+testpaths = tests
+; Fail on an unregistered marker or an unknown config key — both are typos that
+; otherwise silently skip tests.
+addopts = --strict-markers --strict-config
+; A warning that nobody ever sees is a bug waiting for a major version bump.
+filterwarnings =
+    error
+    ignore::DeprecationWarning:pkg_resources.*

package/tooling/python/ruff.toml

@@ -0,0 +1,32 @@
+# ruff.toml — @rtorcato/repo-tooling Python preset
+#
+# Ruff is both the linter and the formatter here. Its formatter is
+# black-compatible, so a separate black config would be a second rewriting
+# formatter fighting the first — see src/languages/python/checks.ts.
+
+line-length = 100
+target-version = "py310"
+
+exclude = [
+  ".venv",
+  "build",
+  "dist",
+]
+
+[lint]
+# E/W pycodestyle, F pyflakes, I isort, UP pyupgrade, B bugbear,
+# SIM simplify, RUF ruff-specific. The set flake8 + isort + pyupgrade would
+# have given you, minus the four extra dependencies.
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "RUF"]
+
+# E501 is the formatter's job — leaving it on makes every long string a lint
+# error the formatter is not allowed to fix.
+ignore = ["E501"]
+
+[lint.per-file-ignores]
+# Test files legitimately shadow names and use bare asserts.
+"tests/**" = ["S101"]
+
+[format]
+quote-style = "double"
+indent-style = "space"