@vibe-agent-toolkit/resources 0.1.38 → 0.1.39-rc.10

package/src/link-parser.ts

@@ -1,5 +1,5 @@
 /**
- * Markdown link parser and analyzer.
+ * Markdown link parser and shared resource-parsing types.
  *
  * Parses markdown files to extract:
  * - Links (regular, reference-style, autolinks)
@@ -7,6 +7,10 @@
  * - File size and token estimates
  *
  * Uses unified/remark for robust markdown parsing with GFM support.
+ *
+ * Also defines the format-neutral `ParseResult` contract shared with the HTML
+ * parser (`html-link-parser.ts`). The `HtmlParseError` shape is Zod-sourced
+ * from `schemas/resource-metadata.ts` (single source of truth).
  */
 
 import { readFile, stat } from 'node:fs/promises';
@@ -20,10 +24,11 @@ import { unified } from 'unified';
 import { visit } from 'unist-util-visit';
 import * as yaml from 'yaml';
 
+import type { HtmlParseError } from './schemas/resource-metadata.js';
 import type { HeadingNode, LinkType, ResourceLink } from './types.js';
 
 /**
- * Result of parsing a markdown file.
+ * Result of parsing a resource file (markdown or HTML).
  */
 export interface ParseResult {
   links: ResourceLink[];
@@ -33,6 +38,10 @@ export interface ParseResult {
   content: string;
   sizeBytes: number;
   estimatedTokenCount: number;
+  /** Fragment targets (HTML `id`/`name` attributes). Markdown leaves this undefined. */
+  anchors?: string[];
+  /** HTML well-formedness diagnostics. Markdown leaves this undefined. */
+  parseErrors?: HtmlParseError[];
 }
 
 /**
@@ -185,6 +194,11 @@ function extractLinkText(node: Link | LinkReference): string {
  * classifyLink('#heading') // 'anchor'
  * classifyLink('./file.md') // 'local_file'
  * classifyLink('./file.md#anchor') // 'local_file'
+ * classifyLink('docs/') // 'local_directory'
+ * classifyLink('./docs/') // 'local_directory'
+ * classifyLink('../docs/') // 'local_directory'
+ * classifyLink('/docs/') // 'local_directory'
+ * classifyLink('https://x.com/docs/') // 'external' (not a local ref)
  * ```
  */
 export function classifyLink(href: string): LinkType {
@@ -202,6 +216,12 @@ export function classifyLink(href: string): LinkType {
   if (href.includes(':')) {
     return 'unknown';
   }
+  // Local directory: path component (before any # or ?) ends in '/'.
+  // Must come after all protocol guards so external URLs are never reclassified.
+  const pathPart = href.split(/[#?]/u)[0] ?? href;
+  if (pathPart.endsWith('/')) {
+    return 'local_directory';
+  }
   // Links with anchors are still local file links
   if (href.includes('#')) {
     return 'local_file';
@@ -242,6 +262,19 @@ export function classifyLink(href: string): LinkType {
   return 'unknown';
 }
 
+/**
+ * Returns true for link types that represent local filesystem targets — both
+ * regular files and directories. Other packages (e.g. agent-skills walker)
+ * import this predicate as the single source of truth for "should we treat
+ * this link like a file link during validation/traversal?"
+ *
+ * @param type - The classified link type
+ * @returns `true` for `'local_file'` and `'local_directory'`
+ */
+export function isLocalFileLink(type: LinkType): boolean {
+  return type === 'local_file' || type === 'local_directory';
+}
+
 /**
  * Extract headings from the markdown AST and build a nested tree structure.
  *
@@ -310,29 +343,45 @@ function extractHeadingText(node: Heading): string {
   return extractTextFromChildren(node.children);
 }
 
+/**
+ * Inline node shape for heading text extraction. Leaf inline nodes (`text`,
+ * `inlineCode`) carry their content in `value`; container inline nodes
+ * (`strong`, `emphasis`, `link`, `delete`) carry it in `children`.
+ */
+interface InlineNode {
+  type: string;
+  value?: unknown;
+  children?: InlineNode[];
+}
+
 /**
  * Extract text content from inline children nodes.
  *
- * Handles text nodes, inline code, emphasis, and other inline elements.
+ * Handles leaf nodes (`text`, `inlineCode`) and recurses into container inline
+ * elements (`strong`, `emphasis`, `link`, `delete`) so that styled headings —
+ * e.g. `### **CRITICAL: ...**` — produce the same text (and therefore the same
+ * GitHub slug) as their plain-text equivalents. Without recursion, bold/italic
+ * headings yielded empty text and bogus slugs, causing false LINK_BROKEN_ANCHOR
+ * errors for links targeting them.
  *
  * @param children - Array of child nodes or undefined
  * @returns Concatenated text content
  */
-function extractTextFromChildren(
-  children: Array<{ type: string; value?: unknown }> | undefined
-): string {
+function extractTextFromChildren(children: InlineNode[] | undefined): string {
   if (!children || children.length === 0) {
     return '';
   }
 
   return children
     .map((child) => {
-      if (child.type === 'text') {
-        return child.value as string;
+      // Leaf inline nodes (text, inlineCode) hold their content in `value`.
+      if (typeof child.value === 'string') {
+        return child.value;
       }
-      // Handle other inline elements (code, emphasis, etc.)
-      if ('value' in child) {
-        return String(child.value);
+      // Container inline nodes (strong, emphasis, link, delete) hold text in
+      // their children — recurse to gather it.
+      if (child.children) {
+        return extractTextFromChildren(child.children);
       }
       return '';
     })

package/src/link-validator.ts

@@ -18,15 +18,36 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { createRegistryIssue, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import {
   isGitIgnored,
   type GitTracker,
   verifyCaseSensitiveFilename,
 } from '@vibe-agent-toolkit/utils';
 
-import type { ValidationIssue } from './schemas/validation-result.js';
-import type { HeadingNode, ResourceLink } from './types.js';
-import { isWithinProject, resolveLocalHref } from './utils.js';
+import type { ResourceLink } from './types.js';
+import { isWithinProject, issueLocation, resolveLocalHref } from './utils.js';
+
+type LinkIssueExtras = Partial<Pick<ValidationIssue, 'location' | 'line' | 'link' | 'suggestion'>>;
+
+/**
+ * Build the common `createRegistryIssue` extras for a link issue: relative
+ * location, the problematic href, the line (only when defined — required for
+ * exactOptionalPropertyTypes), and an optional suggestion.
+ */
+function linkExtras(
+  link: ResourceLink,
+  sourceFilePath: string,
+  projectRoot: string | undefined,
+  suggestion?: string,
+): LinkIssueExtras {
+  return {
+    location: issueLocation(sourceFilePath, projectRoot),
+    link: link.href,
+    ...(link.line !== undefined && { line: link.line }),
+    ...(suggestion !== undefined && { suggestion }),
+  };
+}
 
 /**
  * Options for link validation.
@@ -45,7 +66,7 @@ export interface ValidateLinkOptions {
  *
  * @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
+ * @param fragmentsByFile - Fragment index: file path → set of valid fragments (markdown slugs + HTML id/name)
  * @param options - Validation options (projectRoot, skipGitIgnoreCheck)
  * @returns ValidationIssue if link is broken, null if valid
  *
@@ -63,15 +84,16 @@ export interface ValidateLinkOptions {
 export async function validateLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
   switch (link.type) {
     case 'local_file':
-      return await validateLocalFileLink(link, sourceFilePath, headingsByFile, options);
+    case 'local_directory':
+      return await validateLocalFileLink(link, sourceFilePath, fragmentsByFile, options);
 
     case 'anchor':
-      return await validateAnchorLink(link, sourceFilePath, headingsByFile);
+      return await validateAnchorLink(link, sourceFilePath, fragmentsByFile, options?.projectRoot);
 
     case 'external':
       // External URLs are not validated - don't report them
@@ -82,13 +104,11 @@ export async function validateLink(
       return null;
 
     case 'unknown':
-      return {
-        resourcePath: sourceFilePath,
-        line: link.line,
-        type: 'unknown_link',
-        link: link.href,
-        message: 'Unknown link type',
-      };
+      return createRegistryIssue(
+        'LINK_UNKNOWN',
+        'Unknown link type',
+        linkExtras(link, sourceFilePath, options?.projectRoot),
+      );
 
     default: {
       // TypeScript exhaustiveness check
@@ -107,31 +127,29 @@ export function resolutionFailureIssue(
   resolved: ReturnType<typeof resolveLocalHref>,
   link: ResourceLink,
   sourceFilePath: string,
+  projectRoot?: string,
 ): ValidationIssue | null {
   if (resolved.kind === 'absolute_no_root') {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message:
-        `Absolute-path link "${link.href}" requires a configured projectRoot; ` +
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `Absolute-path link "${link.href}" requires a configured projectRoot; ` +
         `none was provided. Configure vibe-agent-toolkit.config.yaml or run ` +
         `from within a git repository.`,
-      suggestion:
+      linkExtras(
+        link,
+        sourceFilePath,
+        projectRoot,
         'Rewrite as a source-relative link, or run from a directory with a config or git ancestor.',
-    };
+      ),
+    );
   }
 
   if (resolved.kind === 'absolute_escapes_root') {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `Absolute-path link "${link.href}" escapes the project root via path traversal.`,
-      suggestion: '',
-    };
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `Absolute-path link "${link.href}" escapes the project root via path traversal.`,
+      linkExtras(link, sourceFilePath, projectRoot, ''),
+    );
   }
 
   return null;
@@ -145,29 +163,29 @@ export function fileExistenceIssue(
   fileResult: { exists: boolean; resolvedPath: string; actualName?: string },
   link: ResourceLink,
   sourceFilePath: string,
+  projectRoot?: string,
 ): ValidationIssue | null {
   if (fileResult.exists) return null;
 
   if (fileResult.actualName) {
     const expectedName = path.basename(fileResult.resolvedPath);
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `File found but case mismatch: expected "${expectedName}" but found "${fileResult.actualName}". This will fail on case-sensitive filesystems (Linux). Update the link to match the actual filename.`,
-      suggestion: `Use "${fileResult.actualName}" instead of "${expectedName}"`,
-    };
+    return createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `File found but case mismatch: expected "${expectedName}" but found "${fileResult.actualName}". This will fail on case-sensitive filesystems (Linux). Update the link to match the actual filename.`,
+      linkExtras(
+        link,
+        sourceFilePath,
+        projectRoot,
+        `Use "${fileResult.actualName}" instead of "${expectedName}"`,
+      ),
+    );
   }
 
-  return {
-    resourcePath: sourceFilePath,
-    line: link.line,
-    type: 'broken_file',
-    link: link.href,
-    message: `File not found: ${fileResult.resolvedPath}`,
-    suggestion: '',
-  };
+  return createRegistryIssue(
+    'LINK_BROKEN_FILE',
+    `File not found: ${fileResult.resolvedPath}`,
+    linkExtras(link, sourceFilePath, projectRoot, ''),
+  );
 }
 
 /**
@@ -202,14 +220,11 @@ export function gitIgnoreSafetyIssue(
 
   if (sourceIsIgnored || !targetIsIgnored) return null;
 
-  return {
-    resourcePath: sourceFilePath,
-    line: link.line,
-    type: 'link_to_gitignored',
-    link: link.href,
-    message: `Non-ignored file links to gitignored file: ${resolvedTarget}. Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.`,
-    suggestion: '',
-  };
+  return createRegistryIssue(
+    'LINK_TO_GITIGNORED',
+    `Non-ignored file links to gitignored file: ${resolvedTarget}. Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.`,
+    linkExtras(link, sourceFilePath, options.projectRoot, ''),
+  );
 }
 
 /**
@@ -218,78 +233,73 @@ export function gitIgnoreSafetyIssue(
 async function validateLocalFileLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
   const resolved = resolveLocalHref(link.href, sourceFilePath, options?.projectRoot);
 
   if (resolved.kind !== 'resolved') {
     // anchor_only → null no-op; absolute_no_root / absolute_escapes_root → broken_file.
-    return resolutionFailureIssue(resolved, link, sourceFilePath);
+    return resolutionFailureIssue(resolved, link, sourceFilePath, options?.projectRoot);
   }
 
   const fileResult = await validateResolvedFile(resolved.resolvedPath);
-  const notFound = fileExistenceIssue(fileResult, link, sourceFilePath);
+  const notFound = fileExistenceIssue(fileResult, link, sourceFilePath, options?.projectRoot);
   if (notFound) return notFound;
 
-  if (fileResult.isDirectory) {
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `Link target is a directory: ${fileResult.resolvedPath}`,
-      suggestion:
-        'Link to a file inside the directory (e.g., README.md or index.md), or fix the link to point at the intended file.',
-    };
-  }
-
   const gitIgnoreIssue = gitIgnoreSafetyIssue(link, sourceFilePath, fileResult.resolvedPath, options);
   if (gitIgnoreIssue) return gitIgnoreIssue;
 
   if (resolved.anchor) {
-    const anchorValid = await validateAnchor(resolved.anchor, fileResult.resolvedPath, headingsByFile);
-    if (!anchorValid) {
-      return {
-        resourcePath: sourceFilePath,
-        line: link.line,
-        type: 'broken_anchor',
-        link: link.href,
-        message: `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
-        suggestion: '',
-      };
+    const check = checkAnchor(resolved.anchor, fileResult.resolvedPath, fragmentsByFile);
+    if (check === 'broken') {
+      return createRegistryIssue(
+        'LINK_BROKEN_ANCHOR',
+        `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
+        linkExtras(link, sourceFilePath, options?.projectRoot, ''),
+      );
     }
   }
 
   return null;
 }
 
+/**
+ * Exhaustiveness guard for the {@link AnchorCheck} union: a compile error at the
+ * call site means a new variant was added without being handled here.
+ */
+function assertNever(value: never): never {
+  throw new Error(`Unhandled AnchorCheck variant: ${String(value)}`);
+}
+
 /**
  * Validate an anchor link (within current file).
  */
 async function validateAnchorLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>
+  fragmentsByFile: FragmentIndex,
+  projectRoot?: string,
 ): 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 {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_anchor',
-      link: link.href,
-      message: `Anchor not found: ${link.href}`,
-      suggestion: '',
-    };
-  }
+  const check = checkAnchor(anchor, sourceFilePath, fragmentsByFile);
 
-  return null;
+  switch (check) {
+    case 'skip':
+    case 'valid':
+      return null;
+    case 'broken':
+      return createRegistryIssue(
+        'LINK_BROKEN_ANCHOR',
+        `Anchor not found: ${link.href}`,
+        linkExtras(link, sourceFilePath, projectRoot, ''),
+      );
+    default:
+      return assertNever(check);
+  }
 }
 
 
@@ -328,65 +338,85 @@ async function validateResolvedFile(
   return result;
 }
 
+/** Result of checking an anchor against the fragment index. */
+export type AnchorCheck = 'skip' | 'valid' | 'broken';
+
 /**
- * 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);
- * ```
+ * A file's fragment targets plus how to match against them. HTML `id`/`name`
+ * anchors are matched case-sensitively; markdown heading slugs are case-folded.
+ * The policy lives on the entry rather than being re-derived from the file
+ * extension at match time, so a new resource format only has to set this flag.
  */
-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;
-  }
+export interface FragmentIndexEntry {
+  /** `true` for case-sensitive matching (HTML ids), `false` for case-folded (markdown slugs). */
+  caseSensitive: boolean;
+  fragments: Set<string>;
+}
 
-  // Search for matching slug (case-insensitive)
-  return findHeadingBySlug(headings, anchor);
+/** File path → its fragment targets and matching policy. */
+export type FragmentIndex = Map<string, FragmentIndexEntry>;
+
+/**
+ * Whether a path is an HTML resource (`.html`/`.htm`). The single place the
+ * extension drives format-specific behavior: case-sensitive ids (via
+ * {@link fragmentIndexEntry}) and the HTML top-fragment navigation rule.
+ */
+export function isHtmlPath(filePath: string): boolean {
+  return /\.html?$/i.test(filePath);
+}
+
+/** Build one index entry, choosing the case-folding policy from the file type. */
+export function fragmentIndexEntry(filePath: string, fragments: Set<string> = new Set()): FragmentIndexEntry {
+  return { caseSensitive: isHtmlPath(filePath), fragments };
 }
 
 /**
- * Recursively search heading tree for a matching slug.
- *
- * Performs case-insensitive comparison of slugs.
+ * Build a {@link FragmentIndex} from `[path, fragments]` pairs, deriving each
+ * entry's matching policy from its path. Single construction path shared by the
+ * registry and tests.
+ */
+export function fragmentIndex(entries: Iterable<readonly [string, Set<string>]> = []): FragmentIndex {
+  const map: FragmentIndex = new Map();
+  for (const [filePath, fragments] of entries) {
+    map.set(filePath, fragmentIndexEntry(filePath, fragments));
+  }
+  return map;
+}
+
+/**
+ * Check whether a fragment exists in the target file's anchor set.
  *
- * @param headings - Array of heading nodes to search
- * @param targetSlug - The slug to find
- * @returns True if slug found, false otherwise
+ * - `'skip'`  — target file is not indexed; we cannot prove the anchor is
+ *   broken, so callers must not emit an issue.
+ * - Matching follows the entry's `caseSensitive` policy (HTML ids exact,
+ *   markdown slugs case-folded). The index carries the policy, so this never
+ *   re-derives the folding rule from the file extension.
+ * - For HTML targets the empty fragment (`#`) and `top` (ASCII
+ *   case-insensitive) are always valid: per the HTML fragment-navigation
+ *   algorithm both scroll to the top of the document regardless of whether a
+ *   matching element exists, so `href="#"` / `href="#top"` are not broken.
  *
- * @example
- * ```typescript
- * const found = findHeadingBySlug(headings, 'my-heading');
- * ```
+ * @param anchor - Fragment without the leading `#`.
+ * @param targetFilePath - Absolute path of the file the fragment lives in.
+ * @param fragmentsByFile - Fragment index carrying each file's matching policy.
  */
-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;
-    }
+export function checkAnchor(
+  anchor: string,
+  targetFilePath: string,
+  fragmentsByFile: FragmentIndex,
+): AnchorCheck {
+  const entry = fragmentsByFile.get(targetFilePath);
+  if (!entry) {
+    return 'skip';
   }
-
-  return false;
+  // HTML spec: the empty fragment and "top" (case-insensitive) always navigate
+  // to the top of the document — valid even with no matching id. This is an
+  // HTML-format navigation rule, distinct from the case-folding policy above.
+  if (isHtmlPath(targetFilePath) && (anchor === '' || anchor.toLowerCase() === 'top')) {
+    return 'valid';
+  }
+  const found = entry.caseSensitive
+    ? entry.fragments.has(anchor)
+    : entry.fragments.has(anchor.toLowerCase());
+  return found ? 'valid' : 'broken';
 }

package/src/multi-schema-validator.ts

@@ -12,12 +12,14 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
+import { createRegistryIssue } from '@vibe-agent-toolkit/agent-schema';
 import { safePath } from '@vibe-agent-toolkit/utils';
 
 import { validateFrontmatter } from './frontmatter-validator.js';
 import type { ValidationMode } from './schemas/project-config.js';
 import type { ValidationIssue } from './schemas/validation-result.js';
 import type { SchemaReference } from './types/resources.js';
+import { issueLocation } from './utils.js';
 
 /**
  * Load a JSON Schema from a file path
@@ -67,7 +69,7 @@ export async function validateFrontmatterMultiSchema(
       const schema = await loadSchema(schemaRef.schema, projectRoot);
 
       // Validate frontmatter
-      const issues = validateFrontmatter(frontmatter, schema, resourcePath, mode);
+      const issues = validateFrontmatter(frontmatter, schema, resourcePath, mode, undefined, projectRoot);
 
       // Update schema reference with results
       const result: SchemaReference = {
@@ -89,13 +91,13 @@ export async function validateFrontmatterMultiSchema(
         ...schemaRef,
         applied: true,
         valid: false,
-        errors: [{
-          resourcePath,
-          line: 1,
-          type: 'frontmatter_schema_error',
-          link: '',
-          message: `Failed to load or validate schema ${schemaRef.schema}: ${message}`,
-        }],
+        errors: [
+          createRegistryIssue(
+            'FRONTMATTER_SCHEMA_ERROR',
+            `Failed to load or validate schema ${schemaRef.schema}: ${message}`,
+            { location: issueLocation(resourcePath, projectRoot), line: 1 },
+          ),
+        ],
       });
     }
   }