@vibe-agent-toolkit/resources 0.1.37 → 0.1.38

package/src/frontmatter-editor.ts

@@ -0,0 +1,214 @@
+/**
+ * FrontmatterEditor — round-trip-safe primitive for editing YAML frontmatter
+ * in markdown files.
+ *
+ * Public surface: openFrontmatter(markdown) → FrontmatterEditor.
+ *
+ * Round-trip identity contract: openFrontmatter(x).toString() === x for any
+ * well-formed input, byte-for-byte. Mutations preserve comments, blank lines,
+ * key ordering, quoting style, and detected EOL.
+ *
+ * See docs/superpowers/specs/2026-05-17-frontmatter-editor-and-yaml-consolidation-design.md
+ * §5 for the full contract.
+ */
+
+import { Document, parseDocument } from 'yaml';
+
+export class FrontmatterParseError extends Error {
+  public override readonly cause: unknown;
+
+  constructor(message: string, cause: unknown) {
+    super(message);
+    this.name = 'FrontmatterParseError';
+    this.cause = cause;
+  }
+}
+
+/** Path to a value in the parsed frontmatter document. */
+export type FrontmatterPath = string | readonly (string | number)[];
+
+/** Scalar value type accepted by mutation methods. */
+export type FrontmatterScalar = string | number | boolean | null;
+
+export interface FrontmatterEditor {
+  body: string;
+  get(path: FrontmatterPath): unknown;
+  set(path: FrontmatterPath, value: FrontmatterScalar): void;
+  setArrayItem(path: FrontmatterPath, index: number, value: FrontmatterScalar): void;
+  appendArrayItem(path: FrontmatterPath, value: FrontmatterScalar): void;
+  delete(path: FrontmatterPath): void;
+  toString(): string;
+  /**
+   * Returns true if any mutating method has been called or `body` was
+   * reassigned to a different string. Use to gate writeFileSync and avoid
+   * the no-op-rewrite churn described in §"What's preserved, what isn't"
+   * of the markdown-rewriting skill.
+   *
+   * **Caveat:** any call to `set` / `setArrayItem` / `appendArrayItem` /
+   * `delete` flips the flag, even if the underlying value didn't change
+   * (e.g. `set('foo', sameValue)`). For strict byte-level dirty detection
+   * compare `editor.toString() !== originalText` instead. `body =` is the
+   * one exception — it only flips dirty on actual string change.
+   */
+  isDirty(): boolean;
+}
+
+interface FrontmatterSplit {
+  hasFrontmatter: boolean;
+  frontmatterText: string;
+  body: string;
+  eol: '\n' | '\r\n';
+}
+
+const OPENING_FENCE = /^---\r?\n/;
+// Closing fence: either immediately after opening (empty frontmatter), or
+// preceded by a newline. Trailing variants accept newline or EOF.
+const EMPTY_CLOSING_FENCE = /^---(?:\r?\n|$)/;
+const CLOSING_FENCE = /(?:\r?\n---\r?\n|\r?\n---$)/;
+
+function detectEol(input: string): '\n' | '\r\n' {
+  const firstBreak = input.indexOf('\n');
+  if (firstBreak === -1) return '\n';
+  return firstBreak > 0 && input.charAt(firstBreak - 1) === '\r' ? '\r\n' : '\n';
+}
+
+function splitFrontmatter(input: string): FrontmatterSplit {
+  const eol = detectEol(input);
+  const openingMatch = OPENING_FENCE.exec(input);
+  if (!openingMatch) {
+    return { hasFrontmatter: false, frontmatterText: '', body: input, eol };
+  }
+  const afterOpening = input.slice(openingMatch[0].length);
+  // Handle empty frontmatter (closing fence immediately follows opening fence)
+  const emptyMatch = EMPTY_CLOSING_FENCE.exec(afterOpening);
+  if (emptyMatch) {
+    const bodyStart = emptyMatch[0].length;
+    return {
+      hasFrontmatter: true,
+      frontmatterText: '',
+      body: afterOpening.slice(bodyStart),
+      eol,
+    };
+  }
+  const closingMatch = CLOSING_FENCE.exec(afterOpening);
+  if (!closingMatch) {
+    return { hasFrontmatter: false, frontmatterText: '', body: input, eol };
+  }
+  const frontmatterText = afterOpening.slice(0, closingMatch.index);
+  const bodyStart = closingMatch.index + closingMatch[0].length;
+  const body = afterOpening.slice(bodyStart);
+  return { hasFrontmatter: true, frontmatterText, body, eol };
+}
+
+class FrontmatterEditorImpl implements FrontmatterEditor {
+  private readonly doc: Document.Parsed | Document;
+  private readonly hasFrontmatter: boolean;
+  private readonly eol: '\n' | '\r\n';
+  private _body: string;
+  private _dirty = false;
+
+  get body(): string {
+    return this._body;
+  }
+
+  set body(value: string) {
+    if (value !== this._body) {
+      this._body = value;
+      this._dirty = true;
+    }
+  }
+
+  isDirty(): boolean {
+    return this._dirty;
+  }
+
+  constructor(input: string) {
+    const split = splitFrontmatter(input);
+    this.hasFrontmatter = split.hasFrontmatter;
+    this.eol = split.eol;
+    this._body = split.body;
+    if (!split.hasFrontmatter) {
+      this.doc = new Document({});
+      return;
+    }
+    try {
+      this.doc = parseDocument(split.frontmatterText, { prettyErrors: true });
+      if (this.doc.errors.length > 0) {
+        throw new FrontmatterParseError(
+          `Invalid YAML frontmatter: ${this.doc.errors[0]?.message ?? 'unknown error'}`,
+          this.doc.errors[0],
+        );
+      }
+    } catch (error) {
+      if (error instanceof FrontmatterParseError) throw error;
+      throw new FrontmatterParseError(
+        `Failed to parse frontmatter: ${error instanceof Error ? error.message : String(error)}`,
+        error,
+      );
+    }
+  }
+
+  private toPath(path: FrontmatterPath): readonly (string | number)[] {
+    if (Array.isArray(path)) return path;
+    if (typeof path === 'string') return [path];
+    return path as readonly (string | number)[];
+  }
+
+  get(path: FrontmatterPath): unknown {
+    const segments = this.toPath(path);
+    if (segments.length === 0) return this.doc.toJS();
+    return this.doc.getIn(segments as Iterable<unknown>, false);
+  }
+
+  set(path: FrontmatterPath, value: FrontmatterScalar): void {
+    const segments = this.toPath(path);
+    this.doc.setIn(segments as Iterable<unknown>, value);
+    this._dirty = true;
+  }
+
+  setArrayItem(path: FrontmatterPath, index: number, value: FrontmatterScalar): void {
+    const segments = [...this.toPath(path), index];
+    this.doc.setIn(segments as Iterable<unknown>, value);
+    this._dirty = true;
+  }
+
+  appendArrayItem(path: FrontmatterPath, value: FrontmatterScalar): void {
+    const segments = this.toPath(path);
+    this.doc.addIn(segments as Iterable<unknown>, value);
+    this._dirty = true;
+  }
+
+  delete(path: FrontmatterPath): void {
+    const segments = this.toPath(path);
+    this.doc.deleteIn(segments as Iterable<unknown>);
+    this._dirty = true;
+  }
+
+  toString(): string {
+    // No frontmatter originally, and nothing was added → return body unchanged.
+    if (!this.hasFrontmatter && this.isDocEffectivelyEmpty()) {
+      return this.body;
+    }
+    // Empty frontmatter (e.g. `---\n---\n`) where the doc remained empty —
+    // preserve the empty fence block without injecting `null` or `{}` between.
+    if (this.hasFrontmatter && this.isDocEffectivelyEmpty()) {
+      return `---${this.eol}---${this.eol}${this.body}`;
+    }
+    const fmText = this.doc.toString();
+    const normalized = this.eol === '\r\n' ? fmText.replaceAll('\n', '\r\n') : fmText;
+    return `---${this.eol}${normalized}---${this.eol}${this.body}`;
+  }
+
+  private isDocEffectivelyEmpty(): boolean {
+    const contents = this.doc.contents;
+    if (contents === null) return true;
+    // yaml.YAMLMap and YAMLSeq expose `items`; an empty map/seq counts as empty.
+    const maybeItems = (contents as { items?: unknown[] }).items;
+    if (Array.isArray(maybeItems) && maybeItems.length === 0) return true;
+    return false;
+  }
+}
+
+export function openFrontmatter(markdown: string): FrontmatterEditor {
+  return new FrontmatterEditorImpl(markdown);
+}

package/src/frontmatter-validator.ts

@@ -13,8 +13,7 @@
  * This is the ONLY place in the codebase that should use AJV.
  */
 
-import { Ajv } from 'ajv';
-
+import { createAjvWithUriFormats } from './ajv-factory.js';
 import type { ValidationMode } from './schemas/project-config.js';
 import type { ValidationIssue } from './schemas/validation-result.js';
 
@@ -65,11 +64,16 @@ export function validateFrontmatter(
     effectiveSchema = makeSchemaPermissive(schema);
   }
 
-  // Configure AJV with permissive settings
-  const ajv = new Ajv({
-    strict: false,           // Allow non-strict schemas
-    allErrors: true,         // Report all errors, not just first
-    allowUnionTypes: true,   // Support JSON Schema draft features
+  // Use the shared Ajv factory so the internal validator and any adopter
+  // consuming `createAjvWithUriFormats` see identical format behavior.
+  // Permissive options match how VAT validates user-supplied schemas:
+  // - strict: false so non-strict schemas compile (older JSON Schema drafts).
+  // - allErrors: true so we report all issues, not just the first.
+  // - allowUnionTypes: true for draft-2019-09+ union type support.
+  const ajv = createAjvWithUriFormats({
+    strict: false,
+    allErrors: true,
+    allowUnionTypes: true,
   });
 
   const validate = ajv.compile(effectiveSchema);

package/src/index.ts

@@ -88,6 +88,11 @@ export { parseMarkdown, type ParseResult } from './link-parser.js';
 // Export frontmatter validation
 export { validateFrontmatter } from './frontmatter-validator.js';
 
+// Public Ajv factory for adopters consuming VAT-generated schemas. Registers
+// URI-family formats (uri, uri-reference, iri, iri-reference) so schemas
+// compile cleanly under Ajv strict mode without throwing on "unknown format".
+export { createAjvWithUriFormats } from './ajv-factory.js';
+
 // Export content transform engine for link rewriting
 export {
   transformContent,
@@ -101,11 +106,25 @@ export {
 // They are implementation details. Users should use ResourceRegistry API.
 
 // Export href resolution utility (shared by audit and validate code paths)
-export { resolveLocalHref } from './utils.js';
+export { resolveLocalHref, type ResolveLocalHrefResult } from './utils.js';
+
+// Export frontmatter editor primitive (comment-preserving round-trip)
+export {
+  openFrontmatter,
+  FrontmatterParseError,
+  type FrontmatterEditor,
+} from './frontmatter-editor.js';
+
+// Export rewriter helpers (built on FrontmatterEditor + shared callback shape)
+export {
+  rewriteFrontmatterUriReferencesFromSchema,
+  rewriteFrontmatterFieldsAtPaths,
+  rewriteBodyLinks,
+  type RewriteHref,
+} from './rewriter-helpers.js';
 
 // Export project config parsing
 export {
-  findConfigFile,
   parseConfigFile,
   loadConfig,
 } from './config-parser.js';

package/src/json-pointer-path.ts

@@ -0,0 +1,29 @@
+/**
+ * Convert an RFC 6901 JSON Pointer string into a path of (string | number)
+ * segments suitable for use with the FrontmatterEditor mutation API.
+ *
+ * Canonical array indices (RFC 6901 §4: no leading zeros except for "0")
+ * are converted to numbers; all other segments are decoded strings.
+ *
+ * @example
+ *   jsonPointerToPath('/adrs-cited/0') // ['adrs-cited', 0]
+ *   jsonPointerToPath('')              // []
+ */
+
+import { decodeJsonPointerSegment, isCanonicalArrayIndex } from './utils.js';
+
+export function jsonPointerToPath(pointer: string): (string | number)[] {
+  if (pointer === '') return [];
+  // eslint-disable-next-line local/no-hardcoded-path-split -- RFC 6901 JSON Pointer delimiter, not a file path
+  const raw = pointer.slice(1).split('/');
+  const result: (string | number)[] = [];
+  for (const seg of raw) {
+    const decoded = decodeJsonPointerSegment(seg);
+    if (isCanonicalArrayIndex(decoded)) {
+      result.push(Number(decoded));
+    } else {
+      result.push(decoded);
+    }
+  }
+  return result;
+}

package/src/link-parser.ts

@@ -12,13 +12,13 @@
 import { readFile, stat } from 'node:fs/promises';
 
 import GithubSlugger from 'github-slugger';
-import * as yaml from 'js-yaml';
 import type { Definition, 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 * as yaml from 'yaml';
 
 import type { HeadingNode, LinkType, ResourceLink } from './types.js';
 
@@ -431,16 +431,7 @@ function extractFrontmatter(tree: Root): {
     }
 
     try {
-      // CORE_SCHEMA is the YAML 1.2 spec — keeps unquoted ISO dates as
-      // strings (`2026-04-15` stays `"2026-04-15"`) instead of promoting
-      // them to JS Date objects (js-yaml's default DEFAULT_SCHEMA still
-      // applies the YAML 1.1 timestamp tag). Date promotion broke schema
-      // validation for any frontmatter field typed `string` in the schema:
-      // the validator saw an instanceof Date and rejected it. Adopters'
-      // ADR/PRD frontmatter conventionally uses unquoted ISO dates per
-      // YAML 1.2; quoting all of them just to placate the parser is
-      // unreasonable.
-      const parsed = yaml.load(node.value, { schema: yaml.CORE_SCHEMA });
+      const parsed = yaml.parse(node.value);
       if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
         frontmatterData = parsed as Record<string, unknown>;
       }

package/src/link-validator.ts

@@ -15,17 +15,18 @@
  * - External resources (outside project) skip git-ignore checks
  */
 
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import {
   isGitIgnored,
   type GitTracker,
-  verifyCaseSensitiveFilename, safePath,
+  verifyCaseSensitiveFilename,
 } from '@vibe-agent-toolkit/utils';
 
 import type { ValidationIssue } from './schemas/validation-result.js';
 import type { HeadingNode, ResourceLink } from './types.js';
-import { isWithinProject, resolveLocalHref, splitHrefAnchor } from './utils.js';
+import { isWithinProject, resolveLocalHref } from './utils.js';
 
 /**
  * Options for link validation.
@@ -97,6 +98,120 @@ export async function validateLink(
   }
 }
 
+/**
+ * Convert a resolution failure kind to a broken_file ValidationIssue. Returns
+ * null for `resolved` (caller continues) and `anchor_only` (defensive no-op —
+ * the parser classifies anchor-only hrefs as 'anchor', not 'local_file').
+ */
+export function resolutionFailureIssue(
+  resolved: ReturnType<typeof resolveLocalHref>,
+  link: ResourceLink,
+  sourceFilePath: 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; ` +
+        `none was provided. Configure vibe-agent-toolkit.config.yaml or run ` +
+        `from within a git repository.`,
+      suggestion:
+        '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 null;
+}
+
+/**
+ * Convert a non-existent file result into a broken_file ValidationIssue.
+ * Returns null when the file exists.
+ */
+export function fileExistenceIssue(
+  fileResult: { exists: boolean; resolvedPath: string; actualName?: string },
+  link: ResourceLink,
+  sourceFilePath: 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 {
+    resourcePath: sourceFilePath,
+    line: link.line,
+    type: 'broken_file',
+    link: link.href,
+    message: `File not found: ${fileResult.resolvedPath}`,
+    suggestion: '',
+  };
+}
+
+/**
+ * Check git-ignore safety: a non-ignored source file must not link to a
+ * gitignored target. Returns a ValidationIssue when this rule is violated,
+ * null otherwise (including when checks are disabled or out of scope).
+ */
+export function gitIgnoreSafetyIssue(
+  link: ResourceLink,
+  sourceFilePath: string,
+  resolvedTarget: string,
+  options: ValidateLinkOptions | undefined,
+): ValidationIssue | null {
+  if (
+    options?.skipGitIgnoreCheck === true ||
+    options?.projectRoot === undefined ||
+    !isWithinProject(resolvedTarget, options.projectRoot)
+  ) {
+    return null;
+  }
+
+  // Prefer the O(1) active-set lookup on the shared GitTracker (no spawn).
+  // isIgnoredByActiveSet falls back internally to isIgnored for paths outside
+  // the project root, so this is safe for the rare out-of-project case.
+  // When no tracker is threaded in, fall back to isGitIgnored (one-off spawn).
+  const sourceIsIgnored = options.gitTracker
+    ? options.gitTracker.isIgnoredByActiveSet(sourceFilePath)
+    : isGitIgnored(sourceFilePath, options.projectRoot);
+  const targetIsIgnored = options.gitTracker
+    ? options.gitTracker.isIgnoredByActiveSet(resolvedTarget)
+    : isGitIgnored(resolvedTarget, options.projectRoot);
+
+  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: '',
+  };
+}
+
 /**
  * Validate a local file link (with optional anchor).
  */
@@ -106,85 +221,41 @@ async function validateLocalFileLink(
   headingsByFile: Map<string, HeadingNode[]>,
   options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
-  // Extract file path and anchor from href
-  const [filePath, anchor] = splitHrefAnchor(link.href);
+  const resolved = resolveLocalHref(link.href, sourceFilePath, options?.projectRoot);
 
-  // Validate the file exists
-  const fileResult = await validateLocalFile(filePath, sourceFilePath);
+  if (resolved.kind !== 'resolved') {
+    // anchor_only → null no-op; absolute_no_root / absolute_escapes_root → broken_file.
+    return resolutionFailureIssue(resolved, link, sourceFilePath);
+  }
 
-  if (!fileResult.exists) {
-    // Check if it's a case mismatch
-    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}"`,
-      };
-    }
+  const fileResult = await validateResolvedFile(resolved.resolvedPath);
+  const notFound = fileExistenceIssue(fileResult, link, sourceFilePath);
+  if (notFound) return notFound;
 
+  if (fileResult.isDirectory) {
     return {
       resourcePath: sourceFilePath,
       line: link.line,
       type: 'broken_file',
       link: link.href,
-      message: `File not found: ${fileResult.resolvedPath}`,
-      suggestion: '',
+      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.',
     };
   }
 
-  // Check git-ignore safety (Phase 3)
-  // Only check if:
-  // 1. skipGitIgnoreCheck is NOT true
-  // 2. projectRoot is provided
-  // 3. target is within project (skip for external resources)
-  if (
-    options?.skipGitIgnoreCheck !== true &&
-    options?.projectRoot !== undefined &&
-    isWithinProject(fileResult.resolvedPath, options.projectRoot)
-  ) {
-    // Prefer the O(1) active-set lookup on the shared GitTracker (no spawn).
-    // isIgnoredByActiveSet falls back internally to isIgnored for paths outside
-    // the project root, so this is safe for the rare out-of-project case.
-    // When no tracker is threaded in, fall back to isGitIgnored (one-off spawn).
-    const sourceIsIgnored = options.gitTracker
-      ? options.gitTracker.isIgnoredByActiveSet(sourceFilePath)
-      : isGitIgnored(sourceFilePath, options.projectRoot);
-    const targetIsIgnored = options.gitTracker
-      ? options.gitTracker.isIgnoredByActiveSet(fileResult.resolvedPath)
-      : isGitIgnored(fileResult.resolvedPath, options.projectRoot);
-
-    // Error ONLY if: source is NOT ignored AND target IS ignored
-    if (!sourceIsIgnored && targetIsIgnored) {
-      return {
-        resourcePath: sourceFilePath,
-        line: link.line,
-        type: 'link_to_gitignored',
-        link: link.href,
-        message: `Non-ignored file links to gitignored file: ${fileResult.resolvedPath}. Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target file.`,
-        suggestion: '',
-      };
-    }
-  }
-
-  // If there's an anchor, validate it too
-  if (anchor) {
-    const anchorValid = await validateAnchor(
-      anchor,
-      fileResult.resolvedPath,
-      headingsByFile
-    );
+  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: #${anchor} in ${fileResult.resolvedPath}`,
+        message: `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
         suggestion: '',
       };
     }
@@ -223,37 +294,31 @@ async function validateAnchorLink(
 
 
 /**
- * Validate that a local file exists with the correct case.
- *
- * @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 optional case mismatch info
+ * Verify that the resolved filesystem path exists with the correct case.
  *
- * @example
- * ```typescript
- * const result = await validateLocalFile('./docs/guide.md', '/project/README.md');
- * if (result.exists) {
- *   console.log('File exists at:', result.resolvedPath);
- * } else if (result.actualName) {
- *   console.log('Case mismatch:', result.actualName);
- * }
- * ```
+ * @param resolvedPath - Absolute filesystem path produced by {@link resolveLocalHref}.
+ * @returns Object with exists flag, the path, and optional case-mismatch info.
  */
-async function validateLocalFile(
-  href: string,
-  sourceFilePath: string
-): Promise<{ exists: boolean; resolvedPath: string; actualName?: string }> {
-  // Resolve href to filesystem path (decode percent-encoding, resolve relative to source)
-  const resolved = resolveLocalHref(href, sourceFilePath);
-  const resolvedPath = resolved?.resolvedPath ?? safePath.resolve(path.dirname(sourceFilePath), href);
-
-  // Check if file exists with correct case
+async function validateResolvedFile(
+  resolvedPath: string,
+): Promise<{ exists: boolean; resolvedPath: string; actualName?: string; isDirectory: boolean }> {
   const verification = await verifyCaseSensitiveFilename(resolvedPath);
 
-  // Build result with optional actualName (only include if present)
-  const result: { exists: boolean; resolvedPath: string; actualName?: string } = {
+  let isDirectory = false;
+  if (verification.exists) {
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolvedPath validated by verifyCaseSensitiveFilename
+      const stats = await fs.stat(resolvedPath);
+      isDirectory = stats.isDirectory();
+    } catch {
+      // Stat failed after verifyCaseSensitiveFilename said exists — treat as file.
+    }
+  }
+
+  const result: { exists: boolean; resolvedPath: string; actualName?: string; isDirectory: boolean } = {
     exists: verification.exists,
     resolvedPath,
+    isDirectory,
   };
 
   if (verification.actualName) {