@kaitranntt/ccs 8.4.0-dev.10 → 8.4.0-dev.12

package/scripts/generate-throw-error-baseline.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Generate the baseline allowlist for eslint-rules/no-new-throw-error.js.
+ *
+ * Walks src/ (non-test), finds every `throw new Error(...)` site using the same
+ * comment-stripping as scripts/maintainability-metrics.js (so the baseline
+ * matches what the ESLint AST sees — comments are not ThrowStatement nodes),
+ * and writes eslint-rules/throw-error-baseline.json as a sorted array of
+ * `${relativePath}:${line}` keys.
+ *
+ * Run after intentionally adding a new grandfathered throw, or quarterly to
+ * prune entries that have since been converted to typed errors.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const SRC_DIR = path.join(ROOT_DIR, 'src');
+const OUTPUT_PATH = path.join(ROOT_DIR, 'eslint-rules', 'throw-error-baseline.json');
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const THROW_NEW_ERROR_REGEX = /\bthrow\s+new\s+Error\s*\(/g;
+
+function isTestPath(relPath) {
+  return (
+    /(?:^|\/)(?:__tests__|tests?)\//.test(relPath) ||
+    /\.test\./.test(relPath) ||
+    /\.spec\./.test(relPath)
+  );
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+function relPath(fullPath) {
+  return toPosix(path.relative(ROOT_DIR, fullPath));
+}
+
+// Lazy require: hardening-inventory.js requires this module's sibling maintainability-metrics.js
+// at top level; requiring it back at top level here would capture a partial module.exports.
+// A function-scope require resolves against the fully-loaded module at call time.
+function stripCommentsOnce(sourceText) {
+  return require('./hardening-inventory.js').stripComments(sourceText);
+}
+
+function walkFiles(dirPath) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+    const full = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      out.push.apply(out, walkFiles(full));
+    } else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(full))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function collectSites() {
+  const sites = [];
+  for (const full of walkFiles(SRC_DIR)) {
+    const rel = relPath(full);
+    if (isTestPath(rel)) continue;
+    // Match on the RAW source (not comment-stripped). ESLint lints the raw
+    // file, so the baseline must reflect real throw lines as the AST sees them.
+    // stripComments can undercount on files whose regex/template literals confuse
+    // its state machine; raw matching is a superset (may include comment/string
+    // mentions, which are harmless unused allowlist entries) and never undercounts.
+    const sourceText = fs.readFileSync(full, 'utf8');
+    const re = new RegExp(THROW_NEW_ERROR_REGEX.source, 'g');
+    let match;
+    while ((match = re.exec(sourceText)) !== null) {
+      const line = sourceText.slice(0, match.index).split(/\r?\n/).length;
+      sites.push(`${rel}:${line}`);
+    }
+  }
+  return sites.sort();
+}
+
+function main() {
+  const sites = collectSites();
+  fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(sites, null, 2) + '\n', 'utf8');
+  console.log(`[throw-error-baseline] ${sites.length} sites -> ${relPath(OUTPUT_PATH)}`);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { collectSites, OUTPUT_PATH };

package/scripts/hardening-inventory.js

@@ -3,6 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { collectMaintainabilityMetrics } = require('./maintainability-metrics.js');
+
 const ROOT_DIR = path.resolve(__dirname, '..');
 const SRC_DIR = path.join(ROOT_DIR, 'src');
 const REPORT_DIR = path.join(ROOT_DIR, 'docs', 'reports');
@@ -430,6 +432,7 @@ function buildReport() {
           .filter((file) => /shim|re-export|compat/i.test(path.basename(file)))
       ),
     },
+    maintainability: collectMaintainabilityMetrics(ROOT_DIR),
   };
 }
 
@@ -489,6 +492,55 @@ function renderMarkdown(report) {
     lines.push('- _none_');
   }
 
+  const m = report.maintainability;
+  if (m) {
+    lines.push('## Maintainability Metrics');
+    lines.push('');
+    lines.push('| Metric | Value |');
+    lines.push('|---|---:|');
+    lines.push(
+      `| typed-error adoption (typed/total throws) | ${(m.typedErrors.adoptionRatio * 100).toFixed(1)}% (${m.typedErrors.typedThrows}/${m.typedErrors.totalThrows}) |`
+    );
+    lines.push(
+      `| typed-error adoption (P4 locked subdomains) | ${(m.typedErrorAdoption.ratio * 100).toFixed(1)}% (${m.typedErrorAdoption.numerator}/${m.typedErrorAdoption.denominator}), target 40% |`
+    );
+    lines.push(
+      `| hotpath console.error/warn occurrences | ${m.hotpathConsoleErrors.hotpathOccurrences} (${m.hotpathConsoleErrors.totalOccurrences} total, ${m.hotpathConsoleErrors.exemptOccurrences} CLI-UX exempt) |`
+    );
+    lines.push(`| hotpath console.error/warn files | ${m.hotpathConsoleErrors.filesAffected} |`);
+    lines.push(
+      `| files with createLogger | ${m.loggerCoverage.filesWithCreateLogger}/${m.loggerCoverage.totalSourceFiles} |`
+    );
+    lines.push(
+      `| subdomains with zero createLogger | ${m.loggerCoverage.subdomainsWithZeroCreateLogger.length} (${m.loggerCoverage.subdomainsWithZeroCreateLogger.join(', ') || 'none'}) |`
+    );
+    lines.push(`| files > 400 LOC | ${m.largeFiles.countOver400} |`);
+    lines.push(`| files > 600 LOC | ${m.largeFiles.countOver600} |`);
+    lines.push('');
+    lines.push('### Top Hotpath console.error/warn Files');
+    lines.push('');
+    lines.push('| File | console.error/warn |');
+    lines.push('|---|---:|');
+    for (const item of m.hotpathConsoleErrors.topFiles) {
+      lines.push(`| \`${item.file}\` | ${item.count} |`);
+    }
+    if (m.hotpathConsoleErrors.topFiles.length === 0) {
+      lines.push('| _none_ | 0 |');
+    }
+    lines.push('');
+    lines.push('### Files > 400 LOC (top 15)');
+    lines.push('');
+    lines.push('| File | LOC |');
+    lines.push('|---|---:|');
+    for (const item of m.largeFiles.topOver400) {
+      lines.push(`| \`${item.file}\` | ${item.loc} |`);
+    }
+    if (m.largeFiles.topOver400.length === 0) {
+      lines.push('| _none_ | 0 |');
+    }
+    lines.push('');
+  }
+
   lines.push('');
   return lines.join('\n');
 }
@@ -510,17 +562,23 @@ function main() {
   console.log(
     `[hardening-inventory] legacy markers total=${report.legacyShim.totalMarkers}, files=${report.legacyShim.filesAffected}`
   );
+  if (report.maintainability) {
+    const mt = report.maintainability;
+    console.log(
+      `[hardening-inventory] maintainability: typed-adoption=${(mt.typedErrors.adoptionRatio * 100).toFixed(1)}% (${mt.typedErrors.typedThrows}/${mt.typedErrors.totalThrows}), locked=${(mt.typedErrorAdoption.ratio * 100).toFixed(1)}% (${mt.typedErrorAdoption.numerator}/${mt.typedErrorAdoption.denominator}), console.error=${mt.hotpathConsoleErrors.hotpathOccurrences}, zero-logger-subdomains=${mt.loggerCoverage.subdomainsWithZeroCreateLogger.length}, >400LOC=${mt.largeFiles.countOver400}`
+    );
+  }
   console.log(`[hardening-inventory] wrote ${relJson}`);
   console.log(`[hardening-inventory] wrote ${relMd}`);
 }
 
-if (require.main === module) {
-  main();
-}
-
 module.exports = {
   buildReport,
   collectSyncCallSites,
   renderMarkdown,
   stripComments,
 };
+
+if (require.main === module) {
+  main();
+}

package/scripts/maintainability-metrics.js

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+
+/**
+ * Maintainability metrics collector for the CCS CLI maintainability epic.
+ *
+ * Computes the metrics the epic tracks across phases:
+ *   - typed-error adoption (throw new <TypedError> vs throw new Error vs other)
+ *   - createLogger coverage by subdomain (which subdomains have zero)
+ *   - hotpath console.error / console.warn call-site count (CLI-UX exempt)
+ *   - files > 400 / 600 LOC
+ *   - typed-error adoption in the P4 LOCKED denominator subdomains
+ *
+ * Accuracy relies on stripping comments/strings before regex matching. We
+ * reuse hardening-inventory.js#stripComments for that. The require is lazy
+ * (inside sanitize()) because hardening-inventory.js requires THIS module at
+ * its top level; a top-level require back would capture hardening-inventory's
+ * partial module.exports during the load cycle (it reassigns module.exports at
+ * the bottom). A function-scope require resolves against the fully-loaded
+ * module at call time, so the cycle is harmless.
+ *
+ * Approximate by design (grep-based). Method documented in
+ * docs/hardening-debt-burndown.md. Re-baseline when the schema changes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+
+// CCSError subclasses (src/errors/error-types.ts). A `throw new <OneOfThese>`
+// counts as TYPED. `throw new Error(...)` is plain. Any other `throw new X(`
+// is "other" (error subclass outside the canonical taxonomy).
+const TYPED_ERROR_CLASSES = new Set([
+  'CCSError',
+  'ConfigError',
+  'NetworkError',
+  'AuthError',
+  'BinaryError',
+  'ProviderError',
+  'ProfileError',
+  'ProxyError',
+  'MigrationError',
+  'UserAbortError',
+  'ValidationError',
+  'RetryableError',
+]);
+
+// P4 LOCKED denominator: typed-error adoption is measured ONLY over these
+// subdomains so the >40% goal cannot be gamed by narrowing scope. Emits both
+// numerator and denominator counts alongside the ratio.
+const TYPED_ADOPTION_SUBDOMAINS = ['cliproxy/quota', 'cliproxy/auth', 'web-server/routes', 'auth'];
+
+// CLI-UX print surfaces exempt from the hotpath console.error sweep (P3).
+// Diagnostics here are legitimate user-facing terminal output, not loggable
+// errors, and stay on stdout/stderr via utils/ui. src/utils/error-manager.ts is
+// the user-facing error display module (ErrorManager.show*), a sibling to
+// utils/ui, so its console.error calls are display output, not diagnostics.
+const CLI_UX_EXEMPT_PREFIXES = [
+  'src/commands/',
+  'src/management/',
+  'src/utils/ui/',
+  'src/utils/error-manager.ts',
+];
+
+const THROW_NEW_REGEX = /\bthrow\s+new\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g;
+const CONSOLE_ERR_WARN_REGEX = /\bconsole\s*\.\s*(?:error|warn)\s*\(/g;
+const CREATE_LOGGER_REGEX = /\bcreateLogger\s*\(/;
+
+function sanitize(sourceText) {
+  // Lazy require; see module header for the circular-dependency rationale.
+  return require('./hardening-inventory.js').stripComments(sourceText);
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function isSourceFile(filePath) {
+  return SOURCE_EXTENSIONS.has(path.extname(filePath));
+}
+
+function isTestFile(relPath) {
+  return (
+    /(?:^|\/)(?:__tests__|tests?)\//.test(relPath) ||
+    /\.test\./.test(relPath) ||
+    /\.spec\./.test(relPath)
+  );
+}
+
+function isCliUxExempt(relPath) {
+  return CLI_UX_EXEMPT_PREFIXES.some(function (prefix) {
+    return relPath.startsWith(prefix);
+  });
+}
+
+/**
+ * Subdomain key for a src-relative path.
+ *   src/cliproxy/quota/x.ts -> "cliproxy/quota"
+ *   src/auth/x.ts           -> "auth"
+ *   src/x.ts                -> "<root>"
+ */
+function subdomainOf(relPath) {
+  const rest = relPath.replace(/^src\//, '');
+  const parts = rest.split('/');
+  if (parts[0] === 'cliproxy' && parts.length > 2) {
+    return parts[0] + '/' + parts[1];
+  }
+  return parts[0] || '<root>';
+}
+
+function round4(n) {
+  return Math.round(n * 10000) / 10000;
+}
+
+// Items may be file-shaped ({file,count}) or subdomain-shaped ({subdomain,count});
+// the tiebreaker key is whichever label field is present.
+function labelOf(item) {
+  return item.file || item.subdomain || '';
+}
+
+function topByCount(items, limit) {
+  return items
+    .slice()
+    .sort(function (a, b) {
+      return b.count - a.count || labelOf(a).localeCompare(labelOf(b));
+    })
+    .slice(0, limit);
+}
+
+/** Classify `throw new X(` occurrences in sanitized source. */
+function classifyThrows(sourceText) {
+  const sanitized = sanitize(sourceText);
+  const counts = { typed: 0, plain: 0, other: 0, total: 0 };
+  const re = new RegExp(THROW_NEW_REGEX.source, 'g');
+  let match;
+  while ((match = re.exec(sanitized)) !== null) {
+    const identifier = match[1];
+    counts.total += 1;
+    if (identifier === 'Error') {
+      counts.plain += 1;
+    } else if (TYPED_ERROR_CLASSES.has(identifier)) {
+      counts.typed += 1;
+    } else {
+      counts.other += 1;
+    }
+  }
+  return counts;
+}
+
+/** Count console.error / console.warn call sites in sanitized source. */
+function countConsoleErrors(sourceText) {
+  const sanitized = sanitize(sourceText);
+  const re = new RegExp(CONSOLE_ERR_WARN_REGEX.source, 'g');
+  return (sanitized.match(re) || []).length;
+}
+
+/** True if the file directly creates a logger via createLogger(...). */
+function hasCreateLogger(sourceText) {
+  return CREATE_LOGGER_REGEX.test(sanitize(sourceText));
+}
+
+/** Raw line count of a source file (matches `wc -l` content semantics). */
+function countLoc(sourceText) {
+  if (!sourceText) return 0;
+  const parts = sourceText.split(/\r?\n/);
+  return sourceText.endsWith('\n') ? parts.length - 1 : parts.length;
+}
+
+function walkFiles(dirPath) {
+  const output = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch (_err) {
+    return output;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      output.push.apply(output, walkFiles(fullPath));
+      continue;
+    }
+    if (entry.isFile() && isSourceFile(fullPath)) output.push(fullPath);
+  }
+  return output;
+}
+
+function emptyAggregates() {
+  return {
+    typedBySubdomain: {},
+    loggerBySubdomain: {},
+    hotpathByFile: [],
+    hotpathTotal: 0,
+    hotpathExempt: 0,
+    hotpathNonExempt: 0,
+    hotpathFilesAffected: 0,
+    filesWithLogger: 0,
+    totalSourceFiles: 0,
+    typedTotal: 0,
+    typedTyped: 0,
+    typedPlain: 0,
+    typedOther: 0,
+    over400: [],
+    over600: [],
+  };
+}
+
+function ensureBucket(obj, key, factory) {
+  if (!obj[key]) obj[key] = factory();
+  return obj[key];
+}
+
+/**
+ * Walk <rootDir>/src and aggregate maintainability metrics.
+ * Returns the `maintainability` block merged into the hardening inventory.
+ */
+function collectMaintainabilityMetrics(rootDir) {
+  const srcDir = path.join(rootDir, 'src');
+  const files = walkFiles(srcDir);
+  const agg = emptyAggregates();
+
+  for (const fullPath of files) {
+    const relPath = toPosixPath(path.relative(rootDir, fullPath));
+    if (isTestFile(relPath)) continue;
+    const sourceText = fs.readFileSync(fullPath, 'utf8');
+    const sub = subdomainOf(relPath);
+
+    const throws = classifyThrows(sourceText);
+    agg.typedTotal += throws.total;
+    agg.typedTyped += throws.typed;
+    agg.typedPlain += throws.plain;
+    agg.typedOther += throws.other;
+    if (throws.total > 0) {
+      const bucket = ensureBucket(agg.typedBySubdomain, sub, function () {
+        return { typed: 0, plain: 0, other: 0, total: 0 };
+      });
+      bucket.typed += throws.typed;
+      bucket.plain += throws.plain;
+      bucket.other += throws.other;
+      bucket.total += throws.total;
+    }
+
+    agg.totalSourceFiles += 1;
+    const hasLogger = hasCreateLogger(sourceText);
+    if (hasLogger) agg.filesWithLogger += 1;
+    const lc = ensureBucket(agg.loggerBySubdomain, sub, function () {
+      return { files: 0, withLogger: 0 };
+    });
+    lc.files += 1;
+    if (hasLogger) lc.withLogger += 1;
+
+    const ce = countConsoleErrors(sourceText);
+    if (ce > 0) {
+      agg.hotpathTotal += ce;
+      if (isCliUxExempt(relPath)) {
+        agg.hotpathExempt += ce;
+      } else {
+        agg.hotpathNonExempt += ce;
+        agg.hotpathFilesAffected += 1;
+        agg.hotpathByFile.push({ file: relPath, count: ce });
+      }
+    }
+
+    const loc = countLoc(sourceText);
+    if (loc > 600) agg.over600.push({ file: relPath, loc: loc });
+    if (loc > 400) agg.over400.push({ file: relPath, loc: loc });
+  }
+
+  const adoptionRatio = agg.typedTotal > 0 ? agg.typedTyped / agg.typedTotal : 0;
+
+  let numerator = 0;
+  let denominator = 0;
+  for (const sub of TYPED_ADOPTION_SUBDOMAINS) {
+    const bucket = agg.typedBySubdomain[sub];
+    if (bucket) {
+      numerator += bucket.typed;
+      denominator += bucket.total;
+    }
+  }
+  const typedAdoptionRatio = denominator > 0 ? numerator / denominator : 0;
+
+  const subdomainsWithZeroCreateLogger = Object.keys(agg.loggerBySubdomain)
+    .filter(function (k) {
+      return agg.loggerBySubdomain[k].files > 0 && agg.loggerBySubdomain[k].withLogger === 0;
+    })
+    .sort();
+
+  const topOver400 = agg.over400
+    .slice()
+    .sort(function (a, b) {
+      return b.loc - a.loc || a.file.localeCompare(b.file);
+    })
+    .slice(0, 15);
+
+  return {
+    typedErrors: {
+      totalThrows: agg.typedTotal,
+      typedThrows: agg.typedTyped,
+      plainThrows: agg.typedPlain,
+      otherThrows: agg.typedOther,
+      adoptionRatio: round4(adoptionRatio),
+      topSubdomainsByThrows: topByCount(
+        Object.keys(agg.typedBySubdomain).map(function (k) {
+          const v = agg.typedBySubdomain[k];
+          return { subdomain: k, count: v.total, typed: v.typed, plain: v.plain };
+        }),
+        10
+      ),
+    },
+    typedErrorAdoption: {
+      subdomains: TYPED_ADOPTION_SUBDOMAINS.slice(),
+      numerator: numerator,
+      denominator: denominator,
+      ratio: round4(typedAdoptionRatio),
+      targetRatio: 0.4,
+    },
+    loggerCoverage: {
+      filesWithCreateLogger: agg.filesWithLogger,
+      totalSourceFiles: agg.totalSourceFiles,
+      coverageRatio: round4(
+        agg.totalSourceFiles > 0 ? agg.filesWithLogger / agg.totalSourceFiles : 0
+      ),
+      subdomainsWithZeroCreateLogger: subdomainsWithZeroCreateLogger,
+      topSubdomainsByFiles: topByCount(
+        Object.keys(agg.loggerBySubdomain).map(function (k) {
+          const v = agg.loggerBySubdomain[k];
+          return { subdomain: k, count: v.files, withLogger: v.withLogger };
+        }),
+        10
+      ),
+    },
+    hotpathConsoleErrors: {
+      totalOccurrences: agg.hotpathTotal,
+      exemptOccurrences: agg.hotpathExempt,
+      hotpathOccurrences: agg.hotpathNonExempt,
+      filesAffected: agg.hotpathFilesAffected,
+      topFiles: topByCount(agg.hotpathByFile, 15),
+    },
+    largeFiles: {
+      countOver400: agg.over400.length,
+      countOver600: agg.over600.length,
+      topOver400: topOver400,
+    },
+  };
+}
+
+module.exports = {
+  collectMaintainabilityMetrics: collectMaintainabilityMetrics,
+  classifyThrows: classifyThrows,
+  countConsoleErrors: countConsoleErrors,
+  hasCreateLogger: hasCreateLogger,
+  countLoc: countLoc,
+  TYPED_ERROR_CLASSES: TYPED_ERROR_CLASSES,
+  TYPED_ADOPTION_SUBDOMAINS: TYPED_ADOPTION_SUBDOMAINS,
+};