roadmapsmith 0.1.0

package/src/match.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const { similarityScore, slugify, tokenize, uniqueBy } = require('./utils');
+const { PHASE_ORDER } = require('./model');
+
+function canonicalSignature(text) {
+  const tokens = uniqueBy(tokenize(text), (token) => token).slice(0, 8);
+  return tokens.join('-') || slugify(text);
+}
+
+function inferPriorityWeight(priority) {
+  const normalized = String(priority || '').toUpperCase();
+  if (normalized === 'P0') return 0;
+  if (normalized === 'P1') return 1;
+  if (normalized === 'P2') return 2;
+  return 3;
+}
+
+function findBestTaskMatch(candidate, existingTasks, minScore = 0.55) {
+  const direct = existingTasks.find((task) => task.id === candidate.id);
+  if (direct) {
+    return { task: direct, score: 1 };
+  }
+
+  let best = null;
+  for (const task of existingTasks) {
+    const score = similarityScore(candidate.text, task.text);
+    if (score < minScore) {
+      continue;
+    }
+    if (!best || score > best.score) {
+      best = { task, score };
+    }
+  }
+
+  return best;
+}
+
+function dedupeTasks(tasks) {
+  const grouped = new Map();
+
+  for (const task of tasks) {
+    const signature = canonicalSignature(task.text);
+    if (!grouped.has(signature)) {
+      grouped.set(signature, task);
+      continue;
+    }
+
+    const current = grouped.get(signature);
+    const candidate = task;
+
+    if (current.checked !== candidate.checked) {
+      grouped.set(signature, candidate.checked ? candidate : current);
+      continue;
+    }
+
+    const currentWeight = inferPriorityWeight(current.priority);
+    const candidateWeight = inferPriorityWeight(candidate.priority);
+    if (candidateWeight < currentWeight) {
+      grouped.set(signature, candidate);
+      continue;
+    }
+
+    if (candidateWeight === currentWeight && candidate.text.length < current.text.length) {
+      grouped.set(signature, candidate);
+    }
+  }
+
+  return Array.from(grouped.values()).sort((left, right) => {
+    const leftPhase = PHASE_ORDER.indexOf(left.phase);
+    const rightPhase = PHASE_ORDER.indexOf(right.phase);
+    if (leftPhase !== rightPhase) {
+      return leftPhase - rightPhase;
+    }
+    if (left.priority !== right.priority) {
+      return inferPriorityWeight(left.priority) - inferPriorityWeight(right.priority);
+    }
+    return left.text.localeCompare(right.text);
+  });
+}
+
+module.exports = {
+  canonicalSignature,
+  dedupeTasks,
+  findBestTaskMatch
+};

package/src/model.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const PHASE_ORDER = ['P0', 'P1', 'P2'];
+
+function phaseWeight(phase) {
+  const idx = PHASE_ORDER.indexOf(phase);
+  return idx >= 0 ? idx : PHASE_ORDER.length;
+}
+
+function createRoadmapModel(input) {
+  return {
+    northStar: input.northStar,
+    currentState: input.currentState,
+    phases: input.phases,
+    milestones: input.milestones,
+    commandBreakdown: input.commandBreakdown,
+    exitCriteria: input.exitCriteria,
+    risks: input.risks,
+    antiGoals: input.antiGoals,
+    customSections: input.customSections || []
+  };
+}
+
+module.exports = {
+  PHASE_ORDER,
+  createRoadmapModel,
+  phaseWeight
+};

package/src/parser/index.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { slugify } = require('../utils');
+
+const TASK_LINE_RE = /^(\s*)- \[( |x|X)\] (.*?)(?:\s*<!--\s*rs:task=([a-z0-9-]+)\s*-->)?\s*$/;
+const WARNING_RE = /^\s*-\s+⚠️ attempted but validation failed:\s*(.+?)\s*$/;
+const HEADING_RE = /^#{2,3}\s+(.*)$/;
+
+const MANAGED_START = '<!-- rs:managed:start -->';
+const MANAGED_END = '<!-- rs:managed:end -->';
+
+function parseRoadmap(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const tasks = [];
+  let section = '';
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const headingMatch = line.match(HEADING_RE);
+    if (headingMatch) {
+      section = headingMatch[1].trim();
+    }
+
+    const taskMatch = line.match(TASK_LINE_RE);
+    if (!taskMatch) {
+      continue;
+    }
+
+    const indent = taskMatch[1] || '';
+    const checked = taskMatch[2].toLowerCase() === 'x';
+    const text = taskMatch[3].trim();
+    const markerId = taskMatch[4] || null;
+
+    let warningLineIndex = null;
+    let warningText = null;
+    if (index + 1 < lines.length) {
+      const nextLine = lines[index + 1];
+      const warningMatch = nextLine.match(WARNING_RE);
+      if (warningMatch) {
+        warningLineIndex = index + 1;
+        warningText = warningMatch[1].trim();
+      }
+    }
+
+    const id = markerId || slugify(text);
+    tasks.push({
+      id,
+      text,
+      checked,
+      lineIndex: index,
+      warningLineIndex,
+      warningText,
+      markerId,
+      indent,
+      section
+    });
+  }
+
+  return {
+    lines,
+    tasks
+  };
+}
+
+function findManagedRange(lines) {
+  let start = -1;
+  let end = -1;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i].trim() === MANAGED_START) {
+      start = i;
+      continue;
+    }
+    if (lines[i].trim() === MANAGED_END) {
+      end = i;
+      break;
+    }
+  }
+
+  if (start >= 0 && end >= 0 && start < end) {
+    return { start, end };
+  }
+  return null;
+}
+
+function upsertManagedBlock(existingContent, managedBody) {
+  const existing = String(existingContent || '');
+  const lines = existing.split(/\r?\n/);
+  const range = findManagedRange(lines);
+  const bodyLines = managedBody.split(/\r?\n/);
+
+  if (!range) {
+    if (existing.trim().length === 0) {
+      return [MANAGED_START, ...bodyLines, MANAGED_END].join('\n');
+    }
+    return `${existing.replace(/\s+$/, '')}\n\n${MANAGED_START}\n${managedBody}\n${MANAGED_END}`;
+  }
+
+  const prefix = lines.slice(0, range.start + 1);
+  const suffix = lines.slice(range.end);
+  return [...prefix, ...bodyLines, ...suffix].join('\n');
+}
+
+module.exports = {
+  MANAGED_END,
+  MANAGED_START,
+  parseRoadmap,
+  upsertManagedBlock
+};

package/src/sync/index.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const { parseRoadmap } = require('../parser');
+const { ensureTrailingNewline } = require('../utils');
+
+function setChecklistState(line, checked) {
+  return line.replace(/- \[( |x|X)\]/, `- [${checked ? 'x' : ' '}]`);
+}
+
+function formatWarning(indent, reason) {
+  return `${indent}  - ⚠️ attempted but validation failed: ${reason}`;
+}
+
+function applySync(content, parsedTasks, results) {
+  const parsed = parseRoadmap(content);
+  const lines = [...parsed.lines];
+  const tasks = parsedTasks || parsed.tasks;
+
+  let offset = 0;
+  for (const task of tasks) {
+    const result = results[task.id];
+    if (!result) {
+      continue;
+    }
+
+    const lineIndex = task.lineIndex + offset;
+    if (lineIndex < 0 || lineIndex >= lines.length) {
+      continue;
+    }
+
+    lines[lineIndex] = setChecklistState(lines[lineIndex], result.passed);
+
+    const reason = result.reasons.join('; ');
+    const warningText = formatWarning(task.indent || '', reason || 'validation failed');
+    const hasWarning = task.warningLineIndex != null;
+    const warningIndex = hasWarning ? task.warningLineIndex + offset : null;
+
+    if (result.passed || !result.attempted) {
+      if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
+        lines.splice(warningIndex, 1);
+        offset -= 1;
+      }
+      continue;
+    }
+
+    if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
+      lines[warningIndex] = warningText;
+    } else {
+      lines.splice(lineIndex + 1, 0, warningText);
+      offset += 1;
+    }
+  }
+
+  return ensureTrailingNewline(lines.join('\n'));
+}
+
+module.exports = {
+  applySync
+};

package/src/templates/index.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readTemplate(name) {
+  const absolutePath = path.resolve(__dirname, '..', '..', 'templates', name);
+  return fs.readFileSync(absolutePath, 'utf8');
+}
+
+function replaceTokens(content, replacements) {
+  let result = content;
+  for (const [key, value] of Object.entries(replacements || {})) {
+    const token = `{{${key}}}`;
+    result = result.split(token).join(String(value));
+  }
+  return result;
+}
+
+function renderRoadmapTemplate(replacements = {}) {
+  return replaceTokens(readTemplate('roadmap.template.md'), replacements);
+}
+
+function renderAgentsTemplate(replacements = {}) {
+  return replaceTokens(readTemplate('agents.template.md'), replacements);
+}
+
+module.exports = {
+  renderAgentsTemplate,
+  renderRoadmapTemplate
+};

package/src/utils.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const path = require('path');
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from', 'in', 'into', 'is', 'it', 'of', 'on', 'or', 'that',
+  'the', 'to', 'with', 'this', 'these', 'those', 'via', 'per', 'task', 'tasks', 'phase', 'priority'
+]);
+
+function toPosix(input) {
+  return input.split(path.sep).join('/');
+}
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-') || 'task';
+}
+
+function normalizeText(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[`*_~#>\[\](){}.!?,:;"']/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function tokenize(text) {
+  return normalizeText(text)
+    .split(' ')
+    .filter(Boolean)
+    .filter((token) => !STOP_WORDS.has(token));
+}
+
+function uniqueBy(items, keyFn) {
+  const seen = new Set();
+  const result = [];
+  for (const item of items) {
+    const key = keyFn(item);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+function similarityScore(left, right) {
+  const leftTokens = new Set(tokenize(left));
+  const rightTokens = new Set(tokenize(right));
+  if (leftTokens.size === 0 || rightTokens.size === 0) {
+    return 0;
+  }
+
+  let shared = 0;
+  for (const token of leftTokens) {
+    if (rightTokens.has(token)) {
+      shared += 1;
+    }
+  }
+
+  const union = new Set([...leftTokens, ...rightTokens]);
+  return shared / union.size;
+}
+
+function ensureTrailingNewline(text) {
+  return text.endsWith('\n') ? text : `${text}\n`;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function parseArgv(argv) {
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const current = argv[i];
+    if (!current.startsWith('-')) {
+      positionals.push(current);
+      continue;
+    }
+
+    if (current.startsWith('--')) {
+      const withoutPrefix = current.slice(2);
+      const eqIndex = withoutPrefix.indexOf('=');
+      let key;
+      let value;
+
+      if (eqIndex >= 0) {
+        key = withoutPrefix.slice(0, eqIndex);
+        value = withoutPrefix.slice(eqIndex + 1);
+      } else {
+        key = withoutPrefix;
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-')) {
+          value = next;
+          i += 1;
+        } else {
+          value = true;
+        }
+      }
+
+      if (Object.prototype.hasOwnProperty.call(flags, key)) {
+        if (Array.isArray(flags[key])) {
+          flags[key].push(value);
+        } else {
+          flags[key] = [flags[key], value];
+        }
+      } else {
+        flags[key] = value;
+      }
+      continue;
+    }
+
+    const short = current.slice(1);
+    flags[short] = true;
+  }
+
+  const command = positionals.length > 0 ? positionals[0] : null;
+  return {
+    command,
+    args: positionals.slice(1),
+    flags,
+    positionals
+  };
+}
+
+module.exports = {
+  escapeRegExp,
+  ensureTrailingNewline,
+  normalizeText,
+  parseArgv,
+  similarityScore,
+  slugify,
+  toPosix,
+  tokenize,
+  uniqueBy
+};