@joshski/dust 0.1.97 → 0.1.99

package/dist/validation.js

@@ -1,27 +1,177 @@
 // lib/validation/index.ts
 import { relative } from "node:path";
 
-// lib/markdown/markdown-utilities.ts
-function extractTitle(content) {
-  const match = content.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : null;
+// lib/validation/overlay-filesystem.ts
+function createOverlayFileSystem(base, patchFiles, deletedPaths = new Set) {
+  const patchDirs = new Set;
+  for (const path of patchFiles.keys()) {
+    let dir = path;
+    while (dir.includes("/")) {
+      dir = dir.substring(0, dir.lastIndexOf("/"));
+      if (dir)
+        patchDirs.add(dir);
+    }
+  }
+  function isDeleted(path) {
+    return deletedPaths.has(path);
+  }
+  return {
+    exists(path) {
+      if (isDeleted(path))
+        return false;
+      return patchFiles.has(path) || patchDirs.has(path) || base.exists(path);
+    },
+    async readFile(path) {
+      if (isDeleted(path)) {
+        const error = new Error(`ENOENT: no such file or directory, open '${path}'`);
+        error.code = "ENOENT";
+        throw error;
+      }
+      const patchContent = patchFiles.get(path);
+      if (patchContent !== undefined) {
+        return patchContent;
+      }
+      return base.readFile(path);
+    },
+    async readdir(path) {
+      const prefix = `${path}/`;
+      const entries = new Set;
+      for (const patchPath of patchFiles.keys()) {
+        if (patchPath.startsWith(prefix)) {
+          const relative = patchPath.slice(prefix.length);
+          const firstSegment = relative.split("/")[0];
+          entries.add(firstSegment);
+        }
+      }
+      try {
+        const baseEntries = await base.readdir(path);
+        for (const entry of baseEntries) {
+          const entryPath = `${path}/${entry}`;
+          if (!isDeleted(entryPath)) {
+            entries.add(entry);
+          }
+        }
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      return Array.from(entries);
+    },
+    isDirectory(path) {
+      if (isDeleted(path))
+        return false;
+      return patchDirs.has(path) || base.isDirectory(path);
+    }
+  };
 }
-var MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/;
-function findH1Index(lines) {
+
+// lib/artifacts/parsed-artifact.ts
+var MARKDOWN_LINK_PATTERN2 = /\[([^\]]+)\]\(([^)]+)\)/g;
+function parseArtifact(filePath, content) {
+  const lines = content.split(`
+`);
+  let title = null;
+  let titleLine = null;
+  let openingSentence = null;
+  let openingSentenceLine = null;
+  const sections = [];
+  const allLinks = [];
+  let currentSection = null;
+  let inCodeFence = false;
+  let openingSentenceResolved = false;
   for (let i = 0;i < lines.length; i++) {
-    if (lines[i].match(/^#\s+.+$/)) {
-      return i;
+    const line = lines[i];
+    const lineNumber = i + 1;
+    if (line.startsWith("```")) {
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+    if (inCodeFence) {
+      continue;
+    }
+    const h1Match = line.match(/^#\s+(.+)$/);
+    if (h1Match) {
+      if (title === null) {
+        title = h1Match[1].trim();
+        titleLine = lineNumber;
+      } else {
+        if (currentSection !== null) {
+          currentSection.endLine = findLastNonEmptyLine(lines, currentSection.startLine, lineNumber - 2);
+          sections.push(currentSection);
+          currentSection = null;
+        }
+      }
+      continue;
+    }
+    const headingMatch = line.match(/^(#{2,6})\s+(.+)$/);
+    if (headingMatch) {
+      openingSentenceResolved = true;
+      if (currentSection !== null) {
+        currentSection.endLine = findLastNonEmptyLine(lines, currentSection.startLine, lineNumber - 2);
+        sections.push(currentSection);
+      }
+      currentSection = {
+        heading: headingMatch[2].trim(),
+        level: headingMatch[1].length,
+        startLine: lineNumber,
+        endLine: -1,
+        links: []
+      };
+      continue;
     }
+    if (shouldCheckForOpeningSentence(title, openingSentenceResolved, line)) {
+      const result = tryExtractOpeningSentence(lines, i);
+      openingSentence = result.sentence;
+      openingSentenceLine = result.sentence !== null ? lineNumber : null;
+      openingSentenceResolved = true;
+    }
+    const linkMatches = line.matchAll(MARKDOWN_LINK_PATTERN2);
+    for (const match of linkMatches) {
+      const link = {
+        text: match[1],
+        target: match[2],
+        line: lineNumber
+      };
+      allLinks.push(link);
+      if (currentSection !== null) {
+        currentSection.links.push(link);
+      }
+    }
+  }
+  if (currentSection !== null) {
+    currentSection.endLine = findLastNonEmptyLine(lines, currentSection.startLine, lines.length - 1);
+    sections.push(currentSection);
   }
-  return -1;
+  return {
+    filePath,
+    rawContent: content,
+    title,
+    titleLine,
+    openingSentence,
+    openingSentenceLine,
+    sections,
+    allLinks
+  };
+}
+function shouldCheckForOpeningSentence(title, resolved, line) {
+  if (title === null || resolved) {
+    return false;
+  }
+  const trimmed = line.trim();
+  return trimmed !== "" && !isStructuralElement(trimmed);
+}
+function tryExtractOpeningSentence(lines, startIndex) {
+  const paragraph = collectParagraph(lines, startIndex);
+  return { sentence: extractFirstSentence(paragraph) };
 }
-function findFirstNonBlankLineAfter(lines, startIndex) {
-  for (let i = startIndex + 1;i < lines.length; i++) {
+function findLastNonEmptyLine(lines, contentStartIndex, fromIndex) {
+  for (let i = fromIndex;i >= contentStartIndex; i--) {
     if (lines[i].trim() !== "") {
-      return i;
+      return i + 1;
     }
   }
-  return -1;
+  return contentStartIndex;
 }
 var LIST_ITEM_PREFIXES = ["-", "*", "+"];
 var STRUCTURAL_PREFIXES = ["#", "```", ">"];
@@ -52,27 +202,28 @@ function extractFirstSentence(paragraph) {
   const match = paragraph.match(/^(.+?[.?!])(?:\s|$)/);
   return match ? match[1] : null;
 }
-function extractOpeningSentence(content) {
-  const lines = content.split(`
-`);
-  const h1Index = findH1Index(lines);
-  if (h1Index === -1) {
-    return null;
-  }
-  const paragraphStart = findFirstNonBlankLineAfter(lines, h1Index);
-  if (paragraphStart === -1) {
-    return null;
-  }
-  const trimmedFirstLine = lines[paragraphStart].trim();
-  if (isStructuralElement(trimmedFirstLine)) {
-    return null;
-  }
-  const paragraph = collectParagraph(lines, paragraphStart);
-  return extractFirstSentence(paragraph);
+
+// lib/artifacts/workflow-tasks.ts
+var IDEA_TRANSITION_PREFIXES = [
+  "Refine Idea: ",
+  "Decompose Idea: ",
+  "Shelve Idea: ",
+  "Expedite Idea: "
+];
+function titleToFilename(title) {
+  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
 }
 
+// lib/artifacts/index.ts
+var ARTIFACT_TYPES = [
+  "facts",
+  "ideas",
+  "principles",
+  "tasks"
+];
+
 // lib/lint/validators/content-validator.ts
-var REQUIRED_HEADINGS = ["## Blocked By", "## Definition of Done"];
+var REQUIRED_TASK_HEADINGS = ["Blocked By", "Definition of Done"];
 var MAX_OPENING_SENTENCE_LENGTH = 150;
 var NON_IMPERATIVE_STARTERS = new Set([
   "the",
@@ -88,31 +239,32 @@ var NON_IMPERATIVE_STARTERS = new Set([
   "you",
   "i"
 ]);
-function validateOpeningSentence(filePath, content) {
-  const openingSentence = extractOpeningSentence(content);
-  if (!openingSentence) {
+function validateOpeningSentence(artifact) {
+  if (!artifact.openingSentence) {
     return {
-      file: filePath,
+      file: artifact.filePath,
+      line: artifact.titleLine ?? undefined,
       message: "Missing or malformed opening sentence after H1 heading"
     };
   }
   return null;
 }
-function validateOpeningSentenceLength(filePath, content) {
-  const openingSentence = extractOpeningSentence(content);
+function validateOpeningSentenceLength(artifact) {
+  const openingSentence = artifact.openingSentence;
   if (!openingSentence) {
     return null;
   }
   if (openingSentence.length > MAX_OPENING_SENTENCE_LENGTH) {
     return {
-      file: filePath,
+      file: artifact.filePath,
+      line: artifact.openingSentenceLine ?? undefined,
       message: `Opening sentence is ${openingSentence.length} characters (max ${MAX_OPENING_SENTENCE_LENGTH}). Split into multiple sentences; only the first sentence is checked.`
     };
   }
   return null;
 }
-function validateImperativeOpeningSentence(filePath, content) {
-  const openingSentence = extractOpeningSentence(content);
+function validateImperativeOpeningSentence(artifact) {
+  const openingSentence = artifact.openingSentence;
   if (!openingSentence) {
     return null;
   }
@@ -121,19 +273,21 @@ function validateImperativeOpeningSentence(filePath, content) {
   if (NON_IMPERATIVE_STARTERS.has(lower) || lower.endsWith("ing")) {
     const preview = openingSentence.length > 40 ? `${openingSentence.slice(0, 40)}...` : openingSentence;
     return {
-      file: filePath,
+      file: artifact.filePath,
+      line: artifact.openingSentenceLine ?? undefined,
       message: `Opening sentence should use imperative form (e.g., "Add X" not "This adds X"). Found: "${preview}"`
     };
   }
   return null;
 }
-function validateTaskHeadings(filePath, content) {
+function validateTaskHeadings(artifact) {
   const violations = [];
-  for (const heading of REQUIRED_HEADINGS) {
-    if (!content.includes(heading)) {
+  const sectionHeadings = new Set(artifact.sections.map((s) => s.heading));
+  for (const heading of REQUIRED_TASK_HEADINGS) {
+    if (!sectionHeadings.has(heading)) {
       violations.push({
-        file: filePath,
-        message: `Missing required heading: "${heading}"`
+        file: artifact.filePath,
+        message: `Missing required heading: "## ${heading}"`
       });
     }
   }
@@ -141,6 +295,7 @@ function validateTaskHeadings(filePath, content) {
 }
 
 // lib/lint/validators/directory-validator.ts
+var EXPECTED_DIRECTORIES = [...ARTIFACT_TYPES, "config"];
 async function validateContentDirectoryFiles(dirPath, fileSystem) {
   const violations = [];
   let entries;
@@ -178,17 +333,6 @@ async function validateContentDirectoryFiles(dirPath, fileSystem) {
   return violations;
 }
 
-// lib/artifacts/workflow-tasks.ts
-var IDEA_TRANSITION_PREFIXES = [
-  "Refine Idea: ",
-  "Decompose Idea: ",
-  "Shelve Idea: ",
-  "Expedite Idea: "
-];
-function titleToFilename(title) {
-  return `${title.toLowerCase().replace(/\./g, "-").replace(/[^a-z0-9\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "")}.md`;
-}
-
 // lib/lint/validators/filename-validator.ts
 var SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*\.md$/;
 function validateFilename(filePath) {
@@ -202,17 +346,17 @@ function validateFilename(filePath) {
   }
   return null;
 }
-function validateTitleFilenameMatch(filePath, content) {
-  const title = extractTitle(content);
+function validateTitleFilenameMatch(artifact) {
+  const title = artifact.title;
   if (!title) {
     return null;
   }
-  const parts = filePath.split("/");
+  const parts = artifact.filePath.split("/");
   const actualFilename = parts[parts.length - 1];
   const expectedFilename = titleToFilename(title);
   if (actualFilename !== expectedFilename) {
     return {
-      file: filePath,
+      file: artifact.filePath,
       message: `Filename "${actualFilename}" does not match title "${title}" (expected "${expectedFilename}")`
     };
   }
@@ -252,10 +396,11 @@ function validateH2Heading(filePath, line, lineNumber, inOpenQuestions, currentQ
   }
   return violations;
 }
-function validateIdeaOpenQuestions(filePath, content) {
+function validateIdeaOpenQuestions(artifact) {
   const violations = [];
-  const lines = content.split(`
+  const lines = artifact.rawContent.split(`
 `);
+  const filePath = artifact.filePath;
   const topLevelStructureMessage = "Open Questions must use `### Question?` headings and `#### Option` headings at the top level. Put supporting markdown (including lists and code blocks) under an option heading. Run `dust new idea` to see the expected format.";
   let inOpenQuestions = false;
   let currentQuestionLine = null;
@@ -331,18 +476,24 @@ function validateIdeaOpenQuestions(filePath, content) {
   }
   return violations;
 }
-function validateIdeaTransitionTitle(filePath, content, ideasPath, fileSystem) {
-  const title = extractTitle(content);
+function validateIdeaTransitionTitle(artifact, ideasPath, fileSystem) {
+  const title = artifact.title;
   if (!title) {
     return null;
   }
   for (const prefix of IDEA_TRANSITION_PREFIXES) {
     if (title.startsWith(prefix)) {
+      if (prefix === "Expedite Idea: ") {
+        const hasIdeaDescriptionSection = artifact.sections.some((s) => s.heading === "Idea Description" && s.level === 2);
+        if (hasIdeaDescriptionSection) {
+          return null;
+        }
+      }
       const ideaTitle = title.slice(prefix.length);
       const ideaFilename = titleToFilename(ideaTitle);
       if (!fileSystem.exists(`${ideasPath}/${ideaFilename}`)) {
         return {
-          file: filePath,
+          file: artifact.filePath,
           message: `Idea transition task references non-existent idea: "${ideaTitle}" (expected file "${ideaFilename}" in ideas/)`
         };
       }
@@ -351,37 +502,9 @@ function validateIdeaTransitionTitle(filePath, content, ideasPath, fileSystem) {
   }
   return null;
 }
-function extractSectionContent(content, sectionHeading) {
-  const lines = content.split(`
-`);
-  let inSection = false;
-  let sectionContent = "";
-  let startLine = 0;
-  for (let i = 0;i < lines.length; i++) {
-    const line = lines[i];
-    if (line.startsWith("## ")) {
-      if (inSection)
-        break;
-      if (line.trimEnd() === `## ${sectionHeading}`) {
-        inSection = true;
-        startLine = i + 1;
-      }
-      continue;
-    }
-    if (line.startsWith("# ") && inSection)
-      break;
-    if (inSection) {
-      sectionContent += `${line}
-`;
-    }
-  }
-  if (!inSection)
-    return null;
-  return { content: sectionContent, startLine };
-}
-function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSystem) {
+function validateWorkflowTaskBodySection(artifact, ideasPath, fileSystem) {
   const violations = [];
-  const title = extractTitle(content);
+  const title = artifact.title;
   if (!title)
     return violations;
   let matchedPrefix = null;
@@ -394,10 +517,10 @@ function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSyste
   if (!matchedPrefix)
     return violations;
   const expectedHeading = WORKFLOW_PREFIX_TO_SECTION[matchedPrefix];
-  const section = extractSectionContent(content, expectedHeading);
+  const section = artifact.sections.find((s) => s.heading === expectedHeading && s.level === 2);
   if (!section) {
     violations.push({
-      file: filePath,
+      file: artifact.filePath,
       message: `Workflow task with "${matchedPrefix.trim()}" prefix is missing required "## ${expectedHeading}" section. Add a section with a link to the idea file, e.g.:
 
 ## ${expectedHeading}
@@ -406,25 +529,9 @@ function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSyste
     });
     return violations;
   }
-  const linkRegex = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
-  const links = [];
-  const sectionLines = section.content.split(`
-`);
-  for (let i = 0;i < sectionLines.length; i++) {
-    const line = sectionLines[i];
-    let match = linkRegex.exec(line);
-    while (match !== null) {
-      links.push({
-        text: match[1],
-        target: match[2],
-        line: section.startLine + i + 1
-      });
-      match = linkRegex.exec(line);
-    }
-  }
-  if (links.length === 0) {
+  if (section.links.length === 0) {
     violations.push({
-      file: filePath,
+      file: artifact.filePath,
       message: `"## ${expectedHeading}" section contains no link. Add a markdown link to the idea file, e.g.:
 
 - [Idea Title](../ideas/idea-slug.md)`,
@@ -432,10 +539,10 @@ function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSyste
     });
     return violations;
   }
-  const ideaLinks = links.filter((l) => l.target.includes("/ideas/") || l.target.startsWith("../ideas/"));
+  const ideaLinks = section.links.filter((l) => l.target.includes("/ideas/") || l.target.startsWith("../ideas/"));
   if (ideaLinks.length === 0) {
     violations.push({
-      file: filePath,
+      file: artifact.filePath,
       message: `"## ${expectedHeading}" section contains no link to an idea file. Links must point to a file in ../ideas/, e.g.:
 
 - [Idea Title](../ideas/idea-slug.md)`,
@@ -451,7 +558,7 @@ function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSyste
     const ideaFilePath = `${ideasPath}/${ideaSlug}.md`;
     if (!fileSystem.exists(ideaFilePath)) {
       violations.push({
-        file: filePath,
+        file: artifact.filePath,
         message: `Link to idea "${link.text}" points to non-existent file: ${ideaSlug}.md. Either create the idea file at ideas/${ideaSlug}.md or update the link to point to an existing idea.`,
         line: link.line
       });
@@ -464,153 +571,129 @@ function validateWorkflowTaskBodySection(filePath, content, ideasPath, fileSyste
 import { dirname, resolve } from "node:path";
 var SEMANTIC_RULES = [
   {
-    section: "## Principles",
+    sectionHeading: "Principles",
     requiredPath: "/.dust/principles/",
     description: "principle"
   },
   {
-    section: "## Blocked By",
+    sectionHeading: "Blocked By",
     requiredPath: "/.dust/tasks/",
     description: "task"
   }
 ];
-function validateLinks(filePath, content, fileSystem) {
+function isExternalOrAnchorLink(target) {
+  return target.startsWith("http://") || target.startsWith("https://") || target.startsWith("#");
+}
+function isAnchorLink(target) {
+  return target.startsWith("#");
+}
+function isExternalLink(target) {
+  return target.startsWith("http://") || target.startsWith("https://");
+}
+function validateLinks(artifact, fileSystem) {
   const violations = [];
-  const lines = content.split(`
-`);
-  const fileDir = dirname(filePath);
-  for (let i = 0;i < lines.length; i++) {
-    const line = lines[i];
-    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
-    let match = linkPattern.exec(line);
-    while (match) {
-      const linkTarget = match[2];
-      const isExternalOrAnchorLink = linkTarget.startsWith("http://") || linkTarget.startsWith("https://") || linkTarget.startsWith("#");
-      if (isExternalOrAnchorLink) {
-        match = linkPattern.exec(line);
-        continue;
-      }
-      if (linkTarget.startsWith("/")) {
-        violations.push({
-          file: filePath,
-          message: `Absolute link not allowed: "${linkTarget}" (use a relative path instead)`,
-          line: i + 1
-        });
-        match = linkPattern.exec(line);
-        continue;
-      }
-      const targetPath = linkTarget.split("#")[0];
-      const resolvedPath = resolve(fileDir, targetPath);
-      if (!fileSystem.exists(resolvedPath)) {
-        violations.push({
-          file: filePath,
-          message: `Broken link: "${linkTarget}"`,
-          line: i + 1
-        });
-      }
-      match = linkPattern.exec(line);
+  const fileDir = dirname(artifact.filePath);
+  for (const link of artifact.allLinks) {
+    if (isExternalOrAnchorLink(link.target)) {
+      continue;
+    }
+    if (link.target.startsWith("/")) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Absolute link not allowed: "${link.target}" (use a relative path instead)`,
+        line: link.line
+      });
+      continue;
+    }
+    const targetPath = link.target.split("#")[0];
+    const resolvedPath = resolve(fileDir, targetPath);
+    if (!fileSystem.exists(resolvedPath)) {
+      violations.push({
+        file: artifact.filePath,
+        message: `Broken link: "${link.target}"`,
+        line: link.line
+      });
     }
   }
   return violations;
 }
-function validateSemanticLinks(filePath, content) {
+function validateSectionLink(artifact, link, rule) {
+  const sectionLabel = `## ${rule.sectionHeading}`;
+  if (isAnchorLink(link.target)) {
+    return {
+      file: artifact.filePath,
+      message: `Link in "${sectionLabel}" must point to a ${rule.description} file, not an anchor: "${link.target}"`,
+      line: link.line
+    };
+  }
+  if (isExternalLink(link.target)) {
+    return {
+      file: artifact.filePath,
+      message: `Link in "${sectionLabel}" must point to a ${rule.description} file, not an external URL: "${link.target}"`,
+      line: link.line
+    };
+  }
+  const fileDir = dirname(artifact.filePath);
+  const targetPath = link.target.split("#")[0];
+  const resolvedPath = resolve(fileDir, targetPath);
+  if (!resolvedPath.includes(rule.requiredPath)) {
+    return {
+      file: artifact.filePath,
+      message: `Link in "${sectionLabel}" must point to a ${rule.description} file: "${link.target}"`,
+      line: link.line
+    };
+  }
+  return null;
+}
+function validateSemanticLinks(artifact) {
   const violations = [];
-  const lines = content.split(`
-`);
-  const fileDir = dirname(filePath);
-  let currentSection = null;
-  for (let i = 0;i < lines.length; i++) {
-    const line = lines[i];
-    if (line.startsWith("## ")) {
-      currentSection = line;
-      continue;
-    }
-    const rule = SEMANTIC_RULES.find((r) => r.section === currentSection);
+  for (const section of artifact.sections) {
+    const rule = SEMANTIC_RULES.find((r) => r.sectionHeading === section.heading);
     if (!rule)
       continue;
-    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
-    let match = linkPattern.exec(line);
-    while (match) {
-      const linkTarget = match[2];
-      if (linkTarget.startsWith("#")) {
-        violations.push({
-          file: filePath,
-          message: `Link in "${rule.section}" must point to a ${rule.description} file, not an anchor: "${linkTarget}"`,
-          line: i + 1
-        });
-        match = linkPattern.exec(line);
-        continue;
-      }
-      if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
-        violations.push({
-          file: filePath,
-          message: `Link in "${rule.section}" must point to a ${rule.description} file, not an external URL: "${linkTarget}"`,
-          line: i + 1
-        });
-        match = linkPattern.exec(line);
-        continue;
-      }
-      const targetPath = linkTarget.split("#")[0];
-      const resolvedPath = resolve(fileDir, targetPath);
-      if (!resolvedPath.includes(rule.requiredPath)) {
-        violations.push({
-          file: filePath,
-          message: `Link in "${rule.section}" must point to a ${rule.description} file: "${linkTarget}"`,
-          line: i + 1
-        });
+    for (const link of section.links) {
+      const violation = validateSectionLink(artifact, link, rule);
+      if (violation) {
+        violations.push(violation);
       }
-      match = linkPattern.exec(line);
     }
   }
   return violations;
 }
-function validatePrincipleHierarchyLinks(filePath, content) {
+function validatePrincipleHierarchyLinks(artifact) {
   const violations = [];
-  const lines = content.split(`
-`);
-  const fileDir = dirname(filePath);
-  let currentSection = null;
-  for (let i = 0;i < lines.length; i++) {
-    const line = lines[i];
-    if (line.startsWith("## ")) {
-      currentSection = line;
-      continue;
-    }
-    if (currentSection !== "## Parent Principle" && currentSection !== "## Sub-Principles") {
+  const hierarchySections = ["Parent Principle", "Sub-Principles"];
+  for (const section of artifact.sections) {
+    if (!hierarchySections.includes(section.heading))
       continue;
-    }
-    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
-    let match = linkPattern.exec(line);
-    while (match) {
-      const linkTarget = match[2];
-      if (linkTarget.startsWith("#")) {
+    const sectionLabel = `## ${section.heading}`;
+    const fileDir = dirname(artifact.filePath);
+    for (const link of section.links) {
+      if (isAnchorLink(link.target)) {
         violations.push({
-          file: filePath,
-          message: `Link in "${currentSection}" must point to a principle file, not an anchor: "${linkTarget}"`,
-          line: i + 1
+          file: artifact.filePath,
+          message: `Link in "${sectionLabel}" must point to a principle file, not an anchor: "${link.target}"`,
+          line: link.line
         });
-        match = linkPattern.exec(line);
         continue;
       }
-      if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
+      if (isExternalLink(link.target)) {
         violations.push({
-          file: filePath,
-          message: `Link in "${currentSection}" must point to a principle file, not an external URL: "${linkTarget}"`,
-          line: i + 1
+          file: artifact.filePath,
+          message: `Link in "${sectionLabel}" must point to a principle file, not an external URL: "${link.target}"`,
+          line: link.line
         });
-        match = linkPattern.exec(line);
         continue;
       }
-      const targetPath = linkTarget.split("#")[0];
+      const targetPath = link.target.split("#")[0];
       const resolvedPath = resolve(fileDir, targetPath);
       if (!resolvedPath.includes("/.dust/principles/")) {
         violations.push({
-          file: filePath,
-          message: `Link in "${currentSection}" must point to a principle file: "${linkTarget}"`,
-          line: i + 1
+          file: artifact.filePath,
+          message: `Link in "${sectionLabel}" must point to a principle file: "${link.target}"`,
+          line: link.line
         });
       }
-      match = linkPattern.exec(line);
     }
   }
   return violations;
@@ -618,58 +701,46 @@ function validatePrincipleHierarchyLinks(filePath, content) {
 
 // lib/lint/validators/principle-hierarchy.ts
 import { dirname as dirname2, resolve as resolve2 } from "node:path";
-var REQUIRED_PRINCIPLE_HEADINGS = ["## Parent Principle", "## Sub-Principles"];
-function validatePrincipleHierarchySections(filePath, content) {
+var REQUIRED_PRINCIPLE_HEADINGS = ["Parent Principle", "Sub-Principles"];
+function validatePrincipleHierarchySections(artifact) {
   const violations = [];
+  const sectionHeadings = new Set(artifact.sections.map((s) => s.heading));
   for (const heading of REQUIRED_PRINCIPLE_HEADINGS) {
-    if (!content.includes(heading)) {
+    if (!sectionHeadings.has(heading)) {
       violations.push({
-        file: filePath,
-        message: `Missing required heading: "${heading}"`
+        file: artifact.filePath,
+        message: `Missing required heading: "## ${heading}"`
       });
     }
   }
   return violations;
 }
-function extractPrincipleRelationships(filePath, content) {
-  const lines = content.split(`
-`);
-  const fileDir = dirname2(filePath);
+function isLocalPrincipleLink(target, resolvedPath) {
+  const isLocalLink = !target.startsWith("#") && !target.startsWith("http://") && !target.startsWith("https://");
+  return isLocalLink && resolvedPath.includes("/.dust/principles/");
+}
+function extractPrincipleRelationships(artifact) {
+  const fileDir = dirname2(artifact.filePath);
   const parentPrinciples = [];
   const subPrinciples = [];
-  let currentSection = null;
-  for (const line of lines) {
-    if (line.startsWith("## ")) {
-      currentSection = line;
+  for (const section of artifact.sections) {
+    if (section.heading !== "Parent Principle" && section.heading !== "Sub-Principles") {
       continue;
     }
-    if (currentSection !== "## Parent Principle" && currentSection !== "## Sub-Principles") {
-      continue;
-    }
-    const linkPattern = new RegExp(MARKDOWN_LINK_PATTERN.source, "g");
-    let match = linkPattern.exec(line);
-    while (match) {
-      const linkTarget = match[2];
-      const isLocalLink = !linkTarget.startsWith("#") && !linkTarget.startsWith("http://") && !linkTarget.startsWith("https://");
-      if (!isLocalLink) {
-        match = linkPattern.exec(line);
-        continue;
-      }
-      const targetPath = linkTarget.split("#")[0];
+    for (const link of section.links) {
+      const targetPath = link.target.split("#")[0];
       const resolvedPath = resolve2(fileDir, targetPath);
-      if (!resolvedPath.includes("/.dust/principles/")) {
-        match = linkPattern.exec(line);
+      if (!isLocalPrincipleLink(link.target, resolvedPath)) {
         continue;
       }
-      if (currentSection === "## Parent Principle") {
+      if (section.heading === "Parent Principle") {
         parentPrinciples.push(resolvedPath);
       } else {
         subPrinciples.push(resolvedPath);
       }
-      match = linkPattern.exec(line);
     }
   }
-  return { filePath, parentPrinciples, subPrinciples };
+  return { filePath: artifact.filePath, parentPrinciples, subPrinciples };
 }
 function validateBidirectionalLinks(allPrincipleRelationships) {
   const violations = [];
@@ -732,70 +803,133 @@ function validateNoCycles(allPrincipleRelationships) {
   return violations;
 }
 
-// lib/validation/overlay-filesystem.ts
-function createOverlayFileSystem(base, patchFiles, deletedPaths = new Set) {
-  const patchDirs = new Set;
-  for (const path of patchFiles.keys()) {
-    let dir = path;
-    while (dir.includes("/")) {
-      dir = dir.substring(0, dir.lastIndexOf("/"));
-      if (dir)
-        patchDirs.add(dir);
+// lib/validation/validation-pipeline.ts
+async function parseArtifacts(fileSystem, dustPath) {
+  const artifacts = new Map;
+  const byType = {
+    facts: [],
+    ideas: [],
+    principles: [],
+    tasks: []
+  };
+  const rootFiles = [];
+  const violations = [];
+  let rootEntries;
+  try {
+    rootEntries = await fileSystem.readdir(dustPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      rootEntries = [];
+    } else {
+      throw error;
     }
   }
-  function isDeleted(path) {
-    return deletedPaths.has(path);
-  }
-  return {
-    exists(path) {
-      if (isDeleted(path))
-        return false;
-      return patchFiles.has(path) || patchDirs.has(path) || base.exists(path);
-    },
-    async readFile(path) {
-      if (isDeleted(path)) {
-        const error = new Error(`ENOENT: no such file or directory, open '${path}'`);
-        error.code = "ENOENT";
-        throw error;
-      }
-      const patchContent = patchFiles.get(path);
-      if (patchContent !== undefined) {
-        return patchContent;
+  for (const entry of rootEntries) {
+    if (!entry.endsWith(".md"))
+      continue;
+    const filePath = `${dustPath}/${entry}`;
+    let content;
+    try {
+      content = await fileSystem.readFile(filePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
       }
-      return base.readFile(path);
-    },
-    async readdir(path) {
-      const prefix = `${path}/`;
-      const entries = new Set;
-      for (const patchPath of patchFiles.keys()) {
-        if (patchPath.startsWith(prefix)) {
-          const relative = patchPath.slice(prefix.length);
-          const firstSegment = relative.split("/")[0];
-          entries.add(firstSegment);
-        }
+      throw error;
+    }
+    const artifact = parseArtifact(filePath, content);
+    artifacts.set(filePath, artifact);
+    rootFiles.push(artifact);
+  }
+  for (const dir of ARTIFACT_TYPES) {
+    const dirPath = `${dustPath}/${dir}`;
+    violations.push(...await validateContentDirectoryFiles(dirPath, fileSystem));
+    let entries;
+    try {
+      entries = await fileSystem.readdir(dirPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
       }
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".md"))
+        continue;
+      const filePath = `${dirPath}/${entry}`;
+      let content;
       try {
-        const baseEntries = await base.readdir(path);
-        for (const entry of baseEntries) {
-          const entryPath = `${path}/${entry}`;
-          if (!isDeleted(entryPath)) {
-            entries.add(entry);
-          }
-        }
+        content = await fileSystem.readFile(filePath);
       } catch (error) {
-        if (error.code !== "ENOENT") {
-          throw error;
+        if (error.code === "ENOENT") {
+          continue;
         }
+        throw error;
       }
-      return Array.from(entries);
-    },
-    isDirectory(path) {
-      if (isDeleted(path))
-        return false;
-      return patchDirs.has(path) || base.isDirectory(path);
+      const artifact = parseArtifact(filePath, content);
+      artifacts.set(filePath, artifact);
+      byType[dir].push(artifact);
     }
+  }
+  return {
+    context: {
+      artifacts,
+      byType,
+      rootFiles,
+      dustPath,
+      fileSystem
+    },
+    violations
   };
 }
+function validateArtifacts(context) {
+  const violations = [];
+  const { byType, rootFiles, dustPath, fileSystem } = context;
+  const ideasPath = `${dustPath}/ideas`;
+  for (const artifact of rootFiles) {
+    violations.push(...validateLinks(artifact, fileSystem));
+  }
+  for (const artifacts of Object.values(byType)) {
+    for (const artifact of artifacts) {
+      const openingSentenceViolation = validateOpeningSentence(artifact);
+      if (openingSentenceViolation)
+        violations.push(openingSentenceViolation);
+      const lengthViolation = validateOpeningSentenceLength(artifact);
+      if (lengthViolation)
+        violations.push(lengthViolation);
+      const titleViolation = validateTitleFilenameMatch(artifact);
+      if (titleViolation)
+        violations.push(titleViolation);
+      violations.push(...validateLinks(artifact, fileSystem));
+    }
+  }
+  for (const artifact of byType.ideas) {
+    violations.push(...validateIdeaOpenQuestions(artifact));
+  }
+  for (const artifact of byType.tasks) {
+    const filenameViolation = validateFilename(artifact.filePath);
+    if (filenameViolation)
+      violations.push(filenameViolation);
+    violations.push(...validateTaskHeadings(artifact));
+    violations.push(...validateSemanticLinks(artifact));
+    const imperativeViolation = validateImperativeOpeningSentence(artifact);
+    if (imperativeViolation)
+      violations.push(imperativeViolation);
+    const ideaTransitionViolation = validateIdeaTransitionTitle(artifact, ideasPath, fileSystem);
+    if (ideaTransitionViolation)
+      violations.push(ideaTransitionViolation);
+    violations.push(...validateWorkflowTaskBodySection(artifact, ideasPath, fileSystem));
+  }
+  const allPrincipleRelationships = [];
+  for (const artifact of byType.principles) {
+    violations.push(...validatePrincipleHierarchySections(artifact));
+    violations.push(...validatePrincipleHierarchyLinks(artifact));
+    allPrincipleRelationships.push(extractPrincipleRelationships(artifact));
+  }
+  violations.push(...validateBidirectionalLinks(allPrincipleRelationships));
+  violations.push(...validateNoCycles(allPrincipleRelationships));
+  return violations;
+}
 
 // lib/validation/index.ts
 var ALLOWED_ROOT_DIRECTORIES = [
@@ -855,36 +989,6 @@ function relativizeViolations(violations, cwd) {
     file: relativizeViolationFilePath(violation.file, cwd)
   }));
 }
-var CONTENT_DIRS = ["principles", "facts", "ideas", "tasks"];
-function validateContentFile(filePath, content) {
-  const violations = [];
-  const openingSentence = validateOpeningSentence(filePath, content);
-  if (openingSentence)
-    violations.push(openingSentence);
-  const openingSentenceLength = validateOpeningSentenceLength(filePath, content);
-  if (openingSentenceLength)
-    violations.push(openingSentenceLength);
-  const titleFilename = validateTitleFilenameMatch(filePath, content);
-  if (titleFilename)
-    violations.push(titleFilename);
-  return violations;
-}
-function validateTaskFile(filePath, content, ideasPath, overlayFs) {
-  const violations = [];
-  const filenameViolation = validateFilename(filePath);
-  if (filenameViolation)
-    violations.push(filenameViolation);
-  violations.push(...validateTaskHeadings(filePath, content));
-  violations.push(...validateSemanticLinks(filePath, content));
-  const imperativeViolation = validateImperativeOpeningSentence(filePath, content);
-  if (imperativeViolation)
-    violations.push(imperativeViolation);
-  const ideaTransition = validateIdeaTransitionTitle(filePath, content, ideasPath, overlayFs);
-  if (ideaTransition)
-    violations.push(ideaTransition);
-  violations.push(...validateWorkflowTaskBodySection(filePath, content, ideasPath, overlayFs));
-  return violations;
-}
 function parsePatchFiles(dustPath, patch) {
   const absolutePatchFiles = new Map;
   const deletedPaths = new Set;
@@ -898,75 +1002,15 @@ function parsePatchFiles(dustPath, patch) {
   }
   return { absolutePatchFiles, deletedPaths };
 }
-function collectPatchDirs(patch) {
-  const patchDirs = new Set;
-  for (const relativePath of Object.keys(patch.files)) {
-    const dir = relativePath.split("/")[0];
-    if (CONTENT_DIRS.includes(dir)) {
-      patchDirs.add(dir);
-    }
-  }
-  return patchDirs;
-}
-async function validatePrincipleRelationships(dustPath, overlayFs) {
-  const allRelationships = [];
-  const principlesPath = `${dustPath}/principles`;
-  try {
-    const existingFiles = await overlayFs.readdir(principlesPath);
-    for (const file of existingFiles) {
-      if (!file.endsWith(".md"))
-        continue;
-      const filePath = `${principlesPath}/${file}`;
-      const content = await overlayFs.readFile(filePath);
-      allRelationships.push(extractPrincipleRelationships(filePath, content));
-    }
-  } catch (error) {
-    if (error.code !== "ENOENT") {
-      throw error;
-    }
-  }
-  return [
-    ...validateBidirectionalLinks(allRelationships),
-    ...validateNoCycles(allRelationships)
-  ];
-}
 async function validatePatch(fileSystem, dustPath, patch, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const { absolutePatchFiles, deletedPaths } = parsePatchFiles(dustPath, patch);
   const overlayFs = createOverlayFileSystem(fileSystem, absolutePatchFiles, deletedPaths);
   const violations = [];
   violations.push(...validatePatchRootEntries(fileSystem, dustPath, patch));
-  const patchDirs = collectPatchDirs(patch);
-  for (const dir of patchDirs) {
-    violations.push(...await validateContentDirectoryFiles(`${dustPath}/${dir}`, overlayFs));
-  }
-  const ideasPath = `${dustPath}/ideas`;
-  for (const [relativePath, content] of Object.entries(patch.files)) {
-    if (content === null)
-      continue;
-    if (!relativePath.endsWith(".md"))
-      continue;
-    const filePath = `${dustPath}/${relativePath}`;
-    const dir = relativePath.split("/")[0];
-    violations.push(...validateLinks(filePath, content, overlayFs));
-    if (CONTENT_DIRS.includes(dir)) {
-      violations.push(...validateContentFile(filePath, content));
-    }
-    if (dir === "ideas") {
-      violations.push(...validateIdeaOpenQuestions(filePath, content));
-    }
-    if (dir === "tasks") {
-      violations.push(...validateTaskFile(filePath, content, ideasPath, overlayFs));
-    }
-    if (dir === "principles") {
-      violations.push(...validatePrincipleHierarchySections(filePath, content));
-      violations.push(...validatePrincipleHierarchyLinks(filePath, content));
-    }
-  }
-  const hasPrinciplePatches = Object.keys(patch.files).some((p) => p.startsWith("principles/"));
-  if (hasPrinciplePatches) {
-    violations.push(...await validatePrincipleRelationships(dustPath, overlayFs));
-  }
+  const { context, violations: parseViolations } = await parseArtifacts(overlayFs, dustPath);
+  violations.push(...parseViolations);
+  violations.push(...validateArtifacts(context));
   return {
     valid: violations.length === 0,
     violations: relativizeViolations(violations, cwd)