@thejoseki/clawform 2.3.1 → 2.4.0

package/src/lib/lint-overrides.js

@@ -1,226 +1,226 @@
-// Lint-override loader + cfn-guard SuppressedRules wrapper.
-//
-// Reads rules/lint-overrides.md (the single, audited allowlist), turns its
-// Markdown table into structured overrides, partitions expired rows, injects
-// the active ones into a CFN template's Metadata.guard.SuppressedRules so
-// cfn-guard skips them, and detects in-template suppressions that lack an
-// overrides-file row (anti-rot — "suppression without justification").
-//
-// Functions are pure where possible: every time-sensitive call (filterExpired)
-// takes the current Date as an argument so tests are deterministic. Callers
-// (src/commands/validate.js) supply `new Date()` at the call site.
-//
-// YAML round-trip uses the shared CFN short-tag schema in src/lib/cfn-yaml.js.
-// iam-audit / graph.js still carry local copies — they COULD import src/lib via
-// the same upward-probe graph.js already uses for project-config.js; folding
-// them onto cfn-yaml.js is a worthwhile follow-up (the copies have drifted
-// before: graph.js was missing `!Transform` until 1.2.0). The schema is
-// construct-only, so `!Sub "x"` round-trips to `Fn::Sub: x` — both forms are
-// valid CloudFormation and cfn-guard accepts either.
-
-import { readFileSync, existsSync } from 'node:fs';
-import yaml from 'js-yaml';
-import { CFN_SCHEMA } from './cfn-yaml.js';
-
-// --- loadOverrides ---------------------------------------------------------
-// Parse the Markdown table in rules/lint-overrides.md and return an array of
-//   { ruleId, scopeGlob, reason, expires, owner }
-//
-// Header-name driven: we normalize `rule-id` → `ruleId`, `scope` → `scopeGlob`.
-// The doc's `tool` column is read but discarded (cfn-guard SuppressedRules
-// don't distinguish source). `owner` is optional and defaults to null when the
-// column is absent or empty.
-//
-// Placeholder rows (empty rule-id, or markdown-italic markers like `_none yet_`)
-// are skipped — the bundled doc ships with one such row by design.
-//
-// Missing file: returns [] (a fresh consumer with no overrides is a valid
-// state, mirroring the legacy_prefixes contract).
-export function loadOverrides(mdPath) {
-  if (!existsSync(mdPath)) return [];
-  const text = readFileSync(mdPath, 'utf8');
-  return parseOverridesMarkdown(text);
-}
-
-export function parseOverridesMarkdown(text) {
-  const lines = text.split(/\r?\n/);
-  // Find the first table whose header includes a "rule-id" column.
-  const out = [];
-  let i = 0;
-  while (i < lines.length) {
-    const line = lines[i];
-    if (isTableRow(line)) {
-      const header = splitRow(line);
-      const norm = header.map(normalizeHeader);
-      const idIdx = norm.indexOf('ruleId');
-      if (idIdx === -1) { i++; continue; }
-      // Next line should be the separator (|---|---|...). Skip it.
-      const sep = lines[i + 1];
-      if (!sep || !/^\s*\|?\s*:?-{2,}/.test(sep.trim())) { i++; continue; }
-      i += 2;
-      while (i < lines.length && isTableRow(lines[i])) {
-        const cells = splitRow(lines[i]);
-        const row = {};
-        for (let c = 0; c < norm.length; c++) row[norm[c]] = (cells[c] ?? '').trim();
-        const entry = rowToOverride(row);
-        if (entry) out.push(entry);
-        i++;
-      }
-      return out;
-    }
-    i++;
-  }
-  return out;
-}
-
-function isTableRow(line) {
-  return typeof line === 'string' && line.trim().startsWith('|') && line.trim().endsWith('|');
-}
-
-function splitRow(line) {
-  // Strip leading/trailing pipes then split on remaining pipes.
-  const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, '');
-  return trimmed.split('|').map((s) => s.trim());
-}
-
-function normalizeHeader(h) {
-  const k = h.trim().toLowerCase();
-  if (k === 'rule-id' || k === 'rule id' || k === 'ruleid') return 'ruleId';
-  if (k === 'scope' || k === 'scope-glob' || k === 'scopeglob') return 'scopeGlob';
-  return k;
-}
-
-function rowToOverride(row) {
-  const ruleId = row.ruleId;
-  if (!ruleId) return null;
-  // Skip markdown placeholder markers like `_none yet_`, `_pending_`, `n/a`.
-  if (/^_.*_$/.test(ruleId) || /^n\/a$/i.test(ruleId)) return null;
-  const scopeGlob = row.scopeGlob || '*';
-  const reason = row.reason || '';
-  const owner = row.owner ? row.owner : null;
-  const expires = parseExpires(row.expires);
-  return { ruleId, scopeGlob, reason, expires, owner };
-}
-
-function parseExpires(raw) {
-  if (!raw) return null;
-  const v = raw.trim();
-  if (!v || /^_.*_$/.test(v) || /^n\/a$/i.test(v) || v === '-') return null;
-  const d = new Date(v);
-  if (Number.isNaN(d.getTime())) return null;
-  return d;
-}
-
-// --- filterExpired ---------------------------------------------------------
-// Pure partition. `now` is REQUIRED — callers pass `new Date()` in production
-// and a fixed Date instance in tests. Entries with expires: null never expire.
-export function filterExpired(overrides, now) {
-  if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
-    throw new TypeError('filterExpired(overrides, now): `now` must be a valid Date instance');
-  }
-  const active = [];
-  const expired = [];
-  for (const o of overrides) {
-    if (o.expires && o.expires.getTime() < now.getTime()) expired.push(o);
-    else active.push(o);
-  }
-  return { active, expired };
-}
-
-// --- glob matching for logical IDs ----------------------------------------
-// Tiny `*` → `.*` translator; `?` → `.`. `global` and `*` both mean match-all.
-// We intentionally don't pull a glob lib — overrides scope is a single token
-// against a CFN logical ID (alphanumeric), so the surface is small.
-export function matchesGlob(glob, value) {
-  if (!glob || glob === '*' || glob.toLowerCase() === 'global') return true;
-  const re = globToRegex(glob);
-  return re.test(value);
-}
-
-function globToRegex(glob) {
-  let out = '^';
-  for (const ch of glob) {
-    if (ch === '*') out += '.*';
-    else if (ch === '?') out += '.';
-    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
-  }
-  out += '$';
-  return new RegExp(out);
-}
-
-// --- injectSuppressions ----------------------------------------------------
-// For each resource in the template, append (deduped) any overrides whose
-// scopeGlob matches the logical ID to Metadata.guard.SuppressedRules. Does
-// NOT clobber pre-existing inline entries — a resource may legitimately carry
-// one (and detectUnauthorizedSuppressions decides if that's allowed).
-//
-// Returns the modified YAML string (long-form intrinsics — see schema note
-// at top of file).
-export function injectSuppressions(templateYaml, activeOverrides) {
-  let doc;
-  try {
-    doc = yaml.load(templateYaml, { schema: CFN_SCHEMA });
-  } catch {
-    // Unknown short tag (e.g. `!Length`, language-extension tags we don't
-    // have a construct for), or any other YAML parse error. Returning the
-    // input unchanged preserves the contract "injection is best-effort, never
-    // a deploy-gate crash" — the real linters (cfn-lint / cfn-nag / cfn-guard)
-    // still run against the original file and will surface the parse problem
-    // with their own diagnostics.
-    return templateYaml;
-  }
-  if (!doc || typeof doc !== 'object' || !doc.Resources || typeof doc.Resources !== 'object') {
-    return templateYaml;
-  }
-  for (const [logicalId, resource] of Object.entries(doc.Resources)) {
-    if (!resource || typeof resource !== 'object') continue;
-    const ruleIds = [];
-    for (const o of activeOverrides) {
-      if (matchesGlob(o.scopeGlob, logicalId)) ruleIds.push(o.ruleId);
-    }
-    if (ruleIds.length === 0) continue;
-    resource.Metadata = resource.Metadata || {};
-    resource.Metadata.guard = resource.Metadata.guard || {};
-    const existing = Array.isArray(resource.Metadata.guard.SuppressedRules)
-      ? resource.Metadata.guard.SuppressedRules
-      : [];
-    const merged = Array.from(new Set([...existing, ...ruleIds]));
-    resource.Metadata.guard.SuppressedRules = merged;
-  }
-  return yaml.dump(doc, { schema: CFN_SCHEMA, lineWidth: 200, noRefs: true });
-}
-
-// --- detectUnauthorizedSuppressions ---------------------------------------
-// Walk the ORIGINAL template (not the injected copy) and return any inline
-// Metadata.guard.SuppressedRules entries that are NOT covered by an active
-// override row. "Covered" = some active override matches BOTH the resource's
-// logical ID (scopeGlob) AND the suppressed rule ID. This is the anti-rot
-// check — a hand-edited suppression in YAML must trace back to an audited row.
-export function detectUnauthorizedSuppressions(templateYaml, activeOverrides) {
-  const findings = [];
-  let doc;
-  try {
-    doc = yaml.load(templateYaml, { schema: CFN_SCHEMA });
-  } catch {
-    // Same rationale as injectSuppressions: an unknown tag must not turn the
-    // anti-rot check into a Node crash that takes down the whole validate
-    // pipeline. The linters will report the parse problem; we report no
-    // unauthorized suppressions because we couldn't see them.
-    return findings;
-  }
-  if (!doc || typeof doc !== 'object' || !doc.Resources || typeof doc.Resources !== 'object') {
-    return findings;
-  }
-  for (const [logicalId, resource] of Object.entries(doc.Resources)) {
-    if (!resource || typeof resource !== 'object') continue;
-    const suppressed = resource?.Metadata?.guard?.SuppressedRules;
-    if (!Array.isArray(suppressed)) continue;
-    for (const ruleId of suppressed) {
-      const covered = activeOverrides.some(
-        (o) => o.ruleId === ruleId && matchesGlob(o.scopeGlob, logicalId),
-      );
-      if (!covered) findings.push({ resourceId: logicalId, ruleId });
-    }
-  }
-  return findings;
-}
+// Lint-override loader + cfn-guard SuppressedRules wrapper.
+//
+// Reads rules/lint-overrides.md (the single, audited allowlist), turns its
+// Markdown table into structured overrides, partitions expired rows, injects
+// the active ones into a CFN template's Metadata.guard.SuppressedRules so
+// cfn-guard skips them, and detects in-template suppressions that lack an
+// overrides-file row (anti-rot — "suppression without justification").
+//
+// Functions are pure where possible: every time-sensitive call (filterExpired)
+// takes the current Date as an argument so tests are deterministic. Callers
+// (src/commands/validate.js) supply `new Date()` at the call site.
+//
+// YAML round-trip uses the shared CFN short-tag schema in src/lib/cfn-yaml.js.
+// iam-audit / graph.js still carry local copies — they COULD import src/lib via
+// the same upward-probe graph.js already uses for project-config.js; folding
+// them onto cfn-yaml.js is a worthwhile follow-up (the copies have drifted
+// before: graph.js was missing `!Transform` until 1.2.0). The schema is
+// construct-only, so `!Sub "x"` round-trips to `Fn::Sub: x` — both forms are
+// valid CloudFormation and cfn-guard accepts either.
+
+import { readFileSync, existsSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { CFN_SCHEMA } from './cfn-yaml.js';
+
+// --- loadOverrides ---------------------------------------------------------
+// Parse the Markdown table in rules/lint-overrides.md and return an array of
+//   { ruleId, scopeGlob, reason, expires, owner }
+//
+// Header-name driven: we normalize `rule-id` → `ruleId`, `scope` → `scopeGlob`.
+// The doc's `tool` column is read but discarded (cfn-guard SuppressedRules
+// don't distinguish source). `owner` is optional and defaults to null when the
+// column is absent or empty.
+//
+// Placeholder rows (empty rule-id, or markdown-italic markers like `_none yet_`)
+// are skipped — the bundled doc ships with one such row by design.
+//
+// Missing file: returns [] (a fresh consumer with no overrides is a valid
+// state, mirroring the legacy_prefixes contract).
+export function loadOverrides(mdPath) {
+  if (!existsSync(mdPath)) return [];
+  const text = readFileSync(mdPath, 'utf8');
+  return parseOverridesMarkdown(text);
+}
+
+export function parseOverridesMarkdown(text) {
+  const lines = text.split(/\r?\n/);
+  // Find the first table whose header includes a "rule-id" column.
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (isTableRow(line)) {
+      const header = splitRow(line);
+      const norm = header.map(normalizeHeader);
+      const idIdx = norm.indexOf('ruleId');
+      if (idIdx === -1) { i++; continue; }
+      // Next line should be the separator (|---|---|...). Skip it.
+      const sep = lines[i + 1];
+      if (!sep || !/^\s*\|?\s*:?-{2,}/.test(sep.trim())) { i++; continue; }
+      i += 2;
+      while (i < lines.length && isTableRow(lines[i])) {
+        const cells = splitRow(lines[i]);
+        const row = {};
+        for (let c = 0; c < norm.length; c++) row[norm[c]] = (cells[c] ?? '').trim();
+        const entry = rowToOverride(row);
+        if (entry) out.push(entry);
+        i++;
+      }
+      return out;
+    }
+    i++;
+  }
+  return out;
+}
+
+function isTableRow(line) {
+  return typeof line === 'string' && line.trim().startsWith('|') && line.trim().endsWith('|');
+}
+
+function splitRow(line) {
+  // Strip leading/trailing pipes then split on remaining pipes.
+  const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return trimmed.split('|').map((s) => s.trim());
+}
+
+function normalizeHeader(h) {
+  const k = h.trim().toLowerCase();
+  if (k === 'rule-id' || k === 'rule id' || k === 'ruleid') return 'ruleId';
+  if (k === 'scope' || k === 'scope-glob' || k === 'scopeglob') return 'scopeGlob';
+  return k;
+}
+
+function rowToOverride(row) {
+  const ruleId = row.ruleId;
+  if (!ruleId) return null;
+  // Skip markdown placeholder markers like `_none yet_`, `_pending_`, `n/a`.
+  if (/^_.*_$/.test(ruleId) || /^n\/a$/i.test(ruleId)) return null;
+  const scopeGlob = row.scopeGlob || '*';
+  const reason = row.reason || '';
+  const owner = row.owner ? row.owner : null;
+  const expires = parseExpires(row.expires);
+  return { ruleId, scopeGlob, reason, expires, owner };
+}
+
+function parseExpires(raw) {
+  if (!raw) return null;
+  const v = raw.trim();
+  if (!v || /^_.*_$/.test(v) || /^n\/a$/i.test(v) || v === '-') return null;
+  const d = new Date(v);
+  if (Number.isNaN(d.getTime())) return null;
+  return d;
+}
+
+// --- filterExpired ---------------------------------------------------------
+// Pure partition. `now` is REQUIRED — callers pass `new Date()` in production
+// and a fixed Date instance in tests. Entries with expires: null never expire.
+export function filterExpired(overrides, now) {
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) {
+    throw new TypeError('filterExpired(overrides, now): `now` must be a valid Date instance');
+  }
+  const active = [];
+  const expired = [];
+  for (const o of overrides) {
+    if (o.expires && o.expires.getTime() < now.getTime()) expired.push(o);
+    else active.push(o);
+  }
+  return { active, expired };
+}
+
+// --- glob matching for logical IDs ----------------------------------------
+// Tiny `*` → `.*` translator; `?` → `.`. `global` and `*` both mean match-all.
+// We intentionally don't pull a glob lib — overrides scope is a single token
+// against a CFN logical ID (alphanumeric), so the surface is small.
+export function matchesGlob(glob, value) {
+  if (!glob || glob === '*' || glob.toLowerCase() === 'global') return true;
+  const re = globToRegex(glob);
+  return re.test(value);
+}
+
+function globToRegex(glob) {
+  let out = '^';
+  for (const ch of glob) {
+    if (ch === '*') out += '.*';
+    else if (ch === '?') out += '.';
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  out += '$';
+  return new RegExp(out);
+}
+
+// --- injectSuppressions ----------------------------------------------------
+// For each resource in the template, append (deduped) any overrides whose
+// scopeGlob matches the logical ID to Metadata.guard.SuppressedRules. Does
+// NOT clobber pre-existing inline entries — a resource may legitimately carry
+// one (and detectUnauthorizedSuppressions decides if that's allowed).
+//
+// Returns the modified YAML string (long-form intrinsics — see schema note
+// at top of file).
+export function injectSuppressions(templateYaml, activeOverrides) {
+  let doc;
+  try {
+    doc = yaml.load(templateYaml, { schema: CFN_SCHEMA });
+  } catch {
+    // Unknown short tag (e.g. `!Length`, language-extension tags we don't
+    // have a construct for), or any other YAML parse error. Returning the
+    // input unchanged preserves the contract "injection is best-effort, never
+    // a deploy-gate crash" — the real linters (cfn-lint / cfn-nag / cfn-guard)
+    // still run against the original file and will surface the parse problem
+    // with their own diagnostics.
+    return templateYaml;
+  }
+  if (!doc || typeof doc !== 'object' || !doc.Resources || typeof doc.Resources !== 'object') {
+    return templateYaml;
+  }
+  for (const [logicalId, resource] of Object.entries(doc.Resources)) {
+    if (!resource || typeof resource !== 'object') continue;
+    const ruleIds = [];
+    for (const o of activeOverrides) {
+      if (matchesGlob(o.scopeGlob, logicalId)) ruleIds.push(o.ruleId);
+    }
+    if (ruleIds.length === 0) continue;
+    resource.Metadata = resource.Metadata || {};
+    resource.Metadata.guard = resource.Metadata.guard || {};
+    const existing = Array.isArray(resource.Metadata.guard.SuppressedRules)
+      ? resource.Metadata.guard.SuppressedRules
+      : [];
+    const merged = Array.from(new Set([...existing, ...ruleIds]));
+    resource.Metadata.guard.SuppressedRules = merged;
+  }
+  return yaml.dump(doc, { schema: CFN_SCHEMA, lineWidth: 200, noRefs: true });
+}
+
+// --- detectUnauthorizedSuppressions ---------------------------------------
+// Walk the ORIGINAL template (not the injected copy) and return any inline
+// Metadata.guard.SuppressedRules entries that are NOT covered by an active
+// override row. "Covered" = some active override matches BOTH the resource's
+// logical ID (scopeGlob) AND the suppressed rule ID. This is the anti-rot
+// check — a hand-edited suppression in YAML must trace back to an audited row.
+export function detectUnauthorizedSuppressions(templateYaml, activeOverrides) {
+  const findings = [];
+  let doc;
+  try {
+    doc = yaml.load(templateYaml, { schema: CFN_SCHEMA });
+  } catch {
+    // Same rationale as injectSuppressions: an unknown tag must not turn the
+    // anti-rot check into a Node crash that takes down the whole validate
+    // pipeline. The linters will report the parse problem; we report no
+    // unauthorized suppressions because we couldn't see them.
+    return findings;
+  }
+  if (!doc || typeof doc !== 'object' || !doc.Resources || typeof doc.Resources !== 'object') {
+    return findings;
+  }
+  for (const [logicalId, resource] of Object.entries(doc.Resources)) {
+    if (!resource || typeof resource !== 'object') continue;
+    const suppressed = resource?.Metadata?.guard?.SuppressedRules;
+    if (!Array.isArray(suppressed)) continue;
+    for (const ruleId of suppressed) {
+      const covered = activeOverrides.some(
+        (o) => o.ruleId === ruleId && matchesGlob(o.scopeGlob, logicalId),
+      );
+      if (!covered) findings.push({ resourceId: logicalId, ruleId });
+    }
+  }
+  return findings;
+}

package/src/lib/logger.js

@@ -1,17 +1,17 @@
 import chalk from 'chalk';
-import { readEnv } from './rename-compat.js';
-
-const ts = () => new Date().toISOString().slice(11, 19);
-
-export const logger = {
-  info: (msg) => console.log(`${chalk.gray(ts())} ${chalk.cyan('•')} ${msg}`),
-  ok: (msg) => console.log(`${chalk.gray(ts())} ${chalk.green('✓')} ${msg}`),
-  warn: (msg) => console.warn(`${chalk.gray(ts())} ${chalk.yellow('!')} ${msg}`),
-  error: (msg) => console.error(`${chalk.gray(ts())} ${chalk.red('✗')} ${msg}`),
-  step: (msg) => console.log(`${chalk.gray(ts())} ${chalk.magenta('→')} ${chalk.bold(msg)}`),
-  debug: (msg) => {
-    if (readEnv('DEBUG')) {
-      console.log(`${chalk.gray(ts())} ${chalk.gray('debug')} ${chalk.gray(msg)}`);
-    }
-  },
-};
+import { readEnv } from './rename-compat.js';
+
+const ts = () => new Date().toISOString().slice(11, 19);
+
+export const logger = {
+  info: (msg) => console.log(`${chalk.gray(ts())} ${chalk.cyan('•')} ${msg}`),
+  ok: (msg) => console.log(`${chalk.gray(ts())} ${chalk.green('✓')} ${msg}`),
+  warn: (msg) => console.warn(`${chalk.gray(ts())} ${chalk.yellow('!')} ${msg}`),
+  error: (msg) => console.error(`${chalk.gray(ts())} ${chalk.red('✗')} ${msg}`),
+  step: (msg) => console.log(`${chalk.gray(ts())} ${chalk.magenta('→')} ${chalk.bold(msg)}`),
+  debug: (msg) => {
+    if (readEnv('DEBUG')) {
+      console.log(`${chalk.gray(ts())} ${chalk.gray('debug')} ${chalk.gray(msg)}`);
+    }
+  },
+};