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

package/src/frontmatter-validator.ts

@@ -13,10 +13,11 @@
  * This is the ONLY place in the codebase that should use AJV.
  */
 
-import { Ajv } from '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.
@@ -32,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
@@ -55,7 +57,8 @@ export function validateFrontmatter(
   schema: object,
   resourcePath: string,
   mode: ValidationMode = 'strict',
-  schemaPath?: string
+  schemaPath?: string,
+  projectRoot?: string,
 ): ValidationIssue[] {
   const issues: ValidationIssue[] = [];
 
@@ -65,11 +68,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);
@@ -83,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;
   }
@@ -104,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/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';
 
@@ -310,29 +310,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 '';
     })
@@ -431,16 +447,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,39 @@
  * - External resources (outside project) skip git-ignore checks
  */
 
+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, 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, 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.
@@ -70,7 +92,7 @@ export async function validateLink(
       return await validateLocalFileLink(link, sourceFilePath, headingsByFile, options);
 
     case 'anchor':
-      return await validateAnchorLink(link, sourceFilePath, headingsByFile);
+      return await validateAnchorLink(link, sourceFilePath, headingsByFile, options?.projectRoot);
 
     case 'external':
       // External URLs are not validated - don't report them
@@ -81,13 +103,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
@@ -97,6 +117,115 @@ 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,
+  projectRoot?: string,
+): ValidationIssue | null {
+  if (resolved.kind === 'absolute_no_root') {
+    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.`,
+      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 createRegistryIssue(
+      'LINK_BROKEN_FILE',
+      `Absolute-path link "${link.href}" escapes the project root via path traversal.`,
+      linkExtras(link, sourceFilePath, projectRoot, ''),
+    );
+  }
+
+  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,
+  projectRoot?: string,
+): ValidationIssue | null {
+  if (fileResult.exists) return null;
+
+  if (fileResult.actualName) {
+    const expectedName = path.basename(fileResult.resolvedPath);
+    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 createRegistryIssue(
+    'LINK_BROKEN_FILE',
+    `File not found: ${fileResult.resolvedPath}`,
+    linkExtras(link, sourceFilePath, projectRoot, ''),
+  );
+}
+
+/**
+ * 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 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, ''),
+  );
+}
+
 /**
  * Validate a local file link (with optional anchor).
  */
@@ -106,87 +235,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);
-
-  // Validate the file exists
-  const fileResult = await validateLocalFile(filePath, 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 resolved = resolveLocalHref(link.href, sourceFilePath, options?.projectRoot);
 
-    return {
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `File not found: ${fileResult.resolvedPath}`,
-      suggestion: '',
-    };
+  if (resolved.kind !== 'resolved') {
+    // anchor_only → null no-op; absolute_no_root / absolute_escapes_root → broken_file.
+    return resolutionFailureIssue(resolved, link, sourceFilePath, options?.projectRoot);
   }
 
-  // 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: '',
-      };
-    }
+  const fileResult = await validateResolvedFile(resolved.resolvedPath);
+  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.',
+      ),
+    );
   }
 
-  // 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}`,
-        suggestion: '',
-      };
+      return createRegistryIssue(
+        'LINK_BROKEN_ANCHOR',
+        `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
+        linkExtras(link, sourceFilePath, options?.projectRoot, ''),
+      );
     }
   }
 
@@ -199,7 +282,8 @@ async function validateLocalFileLink(
 async function validateAnchorLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>
+  headingsByFile: Map<string, HeadingNode[]>,
+  projectRoot?: string,
 ): Promise<ValidationIssue | null> {
   // Extract anchor (strip leading #)
   const anchor = link.href.startsWith('#') ? link.href.slice(1) : link.href;
@@ -208,14 +292,11 @@ async function validateAnchorLink(
   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: '',
-    };
+    return createRegistryIssue(
+      'LINK_BROKEN_ANCHOR',
+      `Anchor not found: ${link.href}`,
+      linkExtras(link, sourceFilePath, projectRoot, ''),
+    );
   }
 
   return null;
@@ -223,37 +304,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) {