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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/resources",
-  "version": "0.1.38",
+  "version": "0.1.39-rc.2",
   "description": "Markdown resource parsing, validation, and link integrity checking",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,12 +33,13 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.38",
-    "@vibe-agent-toolkit/utils": "0.1.38",
+    "@vibe-agent-toolkit/agent-schema": "0.1.39-rc.2",
+    "@vibe-agent-toolkit/utils": "0.1.39-rc.2",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "github-slugger": "^2.0.0",
     "markdown-link-check": "^3.14.2",
+    "parse5": "^7.2.1",
     "picomatch": "^4.0.3",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",

package/src/frontmatter-link-validator.ts

@@ -7,21 +7,31 @@
  * frontmatter-specific type codes plus a list of external URLs the registry
  * can fold into its existing external URL collection.
  *
- * Type mapping:
- *   broken_file        -> frontmatter_link_broken
- *   broken_anchor      -> frontmatter_anchor_missing
- *   link_to_gitignored -> frontmatter_link_to_gitignored
- *   unknown_link       -> frontmatter_unknown_link
+ * Code mapping:
+ *   LINK_BROKEN_FILE    -> FRONTMATTER_LINK_BROKEN
+ *   LINK_BROKEN_ANCHOR  -> FRONTMATTER_ANCHOR_MISSING
+ *   LINK_TO_GITIGNORED  -> FRONTMATTER_LINK_TO_GITIGNORED
+ *   LINK_UNKNOWN        -> FRONTMATTER_UNKNOWN_LINK
  *
  * Skipped (no issue, no external):
  *   email (mailto:)
  *   anchor-only (validated as anchor in current file via validateLink)
  */
 
+import { createRegistryIssue, type IssueCode } from '@vibe-agent-toolkit/agent-schema';
+
 import { classifyLink } from './link-parser.js';
-import { validateLink, type ValidateLinkOptions } from './link-validator.js';
+import { validateLink, type FragmentIndex, type ValidateLinkOptions } from './link-validator.js';
 import { walkFrontmatterUriReferences } from './schema-uri-walker.js';
-import type { HeadingNode, ResourceLink, ValidationIssue } from './types.js';
+import type { ResourceLink, ValidationIssue } from './types.js';
+
+/** Map the link-level code emitted by validateLink to its frontmatter-scoped code. */
+const LINK_CODE_TO_FRONTMATTER_CODE: Partial<Record<IssueCode, IssueCode>> = {
+  LINK_BROKEN_FILE: 'FRONTMATTER_LINK_BROKEN',
+  LINK_BROKEN_ANCHOR: 'FRONTMATTER_ANCHOR_MISSING',
+  LINK_TO_GITIGNORED: 'FRONTMATTER_LINK_TO_GITIGNORED',
+  LINK_UNKNOWN: 'FRONTMATTER_UNKNOWN_LINK',
+};
 
 /** A frontmatter-sourced external URL captured for downstream health checking. */
 export interface FrontmatterExternalUrl {
@@ -41,14 +51,14 @@ export interface FrontmatterLinkValidationResult {
  * @param frontmatter - Parsed frontmatter (or undefined)
  * @param schema - JSON Schema for the collection
  * @param sourceFilePath - Absolute path to the source file
- * @param headingsByFile - Heading trees (for anchor validation)
+ * @param fragmentsByFile - Fragment index (file path → set of valid fragments) for anchor validation
  * @param options - Same shape as validateLink (projectRoot, gitTracker, ...)
  */
 export async function validateFrontmatterLinks(
   frontmatter: Record<string, unknown> | undefined,
   schema: object,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   options?: ValidateLinkOptions,
 ): Promise<FrontmatterLinkValidationResult> {
   if (!frontmatter) return { issues: [], externalUrls: [] };
@@ -79,7 +89,7 @@ export async function validateFrontmatterLinks(
       line: 1, // Frontmatter per-field line numbers are post-v1.
     };
 
-    const issue = await validateLink(syntheticLink, sourceFilePath, headingsByFile, options);
+    const issue = await validateLink(syntheticLink, sourceFilePath, fragmentsByFile, options);
     if (!issue) continue;
 
     issues.push(rewriteIssue(issue, capture.dottedPath));
@@ -89,24 +99,12 @@ export async function validateFrontmatterLinks(
 }
 
 function rewriteIssue(issue: ValidationIssue, dottedPath: string): ValidationIssue {
-  return {
-    ...issue,
-    type: mapType(issue.type),
-    message: `field \`${dottedPath}\`: ${issue.message}`,
-  };
-}
-
-function mapType(originalType: string): string {
-  switch (originalType) {
-    case 'broken_file':
-      return 'frontmatter_link_broken';
-    case 'broken_anchor':
-      return 'frontmatter_anchor_missing';
-    case 'link_to_gitignored':
-      return 'frontmatter_link_to_gitignored';
-    case 'unknown_link':
-      return 'frontmatter_unknown_link';
-    default:
-      return originalType;
-  }
+  const mappedCode = LINK_CODE_TO_FRONTMATTER_CODE[issue.code as IssueCode] ?? (issue.code as IssueCode);
+  const message = `field \`${dottedPath}\`: ${issue.message}`;
+  const extras: Partial<Pick<ValidationIssue, 'location' | 'line' | 'link' | 'suggestion'>> = {};
+  if (issue.location !== undefined) extras.location = issue.location;
+  if (issue.line !== undefined) extras.line = issue.line;
+  if (issue.link !== undefined) extras.link = issue.link;
+  if (issue.suggestion !== undefined) extras.suggestion = issue.suggestion;
+  return createRegistryIssue(mappedCode, message, extras);
 }

package/src/frontmatter-validator.ts

@@ -13,9 +13,11 @@
  * This is the ONLY place in the codebase that should use AJV.
  */
 
+import { createRegistryIssue, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+
 import { createAjvWithUriFormats } from './ajv-factory.js';
 import type { ValidationMode } from './schemas/project-config.js';
-import type { ValidationIssue } from './schemas/validation-result.js';
+import { issueLocation } from './utils.js';
 
 /**
  * Validate frontmatter against a JSON Schema.
@@ -31,6 +33,7 @@ import type { ValidationIssue } from './schemas/validation-result.js';
  * @param resourcePath - File path for error reporting
  * @param mode - Validation mode: 'strict' (default) or 'permissive'
  * @param schemaPath - Path to schema file (for error context)
+ * @param projectRoot - Project root for computing relative issue locations
  * @returns Array of validation issues (empty if valid)
  *
  * @example
@@ -54,7 +57,8 @@ export function validateFrontmatter(
   schema: object,
   resourcePath: string,
   mode: ValidationMode = 'strict',
-  schemaPath?: string
+  schemaPath?: string,
+  projectRoot?: string,
 ): ValidationIssue[] {
   const issues: ValidationIssue[] = [];
 
@@ -87,13 +91,13 @@ export function validateFrontmatter(
       const schemaContext = schemaPath ? ` (schema: ${schemaPath}, mode: ${mode})` : '';
       const requiredFields = schemaRequires.join(', ');
 
-      issues.push({
-        resourcePath,
-        line: 1,
-        type: 'frontmatter_missing',
-        link: '',
-        message: `No frontmatter found in file. Schema requires: ${requiredFields}${schemaContext}`,
-      });
+      issues.push(
+        createRegistryIssue(
+          'FRONTMATTER_MISSING',
+          `No frontmatter found in file. Schema requires: ${requiredFields}${schemaContext}`,
+          { location: issueLocation(resourcePath, projectRoot), line: 1 },
+        ),
+      );
     }
     return issues;
   }
@@ -108,13 +112,12 @@ export function validateFrontmatter(
   // Format validation errors with helpful messages
   for (const error of validate.errors) {
     const message = formatValidationError(error, frontmatter, mode, schemaPath);
-    issues.push({
-      resourcePath,
-      line: 1,
-      type: 'frontmatter_schema_error',
-      link: '',
-      message,
-    });
+    issues.push(
+      createRegistryIssue('FRONTMATTER_SCHEMA_ERROR', message, {
+        location: issueLocation(resourcePath, projectRoot),
+        line: 1,
+      }),
+    );
   }
 
   return issues;

package/src/html-link-parser.ts

@@ -0,0 +1,140 @@
+/**
+ * HTML resource parser.
+ *
+ * Parses local HTML files into the shared `ParseResult` shape:
+ * - `<a href>` and `<img src>` links (classified by `classifyLink`)
+ * - `id` / `name` attributes as fragment anchors
+ * - well-formedness diagnostics from parse5's `onParseError`
+ *
+ * Uses parse5 (WHATWG-conformant). The parse5 document + element walker are
+ * exported so the link rewriter (html-transform.ts) shares one parser path.
+ *
+ * Non-goal: `<base href>` is not honored — relative links are resolved against
+ * the file's own directory, not a document base.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+
+import { parse, type DefaultTreeAdapterMap } from 'parse5';
+
+import { classifyLink, type ParseResult } from './link-parser.js';
+import type { HtmlParseError } from './schemas/resource-metadata.js';
+import type { ResourceLink } from './types.js';
+
+type P5Node = DefaultTreeAdapterMap['node'];
+type P5Element = DefaultTreeAdapterMap['element'];
+type P5ChildNode = DefaultTreeAdapterMap['childNode'];
+
+/** A parsed parse5 document together with any well-formedness diagnostics. */
+export interface HtmlDocument {
+  document: DefaultTreeAdapterMap['document'];
+  parseErrors: HtmlParseError[];
+}
+
+/**
+ * Parse an HTML source string with source-location info and collect parser
+ * errors. Shared by `parseHtml` (link/anchor extraction) and `rewriteHtmlLinks`
+ * (attribute offset splicing).
+ */
+export function parseHtmlDocument(source: string): HtmlDocument {
+  const parseErrors: HtmlParseError[] = [];
+  const document = parse(source, {
+    sourceCodeLocationInfo: true,
+    onParseError: (err) => {
+      // parse5's ParserError extends Location which always has startLine: number.
+      // We always include line since it is always present.
+      parseErrors.push({ message: err.code, line: err.startLine });
+    },
+  });
+  return { document, parseErrors };
+}
+
+/**
+ * Depth-first walk yielding every element node in the tree.
+ *
+ * Deliberate gap: a `<template>` element's content lives in its separate
+ * `content` fragment (not `childNodes`), so links inside `<template>` are not
+ * walked, and foreign-content (SVG/MathML) subtrees are not special-cased.
+ * Both are rare in the content link graph we rewrite.
+ */
+export function* walkElements(node: P5Node): Generator<P5Element> {
+  if ('tagName' in node) {
+    yield node;
+  }
+  if ('childNodes' in node) {
+    for (const child of node.childNodes as P5ChildNode[]) {
+      yield* walkElements(child);
+    }
+  }
+}
+
+function getAttr(element: P5Element, name: string): string | undefined {
+  return element.attrs.find((a) => a.name === name)?.value;
+}
+
+function makeLink(href: string, line: number | undefined): ResourceLink {
+  return { text: '', href, type: classifyLink(href), ...(line !== undefined && { line }) };
+}
+
+function visitElement(
+  element: P5Element,
+  links: ResourceLink[],
+  anchors: Set<string>,
+): void {
+  const line = element.sourceCodeLocation?.startLine;
+
+  if (element.tagName === 'a') {
+    const href = getAttr(element, 'href');
+    if (href !== undefined) {
+      links.push(makeLink(href, line));
+    }
+    const name = getAttr(element, 'name');
+    if (name !== undefined && name !== '') {
+      anchors.add(name);
+    }
+  } else if (element.tagName === 'img') {
+    const src = getAttr(element, 'src');
+    if (src !== undefined) {
+      links.push(makeLink(src, line));
+    }
+  }
+
+  const id = getAttr(element, 'id');
+  if (id !== undefined && id !== '') {
+    anchors.add(id);
+  }
+}
+
+/**
+ * Parse an HTML file into a `ParseResult`.
+ *
+ * @param filePath - Absolute path to the HTML file.
+ */
+export async function parseHtml(filePath: string): Promise<ParseResult> {
+  const [content, stats] = await Promise.all([
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a user-provided path parameter
+    readFile(filePath, 'utf-8'),
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a user-provided path parameter
+    stat(filePath),
+  ]);
+
+  const { document, parseErrors } = parseHtmlDocument(content);
+
+  const links: ResourceLink[] = [];
+  const anchors = new Set<string>();
+
+  for (const element of walkElements(document)) {
+    visitElement(element, links, anchors);
+  }
+
+  const anchorList = [...anchors];
+  return {
+    links,
+    headings: [],
+    content,
+    sizeBytes: stats.size,
+    estimatedTokenCount: Math.ceil(content.length / 4),
+    ...(anchorList.length > 0 && { anchors: anchorList }),
+    ...(parseErrors.length > 0 && { parseErrors }),
+  };
+}

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.
  *
@@ -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 '';
     })