sandtable 0.4.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandtable",
-  "version": "0.4.0",
+  "version": "1.0.1",
   "description": "AI 编程项目可视化指挥面板 — 双视图 dashboard，多源数据融合",
   "main": "src/cli/sandtable.js",
   "bin": {

package/server.js

@@ -36,17 +36,26 @@ const MIME = {
   '.svg': 'image/svg+xml',
 };
 
-// Only serve from these two directories — project sources are not exposed
+// Only serve from these directories — project sources are not exposed
 const ALLOWED_PREFIXES = [
   path.join(ROOT, 'dashboard'),
   path.join(ROOT, 'data'),
+  path.join(ROOT, 'docs'),
 ];
 
+// Root-level files that are safe to serve (documentation, config)
+const ROOT_ALLOWED = new Set([
+  'AGENTS.md', 'CLAUDE.md', 'README.md', 'INSTALL.md',
+  'CHANGELOG.md', 'CONTRIBUTING.md',
+]);
+
 function isAllowed(filePath) {
   if (!filePath.startsWith(ROOT)) return false;
   for (const prefix of ALLOWED_PREFIXES) {
     if (filePath.startsWith(prefix)) return true;
   }
+  // Allow specific root-level documentation files
+  if (ROOT_ALLOWED.has(path.relative(ROOT, filePath))) return true;
   return false;
 }
 

package/src/builder/build.js

@@ -3,7 +3,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { scan, loadConfig, normalizeCategory, DISPLAY_CATEGORIES, PRIMARY_CATEGORIES } = require('../scanner/scan');
+const { scan } = require('../scanner/scan');
+const { buildTracks } = require('../progress/parser');
+const { loadContract } = require('../contract/loader');
 
 // ---- Markdown Table Parser (unchanged from v1) ----
 function parseMarkdownTables(content) {
@@ -30,201 +32,45 @@ function parseMarkdownTables(content) {
   return results;
 }
 
-// ---- Primary Tree Builder ----
-function buildPrimaryTree(planFiles, allFiles, projectRoot) {
+// ---- Tracks to Elements (converts parser output to timeline element format) ----
+function tracksToElements(tracks) {
   const elements = [];
-
-  // Collect task rows from task-board-like files
-  const taskRows = [];
-  for (const pf of planFiles) {
-    const fp = path.join(projectRoot, pf.path);
-    if (!fs.existsSync(fp)) continue;
-    const content = fs.readFileSync(fp, 'utf-8');
-    const tables = parseMarkdownTables(content);
-    const hasTaskCols = tables.length > 0 &&
-      (Object.keys(tables[0]).some(k => /任务|task|#/.test(k)));
-    if (hasTaskCols) {
-      for (const row of tables) {
-        taskRows.push({ ...row, _source: pf.path });
-      }
-    }
-  }
-
-  // Build phases from milestone/plan files with markdown tables
-  const milestoneFiles = planFiles.filter(f =>
-    f.elementType === 'milestone' ||
-    (f.summary && f.summary.type === 'milestone')
-  );
-
-  for (const mf of milestoneFiles) {
-    const fp = path.join(projectRoot, mf.path);
-    if (!fs.existsSync(fp)) continue;
-    const content = fs.readFileSync(fp, 'utf-8');
-    const rows = parseMarkdownTables(content);
-
-    const milestones = rows.map((row, i) => {
-      const keys = Object.keys(row);
-      const milestoneName = row[keys[0]] || '';
-      const version = row[keys[1]] || '';
-      const signal = row[keys[2]] || '';
-      const statusRaw = (row[keys[3]] || 'pending').toLowerCase();
-      const status = statusRaw.includes('in_progress') ? 'in_progress'
-        : statusRaw.includes('complete') ? 'completed'
-        : statusRaw.includes('block') ? 'blocked'
-        : 'pending';
-
-      // Match subtasks from task board
-      const subtasks = taskRows
-        .filter(tr => {
-          const taskName = tr[Object.keys(tr)[1]] || tr[Object.keys(tr)[0]] || '';
-          return taskName.includes(milestoneName) ||
-            milestoneName.includes(taskName.substring(0, 6));
-        })
-        .slice(0, 3)
-        .map(tr => {
-          const tKeys = Object.keys(tr);
-          const statusKey = tKeys.find(k => /状态|status/i.test(k));
-          const statusCol = statusKey ? tr[statusKey] : (tr[tKeys[4]] || tr[tKeys[3]] || '');
-          const isCompleted = /✅|\[x\]|completed|complete/i.test(statusCol);
-          const isInProgress = /⏳|\[\s*\]|in.progress/i.test(statusCol);
-          const typeKey = tKeys.find(k => /类型|type/i.test(k));
-          const typeCol = typeKey ? tr[typeKey] : (tr[tKeys[3]] || tr[tKeys[2]] || '');
-          return {
-            id: tr[tKeys[0]] || '',
-            name: tr[tKeys[1]] || tr[tKeys[0]] || '',
-            status: isCompleted ? 'completed' : isInProgress ? 'in_progress' : 'pending',
-            kind: 'primary',
-            elementType: 'subtask',
-            timeGroup: 'current',
-            timeLabel: '',
-            date: null,
-            source: { file: tr._source || mf.path, title: mf.title },
-            summary: '',
-            tags: [],
-            related: [],
-            children: [],
-          };
-        });
-
-      return {
-        id: 'ms-' + (milestoneName.replace(/^M/, '').substring(0, 10) || `M${i + 1}`),
-        kind: 'primary',
-        elementType: 'milestone',
-        category: 'roadmap',
-        name: version ? `${milestoneName} (${version})` : milestoneName,
-        status,
-        timeGroup: 'current',
-        timeLabel: signal,
-        date: mf.date || null,
-        source: { file: mf.path, title: mf.title },
-        summary: '',
-        tags: [],
-        related: [],
-        children: subtasks,
-        order: i + 1,
-      };
-    });
-
-    elements.push({
-      id: 'phase-' + (elements.length + 1),
-      kind: 'primary',
-      elementType: 'phase',
-      category: 'roadmap',
-      name: mf.summary ? mf.summary.summary : mf.title,
-      status: mf.summary ? mf.summary.status : 'in_progress',
-      timeGroup: 'current',
-      timeLabel: '',
-      date: mf.date || null,
-      source: { file: mf.path, title: mf.title },
-      summary: mf.summary ? (mf.summary.summary || '') : '',
-      tags: mf.summary ? (mf.summary.tags || []) : [],
-      related: mf.summary ? (mf.summary.related || []) : [],
-      children: milestones,
-      order: elements.length + 1,
-    });
-  }
-
-  // Fallback: default phase from any plan-category files with summaries
-  if (elements.length === 0 && planFiles.length > 0) {
-    const tasks = planFiles
-      .filter(f => f.summary)
-      .map(f => ({
-        id: 'task-' + f.path.replace(/[/.]/g, '-'),
-        kind: 'primary',
-        elementType: 'task',
-        category: 'roadmap',
-        name: f.summary.summary,
-        status: f.summary.status || 'pending',
-        timeGroup: 'current',
-        timeLabel: '',
-        date: f.date || null,
-        source: { file: f.path, title: f.title },
-        summary: f.summary.summary || '',
-        tags: f.summary.tags || [],
-        related: f.summary.related || [],
-        children: [],
-      }));
-
-    elements.push({
-      id: 'phase-default',
-      kind: 'primary',
-      elementType: 'phase',
-      category: 'roadmap',
-      name: '当前阶段',
-      status: 'in_progress',
-      timeGroup: 'current',
-      timeLabel: '',
-      date: null,
-      source: { file: '', title: '' },
-      summary: '',
-      tags: [],
-      related: [],
-      children: [{
-        id: 'ms-current',
+  for (const track of tracks) {
+    for (const phase of track.phases) {
+      elements.push({
+        id: 'ms-' + track.id + '-' + phase.id.replace(/[^a-zA-Z0-9]/g, '-'),
         kind: 'primary',
         elementType: 'milestone',
         category: 'roadmap',
-        name: '进行中',
-        status: 'in_progress',
+        name: phase.name,
+        status: phase.status,
         timeGroup: 'current',
-        timeLabel: '',
-        date: null,
-        source: { file: '', title: '' },
+        timeLabel: phase.batch || '',
+        date: phase.date || null,
+        source: { file: track.source, title: phase.name },
         summary: '',
-        tags: [],
+        tags: [track.id],
         related: [],
-        children: tasks,
-        order: 1,
-      }],
-      order: 1,
-    });
-  }
-
-  // Extract conclusion elements from files with type=conclusion
-  const conclusionFiles = allFiles.filter(f =>
-    f.elementType === 'conclusion' ||
-    (f.summary && f.summary.type === 'conclusion')
-  );
-  for (const cf of conclusionFiles) {
-    elements.push({
-      id: 'conclusion-' + cf.path.replace(/[/.]/g, '-'),
-      kind: 'primary',
-      elementType: 'conclusion',
-      category: 'roadmap',
-      name: cf.title,
-      status: cf.summary ? (cf.summary.status || 'completed') : 'completed',
-      timeGroup: 'past',
-      timeLabel: cf.date || '',
-      date: cf.date || null,
-      source: { file: cf.path, title: cf.title },
-      summary: cf.summary ? (cf.summary.summary || '') : '',
-      tags: cf.summary ? (cf.summary.tags || []) : [],
-      related: cf.summary ? (cf.summary.related || []) : [],
-      children: [],
-      order: 0,
-    });
+        children: (phase.tasks || []).map(t => ({
+          id: 'task-' + t.id.replace(/[^a-zA-Z0-9]/g, '-'),
+          kind: 'primary',
+          elementType: 'subtask',
+          category: 'roadmap',
+          name: t.title,
+          status: t.status,
+          timeGroup: 'current',
+          timeLabel: '',
+          date: null,
+          source: { file: track.source, title: t.title },
+          summary: '',
+          tags: [track.id, t.actor].filter(Boolean),
+          related: [],
+          children: [],
+        })),
+        order: elements.length + 1,
+      });
+    }
   }
-
   return elements;
 }
 
@@ -278,25 +124,29 @@ function classifyTimeGroup(element, timeRules, today) {
 
 // ---- Filter Type Manifest Builder ----
 function buildFilterTypes(files, secondaryTypesDefaultOff) {
-  const secondaryFiles = files.filter(f => f.kind === 'secondary');
-  const catCounts = {};
-
-  for (const f of secondaryFiles) {
-    const cat = normalizeCategory(f.elementType);
-    catCounts[cat] = (catCounts[cat] || 0) + 1;
-  }
-
-  const result = [];
-  for (const [cat, def] of Object.entries(DISPLAY_CATEGORIES)) {
-    // Skip primary-only categories (all their elementTypes are kind=primary, no secondary files)
-    if (PRIMARY_CATEGORIES && PRIMARY_CATEGORIES.has(cat)) continue;
-    const count = catCounts[cat] || 0;
-    if (count > 0) {
-      result.push({ type: cat, label: def.label, count, defaultEnabled: !secondaryTypesDefaultOff });
+  // Derive filter types from actual file data instead of hardcoded constants
+  const filterTypes = [];
+  const seen = new Set();
+  for (const f of files) {
+    const key = f.category + ':' + f.elementType;
+    if (!seen.has(key)) {
+      seen.add(key);
+      filterTypes.push({
+        category: f.category,
+        type: f.elementType,
+        label: (f.category || 'unknown') + ' › ' + (f.elementType || 'unknown'),
+        count: 0,
+        defaultEnabled: !secondaryTypesDefaultOff
+      });
     }
   }
-
-  return result;
+  // Count occurrences
+  for (const f of files) {
+    const key = f.category + ':' + f.elementType;
+    const ft = filterTypes.find(ft => (ft.category + ':' + ft.type) === key);
+    if (ft) ft.count++;
+  }
+  return filterTypes;
 }
 
 // ---- Conventions Builder (auto-extract from docs/conventions/) ----
@@ -768,21 +618,20 @@ function buildTimeline(files, projectRoot, config) {
   const displayCfg = (config && config.display) ? config.display : {};
   const maxBriefLength = displayCfg.maxBriefLength || 200;
 
-  // Step 1: Build primary tree from roadmap-category files
-  const planFiles = files.filter(f =>
-    f.kind === 'primary' && (f.category === 'roadmap' || f.elementType === 'phase' ||
-      f.elementType === 'milestone' || f.elementType === 'roadmap' || f.elementType === 'task' || f.elementType === 'subtask')
-  );
+  // Step 1: Build tracks from progressSources (replaces buildPrimaryTree)
+  const progressSources = (config && config._progressSources) ? config._progressSources : [];
+  const { tracks, currentNode } = buildTracks(progressSources, projectRoot);
+
+  // Convert tracks to elements format for backward compatibility
+  const primaryTree = tracksToElements(tracks);
 
   // Also include decision/refactor/conclusion type primary files
   const otherPrimary = files.filter(f =>
-    f.kind === 'primary' && !planFiles.includes(f) &&
+    f.kind === 'primary' &&
     (f.elementType === 'decision' || f.elementType === 'conclusion' ||
      f.elementType === 'refactor' || f.category === 'decision')
   );
 
-  const primaryTree = buildPrimaryTree(planFiles, files, projectRoot);
-
   // Build primary flat list for non-plan primary files
   const primaryFlat = otherPrimary
     .filter(f => f.hasSummary || f.elementType !== 'unknown')
@@ -844,6 +693,8 @@ function buildTimeline(files, projectRoot, config) {
     elements: allElements,
     events,
     filterTypes,
+    tracks,
+    currentNode,
     display: {
       secondaryTypesDefaultOff: displayCfg.secondaryTypesDefaultOff !== false,
       conventionsManualOnly: displayCfg.conventionsManualOnly !== false,
@@ -854,34 +705,73 @@ function buildTimeline(files, projectRoot, config) {
 
 // ---- Backward Compatibility: timeline → roadmap.json ----
 function timelineToRoadmapCompat(timeline) {
-  const phases = [];
-  for (const el of timeline.elements) {
+  var phases = [];
+
+  // New: source phases from tracks when available
+  if (timeline.tracks && timeline.tracks.length > 0) {
+    for (var ti = 0; ti < timeline.tracks.length; ti++) {
+      var track = timeline.tracks[ti];
+      for (var pi = 0; pi < track.phases.length; pi++) {
+        var phase = track.phases[pi];
+        phases.push({
+          id: 'phase-' + track.id + '-' + phase.id.replace(/[^a-zA-Z0-9]/g, '-'),
+          name: phase.name,
+          status: phase.status,
+          order: phases.length + 1,
+          trackId: track.id,
+          milestones: [{
+            id: 'ms-' + track.id + '-' + phase.id.replace(/[^a-zA-Z0-9]/g, '-'),
+            name: phase.name,
+            status: phase.status,
+            owner: phase.batch || '',
+            subtasks: (phase.tasks || []).map(function(t) {
+              return {
+                id: 'task-' + t.id.replace(/[^a-zA-Z0-9]/g, '-'),
+                name: t.title,
+                status: t.status,
+                type: t.actor || 'hand',
+              };
+            }),
+          }],
+        });
+      }
+    }
+  }
+
+  // Fallback: old phase-based filtering (for non-track elements)
+  for (var i = 0; i < timeline.elements.length; i++) {
+    var el = timeline.elements[i];
     if (el.kind === 'primary' && el.elementType === 'phase') {
       phases.push({
         id: el.id,
         name: el.name,
         status: el.status,
         order: el.order || phases.length + 1,
-        milestones: (el.children || []).map(ch => ({
-          id: ch.id,
-          name: ch.name,
-          status: ch.status,
-          owner: ch.source ? ch.source.file : '',
-          subtasks: (ch.children || []).map(st => ({
-            id: st.id,
-            name: st.name,
-            status: st.status,
-            type: st.elementType || 'hand',
-          })),
-        })),
+        milestones: [{
+          id: el.id,
+          name: el.name,
+          status: el.status,
+          owner: el.source ? el.source.file : '',
+          subtasks: (el.children || []).map(function(st) {
+            return {
+              id: st.id,
+              name: st.name,
+              status: st.status,
+              type: st.elementType || 'hand',
+            };
+          }),
+        }],
       });
     }
   }
+
   return {
     project: timeline.project,
     updated: timeline.updated,
     brief: timeline.brief,
-    phases,
+    tracks: timeline.tracks || [],
+    currentNode: timeline.currentNode || null,
+    phases: phases,
   };
 }
 
@@ -947,7 +837,7 @@ function buildTokenSummary(projectRoot, config) {
 function build(projectRoot) {
   const scanResult = scan(projectRoot);
   const { files } = scanResult;
-  const config = loadConfig(projectRoot);
+  const { config } = loadContract(projectRoot);
 
   const timeline = buildTimeline(files, projectRoot, config);
   const conventions = buildConventions(files, projectRoot);
@@ -1006,10 +896,11 @@ function build(projectRoot) {
 }
 
 module.exports = {
-  build, buildTimeline, buildPrimaryTree, buildSecondaryList,
+  build, buildTimeline, buildSecondaryList,
   classifyTimeGroup, buildFilterTypes, buildConventions,
   buildAgents, timelineToRoadmapCompat, timelineToJournalCompat,
   EVENT_TYPES, classifyEventPriority, buildTokenSummary,
+  buildTracks, tracksToElements,
 };
 
 if (require.main === module) {

package/src/check/check.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { scan } = require('../scanner/scan');
+const { loadContract } = require('../contract/loader');
+const { buildTracks } = require('../progress/parser');
+
+function check(projectRoot) {
+  try {
+    const results = [];
+    const { contract, config } = loadContract(projectRoot);
+    const scanResult = scan(projectRoot);
+
+    // Check 1: Classification completeness
+    const unclassified = scanResult.files.filter(f => f.category === 'unknown');
+    results.push({
+      id: 'classification',
+      status: unclassified.length === 0 ? 'pass' : 'warning',
+      detail: unclassified.length > 0
+        ? unclassified.length + ' files unclassified: ' + unclassified.map(f => f.path).slice(0, 10).join(', ') + (unclassified.length > 10 ? '...' : '')
+        : 'All files classified'
+    });
+
+    // Check 2: MECE completeness
+    const catCounts = {};
+    for (const f of scanResult.files) {
+      catCounts[f.category] = (catCounts[f.category] || 0) + 1;
+    }
+    const emptyCats = (contract.categories || []).filter(c => !catCounts[c.id]);
+    results.push({
+      id: 'mece',
+      status: emptyCats.length === 0 ? 'pass' : 'warning',
+      detail: emptyCats.length > 0
+        ? 'Empty categories: ' + emptyCats.map(c => c.label).join(', ')
+        : 'All categories have files'
+    });
+
+    // Check 3: Progress consistency (if progressSources configured)
+    const progressSources = config._progressSources || [];
+    if (progressSources.length > 0) {
+      const { tracks } = buildTracks(progressSources, projectRoot);
+      results.push({
+        id: 'progress',
+        status: 'pass',
+        detail: tracks.length + ' tracks parsed'
+      });
+
+      // Check for status conflicts between tracks
+      const conflicts = [];
+      for (let i = 0; i < tracks.length; i++) {
+        for (let j = i + 1; j < tracks.length; j++) {
+          const idsA = new Set(tracks[i].phases.map(p => p.id));
+          for (const phase of tracks[j].phases) {
+            if (idsA.has(phase.id)) {
+              const other = tracks[i].phases.find(p => p.id === phase.id);
+              if (other && other.status !== phase.status) {
+                conflicts.push(phase.id + ': ' + tracks[i].id + '=' + other.status + ' vs ' + tracks[j].id + '=' + phase.status);
+              }
+            }
+          }
+        }
+      }
+      if (conflicts.length > 0) {
+        results.push({
+          id: 'consistency',
+          status: 'warning',
+          detail: 'Status conflicts: ' + conflicts.join('; ')
+        });
+      }
+    }
+
+    // Check 4: SUMMARY coverage
+    const withSummary = scanResult.files.filter(f => f.hasSummary).length;
+    const total = scanResult.files.length;
+    const pct = Math.round(withSummary / Math.max(total, 1) * 100);
+    results.push({
+      id: 'summary',
+      status: pct > 20 ? 'pass' : 'info',
+      detail: withSummary + '/' + total + ' (' + pct + '%) files have SUMMARY'
+    });
+
+    // Check 5: Meta exclusion
+    results.push({
+      id: 'exclusion',
+      status: 'pass',
+      detail: (scanResult.metaExcluded || 0) + ' meta files excluded'
+    });
+
+    // Overall
+    const hasWarning = results.some(r => r.status === 'warning');
+    const hasError = results.some(r => r.status === 'error');
+
+    return {
+      passed: !hasWarning && !hasError,
+      project: path.basename(projectRoot),
+      timestamp: new Date().toISOString(),
+      results
+    };
+  } catch (e) {
+    return {
+      passed: false,
+      project: path.basename(projectRoot),
+      timestamp: new Date().toISOString(),
+      results: [{
+        id: 'fatal',
+        status: 'error',
+        detail: 'Check failed: ' + e.message
+      }]
+    };
+  }
+}
+
+// Human-readable output
+function printCheck(report) {
+  console.log('\n=== Sandtable Check ===');
+  for (const r of report.results) {
+    const icon = r.status === 'pass' ? '\u2713' : r.status === 'warning' ? '\u26A0' : '\u2717';
+    console.log(icon + ' ' + r.id + ': ' + r.detail);
+  }
+  console.log('\nexit code: ' + (report.passed ? 0 : 1));
+}
+
+module.exports = { check, printCheck };
+
+if (require.main === module) {
+  const root = process.argv[2] || process.cwd();
+  const report = check(root);
+  printCheck(report);
+
+  // Write JSON report
+  const dataDir = path.join(root, 'data');
+  if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(path.join(dataDir, 'check-report.json'), JSON.stringify(report, null, 2));
+  process.exit(report.passed ? 0 : 1);
+}

package/src/cli/sandtable.js

@@ -814,6 +814,40 @@ switch (command) {
     initCommand(process.cwd(), applyMode, lang, hooksMode, injectAgentsMd);
     break;
   }
+  case 'check': {
+    const { check, printCheck } = require('../check/check');
+    const projectRoot = process.argv[3] || process.cwd();
+    const report = check(projectRoot);
+    printCheck(report);
+
+    // Write JSON report
+    const dataDir = path.join(projectRoot, 'data');
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(path.join(dataDir, 'check-report.json'), JSON.stringify(report, null, 2));
+    process.exit(report.passed ? 0 : 1);
+  }
+  case 'test': {
+    const fixtureIdx = process.argv.indexOf('--fixture');
+    if (fixtureIdx === -1) {
+      console.log('用法: sandtable test --fixture <项目路径>');
+      console.log('  以指定项目为 golden fixture 运行回归验证');
+      process.exit(1);
+    }
+    const fixturePath = process.argv[fixtureIdx + 1];
+    if (!fixturePath) {
+      console.log('错误：--fixture 需要指定项目路径');
+      process.exit(1);
+    }
+    // Run the fixture test
+    const testScript = require('path').join(__dirname, '..', '..', 'tests', 'run-libero-validation.js');
+    if (require('fs').existsSync(testScript)) {
+      require(testScript).run(fixturePath);
+    } else {
+      console.log('Fixture test script not found (' + testScript + '). Run from Sandtable repo root.');
+      process.exit(1);
+    }
+    break;
+  }
   case 'summarize': {
     const scanResult = scan(root);
     const missing = scanResult.files.filter(f => !f.hasSummary);
@@ -1291,6 +1325,8 @@ case 'token-log': {
     console.log('  sandtable scan       [projectRoot]             扫描文档目录');
     console.log('  sandtable build      [projectRoot]             生成 data/*.json');
     console.log('  sandtable serve      [port] [--watch] [--host <ip>] [--token <token>]  启动服务 + 打开浏览器');
+    console.log('  sandtable check      [projectRoot]             一致性校验');
+    console.log('  sandtable test       --fixture <path>           golden fixture 回归测试');
     console.log('  sandtable summarize  [projectRoot]             列出缺少摘要块的文件');
     console.log('  sandtable event-log  <typeId> <title> [...]    记录人机协同事件');
     console.log('  sandtable token-log  <skill> <in> <out> [...]  追加 token 消耗日志');