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

package/src/multi-schema-validator.ts

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

package/src/resource-registry.ts

@@ -11,6 +11,7 @@
 import type fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { createRegistryIssue, type IssueCode, runValidationFramework, type ValidationConfig, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import { crawlDirectory, type CrawlOptions as UtilsCrawlOptions, type GitTracker, normalizedTmpdir, resolveAssetReference, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 
 import { calculateChecksum } from './checksum.js';
@@ -27,8 +28,8 @@ import type { ResourceCollectionInterface } from './resource-collection-interfac
 import type { SHA256 } from './schemas/checksum.js';
 import type { ProjectConfig } from './schemas/project-config.js';
 import type { HeadingNode, ResourceMetadata } from './schemas/resource-metadata.js';
-import type { ValidationIssue, ValidationResult } from './schemas/validation-result.js';
-import { matchesGlobPattern, splitHrefAnchor } from './utils.js';
+import type { ValidationResult } from './schemas/validation-result.js';
+import { issueLocation, matchesGlobPattern, splitHrefAnchor } from './utils.js';
 
 /**
  * Options for crawling directories to add resources.
@@ -72,6 +73,13 @@ export interface ValidateOptions {
   checkExternalUrls?: boolean;
   /** Disable cache for external URL checks (default: false) */
   noCache?: boolean;
+  /**
+   * Validation framework config (severity overrides + per-code allow entries).
+   * Applied INSIDE validate() via runValidationFramework — the library, not the
+   * CLI, resolves severity and drops ignored issues. Defaults to `{}` (no
+   * overrides: every issue keeps its registry default severity).
+   */
+  validationConfig?: ValidationConfig;
 }
 
 /**
@@ -422,13 +430,13 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     const issues: ValidationIssue[] = [];
     for (const resource of this.resourcesByPath.values()) {
       if (resource.frontmatterError) {
-        issues.push({
-          resourcePath: resource.filePath,
-          line: 1,
-          type: 'frontmatter_invalid_yaml',
-          link: '',
-          message: `Invalid YAML syntax in frontmatter: ${resource.frontmatterError}`,
-        });
+        issues.push(
+          createRegistryIssue(
+            'FRONTMATTER_INVALID_YAML',
+            `Invalid YAML syntax in frontmatter: ${resource.frontmatterError}`,
+            { location: issueLocation(resource.filePath, this.baseDir), line: 1 },
+          ),
+        );
       }
     }
     return issues;
@@ -479,7 +487,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         resource.frontmatter,
         schema,
         resource.filePath,
-        mode
+        mode,
+        undefined,
+        this.baseDir,
       );
       issues.push(...frontmatterIssues);
     }
@@ -593,6 +603,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         resource.filePath,
         mode,
         schemaPath,
+        this.baseDir,
       );
 
       // New: walk URI-family frontmatter values. Default-on; explicit `false` disables.
@@ -624,13 +635,13 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     } catch (error) {
       // Handle missing or invalid schema files gracefully
       const errorMessage = error instanceof Error ? error.message : String(error);
-      return [{
-        resourcePath: resource.filePath,
-        line: 1,
-        type: 'frontmatter_schema_error',
-        link: '',
-        message: `Failed to load or parse frontmatter schema '${validation.frontmatterSchema}': ${errorMessage}`,
-      }];
+      return [
+        createRegistryIssue(
+          'FRONTMATTER_SCHEMA_ERROR',
+          `Failed to load or parse frontmatter schema '${validation.frontmatterSchema}': ${errorMessage}`,
+          { location: issueLocation(resource.filePath, this.baseDir), line: 1 },
+        ),
+      ];
     }
   }
 
@@ -706,8 +717,11 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       issues.push(...externalUrlIssues);
     }
 
-    // Count issues (all are errors now)
-    const errorCount = issues.length;
+    // Resolve severity + apply allow-filter INSIDE the library (not the CLI).
+    // `emitted` = post-allow-filter, severity-resolved, with `ignore`d dropped.
+    const framework = runValidationFramework(issues, options?.validationConfig ?? {});
+    const emitted = framework.emitted;
+    const errorCount = emitted.length;
 
     // Count links by type
     const linksByType: Record<string, number> = {};
@@ -726,9 +740,10 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         0
       ),
       linksByType,
-      issues,
+      issues: emitted,
       errorCount,
       passed: errorCount === 0,
+      hasErrors: framework.hasErrors,
       durationMs,
       timestamp: new Date(),
     };
@@ -830,17 +845,17 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         continue;
       }
 
-      const issueType = this.determineExternalUrlIssueType(result.statusCode, result.error);
+      const issueCode = this.determineExternalUrlIssueCode(result.statusCode, result.error);
       const errorMessage = result.error ?? `HTTP ${result.statusCode}`;
 
       for (const location of locations) {
-        issues.push({
-          resourcePath: location.resourcePath,
-          line: location.line,
-          type: issueType,
-          link: result.url,
-          message: `External URL failed: ${errorMessage}`,
-        });
+        issues.push(
+          createRegistryIssue(issueCode, `External URL failed: ${errorMessage}`, {
+            location: issueLocation(location.resourcePath, this.baseDir),
+            link: result.url,
+            ...(location.line !== undefined && { line: location.line }),
+          }),
+        );
       }
     }
 
@@ -848,18 +863,18 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   }
 
   /**
-   * Determine issue type based on validation error.
+   * Determine the registry issue code based on the external-URL validation error.
    * @private
    */
-  private determineExternalUrlIssueType(statusCode: number, error?: string): string {
+  private determineExternalUrlIssueCode(statusCode: number, error?: string): IssueCode {
     if (statusCode === 0) {
       const errorLower = error?.toString().toLowerCase();
       if (errorLower?.includes('timeout')) {
-        return 'external_url_timeout';
+        return 'EXTERNAL_URL_TIMEOUT';
       }
-      return 'external_url_error';
+      return 'EXTERNAL_URL_ERROR';
     }
-    return 'external_url_dead';
+    return 'EXTERNAL_URL_DEAD';
   }
 
   /**

package/src/rewriter-helpers.ts

@@ -0,0 +1,166 @@
+/**
+ * Public rewriter helpers built on FrontmatterEditor and shared callback
+ * shape `(href: string) => string`.
+ *
+ * Three layers:
+ *   1. rewriteFrontmatterUriReferencesFromSchema — schema-driven; used by
+ *      VAT packager and by schema-aware adopter scripts.
+ *   2. rewriteFrontmatterFieldsAtPaths — path-driven; used by ad-hoc
+ *      adopter scripts (no JSON Schema available; field paths known by
+ *      convention).
+ *   3. rewriteBodyLinks — standalone body-side counterpart. Parallel to
+ *      `transformContent` but with a callback model instead of templates.
+ *
+ * See docs/superpowers/specs/2026-05-17-frontmatter-editor-and-yaml-consolidation-design.md
+ * §6 for the design contract.
+ */
+
+import { isNode } from 'yaml';
+
+import type { FrontmatterEditor } from './frontmatter-editor.js';
+import { jsonPointerToPath } from './json-pointer-path.js';
+import { walkFrontmatterUriReferences } from './schema-uri-walker.js';
+
+/**
+ * Normalize a value returned by `FrontmatterEditor.get(path)` into plain JS.
+ *
+ * The underlying yaml library's `getIn(path, false)` unwraps scalar leaves to
+ * JS primitives but leaves YAMLMap / YAMLSeq collections as Node instances.
+ * The rewriter helpers reason in terms of JS values (arrays, strings), so we
+ * unwrap collection Nodes here once at the boundary.
+ */
+function toPlainJs(value: unknown): unknown {
+  if (isNode(value)) return value.toJSON();
+  return value;
+}
+
+/** Type for the rewrite policy callback — same shape for body and frontmatter. */
+export type RewriteHref = (href: string) => string;
+
+/**
+ * Apply `rewriteHref` to every frontmatter scalar whose schema position has
+ * a URI-family `format`. Preserves comments via FrontmatterEditor.
+ */
+export function rewriteFrontmatterUriReferencesFromSchema(
+  editor: FrontmatterEditor,
+  schema: object,
+  rewriteHref: RewriteHref,
+): void {
+  const frontmatter = editor.get([]);
+  if (frontmatter === undefined || frontmatter === null) return;
+  if (typeof frontmatter !== 'object') return;
+
+  const captures = walkFrontmatterUriReferences(frontmatter, schema);
+  for (const capture of captures) {
+    const path = jsonPointerToPath(capture.pointer);
+    if (path.length === 0) continue;
+    const newValue = rewriteHref(capture.value);
+    if (newValue === capture.value) continue;
+    const lastSegment = path.at(-1);
+    if (typeof lastSegment === 'number') {
+      const parentPath = path.slice(0, -1);
+      editor.setArrayItem(parentPath, lastSegment, newValue);
+    } else {
+      editor.set(path, newValue);
+    }
+  }
+}
+
+interface ParsedPath {
+  segments: readonly (string | number)[];
+  isArray: boolean;
+}
+
+function parsePathPattern(pattern: string): ParsedPath {
+  const isArray = pattern.endsWith('[]');
+  const cleaned = isArray ? pattern.slice(0, -2) : pattern;
+  const segments = cleaned.split('.');
+  return { segments, isArray };
+}
+
+function rewriteArrayPath(
+  editor: FrontmatterEditor,
+  segments: readonly (string | number)[],
+  value: unknown,
+  rewriteHref: RewriteHref,
+): void {
+  if (!Array.isArray(value)) return;
+  for (const [i, item] of value.entries()) {
+    if (typeof item !== 'string') continue;
+    const newValue = rewriteHref(item);
+    if (newValue !== item) editor.setArrayItem(segments, i, newValue);
+  }
+}
+
+function rewriteScalarPath(
+  editor: FrontmatterEditor,
+  segments: readonly (string | number)[],
+  value: unknown,
+  rewriteHref: RewriteHref,
+): void {
+  if (typeof value !== 'string') return;
+  const newValue = rewriteHref(value);
+  if (newValue !== value) editor.set(segments, newValue);
+}
+
+/**
+ * Apply `rewriteHref` to specific frontmatter fields named by explicit
+ * dotted paths. Used by adopter scripts that know which fields hold
+ * references without a JSON Schema.
+ *
+ * Path syntax:
+ *   - 'name'            — top-level scalar
+ *   - 'name[]'          — array of strings (rewrite each string item)
+ *   - 'meta.parent'     — dotted nested scalar
+ *   - 'meta.refs[]'     — dotted nested array of strings
+ *
+ * Missing paths are silent no-ops. Non-string values are skipped.
+ */
+export function rewriteFrontmatterFieldsAtPaths(
+  editor: FrontmatterEditor,
+  paths: readonly string[],
+  rewriteHref: RewriteHref,
+): void {
+  for (const pattern of paths) {
+    const { segments, isArray } = parsePathPattern(pattern);
+    const value = toPlainJs(editor.get(segments));
+    if (value === undefined || value === null) continue;
+    if (isArray) {
+      rewriteArrayPath(editor, segments, value, rewriteHref);
+    } else {
+      rewriteScalarPath(editor, segments, value, rewriteHref);
+    }
+  }
+}
+
+/**
+ * Inline + reference-style link patterns. These match `transformContent`'s
+ * regex contract — see content-transform.ts for the rationale on negated
+ * character classes.
+ */
+// eslint-disable-next-line sonarjs/slow-regex -- negated character classes [^\]] and [^)] are non-backtracking
+const INLINE_LINK_REGEX = /\[([^\]]*)\]\(([^)]*)\)/g;
+// eslint-disable-next-line sonarjs/slow-regex -- Controlled markdown reference link definitions on line boundaries
+const DEFINITION_LINK_REGEX = /^\[([^\]]*?)\]:\s*(.+)$/gm;
+
+/**
+ * Apply `rewriteHref` to every inline-link and reference-definition href in
+ * a markdown body. Parallel to `transformContent` but with a callback model
+ * — appropriate for adopter scripts and for any caller that wants a
+ * per-href rewrite without rule/template ceremony.
+ *
+ * `rewriteHref` receives the raw href (including any fragment) and returns
+ * the new href. Returning the same string is a no-op for that link.
+ */
+export function rewriteBodyLinks(body: string, rewriteHref: RewriteHref): string {
+  let out = body.replaceAll(INLINE_LINK_REGEX, (full, text: string, href: string) => {
+    const next = rewriteHref(href);
+    return next === href ? full : `[${text}](${next})`;
+  });
+  out = out.replaceAll(DEFINITION_LINK_REGEX, (full, ref: string, href: string) => {
+    const trimmed = href.trim();
+    const next = rewriteHref(trimmed);
+    return next === trimmed ? full : `[${ref}]: ${next}`;
+  });
+  return out;
+}

package/src/schemas/project-config.ts

@@ -96,6 +96,8 @@ export const ResourcesConfigSchema = z.object({
     .describe('Global default exclude patterns (not used by collections in Phase 2)'),
   collections: z.record(z.string(), CollectionConfigSchema).optional()
     .describe('Named collections of resources'),
+  validation: ValidationConfigSchema.optional()
+    .describe('Validation framework config: severity overrides and per-code allow entries (applied inside ResourceRegistry.validate)'),
 }).describe('Resources section of project configuration');
 
 export type ResourcesConfig = z.infer<typeof ResourcesConfigSchema>;

package/src/schemas/validation-result.ts

@@ -1,32 +1,7 @@
+import { ValidationIssueSchema } from '@vibe-agent-toolkit/agent-schema';
 import { z } from 'zod';
 
-/**
- * A single validation issue found during link validation.
- *
- * Issue types:
- * - broken_file: Local file link points to non-existent file
- * - broken_anchor: Anchor link points to non-existent heading
- * - frontmatter_missing: Schema requires frontmatter, file has none
- * - frontmatter_invalid_yaml: YAML syntax error in frontmatter
- * - frontmatter_schema_error: Frontmatter fails JSON Schema validation
- * - external_url_dead: External URL returned error status (4xx, 5xx)
- * - external_url_timeout: External URL request timed out
- * - external_url_error: External URL validation failed (DNS, network, etc.)
- * - unknown_link: Unknown link type
- *
- * Includes details about what went wrong, where it occurred, and optionally
- * how to fix it.
- */
-export const ValidationIssueSchema = z.object({
-  resourcePath: z.string().describe('Absolute path to the resource containing the issue'),
-  line: z.number().int().positive().optional().describe('Line number where the issue occurs'),
-  type: z.string().describe('Issue type identifier (e.g., "broken_file", "broken_anchor", "frontmatter_schema_error", "unknown_link")'),
-  link: z.string().describe('The problematic link'),
-  message: z.string().describe('Human-readable description of the issue'),
-  suggestion: z.string().optional().describe('Optional suggestion for fixing the issue'),
-}).describe('A single validation issue found during link validation');
-
-export type ValidationIssue = z.infer<typeof ValidationIssueSchema>;
+export { type ValidationIssue, ValidationIssueSchema } from '@vibe-agent-toolkit/agent-schema';
 
 /**
  * Complete results from validating a collection of resources.
@@ -38,9 +13,10 @@ export const ValidationResultSchema = z.object({
   totalResources: z.number().int().nonnegative().describe('Total number of resources validated'),
   totalLinks: z.number().int().nonnegative().describe('Total number of links found across all resources'),
   linksByType: z.record(z.string(), z.number().int().nonnegative()).describe('Count of links by type (e.g., {"local_file": 10, "external": 5})'),
-  issues: z.array(ValidationIssueSchema).describe('All validation issues found'),
-  errorCount: z.number().int().nonnegative().describe('Number of issues found'),
+  issues: z.array(ValidationIssueSchema).describe('Emitted validation issues (allow-filtered + severity-resolved; ignored issues dropped)'),
+  errorCount: z.number().int().nonnegative().describe('Number of emitted issues'),
   passed: z.boolean().describe('True if validation succeeded (errorCount === 0)'),
+  hasErrors: z.boolean().describe('True when any emitted issue has resolved severity "error"'),
   durationMs: z.number().nonnegative().describe('Validation duration in milliseconds'),
   timestamp: z.date().describe('When validation was performed'),
 }).describe('Complete results from validating a collection of resources');

package/src/types/resource-parser.ts

@@ -7,7 +7,7 @@
 
 import { promises as fs } from 'node:fs';
 
-import yaml from 'js-yaml';
+import * as yaml from 'yaml';
 
 import { calculateChecksum } from '../checksum.js';
 import { parseMarkdown } from '../link-parser.js';
@@ -213,8 +213,7 @@ export async function parseYamlResource(
   // Read and parse YAML
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   const content = await fs.readFile(absolutePath, 'utf-8');
-  // CORE_SCHEMA: YAML 1.2 spec — see link-parser.ts for rationale.
-  const data = yaml.load(content, { schema: yaml.CORE_SCHEMA });
+  const data = yaml.parse(content);
 
   // Calculate checksum
   const checksum = await calculateChecksum(absolutePath);

package/src/types/resources.ts

@@ -6,8 +6,9 @@
  * with optional absolutePath for runtime operations.
  */
 
+import type { ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+
 import type { SHA256 } from '../schemas/checksum.js';
-import type { ValidationIssue } from '../schemas/validation-result.js';
 
 /**
  * Resource type discriminator for type-safe handling

package/src/types.ts

@@ -89,7 +89,6 @@ export type {
 
 // Config parsing
 export {
-  findConfigFile,
   parseConfigFile,
   loadConfig,
 } from './config-parser.js';

package/src/utils.ts

@@ -9,6 +9,21 @@ import path from 'node:path';
 import { toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
 import picomatch from 'picomatch';
 
+/**
+ * Compute a `ValidationIssue.location`: the (absolute) source file path made
+ * relative to the project root. When no project root is known, fall back to the
+ * source path forward-slashed so the location is still useful and stable.
+ *
+ * @param sourceFilePath - Absolute path to the file the issue was found in.
+ * @param projectRoot - Project root, or undefined when none could be determined.
+ * @returns Forward-slashed relative location (or the forward-slashed absolute path).
+ */
+export function issueLocation(sourceFilePath: string, projectRoot: string | undefined): string {
+  return projectRoot === undefined
+    ? toForwardSlash(sourceFilePath)
+    : safePath.relative(projectRoot, sourceFilePath);
+}
+
 /**
  * Check if a file path matches a glob pattern.
  *
@@ -73,35 +88,58 @@ export function splitHrefAnchor(href: string): [string, string | undefined] {
 }
 
 /**
- * Resolve a markdown link href to an absolute filesystem path.
+ * Discriminated union returned by {@link resolveLocalHref}.
+ *
+ * - `anchor_only` — the href was `#fragment` only (no file component).
+ * - `resolved` — the href resolved to an absolute filesystem path.
+ * - `absolute_no_root` — the href is an RFC 3986 §4.2 absolute-path
+ *   reference (starts with `/`) but no `projectRoot` was supplied.
+ * - `absolute_escapes_root` — the absolute-path reference resolved to a
+ *   location outside `projectRoot` (e.g., via `..` traversal or a symlink
+ *   pointing outside the project).
+ */
+export type ResolveLocalHrefResult =
+  | { kind: 'anchor_only' }
+  | { kind: 'resolved'; resolvedPath: string; anchor: string | undefined }
+  | { kind: 'absolute_no_root'; href: string; anchor: string | undefined }
+  | { kind: 'absolute_escapes_root'; href: string; anchor: string | undefined };
+
+/**
+ * Resolve a markdown link href to a filesystem path or a typed failure.
  *
  * Performs the standard href → path conversion used by both audit and validate:
  * 1. Strips anchor fragment (`#section`)
  * 2. Decodes URL-encoded characters (`%20` → space, `%26` → `&`)
- * 3. Resolves the path relative to the source file's directory
- *
- * Returns `null` for anchor-only links (e.g., `#heading`).
+ * 3. Resolves the path:
+ *    - Leading `/` (RFC 3986 §4.2 absolute-path reference) → resolve against
+ *      `projectRoot`. Requires a `projectRoot`; must not escape it.
+ *    - Otherwise → resolve relative to the source file's directory.
  *
  * @param href - Raw href from a markdown link
  * @param sourceFilePath - Absolute path of the file containing the link
- * @returns Resolved path info, or null for anchor-only links
+ * @param projectRoot - Optional project root for absolute-path references.
+ * @returns A {@link ResolveLocalHrefResult} discriminating success vs failure modes.
  *
  * @example
  * ```typescript
  * resolveLocalHref('My%20Folder/doc.md#intro', '/project/README.md')
- * // { resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
+ * // { kind: 'resolved', resolvedPath: '/project/My Folder/doc.md', anchor: 'intro' }
  *
  * resolveLocalHref('#heading', '/project/README.md')
- * // null
+ * // { kind: 'anchor_only' }
+ *
+ * resolveLocalHref('/docs/foo.md', '/project/docs/sub/page.md', '/project')
+ * // { kind: 'resolved', resolvedPath: '/project/docs/foo.md', anchor: undefined }
  * ```
  */
 export function resolveLocalHref(
   href: string,
   sourceFilePath: string,
-): { resolvedPath: string; anchor: string | undefined } | null {
+  projectRoot?: string,
+): ResolveLocalHrefResult {
   const [fileHref, anchor] = splitHrefAnchor(href);
   if (fileHref === '') {
-    return null;
+    return { kind: 'anchor_only' };
   }
 
   let decodedHref: string;
@@ -111,10 +149,22 @@ export function resolveLocalHref(
     decodedHref = fileHref;
   }
 
+  // RFC 3986 §4.2 absolute-path reference — resolve against projectRoot.
+  if (decodedHref.startsWith('/')) {
+    if (!projectRoot) {
+      return { kind: 'absolute_no_root', href: fileHref, anchor };
+    }
+    const candidate = safePath.resolve(projectRoot, decodedHref.slice(1));
+    if (!isWithinProject(candidate, projectRoot)) {
+      return { kind: 'absolute_escapes_root', href: fileHref, anchor };
+    }
+    return { kind: 'resolved', resolvedPath: candidate, anchor };
+  }
+
+  // Relative reference — resolve against the source file's directory.
   const sourceDir = path.dirname(sourceFilePath);
   const resolvedPath = safePath.resolve(sourceDir, decodedHref);
-
-  return { resolvedPath, anchor };
+  return { kind: 'resolved', resolvedPath, anchor };
 }
 
 /**
@@ -135,7 +185,9 @@ export function resolveLocalHref(
  * ```
  */
 export function isWithinProject(filePath: string, projectRoot: string): boolean {
-  // Resolve symlinks to get real paths
+  // Canonicalize both sides symmetrically. Asymmetric handling (realpath one
+  // side, resolve the other) false-flags legitimate matches when projectRoot
+  // traverses a symlink — e.g. macOS /tmp → /private/tmp, bind mounts.
   let resolvedFilePath: string;
   try {
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is validated path parameter
@@ -145,7 +197,13 @@ export function isWithinProject(filePath: string, projectRoot: string): boolean
     resolvedFilePath = safePath.resolve(filePath);
   }
 
-  const resolvedProjectRoot = safePath.resolve(projectRoot);
+  let resolvedProjectRoot: string;
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- projectRoot is validated path parameter
+    resolvedProjectRoot = fs.realpathSync(projectRoot);
+  } catch {
+    resolvedProjectRoot = safePath.resolve(projectRoot);
+  }
 
   // Normalize to forward slashes for cross-platform comparison
   const normalizedFile = toForwardSlash(resolvedFilePath);
@@ -199,7 +257,7 @@ export function formatJsonPointerAsDotted(pointer: string): string {
   return out;
 }
 
-function isCanonicalArrayIndex(s: string): boolean {
+export function isCanonicalArrayIndex(s: string): boolean {
   // Canonical integer per RFC 6901 §4 + JSON canonical form: no leading zeros
   // except for "0" itself.
   if (s === '') return false;