mdboard 1.2.0 → 2.0.0

package/src/core/scanner.js

@@ -0,0 +1,521 @@
+/**
+ * mdboard — Dynamic file scanner and in-memory model
+ *
+ * Scans project directories based on config-driven hierarchy.
+ * No hardcoded entity types — everything comes from entities.json + structure.json.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter, serializeYaml } = require('./yaml');
+const config = require('./config');
+
+// --- Utilities ---
+
+function safeReadFile(filePath) {
+  try { return fs.readFileSync(filePath, 'utf-8'); } catch { return null; }
+}
+
+function safeDirEntries(dir) {
+  try { return fs.readdirSync(dir).filter(e => !e.startsWith('.')); } catch { return []; }
+}
+
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '') || 'untitled';
+}
+
+/**
+ * Check if a filename matches an entity's file pattern.
+ * Supports "README.md" (directory entity) and "PREFIX-NNN.md" (file entity).
+ */
+function matchesFilePattern(filename, entityDef) {
+  const pattern = entityDef.file || 'README.md';
+  if (pattern === 'README.md') return filename === 'README.md';
+  if (pattern === 'PREFIX-NNN.md') {
+    if (!filename.endsWith('.md')) return false;
+    const prefix = entityDef.prefix;
+    return prefix && filename.startsWith(prefix + '-');
+  }
+  return filename === pattern;
+}
+
+/**
+ * Check if an entity uses directory-based storage (README.md inside a named dir).
+ */
+function isDirEntity(entityDef) {
+  return (entityDef.file || 'README.md') === 'README.md';
+}
+
+// --- Model ---
+
+/**
+ * Create an empty model. Collections are keyed by entity type.
+ * @param {object} cfg - Loaded config
+ * @returns {object}
+ */
+function createModel(cfg) {
+  const model = { project: null, entities: {} };
+  for (const type of config.getEntityTypes(cfg)) {
+    model.entities[type] = [];
+  }
+  return model;
+}
+
+// --- Scanner ---
+
+/**
+ * Scan a single source directory and return all entities found.
+ *
+ * @param {string} sourcePath - Absolute path to the project/ directory
+ * @param {object} cfg - Loaded config
+ * @param {object} [sourceMeta] - { name, label, color, type, readonly }
+ * @returns {object} - { project, entities: { cycle: [...], bet: [...], ... } }
+ */
+function scanSource(sourcePath, cfg, sourceMeta) {
+  const result = createModel(cfg);
+  if (!fs.existsSync(sourcePath)) return result;
+
+  const meta = sourceMeta || {};
+  const sourcePrefix = meta.name ? meta.name + ':' : '';
+
+  function tag(item) {
+    if (meta.name) {
+      item._source = meta.name;
+      item._sourceLabel = meta.label || meta.name;
+      item._sourceColor = meta.color || null;
+      item._sourceType = meta.type || 'local';
+      item._readonly = meta.readonly || false;
+    }
+    return item;
+  }
+
+  function qualifyId(item) {
+    if (sourcePrefix && item.id) {
+      item._originalId = item.id;
+      item.id = sourcePrefix + item.id;
+    }
+    return item;
+  }
+
+  // Scan PROJECT.md
+  const projectMd = safeReadFile(path.join(sourcePath, 'PROJECT.md'));
+  if (projectMd) {
+    const parsed = parseFrontmatter(projectMd);
+    result.project = tag({ ...parsed.frontmatter, content: parsed.content, _file: 'PROJECT.md' });
+  }
+
+  // Scan hierarchy entities
+  const hierarchy = config.getHierarchy(cfg);
+  scanHierarchyLevel(sourcePath, hierarchy, [], result, cfg, tag, qualifyId);
+
+  // Scan standalone entities
+  const standalone = (cfg.structure && cfg.structure.standalone) || {};
+  for (const [type, def] of Object.entries(standalone)) {
+    scanStandaloneEntity(sourcePath, type, def, result, cfg, tag, qualifyId);
+  }
+
+  return result;
+}
+
+/**
+ * Recursively scan a level of the hierarchy.
+ *
+ * @param {string} basePath - Current filesystem path
+ * @param {object} levelDef - Hierarchy level definition { entityType: { dir, children } }
+ * @param {object[]} ancestors - Array of { type, slug } for parent context
+ * @param {object} result - Model being built
+ * @param {object} cfg - Config
+ * @param {function} tag - Source tagger
+ * @param {function} qualifyId - ID qualifier
+ */
+function scanHierarchyLevel(basePath, levelDef, ancestors, result, cfg, tag, qualifyId) {
+  for (const [type, def] of Object.entries(levelDef)) {
+    const entityDef = config.getEntity(cfg, type);
+    if (!entityDef) continue;
+
+    const entityDir = path.join(basePath, def.dir);
+    if (!fs.existsSync(entityDir)) continue;
+
+    if (isDirEntity(entityDef)) {
+      // Directory entity: each subdirectory is an instance
+      for (const slug of safeDirEntries(entityDir)) {
+        const instanceDir = path.join(entityDir, slug);
+        if (!fs.statSync(instanceDir).isDirectory()) continue;
+
+        const content = safeReadFile(path.join(instanceDir, 'README.md'));
+        if (!content) continue;
+
+        const parsed = parseFrontmatter(content);
+        const relFile = buildRelFile(ancestors, def.dir, slug, 'README.md');
+
+        const item = qualifyId(tag({
+          ...parsed.frontmatter,
+          _contentLength: parsed.content ? parsed.content.length : 0,
+          _type: type,
+          _dir: slug,
+          _file: relFile,
+        }));
+
+        // Store ancestor references
+        for (const anc of ancestors) {
+          item['_' + anc.type] = anc.slug;
+        }
+
+        result.entities[type].push(item);
+
+        // Recurse into children
+        if (def.children) {
+          const childAncestors = [...ancestors, { type, slug, dir: def.dir }];
+          scanHierarchyLevel(instanceDir, def.children, childAncestors, result, cfg, tag, qualifyId);
+        }
+      }
+    } else {
+      // File entity: each matching file in the dir is an instance
+      for (const file of safeDirEntries(entityDir)) {
+        if (!matchesFilePattern(file, entityDef)) continue;
+
+        const content = safeReadFile(path.join(entityDir, file));
+        if (!content) continue;
+
+        const parsed = parseFrontmatter(content);
+        const relFile = buildRelFile(ancestors, def.dir, null, file);
+
+        const item = qualifyId(tag({
+          ...parsed.frontmatter,
+          _contentLength: parsed.content ? parsed.content.length : 0,
+          _type: type,
+          _filename: file,
+          _file: relFile,
+        }));
+
+        for (const anc of ancestors) {
+          item['_' + anc.type] = anc.slug;
+        }
+
+        result.entities[type].push(item);
+      }
+    }
+  }
+}
+
+/**
+ * Scan a standalone entity directory (flat, not in hierarchy).
+ */
+function scanStandaloneEntity(sourcePath, type, def, result, cfg, tag, qualifyId) {
+  const entityDef = config.getEntity(cfg, type);
+  if (!entityDef) return;
+
+  const dir = path.join(sourcePath, def.dir);
+  if (!fs.existsSync(dir)) return;
+
+  if (isDirEntity(entityDef)) {
+    for (const slug of safeDirEntries(dir)) {
+      const instanceDir = path.join(dir, slug);
+      if (!fs.statSync(instanceDir).isDirectory()) continue;
+
+      const content = safeReadFile(path.join(instanceDir, 'README.md'));
+      if (!content) continue;
+
+      const parsed = parseFrontmatter(content);
+      result.entities[type].push(qualifyId(tag({
+        ...parsed.frontmatter,
+        _contentLength: parsed.content ? parsed.content.length : 0,
+        _type: type,
+        _dir: slug,
+        _file: def.dir + '/' + slug + '/README.md',
+      })));
+    }
+  } else {
+    for (const file of safeDirEntries(dir)) {
+      if (!matchesFilePattern(file, entityDef)) continue;
+
+      const content = safeReadFile(path.join(dir, file));
+      if (!content) continue;
+
+      const parsed = parseFrontmatter(content);
+      const slug = file.replace(/\.md$/, '');
+
+      result.entities[type].push(qualifyId(tag({
+        id: parsed.frontmatter.id || slug,
+        title: parsed.frontmatter.title || slug,
+        ...parsed.frontmatter,
+        _contentLength: parsed.content ? parsed.content.length : 0,
+        _type: type,
+        _filename: file,
+        _file: def.dir + '/' + file,
+      })));
+    }
+  }
+}
+
+/**
+ * Build a relative file path from ancestors.
+ * Each ancestor has { type, slug, dir } where dir is the hierarchy directory name.
+ */
+function buildRelFile(ancestors, dir, slug, filename) {
+  const parts = [];
+  for (const anc of ancestors) {
+    parts.push(anc.dir); // hierarchy dir name (e.g. "cycles")
+    parts.push(anc.slug); // instance slug (e.g. "cycle-01")
+  }
+  parts.push(dir);
+  if (slug) parts.push(slug);
+  parts.push(filename);
+  return parts.join('/');
+}
+
+// --- Progress ---
+
+/**
+ * Compute progress for all entities that have children.
+ * Walks the hierarchy bottom-up: leaf entities contribute to parent progress.
+ *
+ * @param {object} model - Scanned model
+ * @param {object} cfg - Config
+ */
+function computeProgress(model, cfg) {
+  const flat = config.flattenHierarchy(cfg);
+  const completedStatuses = (cfg.entities && cfg.entities.completedStatuses) || [];
+
+  // Find the leaf entity type (deepest in hierarchy, not standalone)
+  const hierarchyEntities = flat.filter(e => !e.standalone);
+  if (hierarchyEntities.length === 0) return;
+
+  const leafType = hierarchyEntities[hierarchyEntities.length - 1].type;
+  const leafItems = model.entities[leafType] || [];
+
+  // For each non-leaf hierarchy entity, compute progress from its leaf descendants
+  for (const entry of hierarchyEntities) {
+    if (entry.type === leafType) continue;
+
+    const items = model.entities[entry.type] || [];
+    for (const item of items) {
+      // Find leaf items that descend from this entity
+      const descendants = leafItems.filter(leaf => {
+        return leaf['_' + entry.type] === item._dir &&
+          (!item._source || leaf._source === item._source);
+      });
+
+      const total = descendants.length;
+      const done = descendants.filter(d => {
+        const status = d.status || '';
+        return completedStatuses.includes(status);
+      }).length;
+
+      item._childCount = total;
+      item._completedCount = done;
+      item._progress = total > 0 ? Math.round((done / total) * 100) : 0;
+      item._totalPoints = descendants.reduce((sum, d) => sum + (d.points || 0), 0);
+      item._completedPoints = descendants
+        .filter(d => completedStatuses.includes(d.status || ''))
+        .reduce((sum, d) => sum + (d.points || 0), 0);
+    }
+  }
+}
+
+// --- CRUD ---
+
+/**
+ * Get the next auto-incremented ID for an entity type.
+ *
+ * @param {object[]} items - Existing items
+ * @param {string} prefix - ID prefix (e.g. "TASK", "CYC", "BET")
+ * @returns {string}
+ */
+function getNextId(items, prefix) {
+  let max = 0;
+  const re = new RegExp('^(?:[\\w]+:)?' + prefix + '-(\\d+)$');
+  for (const item of items) {
+    const id = item._originalId || item.id || '';
+    const m = id.match(re);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return prefix + '-' + String(max + 1).padStart(3, '0');
+}
+
+/**
+ * Create a new entity.
+ * Generic function that replaces createMilestone, createEpic, createTask, createSprint.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} cfg - Loaded config
+ * @param {string} type - Entity type
+ * @param {object} data - Entity data (title + field values + parent slugs)
+ * @param {object[]} existingItems - Current items of this type for ID generation
+ * @returns {object} - { id, slug, file }
+ */
+function createEntity(sourcePath, cfg, type, data, existingItems) {
+  const entityDef = config.getEntity(cfg, type);
+  if (!entityDef) throw new Error('Unknown entity type: ' + type);
+
+  const prefix = entityDef.prefix;
+  const id = getNextId(existingItems, prefix);
+
+  // Build ancestor ids map from data
+  const ancestors = config.getAncestors(cfg, type);
+  const ids = {};
+  for (const anc of ancestors) {
+    if (!data[anc]) {
+      throw new Error(anc + ' is required to create a ' + type);
+    }
+    ids[anc] = data[anc];
+  }
+
+  // resolveEntityPath includes root (e.g. "project/cycles/..."), but sourcePath
+  // already points to project/, so strip the root prefix
+  const root = config.getRoot(cfg);
+  const relPath = config.resolveEntityPath(cfg, type, ids).replace(new RegExp('^' + root + '/'), '');
+  const dirPath = path.join(sourcePath, relPath);
+
+  if (isDirEntity(entityDef)) {
+    // Directory entity
+    const slug = slugify(data.title || id);
+    const instanceDir = path.join(dirPath, slug);
+
+    if (fs.existsSync(instanceDir)) {
+      throw new Error(entityDef.singular + ' directory already exists: ' + slug);
+    }
+    fs.mkdirSync(instanceDir, { recursive: true });
+
+    // Create child directories
+    const children = config.getChildren(cfg, type);
+    for (const childType of children) {
+      const childEntry = config.flattenHierarchy(cfg).find(e => e.type === childType);
+      if (childEntry) {
+        fs.mkdirSync(path.join(instanceDir, childEntry.dir), { recursive: true });
+      }
+    }
+
+    const fm = buildFrontmatter(cfg, type, id, data);
+    const yaml = serializeYaml(fm);
+    const content = data.content || '';
+    fs.writeFileSync(
+      path.join(instanceDir, 'README.md'),
+      '---\n' + yaml + '\n---\n\n' + content + '\n',
+      'utf-8'
+    );
+
+    const relFile = relPath + '/' + slug + '/README.md';
+    return { id, slug, file: relFile };
+
+  } else {
+    // File entity
+    const filename = id + '.md';
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+
+    const fm = buildFrontmatter(cfg, type, id, data);
+    const yaml = serializeYaml(fm);
+    const content = data.content || '';
+    fs.writeFileSync(
+      path.join(dirPath, filename),
+      '---\n' + yaml + '\n---\n\n' + content + '\n',
+      'utf-8'
+    );
+
+    const relFile = relPath + '/' + filename;
+    return { id, slug: id, file: relFile };
+  }
+}
+
+/**
+ * Build frontmatter object from entity fields config and provided data.
+ */
+function buildFrontmatter(cfg, type, id, data) {
+  const fields = config.getFields(cfg, type);
+  const fm = { id };
+
+  if (data.title) fm.title = data.title;
+
+  for (const [name, def] of Object.entries(fields)) {
+    if (data[name] !== undefined) {
+      fm[name] = data[name];
+    } else if (def.default !== undefined) {
+      fm[name] = def.default;
+    }
+  }
+
+  fm.created = new Date().toISOString().split('T')[0];
+  return fm;
+}
+
+/**
+ * Update an entity's markdown file.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {string} relFile - Relative file path
+ * @param {object} updates - Fields to update
+ */
+function updateEntity(sourcePath, relFile, updates) {
+  const filePath = path.join(sourcePath, relFile);
+  if (!fs.existsSync(filePath)) throw new Error('File not found: ' + relFile);
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const parsed = parseFrontmatter(raw);
+
+  const newFm = { ...parsed.frontmatter };
+  let body = parsed.content;
+
+  for (const [k, v] of Object.entries(updates)) {
+    if (k === 'content') { body = v; continue; }
+    if (k.startsWith('_')) continue;
+    newFm[k] = v;
+  }
+
+  const yaml = serializeYaml(newFm);
+  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + (body || '') + '\n', 'utf-8');
+}
+
+/**
+ * Delete (archive) an entity.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} item - The item with _file property
+ * @returns {boolean}
+ */
+function deleteEntity(sourcePath, item) {
+  if (!item || !item._file) throw new Error('Item has no file path');
+  const srcPath = path.join(sourcePath, item._file);
+  if (!fs.existsSync(srcPath)) throw new Error('File not found: ' + item._file);
+  fs.unlinkSync(srcPath);
+  return true;
+}
+
+/**
+ * Merge results from multiple scanSource calls into a single model.
+ */
+function mergeResults(model, results) {
+  for (const r of results) {
+    if (r.project && !model.project) model.project = r.project;
+    for (const type of Object.keys(model.entities)) {
+      if (r.entities[type]) {
+        model.entities[type].push(...r.entities[type]);
+      }
+    }
+  }
+}
+
+// --- Export ---
+
+module.exports = {
+  createModel,
+  scanSource,
+  computeProgress,
+  mergeResults,
+  getNextId,
+  createEntity,
+  updateEntity,
+  deleteEntity,
+  // Utilities
+  safeReadFile,
+  safeDirEntries,
+  slugify,
+  matchesFilePattern,
+  isDirEntity,
+};

package/{workspace.js → src/core/workspace.js}

@@ -78,21 +78,6 @@ function loadWorkspace(projectDir, explicitPath) {
     }
   }
 
-  // Also resolve the overview (workspace root's project/ dir)
-  const overviewPath = path.join(projectDir, 'project');
-  if (fs.existsSync(overviewPath)) {
-    ws.sources.unshift({
-      name: 'overview',
-      label: 'Overview',
-      icon: '\u2605',
-      color: '#5B6EF5',
-      type: 'local',
-      readonly: false,
-      _resolvedPath: overviewPath,
-      _repoRoot: projectDir,
-    });
-  }
-
   ws._path = wsPath;
   ws.settings = ws.settings || {};
 

package/{yaml.js → src/core/yaml.js}

@@ -117,7 +117,11 @@ function serializeYaml(obj) {
     } else if (typeof value === 'object') {
       lines.push(key + ':');
       for (const [k, v] of Object.entries(value)) {
-        lines.push('  ' + k + ': ' + serializeValue(v));
+        if (Array.isArray(v)) {
+          lines.push('  ' + k + ': ' + (v.length === 0 ? '[]' : '[' + v.map(sv => serializeValue(sv)).join(', ') + ']'));
+        } else {
+          lines.push('  ' + k + ': ' + serializeValue(v));
+        }
       }
     } else {
       lines.push(key + ': ' + serializeValue(value));