sandtable 0.4.0 → 1.0.1

package/src/contract/default-contract.json

@@ -0,0 +1,21 @@
+{
+  "schema": "sandtable-default",
+  "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"
+  ]
+}

package/src/contract/loader.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---- Glob to Regex ----
+const regexCache = {};
+
+function globToRegex(pattern) {
+  if (regexCache[pattern]) return regexCache[pattern];
+
+  let re = '';
+  const parts = pattern.split('/');
+  let skipSep = false;
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === '**') {
+      if (i === 0 && parts.length > 1) {
+        // Leading ** with more parts: match zero or more leading directories
+        re += '(?:.*\\/)?';
+        skipSep = true;
+      } else if (i > 0 && i < parts.length - 1) {
+        // Middle **: required / + optional wildcard dirs including trailing /
+        re += '\\/(?:.*\\/)?';
+        skipSep = true;
+      } else {
+        if (i > 0) re += '\\/';
+        re += '.*';
+      }
+    } else {
+      if (i > 0 && !skipSep) {
+        re += '\\/';
+      }
+      skipSep = false;
+      let seg = parts[i]
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\?/g, '.')
+        .replace(/\*/g, '[^/]*');
+      re += seg;
+    }
+  }
+  if (pattern.endsWith('/**')) {
+    re += '(?:\\/.*)?';
+  }
+  // Case-insensitive matching for cross-platform compatibility
+  const regex = new RegExp('^' + re + '$', 'i');
+  regexCache[pattern] = regex;
+  return regex;
+}
+
+// ---- Load contract: user config > built-in default ----
+function loadContract(projectRoot) {
+  const configPath = path.join(projectRoot, '.sandtable.json');
+  let userContract = null;
+
+  let config = {
+    _progressSources: [],
+    _events: { gitLog: true, maxGitLogEntries: 100 },
+    _exclude: null
+  };
+
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (config.docContract) {
+        userContract = config.docContract;
+      }
+      config._progressSources = config.progressSources || [];
+      config._events = config.events || { gitLog: true, maxGitLogEntries: 100 };
+      config._exclude = config.exclude || null;
+    } catch (e) {
+      // Config parse error — fall through to default
+      console.warn('sandtable: .sandtable.json parse error, using default contract —', e.message);
+    }
+  }
+
+  // Fallback: built-in default contract when no user contract found
+  if (!userContract) {
+    const defaultPath = path.join(__dirname, 'default-contract.json');
+    userContract = JSON.parse(fs.readFileSync(defaultPath, 'utf-8'));
+  }
+
+  return { contract: userContract, config };
+}
+
+// ---- Classify a single file by docContract ----
+// Returns { category, elementType, isMeta } or null if excluded
+function classifyFile(relativePath, contract, summaryBlock) {
+  if (!contract) return null;
+
+  // 1. Check meta exclusion
+  const meta = contract.meta || [];
+  for (const m of meta) {
+    const re = globToRegex(m);
+    if (re.test(relativePath)) {
+      return { category: 'meta', elementType: 'meta', isMeta: true };
+    }
+  }
+
+  // 2. SUMMARY block explicit category override (highest priority)
+  if (summaryBlock && summaryBlock.category) {
+    const cat = contract.categories.find(c => c.id === summaryBlock.category);
+    if (cat) {
+      return {
+        category: cat.id,
+        elementType: summaryBlock.type || 'unknown',
+        isMeta: false
+      };
+    }
+  }
+
+  // 3. Longest-match glob across all category paths
+  let bestMatch = null;
+  let bestLen = 0;
+
+  for (const cat of contract.categories) {
+    for (const pat of (cat.paths || [])) {
+      const re = globToRegex(pat);
+      if (re.test(relativePath)) {
+        if (pat.length > bestLen) {
+          bestLen = pat.length;
+          bestMatch = cat;
+        }
+      }
+    }
+  }
+
+  if (bestMatch) {
+    return {
+      category: bestMatch.id,
+      elementType: inferElementType(relativePath, bestMatch.id),
+      isMeta: false
+    };
+  }
+
+  // 4. Unknown
+  return { category: 'unknown', elementType: 'unknown', isMeta: false };
+}
+
+// ---- Element type inference map (module-level to avoid re-creation) ----
+const ELEMENT_TYPE_MAP = {
+  roadmap: [
+    { test: /roadmap|execution-plan/, type: 'roadmap' },
+    { test: /bug-collect/, type: 'backlog' },
+    { test: /phase/, type: 'phase' }
+  ],
+  decision: [
+    { test: /\d{4}-\d{2}-\d{2}/, type: 'decision' },
+    { test: /refactor/i, type: 'refactor' }
+  ],
+  spec: [
+    { test: /intents?\//, type: 'intent' },
+    { test: /refactors?\//, type: 'refactor' },
+    { test: /testing\//, type: 'spec' },
+    { test: /prompts?\//, type: 'prompt' },
+    { test: /template/, type: 'template' },
+    { test: /architecture/, type: 'spec' }
+  ],
+  convention: [
+    { test: /skills?\//, type: 'convention' },
+    { test: /agents?\//, type: 'convention' },
+    { test: /AGENTS\.md|CLAUDE\.md/, type: 'convention' }
+  ],
+  ops: [
+    { test: /runbooks?\//, type: 'runbook' }
+  ],
+  archive: [
+    { test: /journal/, type: 'journal' },
+    { test: /plans?\//, type: 'plan_doc' },
+    { test: /handover/, type: 'handover' }
+  ]
+};
+
+// ---- Infer elementType from category + path ----
+function inferElementType(relativePath, category) {
+  const rp = relativePath.toLowerCase();
+  const rules = ELEMENT_TYPE_MAP[category] || [];
+  for (const rule of rules) {
+    if (rule.test.test(rp)) return rule.type;
+  }
+  return category;
+}
+
+// ---- Get ordered list of categories for UI ----
+function getCategoryList(contract) {
+  if (!contract) return [];
+  return [...contract.categories].sort((a, b) => a.order - b.order);
+}
+
+// ---- Check if a file path should be excluded ----
+function isExcluded(relativePath, excludeConfig) {
+  if (!excludeConfig) return false;
+  const patternRes = (excludeConfig.patterns || []).map(p => globToRegex(p));
+  for (const re of patternRes) {
+    if (re.test(relativePath)) return true;
+  }
+  return false;
+}
+
+module.exports = {
+  loadContract, classifyFile, getCategoryList,
+  isExcluded, globToRegex, inferElementType
+};

package/src/progress/parser.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { globToRegex } = require('../contract/loader');
+
+// ---- Parse a Markdown table anchored at a specific heading ----
+function parseTableAtAnchor(content, anchor) {
+  const lines = content.split('\n');
+  let inTarget = false;
+  let header = null;
+  const rows = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect anchor heading (e.g. "## 5.2")
+    if (anchor && line.trim().startsWith(anchor)) {
+      inTarget = true;
+      continue;
+    }
+
+    // Stop at next same-level or higher heading
+    if (inTarget && /^##\s/.test(line) && !line.trim().startsWith(anchor)) {
+      if (rows.length > 0) break;
+      inTarget = false;  // No table found in this section, stop looking
+    }
+    if (inTarget && /^#\s/.test(line) && rows.length > 0) break;
+
+    if (!inTarget) continue;
+
+    // Parse table rows
+    const trimmed = line.trim();
+    if (/^\|.+\|$/.test(trimmed) && !/^\|[-| ]+\|$/.test(trimmed)) {
+      if (!header) {
+        header = trimmed.split('|').map(c => c.trim()).filter(Boolean);
+      } else {
+        const cols = trimmed.split('|').map(c => c.trim()).filter(Boolean);
+        if (cols.length >= 2) {
+          const row = {};
+          header.forEach((h, idx) => { row[h] = cols[idx] || ''; });
+          rows.push(row);
+        }
+      }
+    } else if (!/^\|[-| ]+\|$/.test(trimmed)) {
+      // Non-table line — reset header if we're past the table
+      if (header && rows.length > 0) break;
+      header = null;
+    }
+  }
+
+  return { header, rows };
+}
+
+// ---- Normalize status string to standard enum ----
+function normalizeStatus(rawStatus, statusMap) {
+  if (!rawStatus) return 'pending';
+
+  const trimmed = rawStatus.trim();
+
+  // Direct match in map
+  if (statusMap && statusMap[trimmed]) return statusMap[trimmed];
+
+  // Pattern match in map keys
+  if (statusMap) {
+    for (const [key, value] of Object.entries(statusMap)) {
+      if (trimmed.includes(key.replace(/[*_]/g, ''))) return value;
+    }
+  }
+
+  // Built-in fallback patterns
+  if (/✅|completed|complete|完成|完工/i.test(trimmed)) return 'completed';
+  if (/⏳|in.progress|进行中|next/i.test(trimmed)) return 'in_progress';
+  if (/🚫|blocked|阻塞/i.test(trimmed)) return 'blocked';
+  if (/❌|cancel|取消/i.test(trimmed)) return 'cancelled';
+
+  return 'pending';
+}
+
+// ---- Parse progress from a table source ----
+function parseTableSource(source, projectRoot) {
+  const { file, anchor } = source;
+  const filePath = path.join(projectRoot, file);
+  if (!fs.existsSync(filePath)) return null;
+
+  const fileContent = fs.readFileSync(filePath, 'utf-8');
+  const { header, rows } = parseTableAtAnchor(fileContent, anchor || null);
+
+  if (!header || rows.length === 0) return null;
+
+  return { header, rows };
+}
+
+// ---- Parse progress from a statusLine source ----
+function parseStatusLineSource(source, projectRoot) {
+  const results = [];
+
+  if (source.file) {
+    // Single file mode
+    const filePath = path.join(projectRoot, source.file);
+    if (!fs.existsSync(filePath)) return results;
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    const { regex, itemPattern, statusMap } = source.statusLinePattern || {};
+
+    if (!regex) return results;
+    const re = new RegExp(regex, 'g');
+
+    for (const line of lines) {
+      let match;
+      while ((match = re.exec(line)) !== null) {
+        const itemId = match[1] || '';
+        const statusRaw = match[2] || match[0];
+        results.push({
+          id: itemId,
+          status: normalizeStatus(statusRaw, statusMap)
+        });
+      }
+    }
+  } else if (source.glob) {
+    // Multi-file glob mode
+    const re = globToRegex(source.glob);
+
+    // Walk docs/ for matching files
+    function walk(dir) {
+      const out = [];
+      if (!fs.existsSync(dir)) return out;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith('.')) continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          out.push(...walk(full));
+        } else if (entry.isFile() && entry.name.endsWith('.md')) {
+          out.push(full);
+        }
+      }
+      return out;
+    }
+
+    const docsDir = path.join(projectRoot, 'docs');
+    const allFiles = walk(docsDir);
+
+    const { regex: sRegex, itemPattern: sItemPattern, statusMap } = source.statusLinePattern || {};
+    if (!sRegex) return results;
+
+    for (const filePath of allFiles) {
+      const rel = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+      if (!re.test(rel)) continue;
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      // Extract date from filename
+      const dateMatch = path.basename(filePath).match(/(\d{4}-\d{2}-\d{2})/);
+      const date = dateMatch ? dateMatch[1] : null;
+
+      for (const line of lines) {
+        // Look for status line: "> **状态**：..." or "> **状态**: ..."
+        if (/^\s*>\s*\*\*状态\*\*[：:]/.test(line)) {
+          const statusRaw = line.replace(/^\s*>\s*\*\*状态\*\*[：:]\s*/, '').trim();
+          // Extract item ID from file content
+          let itemId = '';
+          if (sItemPattern) {
+            const itemRe = new RegExp(sItemPattern, 'g');
+            // Search context around the status line
+            const ctxStart = Math.max(0, lines.indexOf(line) - 5);
+            const ctxEnd = Math.min(lines.length, lines.indexOf(line) + 5);
+            const ctx = lines.slice(ctxStart, ctxEnd).join('\n');
+            let itemMatch;
+            while ((itemMatch = itemRe.exec(ctx)) !== null) {
+              // Prefer capture group if present, otherwise full match
+              itemId = itemMatch[1] || itemMatch[0];
+              break; // Take first match
+            }
+          }
+          if (!itemId && date) itemId = path.basename(filePath, '.md');
+
+          results.push({
+            id: itemId || path.basename(filePath, '.md'),
+            status: normalizeStatus(statusRaw, statusMap),
+            date: date,
+            source: rel
+          });
+          break; // One status per file
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---- Build tracks from progressSources config ----
+function buildTracks(progressSources, projectRoot) {
+  const sources = progressSources || [];
+  const tracks = [];
+
+  for (const ps of sources) {
+    const track = {
+      id: ps.track,
+      label: ps.label || ps.track,
+      source: ps.source,
+      phases: []
+    };
+
+    if (ps.source && ps.tableMap) {
+      // Table source (e.g. execution-plan §5.2)
+      const parsed = parseTableSource(ps.source, projectRoot);
+      if (parsed) {
+        const { rows } = parsed;
+        const { milestoneCol, taskCol, titleCol, actorCol, statusCol, batchCol } = ps.tableMap;
+        const statusMap = ps.statusNormalize || {};
+        const hierarchyRules = ps.hierarchyRules || {};
+
+        // Separate milestone rows from task rows
+        const parentPattern = hierarchyRules.parentPattern
+          ? new RegExp(hierarchyRules.parentPattern)
+          : null;
+        const childPattern = hierarchyRules.childPattern
+          ? new RegExp(hierarchyRules.childPattern)
+          : null;
+
+        const milestones = [];
+        let currentMilestone = null;
+
+        for (const row of rows) {
+          const id = (row[milestoneCol] || '').trim();
+          if (!id) continue;
+
+          if (parentPattern && parentPattern.test(id)) {
+            // This is a milestone row
+            currentMilestone = {
+              id: id,
+              name: (row[titleCol] || id).trim(),
+              status: normalizeStatus(row[statusCol], statusMap),
+              batch: batchCol ? (row[batchCol] || '').trim() : '',
+              tasks: []
+            };
+            milestones.push(currentMilestone);
+          } else if (childPattern && childPattern.test(id) && currentMilestone) {
+            // This is a task row — attach to current milestone
+            currentMilestone.tasks.push({
+              id: id,
+              title: (row[titleCol] || id).trim(),
+              status: normalizeStatus(row[statusCol], statusMap),
+              actor: actorCol ? (row[actorCol] || '').trim() : ''
+            });
+          }
+        }
+
+        // Sort milestones: extract number from ID for ordering
+        milestones.sort((a, b) => {
+          const na = parseInt(a.id.replace(/[^0-9]/g, '')) || 0;
+          const nb = parseInt(b.id.replace(/[^0-9]/g, '')) || 0;
+          return na - nb;
+        });
+
+        track.phases = milestones;
+      }
+    } else if (ps.source && ps.statusLinePattern) {
+      // StatusLine source (e.g. decision files)
+      const items = parseStatusLineSource(ps.source, projectRoot);
+      for (const item of items) {
+        track.phases.push({
+          id: item.id,
+          name: item.id,
+          status: item.status,
+          date: item.date,
+          source: item.source,
+          tasks: []
+        });
+      }
+    }
+
+    tracks.push(track);
+  }
+
+  // Extract current node from execution-plan content
+  let currentNode = null;
+  const epSource = sources.find(ps =>
+    ps.source && ps.source.file &&
+    ps.source.file.includes('execution-plan')
+  );
+  if (epSource) {
+    const fp = path.join(projectRoot, epSource.source.file);
+    if (fs.existsSync(fp)) {
+      const content = fs.readFileSync(fp, 'utf-8');
+      const cnMatch = content.match(/当前节点[：:]\s*(T\d+)/);
+      if (cnMatch) currentNode = cnMatch[1];
+    }
+  }
+
+  return { tracks, currentNode };
+}
+
+module.exports = {
+  parseTableAtAnchor, normalizeStatus,
+  parseTableSource, parseStatusLineSource, buildTracks
+};