roadmapsmith 0.9.2 → 0.9.4

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.
 
@@ -120,6 +124,12 @@ Create `roadmap-skill.config.json`:
       "type": "file-exists",
       "when": "migration",
       "path": "db/migrations"
+    },
+    {
+      "type": "grant-evidence",
+      "whenId": "^p0-electron-builder-windows$",
+      "evidence": ["test"],
+      "testFiles": ["test/electron-builder.test.js"]
     }
   ],
   "customSections": [
@@ -147,6 +157,20 @@ Create `roadmap-skill.config.json`:
 }
 ```
 
+Task markers can include `rs:no-test` to disable the test-evidence requirement for one task:
+
+```markdown
+- [ ] Add Windows autostart script <!-- rs:task=p0-windows-autostart rs:no-test -->
+```
+
+Validator rules are backward compatible:
+
+- `when` matches task text.
+- `whenId` matches the stable `rs:task` ID.
+- `grant-evidence` can grant `code`, `test`, or `artifact` evidence without `overrideResult`.
+- `overrideResult: true` is only needed when a rule should replace automatic failures.
+- Tests that read a referenced file with `fs.readFileSync`, `fs.readFile`, `readFileSync`, or `readFile` can count as test evidence for tasks that explicitly mention that file.
+
 ## Plugin API
 
 Plugin module path(s) are loaded from `config.plugins` in deterministic order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "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+(.*)$/;
 
@@ -30,6 +30,8 @@ function parseRoadmap(content) {
     const checked = taskMatch[2].toLowerCase() === 'x';
     const text = taskMatch[3].trim();
     const markerId = taskMatch[4] || null;
+    const markerFlags = taskMatch[5] || '';
+    const noTest = /\brs:no-test\b/i.test(markerFlags);
 
     let warningLineIndex = null;
     let warningText = null;
@@ -51,6 +53,7 @@ function parseRoadmap(content) {
       warningLineIndex,
       warningText,
       markerId,
+      noTest,
       indent,
       section
     });

package/src/validator/index.js

@@ -11,6 +11,8 @@ 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 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'];
@@ -80,11 +82,62 @@ function isFixturePath(relativePath) {
   return /(?:^|[/\\])fixtures[/\\]/.test(relativePath);
 }
 
-function readFileIndex(projectRoot, files) {
+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();
@@ -99,6 +152,10 @@ function readFileIndex(projectRoot, files) {
       continue;
     }
 
+    if (isTranslationPath(relativePath)) continue;
+    if (ext === '.json' && looksLikeTranslationJson(content)) continue;
+    if (isMostlyUiStrings(content)) continue;
+
     index.push({
       relativePath,
       absolutePath,
@@ -256,6 +313,46 @@ 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.
 // Those tokens appear in any file that mentions the same path — creating circular
@@ -314,12 +411,45 @@ function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set()) {
   return matches.slice(0, 20);
 }
 
-function findTestEvidence(taskText, fileIndex) {
+function normalizeReferencedPath(rawPath) {
+  return String(rawPath || '').replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+}
+
+function referencedPathMatches(readRef, referencedPath) {
+  const normalizedRef = normalizeReferencedPath(readRef);
+  const normalizedHint = normalizeReferencedPath(referencedPath);
+  if (!normalizedRef || !normalizedHint) return false;
+  if (normalizedRef === normalizedHint || normalizedRef.endsWith('/' + normalizedHint)) {
+    return true;
+  }
+  return path.basename(normalizedRef) === normalizedHint || normalizedRef === path.basename(normalizedHint);
+}
+
+function extractTestReadReferences(content) {
+  const refs = [];
+  const lines = String(content || '').split(/\r?\n/);
+  for (const line of lines) {
+    if (!/\b(?:fs\.)?readFile(?:Sync)?\s*\(/.test(line)) {
+      continue;
+    }
+    const stringLiterals = line.match(/['"`]([^'"`]+)['"`]/g) || [];
+    for (const literal of stringLiterals) {
+      const value = literal.slice(1, -1);
+      if (hasKnownFileExtension(value) || value.includes('/') || value.includes('\\')) {
+        refs.push(value);
+      }
+    }
+  }
+  return refs;
+}
+
+function findTestEvidence(taskText, fileIndex, referencedPaths = []) {
   const tokens = tokenize(taskText)
     .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token) && !token.endsWith('/'))
     .slice(0, 8);
 
-  if (tokens.length === 0) return [];
+  const pathRefs = Array.from(new Set(referencedPaths)).filter(Boolean);
+  if (tokens.length === 0 && pathRefs.length === 0) return [];
 
   // Only tokens of length >= 4 are used for import-reference matching.
   // Very short tokens (e.g. "app", "web") are too generic: they appear as substrings in
@@ -355,6 +485,14 @@ function findTestEvidence(taskText, fileIndex) {
       const lowered = file.content.toLowerCase();
       if (lowered.includes(tokens[0])) {
         matches.push(file.relativePath);
+        continue;
+      }
+    }
+
+    if (pathRefs.length > 0) {
+      const readRefs = extractTestReadReferences(file.content);
+      if (readRefs.some((readRef) => pathRefs.some((pathRef) => referencedPathMatches(readRef, pathRef)))) {
+        matches.push(file.relativePath);
       }
     }
   }
@@ -486,25 +624,33 @@ function checkNamespaceStructuralEvidence(taskId, taskText, fileIndex) {
 
 function evaluateRule(rule, task, context) {
   if (!rule) {
-    return { passed: true, reasons: [], evidence: {} };
+    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: {} };
+      return { passed: true, reasons: [], evidence: {}, overrideResult: false };
+    }
+  }
+
+  if (rule.whenId) {
+    const regexp = new RegExp(rule.whenId, 'i');
+    if (!regexp.test(task.id)) {
+      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: true, reasons: [], evidence: {}, overrideResult: false };
     }
     return {
       passed: custom.passed !== false,
       reasons: Array.isArray(custom.reasons) ? custom.reasons : [],
-      evidence: custom.evidence || {}
+      evidence: custom.evidence || {},
+      overrideResult: rule.overrideResult === true || custom.overrideResult === true
     };
   }
 
@@ -543,16 +689,42 @@ function evaluateRule(rule, task, context) {
     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
+    evidence,
+    overrideResult: rule.overrideResult === true
   };
 }
 
 function buildValidationContext(projectRoot, config, plugins) {
   const files = walkFiles(projectRoot);
-  const fileIndex = readFileIndex(projectRoot, files);
+  const fileIndex = readFileIndex(projectRoot, files, config);
   const testFrameworks = detectTestFrameworks(projectRoot, files);
 
   return {
@@ -577,7 +749,8 @@ function validateTask(task, context, config, plugins) {
   // "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 filesFromWeakPathTokens = findFilesByTaskPathTokens(task.text, context.fileIndex, pathDerivedTokens);
+  const filesFromTests = findTestEvidence(task.text, context.fileIndex, [...pathHints, ...standaloneFilenames]);
   const { files: filesFromArtifacts, heuristicArtifacts } = findArtifactEvidence(task.text, context.fileIndex);
 
   const structuralCheck = checkNamespaceStructuralEvidence(task.id, task.text, context.fileIndex);
@@ -589,6 +762,7 @@ function validateTask(task, context, config, plugins) {
     files: filesFromPaths,
     symbols: filesFromSymbols,
     codeFiles: filesFromCode,
+    weakPathFiles: filesFromWeakPathTokens,
     testFiles: filesFromTests,
     artifactFiles: filesFromArtifacts,
     heuristicArtifacts,
@@ -611,31 +785,56 @@ function validateTask(task, context, config, plugins) {
   }
 
   const hasEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
-  if (!hasEvidence && !structuralCheck.applicable) {
+  const hasWeakEvidence = filesFromWeakPathTokens.length > 0;
+  if (!hasEvidence && !hasWeakEvidence && !structuralCheck.applicable) {
     reasons.push('no code, test, or artifact evidence found');
-  } else if (!hasEvidence && structuralCheck.applicable && structuralCheck.passed) {
+  } else if (!hasEvidence && !hasWeakEvidence && 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 requiresTest = !task.noTest && context.testFrameworks.length > 0 && isCodeTask(task.text) && !isDocTask(task.text);
   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 uniqueReasons = Array.from(new Set(reasons));
-  const attempted = hasEvidence || pathHints.length > 0 || symbolHints.length > 0;
+  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);
+    }
+  }
+
+  if (requiresTest && !evidence.test) {
+    reasons.push('missing test evidence');
+  }
+
+  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;
-  const confidence = evidenceCount >= 2 ? 'high' : evidenceCount === 1 ? 'medium' : 'low';
+  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.
@@ -643,13 +842,13 @@ function validateTask(task, context, config, plugins) {
 
   return {
     taskId: task.id,
-    passed: uniqueReasons.length === 0,
+    passed: overrideResult ? overrideResult.passed !== false : uniqueReasons.length === 0,
     confidence,
     reasons: uniqueReasons,
     evidence,
     evidenceIsDocOnly,
     requiresTest,
-    hasEvidence,
+    hasEvidence: hasStrongEvidence || hasWeakEvidence,
     attempted
   };
 }