@vibe-agent-toolkit/resources 0.1.36 → 0.1.38

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,7 +431,7 @@ function extractFrontmatter(tree: Root): {
     }
 
     try {
-      const parsed = yaml.load(node.value);
+      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) {

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/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,7 +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');
-  const data = yaml.load(content);
+  const data = yaml.parse(content);
 
   // Calculate checksum
   const checksum = await calculateChecksum(absolutePath);

package/src/types.ts

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