@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.0

package/scripts/audit-file-size.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-file-size.mjs
+ *
+ * Enforces the 500 LOC threshold on production source files. Files that exceed
+ * the threshold are hard failures unless they declare a justified exception
+ * with a `// @file-size-exception: <reason>` marker in their first 5 lines.
+ *
+ * Scope:
+ *   lib/     all .mjs/.js files
+ *   scripts/ all .mjs/.js files
+ *   bin/     all .js/.mjs files
+ *
+ * Excluded:
+ *   *.test.mjs / *.test.js (test files have different size economics)
+ *
+ * Usage:
+ *   node scripts/audit-file-size.mjs            (human-readable + machine line)
+ *   node scripts/audit-file-size.mjs --json     (JSON only)
+ *
+ * Exit codes:
+ *   0 — all files within budget (or covered by exception)
+ *   1 — at least one file exceeded the threshold without an exception marker
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+
+export const DEFAULT_LOC_THRESHOLD = 500;
+const EXCEPTION_MARKER_PATTERN = /^\s*(?:\/\/|\*)\s*@file-size-exception:\s*(.+?)\s*(?:\*\/\s*)?$/;
+const EXCEPTION_MARKER_LOOKAHEAD_LINES = 5;
+const SCAN_ROOTS = ['lib', 'scripts', 'bin'];
+const SCAN_EXTENSIONS = new Set(['.mjs', '.js']);
+const SKIP_DIRECTORY_NAMES = new Set(['node_modules', '.git', '.agentic-backup', '.benchmarks']);
+
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+function isTestFile(filePath) {
+  const baseName = filePath.split(/[\\/]/).pop();
+  return /\.test\.(mjs|js)$/.test(baseName);
+}
+
+function collectSourceFiles(scanRootName) {
+  const collected = [];
+  const scanRootAbsolutePath = join(REPOSITORY_ROOT, scanRootName);
+
+  function walk(currentPath) {
+    let entries;
+    try {
+      entries = readdirSync(currentPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRECTORY_NAMES.has(entry.name)) {
+        continue;
+      }
+
+      const entryAbsolute = join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryAbsolute);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      const dotIndex = entry.name.lastIndexOf('.');
+      const extension = dotIndex >= 0 ? entry.name.slice(dotIndex) : '';
+      if (!SCAN_EXTENSIONS.has(extension)) {
+        continue;
+      }
+
+      if (isTestFile(entryAbsolute)) {
+        continue;
+      }
+
+      collected.push(entryAbsolute);
+    }
+  }
+
+  try {
+    statSync(scanRootAbsolutePath);
+  } catch {
+    return collected;
+  }
+
+  walk(scanRootAbsolutePath);
+  return collected;
+}
+
+function detectExceptionMarker(sourceLines) {
+  const lookahead = sourceLines.slice(0, EXCEPTION_MARKER_LOOKAHEAD_LINES);
+  for (const line of lookahead) {
+    const match = line.match(EXCEPTION_MARKER_PATTERN);
+    if (match) {
+      return match[1].trim();
+    }
+  }
+  return null;
+}
+
+function inspectFile(filePath, threshold) {
+  const sourceText = readFileSync(filePath, 'utf8');
+  const lines = sourceText.split(/\r?\n/);
+  const lineCount = lines.length;
+  const overThreshold = lineCount > threshold;
+  const exceptionReason = overThreshold ? detectExceptionMarker(lines) : null;
+  const passed = !overThreshold || Boolean(exceptionReason);
+
+  return {
+    filePath: relative(REPOSITORY_ROOT, filePath).replace(/\\/g, '/'),
+    lineCount,
+    threshold,
+    overThreshold,
+    exceptionReason,
+    passed,
+  };
+}
+
+export function runAuditFileSize({ threshold = DEFAULT_LOC_THRESHOLD } = {}) {
+  const scannedFiles = SCAN_ROOTS.flatMap((scanRootName) => collectSourceFiles(scanRootName));
+  const inspections = scannedFiles.map((filePath) => inspectFile(filePath, threshold));
+  const violations = inspections.filter((entry) => entry.overThreshold && !entry.exceptionReason);
+  const exemptedFiles = inspections.filter((entry) => entry.overThreshold && entry.exceptionReason);
+
+  return {
+    auditName: 'audit-file-size',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    threshold,
+    scannedFileCount: inspections.length,
+    overThresholdCount: inspections.filter((entry) => entry.overThreshold).length,
+    violationCount: violations.length,
+    exemptedCount: exemptedFiles.length,
+    violations: violations.map((entry) => ({
+      filePath: entry.filePath,
+      lineCount: entry.lineCount,
+    })),
+    exemptedFiles: exemptedFiles.map((entry) => ({
+      filePath: entry.filePath,
+      lineCount: entry.lineCount,
+      reason: entry.exceptionReason,
+    })),
+    passed: violations.length === 0,
+  };
+}
+
+function formatHumanLine(prefix, entry) {
+  return `  ${prefix} ${entry.filePath} (${entry.lineCount}/${entry.threshold ?? DEFAULT_LOC_THRESHOLD} LOC)`;
+}
+
+function main() {
+  const report = runAuditFileSize();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:file-size — 500 LOC enforcement');
+  console.log('===============================================');
+  console.log(`  Threshold: ${report.threshold} LOC`);
+  console.log(`  Scanned: ${report.scannedFileCount} files`);
+  console.log('');
+
+  if (report.exemptedCount > 0) {
+    console.log('  Exempted (declared @file-size-exception):');
+    for (const entry of report.exemptedFiles) {
+      console.log(`    EXEMPT ${entry.filePath} (${entry.lineCount} LOC) — ${entry.reason}`);
+    }
+    console.log('');
+  }
+
+  if (report.violationCount === 0) {
+    console.log('  All files within budget.');
+    process.stderr.write(`AUDIT_FILE_SIZE_REPORT: ${JSON.stringify({
+      passed: true,
+      scannedFileCount: report.scannedFileCount,
+      violationCount: 0,
+      exemptedCount: report.exemptedCount,
+    })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const entry of report.violations) {
+    console.log(formatHumanLine('FAIL', { ...entry, threshold: report.threshold }));
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} file(s) exceed the ${report.threshold} LOC threshold.`);
+  console.log('  Either split the file into focused submodules or, when justified,');
+  console.log('  declare an exception in the first 5 lines:');
+  console.log('    // @file-size-exception: <reason>');
+  console.log('');
+
+  process.stderr.write(`AUDIT_FILE_SIZE_REPORT: ${JSON.stringify({
+    passed: false,
+    scannedFileCount: report.scannedFileCount,
+    violationCount: report.violationCount,
+    exemptedCount: report.exemptedCount,
+    violations: report.violations,
+  })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-file-size.mjs')) {
+  main();
+}

package/scripts/audit-reflection-citations.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runRuleIdUniquenessAudit } from './audit-rule-id-uniqueness.mjs';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+const RULE_ID_PATTERN = /\b[A-Z]+-\d{3,4}(?:-[A-Z])?\b/g;
+
+const REQUIRED_REFLECTION_SURFACES = [
+  {
+    path: 'AGENTS.md',
+    requiredSnippets: [
+      '## Bounded Reflection',
+      'REFLECTION',
+      'Rules:',
+      'Risk:',
+      'Action:',
+      'valid rule IDs',
+      'hidden chain-of-thought',
+    ],
+  },
+  {
+    path: '.agent-context/review-checklists/pr-checklist.md',
+    requiredSnippets: [
+      'Bounded Reflection',
+      'valid rule IDs',
+      'hidden chain-of-thought',
+    ],
+  },
+];
+
+function readSource(rootDir, relativePath, sourceOverrides) {
+  if (sourceOverrides && Object.prototype.hasOwnProperty.call(sourceOverrides, relativePath)) {
+    return String(sourceOverrides[relativePath]);
+  }
+
+  const absolutePath = join(rootDir, relativePath);
+  if (!existsSync(absolutePath)) {
+    return null;
+  }
+
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function collectKnownRuleIds() {
+  const ruleIdAudit = runRuleIdUniquenessAudit();
+  const knownRuleIds = new Set();
+
+  for (const fileEntry of ruleIdAudit.perFile || []) {
+    for (const ruleId of fileEntry.knownSectionIdsInFile || []) {
+      knownRuleIds.add(ruleId);
+    }
+  }
+
+  return {
+    ruleIdAudit,
+    knownRuleIds,
+  };
+}
+
+function collectRuleIdsFromSource(sourceText) {
+  return Array.from(new Set(sourceText.match(RULE_ID_PATTERN) || [])).sort();
+}
+
+export function runReflectionCitationAudit(options = {}) {
+  const rootDir = options.rootDir ? resolve(String(options.rootDir)) : REPOSITORY_ROOT;
+  const sourceOverrides = options.sourceOverrides || null;
+  const { ruleIdAudit, knownRuleIds } = collectKnownRuleIds();
+  const violations = [];
+  const surfaceReports = [];
+
+  for (const surface of REQUIRED_REFLECTION_SURFACES) {
+    const sourceText = readSource(rootDir, surface.path, sourceOverrides);
+    if (sourceText === null) {
+      violations.push({
+        file: surface.path,
+        kind: 'surface.missing',
+        detail: 'Required reflection citation surface is missing.',
+      });
+      continue;
+    }
+
+    const missingSnippets = surface.requiredSnippets.filter((snippet) => !sourceText.includes(snippet));
+    for (const missingSnippet of missingSnippets) {
+      violations.push({
+        file: surface.path,
+        kind: 'reflection.snippet-missing',
+        detail: `Missing required reflection snippet: ${missingSnippet}`,
+      });
+    }
+
+    const citedRuleIds = collectRuleIdsFromSource(sourceText);
+    const unknownRuleIds = citedRuleIds.filter((ruleId) => !knownRuleIds.has(ruleId));
+    for (const unknownRuleId of unknownRuleIds) {
+      violations.push({
+        file: surface.path,
+        kind: 'rule-id.unknown',
+        detail: `Rule ID ${unknownRuleId} does not resolve to any canonical rule section.`,
+      });
+    }
+
+    surfaceReports.push({
+      path: surface.path,
+      missingSnippetCount: missingSnippets.length,
+      citedRuleIds,
+      unknownRuleIds,
+    });
+  }
+
+  return {
+    auditName: 'audit-reflection-citations',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    surfaceCount: REQUIRED_REFLECTION_SURFACES.length,
+    knownRuleIdCount: knownRuleIds.size,
+    ruleIdAuditPassed: ruleIdAudit.passed,
+    violationCount: violations.length,
+    passed: violations.length === 0,
+    surfaces: surfaceReports,
+    violations,
+  };
+}
+
+function main() {
+  const report = runReflectionCitationAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:reflection-citations');
+  console.log('===============================================');
+  console.log(`  Reflection surfaces: ${report.surfaceCount}`);
+  console.log(`  Known rule IDs:      ${report.knownRuleIdCount}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  Reflection citation surfaces are present and all cited rule IDs resolve.');
+    process.stderr.write(`AUDIT_REFLECTION_CITATIONS_REPORT: ${JSON.stringify({ passed: true, surfaceCount: report.surfaceCount, knownRuleIdCount: report.knownRuleIdCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.file}: ${violation.detail}`);
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} violation(s) found.`);
+  process.stderr.write(`AUDIT_REFLECTION_CITATIONS_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount, kinds: [...new Set(report.violations.map((violation) => violation.kind))] })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-reflection-citations.mjs')) {
+  main();
+}

package/scripts/audit-release-bundle.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-release-bundle.mjs
+ *
+ * Phase 5 Task 5.4 integrity gate. Validates that
+ * benchmarks/results/release-bundle-4.0.0.json exists, references real source
+ * artifacts, and that each recorded SHA-256 hash still matches the current
+ * file content. Wired into npm run validate.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const DEFAULT_BUNDLE_PATH = join(REPOSITORY_ROOT, 'benchmarks', 'results', 'release-bundle-4.0.0.json');
+
+function sha256Hex(buffer) {
+  // Normalize CRLF -> LF before hashing so bundle integrity is reproducible
+  // across platforms (Windows working tree may be CRLF; CI checkouts are LF).
+  const normalized = buffer.toString('utf8').replace(/\r\n/g, '\n');
+  const hash = createHash('sha256');
+  hash.update(normalized, 'utf8');
+  return hash.digest('hex');
+}
+
+export function runReleaseBundleAudit(options = {}) {
+  const rootDir = options.rootDir ? resolve(String(options.rootDir)) : REPOSITORY_ROOT;
+  const bundlePath = options.bundlePath ? resolve(String(options.bundlePath)) : DEFAULT_BUNDLE_PATH;
+  const violations = [];
+
+  if (!existsSync(bundlePath)) {
+    violations.push({
+      kind: 'bundle.missing',
+      detail: `Release bundle is missing at ${bundlePath}. Run scripts/build-release-benchmark-bundle.mjs to regenerate.`,
+    });
+    return finalizeReport(violations, { bundlePath, artifactCount: 0 });
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(bundlePath, 'utf8'));
+  } catch (error) {
+    violations.push({
+      kind: 'bundle.invalid-json',
+      detail: `Release bundle is not valid JSON: ${error?.message || error}`,
+    });
+    return finalizeReport(violations, { bundlePath, artifactCount: 0 });
+  }
+
+  if (!Array.isArray(parsed.artifacts) || parsed.artifacts.length === 0) {
+    violations.push({
+      kind: 'bundle.empty',
+      detail: 'Release bundle artifacts array must be non-empty.',
+    });
+    return finalizeReport(violations, { bundlePath, artifactCount: 0 });
+  }
+
+  if (parsed.integrity?.hash_algorithm !== 'SHA-256') {
+    violations.push({
+      kind: 'bundle.unexpected-hash-algorithm',
+      detail: `Expected hash_algorithm "SHA-256", got "${parsed.integrity?.hash_algorithm}".`,
+    });
+  }
+
+  if (parsed.release_status !== 'release-candidate-unpublished' && parsed.release_status !== 'released') {
+    violations.push({
+      kind: 'bundle.invalid-release-status',
+      detail: `release_status must be either "release-candidate-unpublished" or "released"; got "${parsed.release_status}".`,
+    });
+  }
+
+  for (const artifact of parsed.artifacts) {
+    if (!artifact.relative_path || typeof artifact.relative_path !== 'string') {
+      violations.push({
+        kind: 'artifact.missing-relative-path',
+        detail: `Artifact "${artifact.artifact_id}" missing relative_path.`,
+      });
+      continue;
+    }
+
+    const absolutePath = join(rootDir, artifact.relative_path);
+    if (!existsSync(absolutePath)) {
+      violations.push({
+        kind: 'artifact.missing-file',
+        detail: `Artifact "${artifact.artifact_id}" references missing file at ${artifact.relative_path}.`,
+      });
+      continue;
+    }
+
+    if (!artifact.sha256 || typeof artifact.sha256 !== 'string') {
+      violations.push({
+        kind: 'artifact.missing-sha256',
+        detail: `Artifact "${artifact.artifact_id}" missing sha256 hash.`,
+      });
+      continue;
+    }
+
+    const currentHash = sha256Hex(readFileSync(absolutePath));
+    if (currentHash !== artifact.sha256) {
+      violations.push({
+        kind: 'artifact.hash-mismatch',
+        detail: `Artifact "${artifact.artifact_id}" sha256 drift: bundle records ${artifact.sha256}, current file is ${currentHash}. Regenerate the bundle via scripts/build-release-benchmark-bundle.mjs.`,
+      });
+    }
+  }
+
+  return finalizeReport(violations, {
+    bundlePath,
+    artifactCount: parsed.artifacts.length,
+    releaseTarget: parsed.release_target || null,
+    releaseStatus: parsed.release_status || null,
+  });
+}
+
+function finalizeReport(violations, extras) {
+  return {
+    auditName: 'audit-release-bundle',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    violationCount: violations.length,
+    passed: violations.length === 0,
+    violations,
+    ...extras,
+  };
+}
+
+function main() {
+  const report = runReleaseBundleAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:release-bundle');
+  console.log('===============================================');
+  console.log(`  Bundle path:      ${report.bundlePath}`);
+  console.log(`  Artifact count:   ${report.artifactCount}`);
+  console.log(`  Release target:   ${report.releaseTarget || '(missing)'}`);
+  console.log(`  Release status:   ${report.releaseStatus || '(missing)'}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  Release bundle is intact. All artifact hashes match.');
+    process.stderr.write(`AUDIT_RELEASE_BUNDLE_REPORT: ${JSON.stringify({ passed: true, artifactCount: report.artifactCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.detail}`);
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} violation(s) found.`);
+  process.stderr.write(`AUDIT_RELEASE_BUNDLE_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount })}\n`);
+  process.exit(1);
+}
+
+if (process.argv[1] && (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-release-bundle.mjs'))) {
+  main();
+}