@vibe-agent-toolkit/resources 0.1.39-rc.1 → 0.1.39-rc.2

package/src/html-transform.ts

@@ -0,0 +1,157 @@
+/**
+ * Structure-preserving HTML link rewriter.
+ *
+ * Rewrites `<a href>` and `<img src>` attribute VALUES in place by splicing the
+ * original source string at parse5-reported offsets. The document is never
+ * re-serialized (parse5's serializer normalizes whitespace, quotes, void
+ * elements, and the doctype), so unchanged input round-trips byte-for-byte.
+ *
+ * Uses the same `RewriteHref` callback model as `rewriteBodyLinks` — callers
+ * supply per-href target resolution; this module owns only the splice mechanics.
+ *
+ * Non-goal: `<base href>` is not honored. Relative hrefs are resolved by the
+ * caller against the file's own directory; a `<base>` element that would
+ * override that in a browser is ignored.
+ */
+
+import { parseHtmlDocument, walkElements } from './html-link-parser.js';
+import type { RewriteHref } from './rewriter-helpers.js';
+
+/** Tag name → the single link-bearing attribute we rewrite. */
+const LINK_ATTR_BY_TAG: Record<string, string | undefined> = { a: 'href', img: 'src' };
+
+interface ValueSpan {
+  valueStart: number;
+  valueEnd: number;
+  /** `"` or `'` for quoted attributes; `''` for unquoted. */
+  quote: string;
+}
+
+interface Edit extends ValueSpan {
+  newValue: string;
+}
+
+/**
+ * Chars that force an unquoted HTML attribute value to be quoted. Follows the
+ * WHATWG unquoted-attribute-value rules: whitespace, quotes, `<`, `>`, plus
+ * backtick and `=` (a superset of paths we expect, kept strict for safety).
+ */
+const UNQUOTED_UNSAFE = /[\s"'`<>=]/;
+
+/**
+ * Locate the value sub-range within an attribute's full source span.
+ *
+ * parse5 reports the whole-attribute span (`href="value"`); this finds the
+ * value's absolute offsets and the quote char. Returns undefined for boolean
+ * attributes (no `=`).
+ */
+function valueSpan(attrSource: string, base: number): ValueSpan | undefined {
+  const eq = attrSource.indexOf('=');
+  if (eq === -1) {
+    return undefined;
+  }
+  let i = eq + 1;
+  while (i < attrSource.length && /\s/.test(attrSource.charAt(i))) {
+    i += 1;
+  }
+  if (i >= attrSource.length) {
+    return undefined;
+  }
+  const ch = attrSource.charAt(i);
+  if (ch === '"' || ch === "'") {
+    const close = attrSource.indexOf(ch, i + 1);
+    const end = close === -1 ? attrSource.length : close;
+    return { valueStart: base + i + 1, valueEnd: base + end, quote: ch };
+  }
+  return { valueStart: base + i, valueEnd: base + attrSource.length, quote: '' };
+}
+
+/**
+ * Encode a new value for writing. For quoted attributes the surrounding quotes
+ * stay in the source (we only replace the inner value), so we escape `&` and the
+ * active quote. For originally-unquoted values we keep them bare when safe, else
+ * wrap in double quotes.
+ */
+function encodeValue(newValue: string, quote: string): string {
+  if (quote === '"' || quote === "'") {
+    const amp = newValue.replaceAll('&', '&amp;');
+    return quote === '"' ? amp.replaceAll('"', '&quot;') : amp.replaceAll("'", '&#39;');
+  }
+  if (newValue.length > 0 && !UNQUOTED_UNSAFE.test(newValue)) {
+    return newValue.replaceAll('&', '&amp;');
+  }
+  const escaped = newValue.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+  return `"${escaped}"`;
+}
+
+/** A wanted link rewrite that could not be spliced back into the source. */
+export interface UnappliedRewrite {
+  tagName: string;
+  attr: string;
+  /** The original attribute value the rewrite targeted. */
+  from: string;
+  /** The value the rewrite wanted to write. */
+  to: string;
+  /**
+   * Why the splice could not be located:
+   * - `no-source-location` — parse5 omitted the attribute's offsets (synthesized
+   *   during error recovery on malformed input).
+   * - `unparseable-attribute` — the attribute's source span had no locatable
+   *   value (e.g. an unterminated quote).
+   */
+  reason: 'no-source-location' | 'unparseable-attribute';
+}
+
+/**
+ * Rewrite `<a href>` / `<img src>` values in `source` using `rewriteHref`.
+ * Returns `source` unchanged (byte-for-byte) when no value changes.
+ *
+ * A rewrite that is wanted (the href resolves to a new value) but cannot be
+ * spliced back — because parse5 omitted the source location or the attribute
+ * span is unparseable — is reported via `onUnapplied` rather than dropped
+ * silently. Malformed pages are exactly the ones that hit this path, so the
+ * caller can surface it instead of shipping a stale link.
+ */
+export function rewriteHtmlLinks(
+  source: string,
+  rewriteHref: RewriteHref,
+  onUnapplied?: (info: UnappliedRewrite) => void,
+): string {
+  const { document } = parseHtmlDocument(source);
+  const edits: Edit[] = [];
+
+  for (const element of walkElements(document)) {
+    const attrName = LINK_ATTR_BY_TAG[element.tagName];
+    if (attrName === undefined) {
+      continue;
+    }
+    const attr = element.attrs.find((a) => a.name === attrName);
+    if (attr === undefined) {
+      continue;
+    }
+    // Resolve first so we only record drops that actually lose a wanted edit.
+    const newValue = rewriteHref(attr.value);
+    if (newValue === attr.value) {
+      continue;
+    }
+    const location = element.sourceCodeLocation?.attrs?.[attrName];
+    if (location === undefined) {
+      onUnapplied?.({ tagName: element.tagName, attr: attrName, from: attr.value, to: newValue, reason: 'no-source-location' });
+      continue;
+    }
+    const span = valueSpan(source.slice(location.startOffset, location.endOffset), location.startOffset);
+    if (span === undefined) {
+      onUnapplied?.({ tagName: element.tagName, attr: attrName, from: attr.value, to: newValue, reason: 'unparseable-attribute' });
+      continue;
+    }
+    edits.push({ ...span, newValue });
+  }
+
+  // Apply descending by start offset so earlier edits don't shift later ones.
+  edits.sort((a, b) => b.valueStart - a.valueStart);
+  let result = source;
+  for (const edit of edits) {
+    result = result.slice(0, edit.valueStart) + encodeValue(edit.newValue, edit.quote) + result.slice(edit.valueEnd);
+  }
+  return result;
+}

package/src/index.ts

@@ -83,7 +83,12 @@ export {
 } from './schemas/validation-result.js';
 
 // Export parser interface for advanced use cases
-export { parseMarkdown, type ParseResult } from './link-parser.js';
+export { parseMarkdown, classifyLink, isLocalFileLink, type ParseResult } from './link-parser.js';
+
+export { parseHtml } from './html-link-parser.js';
+// HtmlParseError is Zod-sourced (single source of truth) — see schemas/resource-metadata.ts.
+export type { HtmlParseError } from './schemas/resource-metadata.js';
+export { rewriteHtmlLinks, type UnappliedRewrite } from './html-transform.js';
 
 // Export frontmatter validation
 export { validateFrontmatter } from './frontmatter-validator.js';

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.
  *

package/src/link-validator.ts

@@ -25,7 +25,7 @@ import {
   verifyCaseSensitiveFilename,
 } from '@vibe-agent-toolkit/utils';
 
-import type { HeadingNode, ResourceLink } from './types.js';
+import type { ResourceLink } from './types.js';
 import { isWithinProject, issueLocation, resolveLocalHref } from './utils.js';
 
 type LinkIssueExtras = Partial<Pick<ValidationIssue, 'location' | 'line' | 'link' | 'suggestion'>>;
@@ -66,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
  *
@@ -84,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, options?.projectRoot);
+      return await validateAnchorLink(link, sourceFilePath, fragmentsByFile, options?.projectRoot);
 
     case 'external':
       // External URLs are not validated - don't report them
@@ -232,7 +233,7 @@ 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);
@@ -246,25 +247,12 @@ async function validateLocalFileLink(
   const notFound = fileExistenceIssue(fileResult, link, sourceFilePath, options?.projectRoot);
   if (notFound) return notFound;
 
-  if (fileResult.isDirectory) {
-    return createRegistryIssue(
-      'LINK_BROKEN_FILE',
-      `Link target is a directory: ${fileResult.resolvedPath}`,
-      linkExtras(
-        link,
-        sourceFilePath,
-        options?.projectRoot,
-        '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) {
+    const check = checkAnchor(resolved.anchor, fileResult.resolvedPath, fragmentsByFile);
+    if (check === 'broken') {
       return createRegistryIssue(
         'LINK_BROKEN_ANCHOR',
         `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
@@ -276,30 +264,42 @@ async function validateLocalFileLink(
   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);
+  const check = checkAnchor(anchor, sourceFilePath, fragmentsByFile);
 
-  if (!isValid) {
-    return createRegistryIssue(
-      'LINK_BROKEN_ANCHOR',
-      `Anchor not found: ${link.href}`,
-      linkExtras(link, sourceFilePath, projectRoot, ''),
-    );
+  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);
   }
-
-  return null;
 }
 
 
@@ -338,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>;
+}
+
+/** File path → its fragment targets and matching policy. */
+export type FragmentIndex = Map<string, FragmentIndexEntry>;
 
-  // Search for matching slug (case-insensitive)
-  return findHeadingBySlug(headings, anchor);
+/**
+ * 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';
 }