sandtable 0.4.0 → 1.0.1

package/src/scanner/scan.js

@@ -3,198 +3,9 @@
 
 const fs = require('fs');
 const path = require('path');
+const { loadContract, classifyFile } = require('../contract/loader');
 
-// ---- Built-in patterns: two-tier (primary vs secondary) ----
-const PATTERNS = [
-  {
-    name: 'decision',
-    test: (filename) => /^\d{4}-\d{2}-\d{2}-.+\.md$/.test(filename),
-    classify: () => ({ kind: 'primary', elementType: 'decision', category: 'decision' }),
-  },
-  {
-    name: 'agent',
-    test: (filename) => /^\d{2}-.+\.md$/.test(filename),
-    classify: () => ({ kind: 'primary', elementType: 'agent', category: 'ops' }),
-  },
-  {
-    name: 'prompt',
-    test: (filename) => /^[A-Z][A-Z_]+\.md$/.test(filename),
-    classify: () => ({ kind: 'secondary', elementType: 'prompt', category: 'spec' }),
-  },
-  {
-    name: 'template',
-    test: (filename) => filename.startsWith('_') && filename.endsWith('.md'),
-    classify: () => ({ kind: 'secondary', elementType: 'template', category: 'template' }),
-  },
-  {
-    name: 'refactor',
-    test: (filename) => /^r\d+-op\d+-.+\.md$/i.test(filename),
-    classify: () => ({ kind: 'primary', elementType: 'refactor', category: 'decision' }),
-  },
-  {
-    name: 'intent',
-    test: (filename) => /^[a-z][a-z_]+\.md$/.test(filename),
-    classify: () => ({ kind: 'secondary', elementType: 'intent', category: 'spec' }),
-  },
-];
-
-// ---- Primary types (structural, always-show) ----
-const PRIMARY_TYPES = new Set([
-  'agent', 'decision', 'milestone', 'roadmap', 'refactor',
-  'phase', 'task', 'subtask', 'conclusion',
-]);
-
-// ---- MECE display categories (PM 6 大分类 + template) ----
-// §10 libero PM 视角 — 9 大分类
-// Primary-only 类别 (roadmap, decision) 不出现在 filterType checkbox 中
-const DISPLAY_CATEGORIES = {
-  roadmap:    { label: '路线图与进度', elementTypes: ['phase', 'milestone', 'task', 'subtask', 'roadmap', 'backlog', 'optimization', 'todo'] },
-  decision:   { label: '决策记录',     elementTypes: ['decision', 'refactor'] },
-  spec:       { label: '业务规格',     elementTypes: ['spec', 'intent', 'prompt'] },
-  convention: { label: '协作纪律',     elementTypes: ['convention'] },
-  ops:        { label: '运维与基建',   elementTypes: ['agent', 'runbook'] },
-  archive:    { label: '历史档案',     elementTypes: ['journal', 'handover', 'plan_doc'] },
-  template:   { label: '工具模板',     elementTypes: ['template'] },
-};
-
-// Primary-only categories (all elementTypes in these categories are kind=primary, show always)
-const PRIMARY_CATEGORIES = new Set(['roadmap', 'decision', 'todo']);
-
-function normalizeCategory(elementType) {
-  for (const [cat, def] of Object.entries(DISPLAY_CATEGORIES)) {
-    if (def.elementTypes.includes(elementType)) return cat;
-  }
-  return 'unknown'; // 标记未知类型，不猜测
-}
-
-// ---- Path-based refinement (directory semantics) ----
-// Path hints refine category/elementType but never downgrade kind (primary → secondary)
-// Sets _pathRefined flag to prevent content from overriding path-based decisions
-function refineByPath(relativePath, current) {
-  const rp = relativePath.toLowerCase();
-  let result = null;
-
-  // Archive paths: journal/, handover/, plans/, archive/ → always secondary
-  if (/(^|\/)(journal|handover|plans|archive)(\/|$)/.test(rp)) {
-    result = { kind: 'secondary', elementType: 'journal', category: 'archive' };
-  }
-  // Runbook paths
-  else if (/(^|\/)runbooks?(\/|$)/.test(rp)) {
-    result = { kind: 'secondary', elementType: 'runbook', category: 'ops' };
-  }
-  // Decision paths → upgrade to primary
-  else if (/(^|\/)decisions?(\/|$)/.test(rp)) {
-    result = { kind: 'primary', elementType: 'decision', category: 'decision' };
-  }
-  // Skill paths + AGENTS.md + agents/ → collaboration (secondary)
-  else if (/(^|\/)skills?(\/|$)/.test(rp) || /(^|\/)agents?(\/|$)/.test(rp) || /^AGENTS\.md$/i.test(rp)) {
-    result = { kind: 'secondary', elementType: 'convention', category: 'convention' };
-  }
-  // Spec/refactor paths only refine when current type is weak or unknown
-  else if (/(^|\/)specs?(\/|$)/.test(rp) && current.elementType === 'unknown') {
-    result = { kind: 'secondary', elementType: 'spec', category: 'spec' };
-  }
-  else if (/(^|\/)refactors?(\/|$)/.test(rp) && current.elementType === 'unknown') {
-    result = { kind: 'primary', elementType: 'refactor', category: 'decision' };
-  }
-
-  if (result) {
-    result._pathRefined = true;
-    return result;
-  }
-  return current;
-}
-
-// ---- Content-based refinement (auto-detection, no SUMMARY block) ----
-function refineByContent(content, current, relativePath) {
-  const rp = relativePath || '';
-
-  // NEVER override archive classification (path-based takes priority)
-  if (current.category === 'archive') return current;
-  // Path-based reclassification is stronger than content guesswork
-  const canUpgradeKind = !current._pathRefined;
-
-  // H1 heading analysis
-  const h1Match = content.match(/^#\s+(.+)$/m);
-  if (h1Match) {
-    const h1 = h1Match[1];
-
-    if (canUpgradeKind && /@(PM|Architect|Coder|Tester|CloudOps|PromptAuthor)/.test(h1)) {
-      return { kind: 'primary', elementType: 'agent', category: 'ops' };
-    }
-    if (canUpgradeKind && /(Phase|第\s*\d+\s*批|阶段\s*\d+|Batch\s*\d+|^S\d+)/i.test(h1)) {
-      return { kind: 'primary', elementType: 'phase', category: 'roadmap' };
-    }
-    if (canUpgradeKind && /M\d+/.test(h1) && /(里程碑|Milestone|迁移)/i.test(h1)) {
-      return { kind: 'primary', elementType: 'milestone', category: 'roadmap' };
-    }
-    if (canUpgradeKind && /(结论|Conclusion|总结|Post-mortem|复盘)/.test(h1)) {
-      return { kind: 'primary', elementType: 'conclusion', category: 'roadmap' };
-    }
-    if (canUpgradeKind && /\bR\d+\b/.test(h1) && /\b(roadmap|实施|计划|Plan)\b/i.test(h1)) {
-      return { kind: 'primary', elementType: 'roadmap', category: 'roadmap' };
-    }
-    if (canUpgradeKind && /\bR\d+\b/.test(h1) && /\b(OP-\d+|spec|重构)\b/i.test(h1)) {
-      return { kind: 'primary', elementType: 'refactor', category: 'decision' };
-    }
-  }
-
-  // 5-field journal detection → secondary
-  // Real journals have date in path (e.g. docs/journal/2026-05/2026-05-23-debug.md)
-  // Files like README.md that mention the 5-field format are conventions, not journals
-  const first500 = content.substring(0, 500);
-  const has5Fields =
-    /场景|卡点|错误/.test(first500) &&
-    /尝试/.test(first500) &&
-    /解法/.test(first500) &&
-    /harness.*建议/.test(first500);
-  if (has5Fields && /\d{4}-\d{2}/.test(rp)) {
-    return { kind: 'secondary', elementType: 'journal', category: 'archive' };
-  }
-  // If 5-field matched but no date in path → likely a journal README/convention
-  if (has5Fields && !/\d{4}-\d{2}/.test(rp)) {
-    return { kind: 'secondary', elementType: 'convention', category: 'convention' };
-  }
-
-  // Convention table detection → secondary
-  if (/(简称|缩写|abbreviation|术语|term|定义|def)/i.test(first500)) {
-    return { kind: 'secondary', elementType: 'convention', category: 'convention' };
-  }
-
-  return current;
-}
-
-// Apply SUMMARY block as fallback correction (only when auto-detection returned 'unknown')
-function applySummaryCorrection(summary, current) {
-  if (!summary || !summary.type) return current;
-  // Correct when: auto-detection is unknown, OR SUMMARY declares a primary type (overrides filename pattern)
-  if (current.elementType === 'unknown' || PRIMARY_TYPES.has(summary.type)) {
-    const kind = summary.kind || (PRIMARY_TYPES.has(summary.type) ? 'primary' : 'secondary');
-    return { kind, elementType: summary.type, category: mapTypeToCategory(summary.type) };
-  }
-  // If auto-detection gave a secondary type but SUMMARY has kind override
-  if (summary.kind) {
-    return { kind: summary.kind, elementType: current.elementType, category: current.category };
-  }
-  return current;
-}
-
-function mapTypeToCategory(type) {
-  const map = {
-    phase: 'roadmap', milestone: 'roadmap', task: 'roadmap', subtask: 'roadmap',
-    roadmap: 'roadmap', backlog: 'roadmap', conclusion: 'roadmap',
-    decision: 'decision', refactor: 'decision',
-    spec: 'spec', intent: 'spec', prompt: 'spec',
-    convention: 'convention',
-    agent: 'ops', runbook: 'ops',
-    journal: 'archive', handover: 'archive', plan_doc: 'archive',
-    template: 'template',
-  };
-  return map[type] || 'unknown';
-}
-
-// ---- Exclusion list (禁读清单) ----
-// Simple glob → regex: supports ** (any depth), * (within segment), ? (single char)
+// ---- Glob to Regex ----
 function globToRegex(pattern) {
   let re = '';
   const parts = pattern.split('/');
@@ -210,13 +21,13 @@ function globToRegex(pattern) {
       re += seg;
     }
   }
-  // '**' at end should match everything under that directory
   if (pattern.endsWith('/**')) {
     re += '(?:\\/.*)?';
   }
   return new RegExp('^' + re + '$', 'i');
 }
 
+// ---- Exclusion list ----
 function applyExclusions(files, excludeConfig, projectRoot) {
   if (!excludeConfig) return files;
 
@@ -294,31 +105,37 @@ function extractTimeInfo(content, filename, fileModified) {
   return { date: mtimeISO, dateSource: 'mtime' };
 }
 
-// ---- Pattern-based classification ----
-function classifyByPattern(filename) {
-  for (const pattern of PATTERNS) {
-    if (pattern.test(filename)) {
-      return pattern.classify();
-    }
+// ---- Build display categories from contract ----
+function buildDisplayCategories(contract) {
+  if (!contract || !contract.categories) return {};
+  const result = {};
+  for (const cat of contract.categories) {
+    result[cat.id] = {
+      label: cat.label,
+      elementTypes: [],
+      defaultHidden: cat.defaultHidden || false
+    };
   }
-  return { kind: 'secondary', elementType: 'unknown', category: 'unknown' };
+  return result;
 }
 
 // ---- Main scan ----
 function scan(projectRoot) {
-  const config = loadConfig(projectRoot);
+  const { contract, config } = loadContract(projectRoot);
   const mdFiles = walkMd(projectRoot);
 
-  // Build file objects with relative paths for exclusion checking
   let fileEntries = mdFiles.map(f => ({
     full: f,
     relative: path.relative(projectRoot, f).replace(/\\/g, '/'),
   }));
 
-  // Apply exclusion list (禁读清单)
-  fileEntries = applyExclusions(fileEntries, config && config.exclude, projectRoot);
+  // Apply exclusion list
+  fileEntries = applyExclusions(fileEntries, config._exclude, projectRoot);
 
-  const files = fileEntries.map(fe => {
+  const files = [];
+  const metaFiles = [];
+
+  for (const fe of fileEntries) {
     const f = fe.full;
     const relative = fe.relative;
     const filename = path.basename(f);
@@ -326,40 +143,16 @@ function scan(projectRoot) {
     const content = fs.readFileSync(f, 'utf-8');
     const summary = extractSummary(content);
 
-    // Step 1: classify by filename pattern
-    let { kind, elementType, category } = classifyByPattern(filename);
-    let meta = {}; // carries flags like _pathRefined across the chain
-
-    // Step 2: path-based refinement (directory semantics)
-    const pathRefined = refineByPath(relative, { kind, elementType, category });
-    kind = pathRefined.kind;
-    elementType = pathRefined.elementType;
-    category = pathRefined.category;
-    if (pathRefined._pathRefined) meta._pathRefined = true;
-
-    // Step 3: auto-detection by content signals
-    const refined = refineByContent(content, { kind, elementType, category, _pathRefined: meta._pathRefined }, relative);
-    kind = refined.kind;
-    elementType = refined.elementType;
-    category = refined.category;
+    // docContract-driven classification
+    const classification = classifyFile(relative, contract, summary);
 
-    // Step 4: SUMMARY block as fallback correction (only if auto-detection returned 'unknown')
-    const corrected = applySummaryCorrection(summary, { kind, elementType, category, _pathRefined: meta._pathRefined });
-    kind = corrected.kind;
-    elementType = corrected.elementType;
-    category = corrected.category;
-
-    // Step 5: config paths override category
-    if (config && config.paths) {
-      for (const [cat, cfgPath] of Object.entries(config.paths)) {
-        const normalizedCfg = cfgPath.replace(/\\/g, '/');
-        if (relative.startsWith(normalizedCfg) || relative === normalizedCfg) {
-          category = cat;
-          break;
-        }
-      }
+    if (!classification || classification.isMeta) {
+      metaFiles.push({ path: relative, reason: classification ? 'meta' : 'excluded' });
+      continue;
     }
 
+    const { category, elementType } = classification;
+
     // Extract time info
     const timeInfo = extractTimeInfo(content, filename, stat.mtime.toISOString());
 
@@ -367,24 +160,27 @@ function scan(projectRoot) {
     const titleMatch = content.match(/^#\s+(.+)$/m);
     const title = titleMatch ? titleMatch[1] : filename.replace(/\.md$/, '');
 
-    return {
+    // Determine kind: roadmap, decision, todo → primary; others → secondary
+    const kind = (category === 'roadmap' || category === 'decision' || category === 'todo')
+      ? 'primary' : 'secondary';
+
+    files.push({
       path: relative,
       filename,
       category,
-      kind,                           // v2: 'primary' | 'secondary'
-      elementType,                    // v2: phase|milestone|subtask|conclusion|decision|journal|...
-      type: elementType,              // backward compat alias
+      kind,
+      elementType,
+      type: elementType,
       title,
       size: stat.size,
       modified: stat.mtime.toISOString(),
-      date: timeInfo.date,            // v2: best-guess date
-      dateSource: timeInfo.dateSource,// v2: how date was determined
+      date: timeInfo.date,
+      dateSource: timeInfo.dateSource,
       hasSummary: summary !== null,
       summary: summary || null,
-    };
-  });
+    });
+  }
 
-  // Collect unique element types (v2 additions)
   const primaryCount = files.filter(f => f.kind === 'primary').length;
   const secondaryCount = files.filter(f => f.kind === 'secondary').length;
 
@@ -392,20 +188,20 @@ function scan(projectRoot) {
     scannedAt: new Date().toISOString(),
     projectRoot,
     totalFiles: files.length,
-    primaryCount,                          // v2
-    secondaryCount,                        // v2
+    primaryCount,
+    secondaryCount,
     filesWithSummary: files.filter(f => f.hasSummary).length,
     categories: [...new Set(files.map(f => f.category))],
-    elementTypes: [...new Set(files.map(f => f.elementType))],  // v2
+    elementTypes: [...new Set(files.map(f => f.elementType))],
+    metaExcluded: metaFiles.length,
     files,
   };
 }
 
 module.exports = {
-  scan, walkMd, classifyByPattern, refineByPath, refineByContent,
-  extractSummary, extractTimeInfo, loadConfig,
-  applySummaryCorrection, applyExclusions, normalizeCategory, DISPLAY_CATEGORIES,
-  PRIMARY_CATEGORIES,
+  scan, walkMd, extractSummary, extractTimeInfo,
+  applyExclusions, loadConfig, buildDisplayCategories,
+  classifyFile: require('../contract/loader').classifyFile
 };
 
 if (require.main === module) {