scene-capability-engine 3.6.48 → 3.6.50

package/scripts/refactor-trigger-audit.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.cjs', '.mjs', '.jsx',
+  '.ts', '.tsx',
+  '.py',
+  '.java',
+  '.go',
+  '.rb',
+  '.php',
+  '.cs'
+]);
+
+const DEFAULT_SCAN_DIRS = [
+  'src',
+  'lib',
+  'scripts',
+  'bin',
+  'app',
+  'server',
+  'client',
+  'packages',
+  'tests'
+];
+
+const SKIP_DIRS = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.turbo',
+  '.idea',
+  '.vscode',
+  '.sce/reports'
+]);
+
+const THRESHOLD_PROFILES = Object.freeze({
+  source: {
+    floors: {
+      assessment: 800,
+      refactor: 1800
+    },
+    defaults: {
+      assessment: 2000,
+      refactor: 4000,
+      redline: 10000
+    }
+  },
+  test: {
+    floors: {
+      assessment: 1200,
+      refactor: 3000
+    },
+    defaults: {
+      assessment: 3000,
+      refactor: 6000,
+      redline: 15000
+    }
+  }
+});
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const options = {
+    projectPath: process.cwd(),
+    json: false,
+    failOnRedline: false,
+    out: null,
+    scanDirs: DEFAULT_SCAN_DIRS.slice()
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = argv[index + 1];
+    if (token === '--project-path' && next) {
+      options.projectPath = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token === '--fail-on-redline') {
+      options.failOnRedline = true;
+      continue;
+    }
+    if (token === '--out' && next) {
+      options.out = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--scan-dir' && next) {
+      options.scanDirs.push(next.trim());
+      index += 1;
+      continue;
+    }
+  }
+
+  options.scanDirs = Array.from(new Set(options.scanDirs.filter(Boolean)));
+  return options;
+}
+
+function normalizePath(value) {
+  return `${value || ''}`.replace(/\\/g, '/');
+}
+
+function shouldSkipDir(relativePath, entryName) {
+  if (SKIP_DIRS.has(entryName)) {
+    return true;
+  }
+  return SKIP_DIRS.has(normalizePath(relativePath));
+}
+
+function collectFilesRecursive(rootDir, relativeRoot = '') {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  const results = [];
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(rootDir, entry.name);
+    const relativePath = normalizePath(path.join(relativeRoot, entry.name));
+    if (entry.isDirectory()) {
+      if (shouldSkipDir(relativePath, entry.name)) {
+        continue;
+      }
+      results.push(...collectFilesRecursive(absolutePath, relativePath));
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (!CODE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+      continue;
+    }
+    results.push({
+      absolutePath,
+      relativePath
+    });
+  }
+  return results;
+}
+
+function classifyFile(relativePath) {
+  const normalized = normalizePath(relativePath).toLowerCase();
+  if (
+    normalized.startsWith('tests/')
+    || normalized.includes('/__tests__/')
+    || normalized.includes('.test.')
+    || normalized.includes('.spec.')
+  ) {
+    return 'test';
+  }
+  return 'source';
+}
+
+function countLines(content) {
+  if (!content) {
+    return 0;
+  }
+  return content.split(/\r?\n/).length;
+}
+
+function roundUp(value, step) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.ceil(value / step) * step;
+}
+
+function quantile(sortedValues, ratio) {
+  if (!Array.isArray(sortedValues) || sortedValues.length === 0) {
+    return 0;
+  }
+  if (sortedValues.length === 1) {
+    return sortedValues[0];
+  }
+  const index = Math.max(0, Math.min(sortedValues.length - 1, Math.ceil(sortedValues.length * ratio) - 1));
+  return sortedValues[index];
+}
+
+function buildStats(files) {
+  const lineValues = files.map((item) => item.lines).sort((left, right) => left - right);
+  const count = lineValues.length;
+  return {
+    count,
+    max: count > 0 ? lineValues[count - 1] : 0,
+    p50: quantile(lineValues, 0.5),
+    p90: quantile(lineValues, 0.9),
+    p95: quantile(lineValues, 0.95)
+  };
+}
+
+function buildRecommendedThresholds(stats, profile) {
+  const assessmentRaw = roundUp(Math.max(profile.floors.assessment, stats.p90 * 1.25), 50);
+  const refactorRaw = roundUp(Math.max(profile.floors.refactor, stats.p95 * 1.35, assessmentRaw + 400), 50);
+
+  const assessment = Math.min(profile.defaults.assessment, Math.max(profile.floors.assessment, assessmentRaw));
+  const refactor = Math.min(profile.defaults.refactor, Math.max(profile.floors.refactor, refactorRaw, assessment + 400));
+  const redline = profile.defaults.redline;
+
+  return {
+    assessment,
+    refactor,
+    redline
+  };
+}
+
+function evaluateFile(lines, thresholds) {
+  if (lines >= thresholds.redline) {
+    return 'redline';
+  }
+  if (lines >= thresholds.refactor) {
+    return 'refactor';
+  }
+  if (lines >= thresholds.assessment) {
+    return 'assessment';
+  }
+  return 'ok';
+}
+
+function auditRefactorTriggers(options = {}) {
+  const projectPath = path.resolve(options.projectPath || process.cwd());
+  const scanDirs = Array.isArray(options.scanDirs) && options.scanDirs.length > 0
+    ? options.scanDirs
+    : DEFAULT_SCAN_DIRS;
+
+  const files = Array.from(new Set(scanDirs))
+    .flatMap((dirName) => collectFilesRecursive(path.join(projectPath, dirName), dirName))
+    .map((file) => {
+      const content = fs.readFileSync(file.absolutePath, 'utf8');
+      const kind = classifyFile(file.relativePath);
+      return {
+        file: file.relativePath,
+        kind,
+        lines: countLines(content)
+      };
+    })
+    .sort((left, right) => right.lines - left.lines || left.file.localeCompare(right.file));
+
+  const sourceFiles = files.filter((item) => item.kind === 'source');
+  const testFiles = files.filter((item) => item.kind === 'test');
+  const sourceStats = buildStats(sourceFiles);
+  const testStats = buildStats(testFiles);
+  const sourceThresholds = buildRecommendedThresholds(sourceStats, THRESHOLD_PROFILES.source);
+  const testThresholds = buildRecommendedThresholds(testStats, THRESHOLD_PROFILES.test);
+
+  const evaluatedFiles = files.map((file) => {
+    const thresholds = file.kind === 'test' ? testThresholds : sourceThresholds;
+    return {
+      ...file,
+      thresholds,
+      trigger: evaluateFile(file.lines, thresholds)
+    };
+  });
+
+  const offenders = evaluatedFiles.filter((item) => item.trigger !== 'ok');
+  const redline = offenders.filter((item) => item.trigger === 'redline');
+  const refactor = offenders.filter((item) => item.trigger === 'refactor');
+  const assessment = offenders.filter((item) => item.trigger === 'assessment');
+
+  const recommendations = [
+    'Run this audit weekly and before each release to recalibrate project-specific refactor trigger points.',
+    'When no project-specific threshold is agreed yet, keep the SCE default source thresholds as the outer guardrail: 2000 / 4000 / 10000 lines.',
+    redline.length > 0
+      ? 'Redline files already exist; new non-emergency changes touching those files should prioritize decomposition instead of feature accretion.'
+      : 'No redline file detected under the current recommended thresholds.'
+  ];
+
+  return {
+    mode: 'refactor-trigger-audit',
+    project_path: projectPath,
+    passed: redline.length === 0,
+    scan_dirs: scanDirs,
+    scanned_file_count: files.length,
+    cadence_recommendation: ['weekly', 'before_release'],
+    thresholds: {
+      source: sourceThresholds,
+      test: testThresholds
+    },
+    stats: {
+      source: sourceStats,
+      test: testStats
+    },
+    summary: {
+      offender_count: offenders.length,
+      assessment_count: assessment.length,
+      refactor_count: refactor.length,
+      redline_count: redline.length
+    },
+    offenders: offenders.slice(0, 50),
+    top_files: evaluatedFiles.slice(0, 20),
+    recommendations
+  };
+}
+
+function maybeWriteReport(result, outPath) {
+  if (!outPath) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+}
+
+function printHumanReport(result) {
+  console.log(
+    `[refactor-trigger-audit] scanned=${result.scanned_file_count} offenders=${result.summary.offender_count} `
+    + `assessment=${result.summary.assessment_count} refactor=${result.summary.refactor_count} redline=${result.summary.redline_count}`
+  );
+  console.log(
+    `[refactor-trigger-audit] source-thresholds=${result.thresholds.source.assessment}/${result.thresholds.source.refactor}/${result.thresholds.source.redline} `
+    + `test-thresholds=${result.thresholds.test.assessment}/${result.thresholds.test.refactor}/${result.thresholds.test.redline}`
+  );
+  if (result.summary.redline_count > 0) {
+    result.offenders
+      .filter((item) => item.trigger === 'redline')
+      .slice(0, 10)
+      .forEach((item) => {
+        console.error(`[refactor-trigger-audit] redline ${item.kind} ${item.file} (${item.lines} lines)`);
+      });
+  }
+}
+
+if (require.main === module) {
+  const options = parseArgs(process.argv.slice(2));
+  const result = auditRefactorTriggers(options);
+  maybeWriteReport(result, options.out);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    printHumanReport(result);
+  }
+
+  if (options.failOnRedline && result.summary.redline_count > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  DEFAULT_SCAN_DIRS,
+  THRESHOLD_PROFILES,
+  auditRefactorTriggers,
+  buildRecommendedThresholds,
+  buildStats,
+  classifyFile,
+  parseArgs
+};

package/scripts/release-doc-version-audit.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RELEASE_DOCS = [
+  {
+    file: 'README.md',
+    label: 'README.md',
+    versionField: 'Version',
+    versionPattern: /\*\*Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/
+  },
+  {
+    file: 'README.zh.md',
+    label: 'README.zh.md',
+    versionField: '版本',
+    versionPattern: /\*\*版本\*\*[：:]\s*([^\s]+)/,
+    updatedField: '最后更新',
+    updatedPattern: /\*\*最后更新\*\*[：:]\s*(\d{4}-\d{2}-\d{2})/
+  },
+  {
+    file: '.sce/README.md',
+    label: '.sce/README.md',
+    versionField: 'sce Version',
+    versionPattern: /\*\*sce Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/,
+    forbidVersionedHeadings: true
+  },
+  {
+    file: 'template/.sce/README.md',
+    label: 'template/.sce/README.md',
+    versionField: 'sce Version',
+    versionPattern: /\*\*sce Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/,
+    forbidVersionedHeadings: true
+  }
+];
+
+const VERSIONED_HEADING_PATTERN = /^#{1,6}\s+.*\((?:v)?\d+\.\d+(?:\.\d+|\.x)\)\s*$/gm;
+const CHANGELOG_RELEASE_PATTERN = /^## \[([^\]]+)\] - (\d{4}-\d{2}-\d{2})(?:\s.*)?$/gm;
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const options = {
+    projectPath: process.cwd(),
+    json: false,
+    failOnError: false,
+    out: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (value === '--fail-on-error') {
+      options.failOnError = true;
+      continue;
+    }
+    if (value === '--project-path') {
+      options.projectPath = path.resolve(argv[index + 1] || process.cwd());
+      index += 1;
+      continue;
+    }
+    if (value === '--out') {
+      options.out = path.resolve(argv[index + 1] || '');
+      index += 1;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function pushViolation(violations, file, rule, message, suggestion) {
+  violations.push({
+    severity: 'error',
+    file,
+    rule,
+    message,
+    suggestion
+  });
+}
+
+function loadPackageVersion(projectPath, violations) {
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    pushViolation(
+      violations,
+      'package.json',
+      'missing_package_json',
+      'package.json is required to resolve the current release version.',
+      'Restore package.json before running the release doc audit.'
+    );
+    return null;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return typeof packageJson.version === 'string' ? packageJson.version.trim() : null;
+}
+
+function extractLatestChangelogRelease(changelogContent) {
+  CHANGELOG_RELEASE_PATTERN.lastIndex = 0;
+  let match = CHANGELOG_RELEASE_PATTERN.exec(changelogContent);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    version: match[1].trim(),
+    date: match[2].trim()
+  };
+}
+
+function loadLatestChangelogRelease(projectPath, packageVersion, violations) {
+  const changelogPath = path.join(projectPath, 'CHANGELOG.md');
+  if (!fs.existsSync(changelogPath)) {
+    pushViolation(
+      violations,
+      'CHANGELOG.md',
+      'missing_changelog',
+      'CHANGELOG.md is required to resolve the latest release date.',
+      'Restore CHANGELOG.md before running the release doc audit.'
+    );
+    return null;
+  }
+
+  const changelogContent = fs.readFileSync(changelogPath, 'utf8');
+  const latestRelease = extractLatestChangelogRelease(changelogContent);
+  if (!latestRelease) {
+    pushViolation(
+      violations,
+      'CHANGELOG.md',
+      'missing_release_entry',
+      'Could not find a released version entry in CHANGELOG.md.',
+      'Add a release entry like `## [x.y.z] - YYYY-MM-DD` before publishing.'
+    );
+    return null;
+  }
+
+  if (packageVersion && latestRelease.version !== packageVersion) {
+    pushViolation(
+      violations,
+      'CHANGELOG.md',
+      'stale_latest_release_entry',
+      `CHANGELOG.md latest release is ${latestRelease.version} but package.json is ${packageVersion}.`,
+      'Update the top released CHANGELOG entry so version and release date match package.json.'
+    );
+  }
+
+  return latestRelease;
+}
+
+function extractField(content, pattern) {
+  const match = content.match(pattern);
+  return match ? match[1].trim() : null;
+}
+
+function collectVersionedHeadings(content) {
+  const matches = [];
+  let match = VERSIONED_HEADING_PATTERN.exec(content);
+  while (match) {
+    matches.push(match[0].trim());
+    match = VERSIONED_HEADING_PATTERN.exec(content);
+  }
+  VERSIONED_HEADING_PATTERN.lastIndex = 0;
+  return matches;
+}
+
+function auditReleaseDocs(options = {}) {
+  const projectPath = path.resolve(options.projectPath || process.cwd());
+  const violations = [];
+  const packageVersion = loadPackageVersion(projectPath, violations);
+  const latestRelease = loadLatestChangelogRelease(projectPath, packageVersion, violations);
+  const expectedVersion = packageVersion;
+  const expectedDate = latestRelease ? latestRelease.date : null;
+  const documents = [];
+
+  for (const doc of RELEASE_DOCS) {
+    const absolutePath = path.join(projectPath, doc.file);
+    if (!fs.existsSync(absolutePath)) {
+      pushViolation(
+        violations,
+        doc.file,
+        'missing_release_doc',
+        `${doc.file} is missing.`,
+        `Restore ${doc.file} so release metadata stays auditable.`
+      );
+      continue;
+    }
+
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    const actualVersion = extractField(content, doc.versionPattern);
+    const actualUpdated = extractField(content, doc.updatedPattern);
+    const versionedHeadings = doc.forbidVersionedHeadings
+      ? collectVersionedHeadings(content)
+      : [];
+
+    if (!actualVersion) {
+      pushViolation(
+        violations,
+        doc.file,
+        'missing_doc_version_field',
+        `${doc.file} is missing the "${doc.versionField}" footer field.`,
+        `Add a "${doc.versionField}" footer line that matches package.json version ${expectedVersion || '<unknown>'}.`
+      );
+    } else if (expectedVersion && actualVersion !== expectedVersion) {
+      pushViolation(
+        violations,
+        doc.file,
+        'stale_doc_version',
+        `${doc.file} tracks version ${actualVersion} but package.json is ${expectedVersion}.`,
+        `Refresh ${doc.file} so "${doc.versionField}" matches ${expectedVersion}.`
+      );
+    }
+
+    if (!actualUpdated) {
+      pushViolation(
+        violations,
+        doc.file,
+        'missing_doc_updated_field',
+        `${doc.file} is missing the "${doc.updatedField}" footer field.`,
+        `Add a "${doc.updatedField}" footer line that matches the latest CHANGELOG release date ${expectedDate || '<unknown>'}.`
+      );
+    } else if (expectedDate && actualUpdated !== expectedDate) {
+      pushViolation(
+        violations,
+        doc.file,
+        'stale_doc_updated_date',
+        `${doc.file} last updated date is ${actualUpdated} but latest CHANGELOG release date is ${expectedDate}.`,
+        `Refresh ${doc.file} so "${doc.updatedField}" matches ${expectedDate}.`
+      );
+    }
+
+    if (versionedHeadings.length > 0) {
+      pushViolation(
+        violations,
+        doc.file,
+        'versioned_capability_headings',
+        `${doc.file} contains version-stamped headings: ${versionedHeadings.join(' | ')}.`,
+        'Remove release/version markers from long-lived README headings and keep current version tracking only in the footer.'
+      );
+    }
+
+    documents.push({
+      file: doc.file,
+      path: absolutePath,
+      actual_version: actualVersion,
+      expected_version: expectedVersion,
+      actual_updated: actualUpdated,
+      expected_updated: expectedDate,
+      versioned_heading_count: versionedHeadings.length
+    });
+  }
+
+  return {
+    mode: 'release-doc-version-audit',
+    passed: violations.length === 0,
+    project_path: projectPath,
+    package_version: packageVersion,
+    changelog_release: latestRelease,
+    error_count: violations.length,
+    documents,
+    violations
+  };
+}
+
+function printHumanReport(result) {
+  if (result.violations.length === 0) {
+    console.log('Release doc version audit passed: README release metadata matches package.json and CHANGELOG.');
+    return;
+  }
+
+  console.error(`Release doc version audit found ${result.error_count} error(s).`);
+  for (const violation of result.violations) {
+    console.error(`- ${violation.file} / ${violation.rule}: ${violation.message}`);
+    if (violation.suggestion) {
+      console.error(`  suggestion: ${violation.suggestion}`);
+    }
+  }
+}
+
+function maybeWriteReport(outputPath, result) {
+  if (!outputPath) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+}
+
+if (require.main === module) {
+  const options = parseArgs(process.argv.slice(2));
+  const result = auditReleaseDocs(options);
+  maybeWriteReport(options.out, result);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    printHumanReport(result);
+  }
+
+  if (options.failOnError && result.error_count > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  RELEASE_DOCS,
+  auditReleaseDocs,
+  extractLatestChangelogRelease,
+  parseArgs
+};