roadmapsmith 0.9.0 → 0.9.3

package/README.md

@@ -1,4 +1,8 @@
-# roadmap-skill
+<p align="center">
+  <img src="https://raw.githubusercontent.com/PapiScholz/roadmapsmith/main/assets/roadmapsmith-logo.png" alt="RoadmapSmith logo" width="180">
+</p>
+
+<h1 align="center">RoadmapSmith</h1>
 
 Production-grade roadmap generator and sync tool for agent-driven projects.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "description": "Evidence-backed ROADMAP.md generator and sync tool for AI coding agents.",
   "main": "src/index.js",
   "bin": {

package/src/parser/index.js

@@ -2,7 +2,7 @@
 
 const { slugify } = require('../utils');
 
-const TASK_LINE_RE = /^(\s*)- \[( |x|X)\] (.*?)(?:\s*<!--\s*rs:task=([a-z0-9-]+)\s*-->)?\s*$/;
+const TASK_LINE_RE = /^(\s*)- \[( |x|X)\] (.*?)(?:\s*<!--\s*rs:task=([a-z0-9-]+)([^>]*)-->)?\s*$/;
 const WARNING_RE = /^\s*-\s+⚠️ attempted but validation failed:\s*(.+?)\s*$/;
 const HEADING_RE = /^#{2,3}\s+(.*)$/;
 
@@ -29,7 +29,9 @@ function parseRoadmap(content) {
     const indent = taskMatch[1] || '';
     const checked = taskMatch[2].toLowerCase() === 'x';
     const text = taskMatch[3].trim();
-    const markerId = taskMatch[4] || null;
+    const markerId = taskMatch[4] || null;
+    const markerFlags = taskMatch[5] || '';
+    const noTest = /\brs:no-test\b/i.test(markerFlags);
 
     let warningLineIndex = null;
     let warningText = null;
@@ -49,11 +51,12 @@ function parseRoadmap(content) {
       checked,
       lineIndex: index,
       warningLineIndex,
-      warningText,
-      markerId,
-      indent,
-      section
-    });
+      warningText,
+      markerId,
+      noTest,
+      indent,
+      section
+    });
   }
 
   return {

package/src/validator/index.js

@@ -8,9 +8,11 @@ const { escapeRegExp, tokenize } = require('../utils');
 
 const CONFIDENCE_RANK = { low: 0, medium: 1, high: 2 };
 
-const CODE_EXTENSIONS = new Set([
-  '.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.rb', '.php', '.cs'
-]);
+const CODE_EXTENSIONS = new Set([
+  '.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.rb', '.php', '.cs'
+]);
+const TRANSLATION_DIR_SEGMENTS = ['locale', 'locales', 'i18n', 'translations'];
+const DEFAULT_EXCLUDED_PATH_PREFIXES = ['.claude/', '.agent/', 'roadmap-skill/'];
 
 // "docs" omitted from DOC_HINTS — it is a path prefix in scan tasks, not a doc-authoring keyword.
 const DOC_HINTS = ['readme', 'changelog', 'documentation', 'spec', 'diagram', 'runbook'];
@@ -76,18 +78,69 @@ const NAMESPACE_STRUCTURAL_PATTERNS = {
 // Test fixture directories contain synthetic code created to drive test scenarios,
 // not real implementations. Including them pollutes the evidence pool with vocabulary
 // that was deliberately seeded for testing purposes (e.g. namespace-vocab fixtures).
-function isFixturePath(relativePath) {
-  return /(?:^|[/\\])fixtures[/\\]/.test(relativePath);
-}
-
-function readFileIndex(projectRoot, files) {
-  const index = [];
-  for (const relativePath of files) {
-    if (SELF_REFERENTIAL_FILES.has(relativePath)) continue;
-    if (isFixturePath(relativePath)) continue;
-
-    const absolutePath = path.resolve(projectRoot, relativePath);
-    const ext = path.extname(relativePath).toLowerCase();
+function isFixturePath(relativePath) {
+  return /(?:^|[/\\])fixtures[/\\]/.test(relativePath);
+}
+
+function normalizePathForMatch(rawPath) {
+  return String(rawPath || '').replace(/\\/g, '/').toLowerCase();
+}
+
+function shouldExcludeByDefaultPath(relativePath, config) {
+  const normalized = normalizePathForMatch(relativePath);
+  if (DEFAULT_EXCLUDED_PATH_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+    return true;
+  }
+
+  const configuredSkillsDir = config && typeof config.skillsDir === 'string'
+    ? normalizePathForMatch(config.skillsDir).replace(/^\.?\//, '')
+    : '';
+  if (configuredSkillsDir && (normalized === configuredSkillsDir || normalized.startsWith(configuredSkillsDir + '/'))) {
+    return true;
+  }
+  return false;
+}
+
+function isTranslationPath(relativePath) {
+  const normalized = normalizePathForMatch(relativePath);
+  const segments = normalized.split('/').filter(Boolean);
+  return segments.some((segment) => TRANSLATION_DIR_SEGMENTS.includes(segment));
+}
+
+function looksLikeTranslationJson(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return false;
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return false;
+  }
+
+  const values = Object.values(parsed);
+  if (values.length === 0) return false;
+  const stringValues = values.filter((value) => typeof value === 'string').length;
+  return stringValues / values.length >= 0.8;
+}
+
+function isMostlyUiStrings(content) {
+  const lines = String(content).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.length < 5) return false;
+  const stringLikeLines = lines.filter((line) => /^['"`][^'"`]{1,200}['"`],?$/.test(line) || /^[A-Za-z0-9_.-]+\s*:\s*['"`][^'"`]{1,200}['"`],?$/.test(line)).length;
+  return stringLikeLines / lines.length > 0.8;
+}
+
+function readFileIndex(projectRoot, files, config) {
+  const index = [];
+  for (const relativePath of files) {
+    if (SELF_REFERENTIAL_FILES.has(relativePath)) continue;
+    if (isFixturePath(relativePath)) continue;
+    if (shouldExcludeByDefaultPath(relativePath, config)) continue;
+
+    const absolutePath = path.resolve(projectRoot, relativePath);
+    const ext = path.extname(relativePath).toLowerCase();
     let content = '';
     try {
       const buffer = fs.readFileSync(absolutePath);
@@ -95,12 +148,16 @@ function readFileIndex(projectRoot, files) {
         continue;
       }
       content = buffer.toString('utf8');
-    } catch {
-      continue;
-    }
-
-    index.push({
-      relativePath,
+    } catch {
+      continue;
+    }
+
+    if (isTranslationPath(relativePath)) continue;
+    if (ext === '.json' && looksLikeTranslationJson(content)) continue;
+    if (isMostlyUiStrings(content)) continue;
+
+    index.push({
+      relativePath,
       absolutePath,
       ext,
       content,
@@ -240,7 +297,7 @@ function findFilesByPathHints(pathHints, fileIndex) {
   return Array.from(new Set(matches)).sort((left, right) => left.localeCompare(right));
 }
 
-function findFilesBySymbols(symbolHints, fileIndex) {
+function findFilesBySymbols(symbolHints, fileIndex) {
   const matches = new Set();
   for (const symbol of symbolHints) {
     const regex = new RegExp(`\\b${escapeRegExp(symbol)}\\b`, 'i');
@@ -254,7 +311,47 @@ function findFilesBySymbols(symbolHints, fileIndex) {
     }
   }
   return Array.from(matches).sort((left, right) => left.localeCompare(right));
-}
+}
+
+function findFilesByTaskPathTokens(taskText, fileIndex, pathDerivedTokens = new Set()) {
+  const tokens = tokenize(taskText)
+    .filter((token) => token.length >= 6 && !GENERIC_TASK_TOKENS.has(token) && !pathDerivedTokens.has(token))
+    .slice(0, 10);
+  if (tokens.length === 0) return [];
+
+  const matches = new Set();
+  for (const file of fileIndex) {
+    const pathSegments = normalizePathForMatch(file.relativePath).split('/').filter(Boolean);
+    for (const token of tokens) {
+      if (pathSegments.some((segment) => segment === token || segment.includes(token))) {
+        matches.add(file.relativePath);
+        break;
+      }
+    }
+    if (matches.size >= 20) break;
+  }
+  return Array.from(matches).sort((left, right) => left.localeCompare(right));
+}
+
+function mergeRuleEvidence(baseEvidence, ruleEvidence) {
+  if (!ruleEvidence || typeof ruleEvidence !== 'object') return baseEvidence;
+  const merged = { ...baseEvidence };
+
+  for (const [key, value] of Object.entries(ruleEvidence)) {
+    if (Array.isArray(value)) {
+      const existing = Array.isArray(merged[key]) ? merged[key] : [];
+      merged[key] = Array.from(new Set([...existing, ...value]));
+      continue;
+    }
+    if (typeof value === 'boolean') {
+      merged[key] = Boolean(merged[key]) || value;
+      continue;
+    }
+    merged[key] = value;
+  }
+
+  return merged;
+}
 
 // Tokens extracted from a referenced file path (e.g. "roadmap-skill" from
 // "roadmap-skill.config.json") must not be reused as code evidence signals.
@@ -484,29 +581,30 @@ function checkNamespaceStructuralEvidence(taskId, taskText, fileIndex) {
   };
 }
 
-function evaluateRule(rule, task, context) {
-  if (!rule) {
-    return { passed: true, reasons: [], evidence: {} };
-  }
+function evaluateRule(rule, task, context) {
+  if (!rule) {
+    return { passed: true, reasons: [], evidence: {}, overrideResult: false };
+  }
 
   if (rule.when) {
     const regexp = new RegExp(rule.when, 'i');
-    if (!regexp.test(task.text)) {
-      return { passed: true, reasons: [], evidence: {} };
-    }
-  }
+    if (!regexp.test(task.text)) {
+      return { passed: true, reasons: [], evidence: {}, overrideResult: false };
+    }
+  }
 
   if (typeof rule.check === 'function') {
     const custom = rule.check(task, context);
-    if (!custom) {
-      return { passed: true, reasons: [], evidence: {} };
-    }
-    return {
-      passed: custom.passed !== false,
-      reasons: Array.isArray(custom.reasons) ? custom.reasons : [],
-      evidence: custom.evidence || {}
-    };
-  }
+    if (!custom) {
+      return { passed: true, reasons: [], evidence: {}, overrideResult: false };
+    }
+    return {
+      passed: custom.passed !== false,
+      reasons: Array.isArray(custom.reasons) ? custom.reasons : [],
+      evidence: custom.evidence || {},
+      overrideResult: rule.overrideResult === true || custom.overrideResult === true
+    };
+  }
 
   const reasons = [];
   const evidence = {};
@@ -539,20 +637,46 @@ function evaluateRule(rule, task, context) {
     }
   }
 
-  if (rule.type === 'test' && context.testFrameworks.length === 0) {
-    reasons.push(rule.message || 'test framework not detected');
-  }
-
-  return {
-    passed: reasons.length === 0,
-    reasons,
-    evidence
-  };
-}
-
-function buildValidationContext(projectRoot, config, plugins) {
-  const files = walkFiles(projectRoot);
-  const fileIndex = readFileIndex(projectRoot, files);
+  if (rule.type === 'test' && context.testFrameworks.length === 0) {
+    reasons.push(rule.message || 'test framework not detected');
+  }
+
+  if (rule.type === 'grant-evidence') {
+    const evidenceTargets = Array.isArray(rule.evidence) ? rule.evidence : [rule.evidence].filter(Boolean);
+    for (const key of evidenceTargets) {
+      evidence[key] = true;
+    }
+    if (Array.isArray(rule.files) && rule.files.length > 0) {
+      evidence.files = rule.files;
+    }
+    if (Array.isArray(rule.symbols) && rule.symbols.length > 0) {
+      evidence.symbols = rule.symbols;
+    }
+    if (Array.isArray(rule.codeFiles) && rule.codeFiles.length > 0) {
+      evidence.codeFiles = rule.codeFiles;
+      evidence.code = true;
+    }
+    if (Array.isArray(rule.testFiles) && rule.testFiles.length > 0) {
+      evidence.testFiles = rule.testFiles;
+      evidence.test = true;
+    }
+    if (Array.isArray(rule.artifactFiles) && rule.artifactFiles.length > 0) {
+      evidence.artifactFiles = rule.artifactFiles;
+      evidence.artifact = true;
+    }
+  }
+
+  return {
+    passed: reasons.length === 0,
+    reasons,
+    evidence,
+    overrideResult: rule.overrideResult === true
+  };
+}
+
+function buildValidationContext(projectRoot, config, plugins) {
+  const files = walkFiles(projectRoot);
+  const fileIndex = readFileIndex(projectRoot, files, config);
   const testFrameworks = detectTestFrameworks(projectRoot, files);
 
   return {
@@ -575,10 +699,11 @@ function validateTask(task, context, config, plugins) {
   // Combine path hints AND standalone filenames for token exclusion so that tokens
   // derived from any referenced filename (e.g. "roadmap-skill" from
   // "roadmap-skill.config.json") are excluded from code evidence scoring.
-  const pathDerivedTokens = extractPathDerivedTokens([...pathHints, ...standaloneFilenames]);
-  const filesFromCode = findCodeEvidence(task.text, context.fileIndex, pathDerivedTokens);
-  const filesFromTests = findTestEvidence(task.text, context.fileIndex);
-  const { files: filesFromArtifacts, heuristicArtifacts } = findArtifactEvidence(task.text, context.fileIndex);
+  const pathDerivedTokens = extractPathDerivedTokens([...pathHints, ...standaloneFilenames]);
+  const filesFromCode = findCodeEvidence(task.text, context.fileIndex, pathDerivedTokens);
+  const filesFromWeakPathTokens = findFilesByTaskPathTokens(task.text, context.fileIndex, pathDerivedTokens);
+  const filesFromTests = findTestEvidence(task.text, context.fileIndex);
+  const { files: filesFromArtifacts, heuristicArtifacts } = findArtifactEvidence(task.text, context.fileIndex);
 
   const structuralCheck = checkNamespaceStructuralEvidence(task.id, task.text, context.fileIndex);
 
@@ -587,9 +712,10 @@ function validateTask(task, context, config, plugins) {
     test: filesFromTests.length > 0,
     artifact: filesFromArtifacts.length > 0,
     files: filesFromPaths,
-    symbols: filesFromSymbols,
-    codeFiles: filesFromCode,
-    testFiles: filesFromTests,
+    symbols: filesFromSymbols,
+    codeFiles: filesFromCode,
+    weakPathFiles: filesFromWeakPathTokens,
+    testFiles: filesFromTests,
     artifactFiles: filesFromArtifacts,
     heuristicArtifacts,
     structuralEvidence: structuralCheck.applicable ? structuralCheck.passed : null,
@@ -610,49 +736,74 @@ function validateTask(task, context, config, plugins) {
     reasons.push(structuralCheck.reason || `no structural evidence for namespace "${extractTaskNamespace(task.id)}"`);
   }
 
-  const hasEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
-  if (!hasEvidence && !structuralCheck.applicable) {
-    reasons.push('no code, test, or artifact evidence found');
-  } else if (!hasEvidence && structuralCheck.applicable && structuralCheck.passed) {
-    reasons.push('no code, test, or artifact evidence found');
-  }
-
-  const requiresTest = context.testFrameworks.length > 0 && isCodeTask(task.text) && !isDocTask(task.text);
-  if (requiresTest && !evidence.test) {
-    reasons.push('missing test evidence');
-  }
-
-  const configuredRules = Array.isArray(config.validators) ? config.validators : [];
-  const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
-  for (const rule of [...configuredRules, ...pluginRules]) {
-    const ruleResult = evaluateRule(rule, task, context);
-    if (!ruleResult.passed) {
-      reasons.push(...ruleResult.reasons);
-    }
-  }
-
-  const uniqueReasons = Array.from(new Set(reasons));
-  const attempted = hasEvidence || pathHints.length > 0 || symbolHints.length > 0;
-
-  const evidenceCount = [evidence.code, evidence.test, evidence.artifact].filter(Boolean).length;
-  const confidence = evidenceCount >= 2 ? 'high' : evidenceCount === 1 ? 'medium' : 'low';
+  const hasEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
+  const hasWeakEvidence = filesFromWeakPathTokens.length > 0;
+  if (!hasEvidence && !hasWeakEvidence && !structuralCheck.applicable) {
+    reasons.push('no code, test, or artifact evidence found');
+  } else if (!hasEvidence && !hasWeakEvidence && structuralCheck.applicable && structuralCheck.passed) {
+    reasons.push('no code, test, or artifact evidence found');
+  }
+
+  const requiresTest = !task.noTest && context.testFrameworks.length > 0 && isCodeTask(task.text) && !isDocTask(task.text);
+  if (requiresTest && !evidence.test) {
+    reasons.push('missing test evidence');
+  }
+
+  const configuredRules = Array.isArray(config.validators) ? config.validators : [];
+  const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
+  let overrideResult = null;
+  for (const rule of [...configuredRules, ...pluginRules]) {
+    const ruleResult = evaluateRule(rule, task, context);
+    if (ruleResult.evidence && Object.keys(ruleResult.evidence).length > 0) {
+      Object.assign(evidence, mergeRuleEvidence(evidence, ruleResult.evidence));
+    }
+    if (!ruleResult.passed) {
+      reasons.push(...ruleResult.reasons);
+    }
+    if (ruleResult.overrideResult) {
+      overrideResult = ruleResult;
+    }
+  }
+
+  const hasStrongEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
+  if (hasStrongEvidence) {
+    const noEvidenceReason = 'no code, test, or artifact evidence found';
+    const idx = reasons.indexOf(noEvidenceReason);
+    if (idx >= 0) {
+      reasons.splice(idx, 1);
+    }
+  }
+
+  let uniqueReasons = Array.from(new Set(reasons));
+
+  if (overrideResult) {
+    uniqueReasons = Array.isArray(overrideResult.reasons) ? Array.from(new Set(overrideResult.reasons)) : [];
+  }
+
+  const attempted = hasStrongEvidence || hasWeakEvidence || pathHints.length > 0 || symbolHints.length > 0;
+
+  const evidenceCount = [evidence.code, evidence.test, evidence.artifact].filter(Boolean).length;
+  let confidence = evidenceCount >= 2 ? 'high' : evidenceCount === 1 ? 'medium' : 'low';
+  if (confidence === 'low' && hasWeakEvidence) {
+    confidence = 'low';
+  }
 
   // True when the only passing evidence is artifact/doc files and the task is not a doc task.
   // Used by auditValidation to flag implementation tasks that pass solely via documentation.
   const evidenceIsDocOnly = !evidence.code && !evidence.test && evidence.artifact && !isDocTask(task.text);
 
-  return {
-    taskId: task.id,
-    passed: uniqueReasons.length === 0,
-    confidence,
-    reasons: uniqueReasons,
+  return {
+    taskId: task.id,
+    passed: overrideResult ? overrideResult.passed !== false : uniqueReasons.length === 0,
+    confidence,
+    reasons: uniqueReasons,
     evidence,
     evidenceIsDocOnly,
     requiresTest,
-    hasEvidence,
-    attempted
-  };
-}
+    hasEvidence: hasStrongEvidence || hasWeakEvidence,
+    attempted
+  };
+}
 
 function validateTasks(tasks, context, config, plugins) {
   const result = {};