@rtorcato/repo-tooling 3.26.0 → 3.28.0

package/AGENTS.md

@@ -18,7 +18,7 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `setup --config <path>` | ✅ | `--dry-run` only | Scaffold with a full `ProjectConfig` JSON file. See `setup --config-schema`. |
 | `setup --config-schema` | ✅ | ✅ (JSON Schema) | Print the JSON Schema for `ProjectConfig`. Use to validate configs before scaffolding. |
 | `setup --dry-run` | ✅ | ✅ | Print resolved config + file list without writing. Pair with `--preset` or `--config`. |
-| `doctor --json` | ✅ | ✅ | Audit a project. Returns `{ directory, results: [{ check, status, detail, hint? }] }`. Status: `ok` / `drift` / `missing` / `optional-missing`. |
+| `doctor --json` | ✅ | ✅ | Audit a project. Returns `{ directory, results: [{ check, status, detail, hint? }] }`. Status: `ok` / `drift` / `missing` / `optional-missing` / `declared`. |
 | `fix --json --yes` | ✅ | ✅ | Walk every doctor finding, apply fixers. Returns `FixActionRecord[]` with `status: applied | dry-run | skipped | already-ok | unsupported`. |
 | `fix <target> --json --yes` | ✅ | ✅ | Apply one fixer. Targets from `list --json`. |
 | `fix --dry-run` | ✅ | ✅ | Print what each fixer would write without writing. Combine with `--json`. |

package/dist/base/git-identity.js

@@ -149,3 +149,72 @@ export async function checkGitIdentity(dir, exec) {
         hint: HINT,
     };
 }
+const HISTORY_CHECK = 'Git author history';
+/**
+ * Bounded so doctor stays cheap on every invocation; the output always names
+ * how many commits were actually examined so "0 found" is never read as "all
+ * history is clean".
+ */
+export const HISTORY_SCAN_LIMIT = 200;
+/** How many offending commits to name; the count carries the rest. */
+const HISTORY_SAMPLE = 3;
+const HISTORY_HINT = 'These commits are already made: the address can never be verified as a secondary email, so they cannot be re-linked to a forge account without a history rewrite (#327). Fix the identity going forward (see the Git identity check) and treat the history as recorded loss.';
+/**
+ * The retrospective half of `checkGitIdentity` (#557): that check reads the
+ * identity the *next* commit will use, this one scans recent history for
+ * commits already made with a bad one. Same classifier — `classifyGitEmail` —
+ * so the two can never drift. Same STATUS reasoning too: history is not
+ * something the repo's author can fix by editing the repo, so a finding is
+ * `optional-missing`, never `drift`/`missing`, and the exit code is untouched.
+ * Detection only — there is deliberately no fixer, because the only "fix" is a
+ * history rewrite no tool should offer unprompted.
+ */
+export async function checkGitIdentityHistory(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        return { check: HISTORY_CHECK, status: 'ok', detail: 'not a git repository' };
+    }
+    if (process.env.CI) {
+        return { check: HISTORY_CHECK, status: 'ok', detail: 'skipped on CI' };
+    }
+    const git = exec ?? ((args) => realGitExec(args, dir));
+    // A shallow clone has almost no history; scanning its stub and reporting
+    // "0 found" would be a false all-clear.
+    if ((await git(['rev-parse', '--is-shallow-repository'])) === 'true') {
+        return {
+            check: HISTORY_CHECK,
+            status: 'ok',
+            detail: 'shallow clone — commit history is not available to scan',
+        };
+    }
+    // %h %ae: abbreviated hash + author email, one commit per line.
+    const log = await git(['log', `-${HISTORY_SCAN_LIMIT}`, '--format=%h %ae']);
+    if (log === null || log === '') {
+        return { check: HISTORY_CHECK, status: 'ok', detail: 'no commits to scan' };
+    }
+    const commits = log.split('\n').map((line) => {
+        const sp = line.indexOf(' ');
+        return { hash: line.slice(0, sp), email: line.slice(sp + 1) };
+    });
+    const bad = commits.filter(({ email }) => {
+        const verdict = classifyGitEmail(email);
+        return verdict === 'placeholder' || verdict === 'generated';
+    });
+    const scanned = `the last ${commits.length} commit${commits.length === 1 ? '' : 's'}`;
+    if (bad.length === 0) {
+        return {
+            check: HISTORY_CHECK,
+            status: 'ok',
+            detail: `no placeholder or machine-derived author emails in ${scanned}`,
+        };
+    }
+    const sample = bad
+        .slice(0, HISTORY_SAMPLE)
+        .map(({ hash, email }) => `${hash} (${email})`)
+        .join(', ');
+    return {
+        check: HISTORY_CHECK,
+        status: 'optional-missing',
+        detail: `${bad.length} of ${scanned} carry a placeholder or machine-derived author email — e.g. ${sample}`,
+        hint: HISTORY_HINT,
+    };
+}

package/dist/cli/commands/doctor.js

@@ -16,7 +16,7 @@ import { checkAgentUser } from '../../base/agent-user.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
 import { checkLoopLabels } from '../../base/labels.js';
 import { checkMilestones } from '../../base/milestones.js';
-import { checkGitIdentity } from '../../base/git-identity.js';
+import { checkGitIdentity, checkGitIdentityHistory } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
@@ -156,6 +156,40 @@ function demoteDeclined(results, lock) {
         };
     });
 }
+// Declared exceptions (#558): a failing check the lock names is reported as
+// `declared` with its reason — shown, never hidden, but no longer failing the
+// run. An exception naming a check this run doesn't know is itself drift:
+// otherwise a typo silently does nothing and a check rename silently
+// un-suppresses a finding, and both are invisible.
+function applyExceptions(results, lock) {
+    const exceptions = lock?.exceptions;
+    if (!exceptions)
+        return results;
+    const known = new Set(results.map((r) => r.check));
+    const overlaid = results.map((r) => {
+        const reason = exceptions[r.check];
+        if (!reason || r.status === 'ok')
+            return r;
+        // Hint deliberately dropped: the deviation is declared, so "how to fix it"
+        // is exactly the noise the exception exists to retire.
+        return {
+            check: r.check,
+            status: 'declared',
+            detail: `${r.detail} — declared exception: ${reason}`,
+        };
+    });
+    for (const name of Object.keys(exceptions)) {
+        if (known.has(name))
+            continue;
+        overlaid.push({
+            check: 'Declared exceptions',
+            status: 'drift',
+            detail: `.repo-tooling.json declares an exception for "${name}", which is not a check this run knows`,
+            hint: 'A typo, or a check that was renamed or removed — fix or delete the entry in `exceptions`',
+        });
+    }
+    return overlaid;
+}
 // The language-agnostic checks (src/base): repo hygiene, git hooks, CI,
 // security, and GitHub repo-settings that apply to any repo regardless of
 // language. Declared once and run for every project — a language module layers
@@ -168,6 +202,8 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(await checkCopiedAssets(dir));
     results.push(await checkNestedLanguages(dir, opts.language));
     results.push(await checkGitIdentity(dir));
+    // The retrospective half (#557): commits already made with a bad identity.
+    results.push(await checkGitIdentityHistory(dir));
     results.push(await checkEditorConfig(dir));
     results.push(await checkFile(dir, COMMITLINT_FILE_CHECK));
     if (opts.hooks) {
@@ -238,7 +274,7 @@ export async function runDoctor(dir, skillsDir) {
                 skillsDir,
             })),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), lock);
     }
     // Swift suite (#286): base checks plus the module's own. Swift repos have no
     // package.json, so nothing JS-shaped runs.
@@ -262,7 +298,7 @@ export async function runDoctor(dir, skillsDir) {
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), 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.
@@ -286,7 +322,7 @@ export async function runDoctor(dir, skillsDir) {
             })),
             ...(await runPythonChecks(targetDir)),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), lock);
     }
     // Perl suite (#289): same shape as Swift and Python — base checks plus the
     // module's own, and nothing JS-shaped, because a distribution has no
@@ -312,7 +348,7 @@ export async function runDoctor(dir, skillsDir) {
             })),
             ...(await runPerlChecks(targetDir)),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), 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
@@ -371,13 +407,14 @@ export async function runDoctor(dir, skillsDir) {
         codeqlLanguages: languageModule.codeqlLanguages,
         skillsDir,
     })));
-    return demoteDeclined(results, lock);
+    return applyExceptions(demoteDeclined(results, lock), lock);
 }
 const STATUS_ICONS = {
     ok: chalk.green('✅'),
     drift: chalk.yellow('⚠️ '),
     missing: chalk.red('❌'),
     'optional-missing': chalk.gray('➖'),
+    declared: chalk.blue('📝'),
 };
 function statusLabel(status) {
     switch (status) {
@@ -389,6 +426,8 @@ function statusLabel(status) {
             return chalk.red('missing');
         case 'optional-missing':
             return chalk.gray('not configured');
+        case 'declared':
+            return chalk.blue('declared');
     }
 }
 const MAX_NEXT_STEP_SUGGESTIONS = 8;
@@ -421,6 +460,7 @@ export function summarize(results) {
         drift: results.filter((r) => r.status === 'drift').length,
         missing: results.filter((r) => r.status === 'missing').length,
         optionalMissing: results.filter((r) => r.status === 'optional-missing').length,
+        declared: results.filter((r) => r.status === 'declared').length,
     };
 }
 export async function doctorCommand(options = {}) {
@@ -440,7 +480,7 @@ export async function doctorCommand(options = {}) {
         }
         const summary = summarize(results);
         console.log();
-        console.log(`  Summary: ${chalk.green(`${summary.ok} ok`)}, ${chalk.yellow(`${summary.drift} drift`)}, ${chalk.red(`${summary.missing} missing`)}, ${chalk.gray(`${summary.optionalMissing} not configured`)}\n`);
+        console.log(`  Summary: ${chalk.green(`${summary.ok} ok`)}, ${chalk.yellow(`${summary.drift} drift`)}, ${chalk.red(`${summary.missing} missing`)}, ${chalk.gray(`${summary.optionalMissing} not configured`)}, ${chalk.blue(`${summary.declared} declared`)}\n`);
         const suggestions = nextStepSuggestions(results, await detectLanguage(dir));
         if (suggestions.length > 0) {
             console.log(chalk.bold('  Next steps:'));

package/dist/cli/commands/fix.js

@@ -436,7 +436,10 @@ export async function fixCommand(target, options = {}) {
         console.log();
         return;
     }
-    const fixable = results.filter((r) => r.status !== 'ok');
+    // `declared` is a deviation the lockfile records on purpose (#558) — a bulk
+    // fix must not "repair" it. A targeted `fix <target>` still can: naming the
+    // fixer is the same explicit override the declined-in-lock path gets.
+    const fixable = results.filter((r) => r.status !== 'ok' && r.status !== 'declared');
     if (fixable.length === 0) {
         if (json)
             return emitJson(null);

package/dist/cli/utils/lockfile.js

@@ -117,6 +117,11 @@ export function lockfileSchema() {
                     },
                 },
             },
+            exceptions: {
+                type: 'object',
+                additionalProperties: { type: 'string', minLength: 1 },
+                description: 'Declared exceptions: doctor check name → the reason this repo deliberately deviates. The reason is mandatory and non-empty — doctor shows the check as `declared` with it (never hidden) and stops failing the run for it. An entry naming a check doctor does not run is itself reported as drift.',
+            },
             writtenBy: {
                 type: 'string',
                 description: 'Package name and version that last wrote this file.',
@@ -193,6 +198,7 @@ export async function writeLockfile(dir, config, assets) {
         ...(existing?.aiLoop ? { aiLoop: existing.aiLoop } : {}),
         ...(existing?.requiredSkills ? { requiredSkills: existing.requiredSkills } : {}),
         ...(existing?.mcp ? { mcp: existing.mcp } : {}),
+        ...(existing?.exceptions ? { exceptions: existing.exceptions } : {}),
         writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
         writtenAt: new Date().toISOString(),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.26.0",
+	"version": "3.28.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/repo-tooling/SKILL.md

@@ -30,6 +30,8 @@ npx @rtorcato/repo-tooling doctor --json                 # confirm clean
   prompt to **No**; `--yes` is required to overwrite. Show `fix <target> --diff` first.
 - `missing` — required and absent → fix it.
 - `optional-missing` — opt-in tool not configured. Only fix if the user wants that tool.
+- `declared` — a real deviation the repo's `.repo-tooling.json` `exceptions` records on
+  purpose, with its reason. Leave it alone; it doesn't fail the run.
 
 `fix` returns `FixActionRecord[]` with `status: applied | dry-run | skipped | already-ok | unsupported`.