scene-capability-engine 3.6.45 → 3.6.47

package/scripts/symbol-evidence-locate.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_MAX_HITS = 10;
+const DEFAULT_MIN_SCORE = 0.35;
+const DEFAULT_MIN_RELIABLE_SCORE = 0.6;
+const FALLBACK_ACTION_ALLOW_WRITE = 'allow_write';
+const FALLBACK_ACTION_CLARIFY_BUSINESS_SCOPE = 'clarify_business_scope';
+const DEFAULT_EXTENSIONS = [
+  '.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx',
+  '.py', '.java', '.go', '.rb', '.php', '.cs',
+  '.json', '.yaml', '.yml', '.md'
+];
+const DEFAULT_IGNORED_DIRS = new Set([
+  '.git',
+  '.svn',
+  '.hg',
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  '.cache'
+]);
+
+function parseArgs(argv = []) {
+  const options = {
+    workspace: process.cwd(),
+    query: '',
+    queryFile: '',
+    maxHits: DEFAULT_MAX_HITS,
+    minScore: DEFAULT_MIN_SCORE,
+    minReliableScore: DEFAULT_MIN_RELIABLE_SCORE,
+    extensions: [...DEFAULT_EXTENSIONS],
+    strict: false,
+    json: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = argv[index + 1];
+
+    if (token === '--workspace' && next) {
+      options.workspace = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--query' && next) {
+      options.query = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--query-file' && next) {
+      options.queryFile = next;
+      index += 1;
+      continue;
+    }
+    if (token === '--max-hits' && next) {
+      options.maxHits = Number(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--min-score' && next) {
+      options.minScore = Number(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--min-reliable-score' && next) {
+      options.minReliableScore = Number(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--extensions' && next) {
+      options.extensions = next
+        .split(',')
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean)
+        .map((item) => (item.startsWith('.') ? item : `.${item}`));
+      index += 1;
+      continue;
+    }
+    if (token === '--strict') {
+      options.strict = true;
+      continue;
+    }
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token === '--help' || token === '-h') {
+      printHelpAndExit(0);
+    }
+  }
+
+  if (!Number.isFinite(options.maxHits) || options.maxHits <= 0) {
+    throw new Error('--max-hits must be a positive number.');
+  }
+  if (!Number.isFinite(options.minScore) || options.minScore < 0 || options.minScore > 1) {
+    throw new Error('--min-score must be between 0 and 1.');
+  }
+  if (
+    !Number.isFinite(options.minReliableScore)
+    || options.minReliableScore < 0
+    || options.minReliableScore > 1
+  ) {
+    throw new Error('--min-reliable-score must be between 0 and 1.');
+  }
+
+  return options;
+}
+
+function printHelpAndExit(code) {
+  const lines = [
+    'Usage: node scripts/symbol-evidence-locate.js --query "<text>" [options]',
+    '',
+    'Options:',
+    '  --workspace <path>            Workspace root to search (default: current directory)',
+    '  --query <text>                Query text for symbol localization',
+    '  --query-file <path>           Query text file (fallback when --query absent)',
+    `  --max-hits <n>                Maximum hits to return (default: ${DEFAULT_MAX_HITS})`,
+    `  --min-score <0-1>             Minimum hit score (default: ${DEFAULT_MIN_SCORE})`,
+    `  --min-reliable-score <0-1>    Reliability threshold (default: ${DEFAULT_MIN_RELIABLE_SCORE})`,
+    `  --extensions <csv>            File extensions (default: ${DEFAULT_EXTENSIONS.join(',')})`,
+    '  --strict                      Exit code 2 when no reliable evidence is found and scope clarification is required',
+    '  --json                        Print JSON payload',
+    '  -h, --help                    Show this help'
+  ];
+  console.log(lines.join('\n'));
+  process.exit(code);
+}
+
+function resolveQuery(options) {
+  if (typeof options.query === 'string' && options.query.trim()) {
+    return options.query.trim();
+  }
+  if (typeof options.queryFile === 'string' && options.queryFile.trim()) {
+    const resolvedFile = path.resolve(options.workspace, options.queryFile);
+    if (!fs.existsSync(resolvedFile)) {
+      throw new Error(`query file not found: ${options.queryFile}`);
+    }
+    const content = fs.readFileSync(resolvedFile, 'utf8').trim();
+    if (!content) {
+      throw new Error(`query file is empty: ${options.queryFile}`);
+    }
+    return content;
+  }
+  throw new Error('query is required. Use --query or --query-file.');
+}
+
+function normalizeQueryTokens(query) {
+  return `${query || ''}`
+    .toLowerCase()
+    .replace(/[^a-z0-9_:\-\s]/g, ' ')
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2);
+}
+
+function listCandidateFiles(workspaceRoot, extensions) {
+  const resolvedRoot = path.resolve(workspaceRoot);
+  const extSet = new Set((extensions || []).map((item) => `${item}`.toLowerCase()));
+  const files = [];
+  const stack = [resolvedRoot];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch (_error) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      const ext = path.extname(entry.name).toLowerCase();
+      if (extSet.size > 0 && !extSet.has(ext)) {
+        continue;
+      }
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function extractSymbolFromLine(line = '') {
+  const patterns = [
+    /\bfunction\s+([A-Za-z_$][\w$]*)\s*\(/,
+    /\bclass\s+([A-Za-z_$][\w$]*)\b/,
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/,
+    /\b([A-Za-z_$][\w$]*)\s*:\s*(?:async\s*)?\(/,
+    /\b([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\(/
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(line);
+    if (match && match[1]) {
+      return match[1];
+    }
+  }
+  return '';
+}
+
+function computeHitScore({ query, queryTokens, line, symbol }) {
+  const loweredLine = `${line || ''}`.toLowerCase();
+  const normalizedQuery = `${query || ''}`.toLowerCase().trim();
+  const normalizedSymbol = `${symbol || ''}`.toLowerCase();
+  if (queryTokens.length === 0) {
+    return 0;
+  }
+
+  const tokenMatches = queryTokens.filter((token) => loweredLine.includes(token)).length;
+  if (tokenMatches === 0) {
+    return 0;
+  }
+
+  const tokenCoverage = tokenMatches / queryTokens.length;
+  const hasPhraseMatch = normalizedQuery && loweredLine.includes(normalizedQuery);
+  const hasSymbolMatch = normalizedSymbol
+    && queryTokens.some((token) => normalizedSymbol.includes(token) || token.includes(normalizedSymbol));
+
+  const rawScore = (tokenCoverage * 0.65) + (hasPhraseMatch ? 0.2 : 0) + (hasSymbolMatch ? 0.15 : 0);
+  return Math.max(0, Math.min(1, Number(rawScore.toFixed(4))));
+}
+
+function confidenceFromScore(score) {
+  if (!Number.isFinite(score) || score <= 0) {
+    return 'none';
+  }
+  if (score >= 0.8) {
+    return 'high';
+  }
+  if (score >= 0.6) {
+    return 'medium';
+  }
+  if (score >= 0.4) {
+    return 'low';
+  }
+  return 'none';
+}
+
+function locateSymbolEvidence({
+  workspace,
+  query,
+  maxHits = DEFAULT_MAX_HITS,
+  minScore = DEFAULT_MIN_SCORE,
+  minReliableScore = DEFAULT_MIN_RELIABLE_SCORE,
+  extensions = DEFAULT_EXTENSIONS
+}) {
+  const workspaceRoot = path.resolve(workspace);
+  const queryTokens = normalizeQueryTokens(query);
+  const candidateFiles = listCandidateFiles(workspaceRoot, extensions);
+  const hits = [];
+
+  for (const filePath of candidateFiles) {
+    let content = '';
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (_error) {
+      continue;
+    }
+
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      const symbol = extractSymbolFromLine(line);
+      const score = computeHitScore({ query, queryTokens, line, symbol });
+      if (score < minScore) {
+        continue;
+      }
+      const relativeFile = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+      hits.push({
+        file: relativeFile || path.basename(filePath),
+        line: index + 1,
+        snippet: line.trim().slice(0, 240),
+        symbol: symbol || 'unknown',
+        score,
+        source: symbol ? 'symbol-heuristic' : 'text-grep'
+      });
+    }
+  }
+
+  hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file) || (a.line - b.line));
+  const slicedHits = hits.slice(0, Math.max(1, Math.floor(maxHits)));
+  const reliableHits = slicedHits.filter((item) => item.score >= minReliableScore);
+  const topScore = slicedHits.length > 0 ? slicedHits[0].score : 0;
+  const confidence = confidenceFromScore(topScore);
+  const reliable = reliableHits.length > 0;
+
+  return {
+    mode: 'symbol-evidence-locate',
+    query,
+    hits: slicedHits,
+    evidence: {
+      confidence,
+      reliable,
+      fallback_action: reliable
+        ? FALLBACK_ACTION_ALLOW_WRITE
+        : FALLBACK_ACTION_CLARIFY_BUSINESS_SCOPE,
+      advisory: reliable
+        ? 'Symbol evidence is reliable; scoped code change can proceed.'
+        : 'No reliable symbol evidence found yet. Clarify target module/page/entity and business constraints before deciding whether scoped writes are safe.'
+    },
+    summary: {
+      searched_files: candidateFiles.length,
+      candidate_files: candidateFiles.length,
+      total_hits: slicedHits.length,
+      reliable_hits: reliableHits.length
+    }
+  };
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const query = resolveQuery(options);
+  const payload = locateSymbolEvidence({
+    workspace: options.workspace,
+    query,
+    maxHits: options.maxHits,
+    minScore: options.minScore,
+    minReliableScore: options.minReliableScore,
+    extensions: options.extensions
+  });
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    process.stdout.write(`symbol evidence confidence=${payload.evidence.confidence}\n`);
+    process.stdout.write(`hits=${payload.hits.length} reliable=${payload.summary.reliable_hits}\n`);
+    process.stdout.write(`fallback_action=${payload.evidence.fallback_action}\n`);
+  }
+
+  if (options.strict && payload.evidence.reliable !== true) {
+    process.exitCode = 2;
+  }
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`symbol-evidence-locate failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  parseArgs,
+  resolveQuery,
+  normalizeQueryTokens,
+  listCandidateFiles,
+  extractSymbolFromLine,
+  computeHitScore,
+  confidenceFromScore,
+  locateSymbolEvidence
+};

package/template/.sce/README.md

@@ -15,6 +15,7 @@ This project uses **Spec-driven development** - a structured approach where:
 - When user requests a feature → Check if Spec exists, if not, help create one
 - When implementing → Follow the Spec's requirements and design
 - When stuck → Read the Spec documents for context
+- When business scene/module/page/entity is unclear → Clarify scope first; do not replace missing understanding with blanket disable
 - Track progress by updating task status
 
 ---

package/template/.sce/steering/CORE_PRINCIPLES.md

@@ -22,6 +22,7 @@
 ## 4. 复用已有机制，不要平行造轮子
 
 - 已有能力优先复用，例如缺陷经验与发布阻断统一走 `errorbook`。
+- 若接管项目中已存在自定义缺陷复盘册、故障账本或问题经验库，必须统一盘点并吸收到 `.sce/errorbook`，不要长期并存混用。
 - 不要在 steering 中额外定义另一套错题、发布、会话或治理模式。
 
 ## 5. 质量问题必须追根
@@ -33,3 +34,27 @@
 
 - 每周、发布前、重大 Spec 收尾后运行 `npm run audit:steering`。
 - 发现问题时优先合并重复、迁移错层、归档历史、删除失效条目。
+
+## 7. 业务场景未知时先澄清，不得直接彻底禁用
+
+- 不了解业务场景、模块、页面、实体或业务约束时，先补上下文并缩小范围。
+- 禁止把“暂时没理解场景”直接变成 blanket disable、answer-only 或一刀切阻断。
+- 只有明确命中安全、权限、合规或破坏性规则时，才允许阻断；否则先澄清业务范围。
+- 这条规则适用于所有使用 SCE 的项目，不设项目级例外。
+
+## 8. 禁止盲改问题
+
+- 修问题前先明确现象、复现条件、影响范围和验证方式。
+- 缺少证据时先补日志、数据、接口样本或最小复现，不要靠猜测连续改代码。
+- 两轮修改仍未收敛时，先回到调试和根因分析，不要盲目扩大改动面。
+
+## 9. Steering 变更先评估，不得随意增删
+
+- 新增、删除或重写 steering 条目前，先判断它是否真属于长期原则，是否应迁到 `CURRENT_CONTEXT.md`、Spec 或项目文档。
+- 未经评估，不要把临时偏好、短期任务或偶发结论直接固化进 steering。
+
+## 10. 问题修复时前后端接口不一致默认以后端契约为准
+
+- 前端调用后端 API 不匹配时，默认以后端现有接口契约为准。
+- 除非明确要求新建或修改后端接口，否则不要为了迁就前端错误调用去改后端。
+- 优先调整前端请求、映射、类型和兼容处理，使其与后端接口一致。