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

package/dist/utils.js

@@ -6,6 +6,20 @@ import fs from 'node:fs';
 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, projectRoot) {
+    return projectRoot === undefined
+        ? toForwardSlash(sourceFilePath)
+        : safePath.relative(projectRoot, sourceFilePath);
+}
 /**
  * Check if a file path matches a glob pattern.
  *
@@ -64,32 +78,37 @@ export function splitHrefAnchor(href) {
     return [filePath, anchor];
 }
 /**
- * Resolve a markdown link href to an absolute filesystem path.
+ * 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, sourceFilePath) {
+export function resolveLocalHref(href, sourceFilePath, projectRoot) {
     const [fileHref, anchor] = splitHrefAnchor(href);
     if (fileHref === '') {
-        return null;
+        return { kind: 'anchor_only' };
     }
     let decodedHref;
     try {
@@ -98,9 +117,21 @@ export function resolveLocalHref(href, sourceFilePath) {
     catch {
         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 };
 }
 /**
  * Check if a file path is within a project directory.
@@ -120,7 +151,9 @@ export function resolveLocalHref(href, sourceFilePath) {
  * ```
  */
 export function isWithinProject(filePath, projectRoot) {
-    // 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;
     try {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is validated path parameter
@@ -130,7 +163,14 @@ export function isWithinProject(filePath, projectRoot) {
         // If realpath fails, file doesn't exist - use original path
         resolvedFilePath = safePath.resolve(filePath);
     }
-    const resolvedProjectRoot = safePath.resolve(projectRoot);
+    let resolvedProjectRoot;
+    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);
     const normalizedRoot = toForwardSlash(resolvedProjectRoot);
@@ -179,7 +219,7 @@ export function formatJsonPointerAsDotted(pointer) {
     }
     return out;
 }
-function isCanonicalArrayIndex(s) {
+export function isCanonicalArrayIndex(s) {
     // Canonical integer per RFC 6901 §4 + JSON canonical form: no leading zeros
     // except for "0" itself.
     if (s === '')

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/resources",
-  "version": "0.1.37",
+  "version": "0.1.39-rc.1",
   "description": "Markdown resource parsing, validation, and link integrity checking",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,11 +33,11 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "dependencies": {
-    "@vibe-agent-toolkit/agent-schema": "0.1.37",
-    "@vibe-agent-toolkit/utils": "0.1.37",
+    "@vibe-agent-toolkit/agent-schema": "0.1.39-rc.1",
+    "@vibe-agent-toolkit/utils": "0.1.39-rc.1",
     "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "github-slugger": "^2.0.0",
-    "js-yaml": "^4.1.1",
     "markdown-link-check": "^3.14.2",
     "picomatch": "^4.0.3",
     "remark-frontmatter": "^5.0.0",
@@ -46,10 +46,10 @@
     "semver": "^7.7.3",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
+    "yaml": "^2.6.1",
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.10.5",
     "@types/picomatch": "^4.0.2",

package/src/ajv-factory.ts

@@ -0,0 +1,56 @@
+/**
+ * Ajv factory for adopters consuming VAT-generated schemas.
+ *
+ * VAT's frontmatter walker treats `format: "uri-reference"` (plus `uri`,
+ * `iri`, `iri-reference`) as first-class URI families and validates the
+ * referenced files via {@link import('./utils.js').resolveLocalHref}, not via
+ * Ajv. But adopters consuming the same schemas with vanilla
+ * `new Ajv(...)` hit Ajv's default strict mode, which upgrades
+ * `unknown format "uri-reference" ignored` from a warning to a thrown error.
+ *
+ * This helper returns an Ajv instance with the standard JSON Schema format
+ * vocabulary registered (via `ajv-formats`) plus no-op shims for
+ * `iri` / `iri-reference` (which `ajv-formats` does not ship). All
+ * URI-family schemas compile cleanly under strict mode.
+ */
+
+import { Ajv, type Options as AjvOptions } from 'ajv';
+// ajv-formats is a CJS module published with `module.exports = formatsPlugin`
+// plus an `exports.default` alias. Under NodeNext module resolution the
+// default import is typed as the namespace object (not callable), even
+// though the runtime value IS the plugin function. The `.default ??
+// namespace` pattern below resolves both at type level and runtime.
+import * as ajvFormatsModule from 'ajv-formats';
+
+type AddFormatsFn = (ajv: Ajv) => Ajv;
+
+const addFormats: AddFormatsFn =
+  (ajvFormatsModule as unknown as { default?: AddFormatsFn }).default ??
+  (ajvFormatsModule as unknown as AddFormatsFn);
+
+/**
+ * Construct an Ajv instance pre-registered with the URI-family formats VAT
+ * schemas use. Use this anywhere downstream code compiles a schema that may
+ * reference `format: "uri-reference"` (or `uri`, `iri`, `iri-reference`).
+ *
+ * @param options - Ajv options. Passed through unchanged — caller controls
+ *   `allErrors`, `strict`, `allowUnionTypes`, `verbose`, etc.
+ *
+ * @example
+ * import { createAjvWithUriFormats } from '@vibe-agent-toolkit/resources';
+ *
+ * const ajv = createAjvWithUriFormats({ allErrors: true });
+ * const validate = ajv.compile(mySchemaWithUriReference);
+ * if (!validate(data)) console.error(validate.errors);
+ */
+export function createAjvWithUriFormats(options: AjvOptions = {}): Ajv {
+  const ajv = new Ajv(options);
+  addFormats(ajv);
+  // ajv-formats does not register `iri` / `iri-reference`. Adopters whose
+  // schemas declare those would still hit "unknown format" under strict
+  // mode. Register no-op validators — Ajv accepts the format token, and
+  // semantic validation happens through resolveLocalHref / equivalent.
+  ajv.addFormat('iri', true);
+  ajv.addFormat('iri-reference', true);
+  return ajv;
+}

package/src/config-parser.ts

@@ -5,58 +5,12 @@
  */
 
 import { readFile } from 'node:fs/promises';
-import path from 'node:path';
 
-import { safePath } from '@vibe-agent-toolkit/utils';
-import { CORE_SCHEMA, load as loadYaml } from 'js-yaml';
+import { findConfigFile } from '@vibe-agent-toolkit/utils';
+import { parse as parseYaml } from 'yaml';
 
 import { ProjectConfigSchema, type ProjectConfig } from './schemas/project-config.js';
 
-const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
-
-/**
- * Find the config file by walking up the directory tree.
- *
- * Starts from the current directory and walks up until the config file is found
- * or the root directory is reached.
- *
- * @param startDir - Directory to start searching from (default: process.cwd())
- * @returns Absolute path to config file, or undefined if not found
- *
- * @example
- * ```typescript
- * const configPath = await findConfigFile();
- * if (configPath) {
- *   console.log(`Found config: ${configPath}`);
- * }
- * ```
- */
-export async function findConfigFile(startDir: string = process.cwd()): Promise<string | undefined> {
-  let currentDir = safePath.resolve(startDir);
-  const { root } = path.parse(currentDir);
-
-  while (true) {
-    const configPath = safePath.join(currentDir, CONFIG_FILENAME);
-
-    try {
-      // Check if file exists by attempting to read metadata
-      // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructing path during tree walk
-      await readFile(configPath, 'utf-8');
-      return configPath;
-    } catch {
-      // File doesn't exist, continue walking up
-    }
-
-    // Check if we've reached the root
-    if (currentDir === root) {
-      return undefined;
-    }
-
-    // Move up one directory
-    currentDir = path.dirname(currentDir);
-  }
-}
-
 /**
  * Parse a project configuration file.
  *
@@ -81,8 +35,7 @@ export async function parseConfigFile(configPath: string): Promise<ProjectConfig
   // Parse YAML
   let parsed: unknown;
   try {
-    // CORE_SCHEMA: YAML 1.2 spec — see link-parser.ts for rationale.
-    parsed = loadYaml(content, { schema: CORE_SCHEMA });
+    parsed = parseYaml(content);
   } catch (error) {
     throw new Error(`Invalid YAML in config file: ${error instanceof Error ? error.message : String(error)}`);
   }
@@ -118,7 +71,8 @@ export async function parseConfigFile(configPath: string): Promise<ProjectConfig
  * ```
  */
 export async function loadConfig(startDir: string = process.cwd()): Promise<ProjectConfig | undefined> {
-  const configPath = await findConfigFile(startDir);
+  // findConfigFile from utils is synchronous; awaiting a non-promise is a no-op.
+  const configPath = findConfigFile(startDir);
   if (!configPath) {
     return undefined;
   }

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-link-validator.ts

@@ -7,22 +7,32 @@
  * 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 { walkFrontmatterUriReferences } from './schema-uri-walker.js';
 import type { HeadingNode, 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 {
   url: string;
@@ -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);
 }