sandtable 0.3.1 → 1.0.1

package/src/scanner/scan.js.v0.4.bak

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---- 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)
+function globToRegex(pattern) {
+  let re = '';
+  const parts = pattern.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    if (i > 0) re += '\\/';
+    if (parts[i] === '**') {
+      re += '.*';
+    } else {
+      let seg = parts[i]
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\?/g, '.')
+        .replace(/\*/g, '[^/]*');
+      re += seg;
+    }
+  }
+  // '**' at end should match everything under that directory
+  if (pattern.endsWith('/**')) {
+    re += '(?:\\/.*)?';
+  }
+  return new RegExp('^' + re + '$', 'i');
+}
+
+function applyExclusions(files, excludeConfig, projectRoot) {
+  if (!excludeConfig) return files;
+
+  const patternRes = (excludeConfig.patterns || []).map(p => globToRegex(p));
+  const pathPrefixes = (excludeConfig.paths || []).map(p => {
+    const abs = require('path').resolve(projectRoot, p).replace(/\\/g, '/');
+    return abs;
+  });
+
+  return files.filter(f => {
+    const rp = f.relative || f.path;
+    for (const re of patternRes) {
+      if (re.test(rp)) return false;
+    }
+    const full = (f.full || require('path').resolve(projectRoot, f.path || '')).replace(/\\/g, '/');
+    for (const prefix of pathPrefixes) {
+      if (full.startsWith(prefix)) return false;
+    }
+    return true;
+  });
+}
+
+// ---- Config loading ----
+function loadConfig(projectRoot) {
+  const configPath = path.join(projectRoot, '.sandtable.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+// ---- File walking ----
+function walkMd(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMd(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+// ---- SUMMARY block extraction ----
+function extractSummary(content) {
+  const match = content.match(/<!--\s*SUMMARY\s*([\s\S]*?)\s*-->/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+// ---- Time info extraction (hour precision) ----
+function extractTimeInfo(content, filename, fileModified) {
+  const mtimeISO = new Date(fileModified).toISOString();
+
+  // 1. Date from filename: YYYY-MM-DD format → set to noon local
+  const dateInName = filename.match(/(\d{4}-\d{2}-\d{2})/);
+  if (dateInName) return { date: dateInName[1] + 'T12:00:00+08:00', dateSource: 'filename' };
+
+  // 2. Date from content (first YYYY-MM-DD occurrence) → set to noon local
+  const dateInContent = content.match(/(\d{4}-\d{2}-\d{2})/);
+  if (dateInContent) return { date: dateInContent[1] + 'T12:00:00+08:00', dateSource: 'content' };
+
+  // 3. Fall back to file modification time (already has hour precision)
+  return { date: mtimeISO, dateSource: 'mtime' };
+}
+
+// ---- Pattern-based classification ----
+function classifyByPattern(filename) {
+  for (const pattern of PATTERNS) {
+    if (pattern.test(filename)) {
+      return pattern.classify();
+    }
+  }
+  return { kind: 'secondary', elementType: 'unknown', category: 'unknown' };
+}
+
+// ---- Main scan ----
+function scan(projectRoot) {
+  const config = loadConfig(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);
+
+  const files = fileEntries.map(fe => {
+    const f = fe.full;
+    const relative = fe.relative;
+    const filename = path.basename(f);
+    const stat = fs.statSync(f);
+    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;
+
+    // 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;
+        }
+      }
+    }
+
+    // Extract time info
+    const timeInfo = extractTimeInfo(content, filename, stat.mtime.toISOString());
+
+    // H1 title
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1] : filename.replace(/\.md$/, '');
+
+    return {
+      path: relative,
+      filename,
+      category,
+      kind,                           // v2: 'primary' | 'secondary'
+      elementType,                    // v2: phase|milestone|subtask|conclusion|decision|journal|...
+      type: elementType,              // backward compat alias
+      title,
+      size: stat.size,
+      modified: stat.mtime.toISOString(),
+      date: timeInfo.date,            // v2: best-guess date
+      dateSource: timeInfo.dateSource,// v2: how date was determined
+      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;
+
+  return {
+    scannedAt: new Date().toISOString(),
+    projectRoot,
+    totalFiles: files.length,
+    primaryCount,                          // v2
+    secondaryCount,                        // v2
+    filesWithSummary: files.filter(f => f.hasSummary).length,
+    categories: [...new Set(files.map(f => f.category))],
+    elementTypes: [...new Set(files.map(f => f.elementType))],  // v2
+    files,
+  };
+}
+
+module.exports = {
+  scan, walkMd, classifyByPattern, refineByPath, refineByContent,
+  extractSummary, extractTimeInfo, loadConfig,
+  applySummaryCorrection, applyExclusions, normalizeCategory, DISPLAY_CATEGORIES,
+  PRIMARY_CATEGORIES,
+};
+
+if (require.main === module) {
+  const root = process.argv[2] || process.cwd();
+  const result = scan(root);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}

package/templates/.sandtable.template.json

@@ -1,32 +1,33 @@
 {
-  "_schema": "3.0",
-  "_comment": "sandtable v3 配置文件。将此文件复制到项目根目录并改名为 .sandtable.json，按需编辑。",
+  "_schema": "4.0",
+  "_comment": "sandtable v1.0 配置文件。将此文件复制到项目根目录并改名为 .sandtable.json，按需编辑。",
 
-  "paths": {
-    "_comment": "覆盖默认目录到类别的映射。不配则用内置规则自动检测。",
-    "plan": "docs/plan/",
-    "archive": "docs/journal/",
-    "convention": "docs/conventions/",
-    "spec": "docs/specs/"
+  "docContract": {
+    "schema": "sandtable-v1",
+    "categories": [
+      { "id": "roadmap", "label": "路线图与进度", "order": 1, "paths": ["docs/plan/**", "docs/specs/*roadmap*", "docs/specs/*phase*", "docs/specs/*bug-collect*"] },
+      { "id": "decision", "label": "决策记录", "order": 2, "paths": ["docs/specs/decisions/**"] },
+      { "id": "spec", "label": "业务规格", "order": 3, "paths": ["docs/specs/**"] },
+      { "id": "convention", "label": "协作纪律", "order": 4, "paths": ["docs/skills/**", "docs/agents/**", "docs/conventions/**", "AGENTS.md", "CLAUDE.md"] },
+      { "id": "ops", "label": "运维与基建", "order": 5, "paths": ["docs/runbooks/**"] },
+      { "id": "archive", "label": "历史档案", "order": 6, "paths": ["docs/plans/**", "docs/journal/**", "docs/archive/**"], "defaultHidden": true }
+    ],
+    "meta": [
+      "docs/*-reference.md",
+      "docs/*-glossary.md"
+    ]
   },
 
-  "timeRules": {
-    "_comment": "classifyBy: 'status' 按状态分类, 'date' 按日期分类。",
-    "classifyBy": "status",
-    "pastStatus": ["completed", "cancelled"],
-    "currentStatus": ["in_progress", "pending"],
-    "futureStatus": []
-  },
+  "progressSources": [],
 
-  "display": {
-    "_comment": "secondaryTypesDefaultOff: true = 次要元素 checkbox 默认不勾选。conventionsManualOnly: true = conventions bar 默认显示'待配置'占位。",
-    "secondaryTypesDefaultOff": true,
-    "conventionsManualOnly": true,
-    "maxBriefLength": 200
+  "events": {
+    "_comment": "事件流配置。gitLog: 是否从 git log 生成代码变更事件。maxGitLogEntries: 最多拉取多少条。",
+    "gitLog": true,
+    "maxGitLogEntries": 100
   },
 
   "exclude": {
-    "_comment": "排除清单（禁读清单）。patterns 用 glob 匹配文件路径，paths 按绝对路径前缀匹配。命中任一规则则跳过不扫描。",
+    "_comment": "排除清单。patterns 用 glob 匹配文件路径。",
     "patterns": [
       "**/.env*",
       "**/credentials*",
@@ -42,10 +43,7 @@
     "paths": []
   },
 
-  "events": {
-    "_comment": "事件流配置。gitLog: 是否从 git log 生成代码变更事件。maxGitLogEntries: 最多拉取多少条。testBaseline: 是否解析测试 JSON（P2）。",
-    "gitLog": true,
-    "maxGitLogEntries": 100,
-    "testBaseline": false
+  "display": {
+    "maxBriefLength": 200
   }
 }