chore(ci): harden dead-code ratchet + comment accuracy (#282 review nits)

Non-blocking follow-ups from krokoko's review:

- Pin knip exactly (6.20.0, drop caret) and make the ratchet fail loud
  instead of open: if a future knip reshapes its JSON so `issues` is not
  an array, countIssues now exits 2 rather than silently counting 0 and
  reporting a passing build (which would disable the gate). Needed before
  the gate flips to blocking.
- COUNTED_KEYS comment: note the list is complete for the pinned knip and
  that nsExports/nsTypes/classMembers are not part of its schema.
- validation.ts: attribute the `void` to tsconfig noUnusedLocals
  specifically (no-unused-vars already exempts the ^_ binding).

Author: bgagent

cdk/src/handlers/shared/validation.ts

@@ -290,8 +290,9 @@ type _AssertAttachmentExhaustive = Exclude<AttachmentType, (typeof ATTACHMENT_TY
 // ATTACHMENT_TYPE_LIST, _AssertAttachmentExhaustive resolves to `never` and
 // assigning `true` is a hard compile error. (A `true as never` assertion would
 // NOT error — assertions are permitted whenever either side is assignable — so
-// it must stay an assignment.) `void` consumes the binding so noUnusedLocals
-// and @typescript-eslint/no-unused-vars stay satisfied without weakening it.
+// it must stay an assignment.) `void` consumes the binding to satisfy
+// tsconfig noUnusedLocals, which — unlike @typescript-eslint/no-unused-vars,
+// already exempt via its ^_ varsIgnorePattern — does not honor the _ prefix.
 const _attachmentExhaustiveCheck: _AssertAttachmentExhaustive = true;
 void _attachmentExhaustiveCheck;
 const VALID_ATTACHMENT_TYPES = new Set<string>(ATTACHMENT_TYPE_LIST);

package.json

@@ -48,6 +48,12 @@ const baselinePath = join(repoRoot, 'knip-baseline.json');
 // inside issues[].files[], NOT at the top level. `duplicates` is an
 // array-of-arrays (one inner array per duplicate group), so its `.length`
 // counts groups, which is the unit we ratchet on.
+//
+// This is the complete set of countable keys for the installed knip (6.20.0,
+// pinned exactly). There is no `nsExports`/`nsTypes`/`classMembers` in this
+// schema — namespace/enum members surface as `namespaceMembers`/`enumMembers`.
+// If knip is bumped, re-derive this list from its JSON (the countIssues guard
+// below will fail loud if the top-level shape changes).
 const COUNTED_KEYS = [
   'files',
   'dependencies',
@@ -87,8 +93,20 @@ function runKnip() {
 }
 
 function countIssues(report) {
+  // Fail loud, not open: if a future knip reshapes its JSON so `issues` is no
+  // longer an array, `?? []` would yield count 0 — silently below any baseline,
+  // reporting a passing build and disabling the gate. Require the array shape so
+  // a schema change surfaces as an error instead. (knip is pinned exactly in
+  // package.json to make such a change a deliberate, reviewed bump.)
+  if (!Array.isArray(report.issues)) {
+    console.error(
+      'check-deadcode-ratchet: knip JSON has no `issues` array — its output schema may have changed. ' +
+        'Re-validate COUNTED_KEYS against the installed knip before trusting the count.',
+    );
+    process.exit(2);
+  }
   let total = 0;
-  for (const issue of report.issues ?? []) {
+  for (const issue of report.issues) {
     for (const key of COUNTED_KEYS) {
       if (Array.isArray(issue[key])) total += issue[key].length;
     }