@rtorcato/repo-tooling 3.26.0 → 3.27.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/cli/commands/doctor.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
@@ -238,7 +272,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 +296,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 +320,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 +346,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 +405,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 +424,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 +458,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 +478,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.27.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`.