@vibe-agent-toolkit/resources 0.1.0-rc.10

package/src/link-parser.ts

@@ -0,0 +1,371 @@
+/**
+ * Markdown link parser and analyzer.
+ *
+ * Parses markdown files to extract:
+ * - Links (regular, reference-style, autolinks)
+ * - Headings (with GitHub-style slugs and nested tree structure)
+ * - File size and token estimates
+ *
+ * Uses unified/remark for robust markdown parsing with GFM support.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+
+import type { Heading, Link, LinkReference, Root } from 'mdast';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+
+import type { HeadingNode, LinkType, ResourceLink } from './types.js';
+
+/**
+ * Result of parsing a markdown file.
+ */
+export interface ParseResult {
+  links: ResourceLink[];
+  headings: HeadingNode[];
+  content: string;
+  sizeBytes: number;
+  estimatedTokenCount: number;
+}
+
+/**
+ * Parse a markdown file and extract all links, headings, and metadata.
+ *
+ * @param filePath - Absolute path to the markdown file
+ * @returns Parsed markdown data including links, headings, size, and token estimate
+ * @throws Error if file cannot be read or parsed
+ *
+ * @example
+ * ```typescript
+ * const result = await parseMarkdown('/path/to/document.md');
+ * console.log(`Found ${result.links.length} links`);
+ * console.log(`Document has ${result.headings.length} top-level headings`);
+ * ```
+ */
+export async function parseMarkdown(filePath: string): Promise<ParseResult> {
+  // Read file content and stats
+  const [content, stats] = await Promise.all([
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is user-provided path parameter
+    readFile(filePath, 'utf-8'),
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is user-provided path parameter
+    stat(filePath),
+  ]);
+
+  const sizeBytes = stats.size;
+  const estimatedTokenCount = Math.ceil(content.length / 4);
+
+  // Parse markdown with unified/remark
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkFrontmatter);
+
+  const tree = processor.parse(content) as Root;
+
+  // Extract links
+  const links = extractLinks(tree);
+
+  // Extract headings with tree structure
+  const headings = extractHeadings(tree);
+
+  return {
+    links,
+    headings,
+    content,
+    sizeBytes,
+    estimatedTokenCount,
+  };
+}
+
+/**
+ * Extract all links from the markdown AST.
+ *
+ * Handles:
+ * - Regular links: [text](href)
+ * - Reference-style links: [text][ref]
+ * - Autolinks: <url>
+ *
+ * @param tree - Markdown AST from unified/remark
+ * @returns Array of classified links with line numbers
+ */
+function extractLinks(tree: Root): ResourceLink[] {
+  const links: ResourceLink[] = [];
+
+  // Visit link nodes (regular links and autolinks)
+  visit(tree, 'link', (node: Link) => {
+    const link: ResourceLink = {
+      text: extractLinkText(node),
+      href: node.url,
+      type: classifyLink(node.url),
+      line: node.position?.start.line,
+    };
+    links.push(link);
+  });
+
+  // Visit linkReference nodes (reference-style links)
+  visit(tree, 'linkReference', (node: LinkReference) => {
+    // For reference-style links, we use the identifier as href
+    // In a full implementation, we'd resolve the definition, but for now
+    // we'll classify based on the identifier pattern
+    const href = node.identifier;
+    const link: ResourceLink = {
+      text: extractLinkText(node),
+      href,
+      type: 'unknown', // Reference links need definition resolution
+      line: node.position?.start.line,
+    };
+    links.push(link);
+  });
+
+  return links;
+}
+
+/**
+ * Extract text content from a link node.
+ *
+ * @param node - Link or LinkReference node
+ * @returns Text content of the link
+ */
+function extractLinkText(node: Link | LinkReference): string {
+  return extractTextFromChildren(node.children);
+}
+
+/**
+ * Classify a link based on its href.
+ *
+ * @param href - The href attribute from the link
+ * @returns Classified link type
+ *
+ * @example
+ * ```typescript
+ * classifyLink('https://example.com') // 'external'
+ * classifyLink('mailto:user@example.com') // 'email'
+ * classifyLink('#heading') // 'anchor'
+ * classifyLink('./file.md') // 'local_file'
+ * classifyLink('./file.md#anchor') // 'local_file'
+ * ```
+ */
+function classifyLink(href: string): LinkType {
+  if (href.startsWith('http://') || href.startsWith('https://')) {
+    return 'external';
+  }
+  if (href.startsWith('mailto:')) {
+    return 'email';
+  }
+  if (href.startsWith('#')) {
+    return 'anchor';
+  }
+  // Links with anchors are still local file links
+  if (href.includes('#')) {
+    return 'local_file';
+  }
+  // .md files are always local files
+  if (href.endsWith('.md')) {
+    return 'local_file';
+  }
+  // Paths that look like file paths (start with ./ or ../ or /) or have no extension
+  if (href.startsWith('./') || href.startsWith('../') || href.startsWith('/')) {
+    return 'local_file';
+  }
+  // Paths without extensions (no dot or last dot is before a slash)
+  const lastSlash = href.lastIndexOf('/');
+  const lastDot = href.lastIndexOf('.');
+  if (lastDot === -1 || lastDot < lastSlash) {
+    return 'local_file';
+  }
+  return 'unknown';
+}
+
+/**
+ * Extract headings from the markdown AST and build a nested tree structure.
+ *
+ * Builds a hierarchical structure where:
+ * - h2 nodes are children of the preceding h1
+ * - h3 nodes are children of the preceding h2
+ * - etc.
+ *
+ * @param tree - Markdown AST from unified/remark
+ * @returns Array of top-level heading nodes with nested children
+ *
+ * @example
+ * For markdown:
+ * ```
+ * # Main
+ * ## Sub
+ * ### Deep
+ * ## Sub2
+ * ```
+ *
+ * Returns:
+ * ```
+ * [
+ *   {
+ *     level: 1,
+ *     text: 'Main',
+ *     slug: 'main',
+ *     children: [
+ *       { level: 2, text: 'Sub', slug: 'sub', children: [
+ *         { level: 3, text: 'Deep', slug: 'deep', children: [] }
+ *       ]},
+ *       { level: 2, text: 'Sub2', slug: 'sub2', children: [] }
+ *     ]
+ *   }
+ * ]
+ * ```
+ */
+function extractHeadings(tree: Root): HeadingNode[] {
+  const flatHeadings: HeadingNode[] = [];
+
+  // First pass: collect all headings in document order
+  visit(tree, 'heading', (node: Heading) => {
+    const text = extractHeadingText(node);
+    const heading: HeadingNode = {
+      level: node.depth,
+      text,
+      slug: generateSlug(text),
+      line: node.position?.start.line,
+    };
+    flatHeadings.push(heading);
+  });
+
+  // Second pass: build tree structure using a stack
+  return buildHeadingTree(flatHeadings);
+}
+
+/**
+ * Extract text content from a heading node.
+ *
+ * @param node - Heading node
+ * @returns Text content of the heading
+ */
+function extractHeadingText(node: Heading): string {
+  return extractTextFromChildren(node.children);
+}
+
+/**
+ * Extract text content from inline children nodes.
+ *
+ * Handles text nodes, inline code, emphasis, and other inline elements.
+ *
+ * @param children - Array of child nodes or undefined
+ * @returns Concatenated text content
+ */
+function extractTextFromChildren(
+  children: Array<{ type: string; value?: unknown }> | undefined
+): string {
+  if (!children || children.length === 0) {
+    return '';
+  }
+
+  return children
+    .map((child) => {
+      if (child.type === 'text') {
+        return child.value as string;
+      }
+      // Handle other inline elements (code, emphasis, etc.)
+      if ('value' in child) {
+        return String(child.value);
+      }
+      return '';
+    })
+    .join('');
+}
+
+/**
+ * Generate a GitHub-style slug from heading text.
+ *
+ * Rules:
+ * - Convert to lowercase
+ * - Replace spaces with hyphens
+ * - Remove special characters
+ * - Collapse multiple hyphens
+ *
+ * @param text - Heading text
+ * @returns GitHub-style slug for anchor links
+ *
+ * @example
+ * ```typescript
+ * generateSlug('Hello World') // 'hello-world'
+ * generateSlug('Section 1.1') // 'section-11'
+ * generateSlug('API Reference (v2)') // 'api-reference-v2'
+ * ```
+ */
+function generateSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replaceAll(/[^\w\s-]/g, '') // Remove special chars
+    .replaceAll(/\s+/g, '-') // Replace spaces with hyphens
+    .replaceAll(/-+/g, '-'); // Collapse multiple hyphens
+}
+
+/**
+ * Build a nested heading tree from a flat list of headings.
+ *
+ * Uses a stack-based algorithm to correctly nest headings:
+ * - When encountering a higher-level heading, pop stack until we find the parent
+ * - Add the heading as a child of the top of stack
+ * - Push the heading onto the stack
+ *
+ * @param flatHeadings - Array of headings in document order
+ * @returns Array of top-level headings with nested children
+ */
+function buildHeadingTree(flatHeadings: HeadingNode[]): HeadingNode[] {
+  if (flatHeadings.length === 0) {
+    return [];
+  }
+
+  const roots: HeadingNode[] = [];
+  const stack: HeadingNode[] = [];
+
+  for (const heading of flatHeadings) {
+    // Initialize children array
+    const headingWithChildren: HeadingNode = {
+      ...heading,
+      children: [],
+    };
+
+    // Pop stack until we find a heading with lower level (the parent)
+    while (stack.length > 0 && (stack.at(-1)?.level ?? 0) >= heading.level) {
+      stack.pop();
+    }
+
+    if (stack.length === 0) {
+      // This is a root-level heading
+      roots.push(headingWithChildren);
+    } else {
+      // Add as child of the top of stack
+      const parent = stack.at(-1);
+      if (parent) {
+        parent.children ??= [];
+        parent.children.push(headingWithChildren);
+      }
+    }
+
+    // Push current heading onto stack
+    stack.push(headingWithChildren);
+  }
+
+  // Clean up empty children arrays (convert to undefined)
+  cleanupEmptyChildren(roots);
+
+  return roots;
+}
+
+/**
+ * Remove empty children arrays from heading tree (convert to undefined).
+ *
+ * @param headings - Array of headings to clean up
+ */
+function cleanupEmptyChildren(headings: HeadingNode[]): void {
+  for (const heading of headings) {
+    if (heading.children?.length === 0) {
+      heading.children = undefined;
+    } else if (heading.children && heading.children.length > 0) {
+      cleanupEmptyChildren(heading.children);
+    }
+  }
+}

package/src/link-validator.ts

@@ -0,0 +1,275 @@
+/**
+ * Link validation for markdown resources.
+ *
+ * Validates different types of links:
+ * - local_file: Checks if file exists, validates anchors if present
+ * - anchor: Validates heading exists in current or target file
+ * - external: Returns info (not validated)
+ * - email: Returns null (valid by default)
+ * - unknown: Returns warning
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { isGitignored } from '@vibe-agent-toolkit/utils';
+
+import type { ValidationIssue } from './schemas/validation-result.js';
+import type { HeadingNode, ResourceLink } from './types.js';
+import { splitHrefAnchor } from './utils.js';
+
+/**
+ * Validate a single link in a markdown resource.
+ *
+ * @param link - The link to validate
+ * @param sourceFilePath - Absolute path to the file containing the link
+ * @param headingsByFile - Map of file paths to their heading trees
+ * @returns ValidationIssue if link is broken, null if valid
+ *
+ * @example
+ * ```typescript
+ * const issue = await validateLink(link, '/project/docs/guide.md', headingsMap);
+ * if (issue) {
+ *   console.log(`${issue.severity}: ${issue.message}`);
+ * }
+ * ```
+ */
+export async function validateLink(
+  link: ResourceLink,
+  sourceFilePath: string,
+  headingsByFile: Map<string, HeadingNode[]>
+): Promise<ValidationIssue | null> {
+  switch (link.type) {
+    case 'local_file':
+      return await validateLocalFileLink(link, sourceFilePath, headingsByFile);
+
+    case 'anchor':
+      return await validateAnchorLink(link, sourceFilePath, headingsByFile);
+
+    case 'external':
+      // External URLs are not validated - return info
+      return {
+        severity: 'info',
+        resourcePath: sourceFilePath,
+        line: link.line,
+        type: 'external_url',
+        link: link.href,
+        message: 'External URL not validated',
+      };
+
+    case 'email':
+      // Email links are valid by default
+      return null;
+
+    case 'unknown':
+      return {
+        severity: 'warning',
+        resourcePath: sourceFilePath,
+        line: link.line,
+        type: 'unknown_link',
+        link: link.href,
+        message: 'Unknown link type',
+      };
+
+    default: {
+      // TypeScript exhaustiveness check
+      const _exhaustive: never = link.type;
+      return _exhaustive;
+    }
+  }
+}
+
+/**
+ * Validate a local file link (with optional anchor).
+ */
+async function validateLocalFileLink(
+  link: ResourceLink,
+  sourceFilePath: string,
+  headingsByFile: Map<string, HeadingNode[]>
+): Promise<ValidationIssue | null> {
+  // Extract file path and anchor from href
+  const [filePath, anchor] = splitHrefAnchor(link.href);
+
+  // Validate the file exists
+  const fileResult = await validateLocalFile(filePath, sourceFilePath);
+
+  if (!fileResult.exists) {
+    return {
+      severity: 'error',
+      resourcePath: sourceFilePath,
+      line: link.line,
+      type: 'broken_file',
+      link: link.href,
+      message: `File not found: ${fileResult.resolvedPath}`,
+      suggestion: 'Check that the file path is correct and the file exists',
+    };
+  }
+
+  // Check if the file is gitignored
+  if (fileResult.isGitignored) {
+    return {
+      severity: 'error',
+      resourcePath: sourceFilePath,
+      line: link.line,
+      type: 'broken_file',
+      link: link.href,
+      message: `File is gitignored: ${fileResult.resolvedPath}`,
+      suggestion:
+        'Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.',
+    };
+  }
+
+  // If there's an anchor, validate it too
+  if (anchor) {
+    const anchorValid = await validateAnchor(
+      anchor,
+      fileResult.resolvedPath,
+      headingsByFile
+    );
+
+    if (!anchorValid) {
+      return {
+        severity: 'error',
+        resourcePath: sourceFilePath,
+        line: link.line,
+        type: 'broken_anchor',
+        link: link.href,
+        message: `Anchor not found: #${anchor} in ${fileResult.resolvedPath}`,
+        suggestion: 'Check that the heading exists in the target file',
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate an anchor link (within current file).
+ */
+async function validateAnchorLink(
+  link: ResourceLink,
+  sourceFilePath: string,
+  headingsByFile: Map<string, HeadingNode[]>
+): Promise<ValidationIssue | null> {
+  // Extract anchor (strip leading #)
+  const anchor = link.href.startsWith('#') ? link.href.slice(1) : link.href;
+
+  // Validate anchor exists in current file
+  const isValid = await validateAnchor(anchor, sourceFilePath, headingsByFile);
+
+  if (!isValid) {
+    return {
+      severity: 'error',
+      resourcePath: sourceFilePath,
+      line: link.line,
+      type: 'broken_anchor',
+      link: link.href,
+      message: `Anchor not found: ${link.href}`,
+      suggestion: 'Check that the heading exists in this file',
+    };
+  }
+
+  return null;
+}
+
+
+/**
+ * Validate that a local file exists and is not gitignored.
+ *
+ * @param href - The href to the file (relative or absolute)
+ * @param sourceFilePath - Absolute path to the source file
+ * @returns Object with exists flag, resolved absolute path, and gitignored flag
+ *
+ * @example
+ * ```typescript
+ * const result = await validateLocalFile('./docs/guide.md', '/project/README.md');
+ * if (result.exists && !result.isGitignored) {
+ *   console.log('File exists at:', result.resolvedPath);
+ * }
+ * ```
+ */
+async function validateLocalFile(
+  href: string,
+  sourceFilePath: string
+): Promise<{ exists: boolean; resolvedPath: string; isGitignored: boolean }> {
+  // Resolve the path relative to the source file's directory
+  const sourceDir = path.dirname(sourceFilePath);
+  const resolvedPath = path.resolve(sourceDir, href);
+
+  // Check if file exists
+  let exists = false;
+  try {
+    await fs.access(resolvedPath, fs.constants.F_OK);
+    exists = true;
+  } catch {
+    exists = false;
+  }
+
+  // Check if file is gitignored (only if it exists)
+  const gitignored = exists && isGitignored(resolvedPath);
+
+  return { exists, resolvedPath, isGitignored: gitignored };
+}
+
+/**
+ * Validate that an anchor (heading slug) exists in a file.
+ *
+ * @param anchor - The heading slug to find (without leading #)
+ * @param targetFilePath - Absolute path to the file containing the heading
+ * @param headingsByFile - Map of file paths to their heading trees
+ * @returns True if anchor exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const valid = await validateAnchor('my-heading', '/project/docs/guide.md', headingsMap);
+ * ```
+ */
+async function validateAnchor(
+  anchor: string,
+  targetFilePath: string,
+  headingsByFile: Map<string, HeadingNode[]>
+): Promise<boolean> {
+  // Get headings for target file
+  const headings = headingsByFile.get(targetFilePath);
+  if (!headings) {
+    return false;
+  }
+
+  // Search for matching slug (case-insensitive)
+  return findHeadingBySlug(headings, anchor);
+}
+
+/**
+ * Recursively search heading tree for a matching slug.
+ *
+ * Performs case-insensitive comparison of slugs.
+ *
+ * @param headings - Array of heading nodes to search
+ * @param targetSlug - The slug to find
+ * @returns True if slug found, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const found = findHeadingBySlug(headings, 'my-heading');
+ * ```
+ */
+function findHeadingBySlug(
+  headings: HeadingNode[],
+  targetSlug: string
+): boolean {
+  const normalizedTarget = targetSlug.toLowerCase();
+
+  for (const heading of headings) {
+    // Check current heading
+    if (heading.slug.toLowerCase() === normalizedTarget) {
+      return true;
+    }
+
+    // Recursively check children
+    if (heading.children && findHeadingBySlug(heading.children, targetSlug)) {
+      return true;
+    }
+  }
+
+  return false;
+}