@vibe-agent-toolkit/resources 0.1.35 → 0.1.36

package/src/frontmatter-link-validator.ts

@@ -0,0 +1,112 @@
+/**
+ * Frontmatter URI-reference link validation.
+ *
+ * For every value in `frontmatter` sitting at a JSON Schema position with a
+ * URI-family `format`, classify the value and run local-file references
+ * through the existing `validateLink` engine. Returns issues with
+ * 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
+ *
+ * Skipped (no issue, no external):
+ *   email (mailto:)
+ *   anchor-only (validated as anchor in current file via validateLink)
+ */
+
+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';
+
+/** A frontmatter-sourced external URL captured for downstream health checking. */
+export interface FrontmatterExternalUrl {
+  url: string;
+  sourcePath: string;
+  dottedPath: string;
+}
+
+export interface FrontmatterLinkValidationResult {
+  issues: ValidationIssue[];
+  externalUrls: FrontmatterExternalUrl[];
+}
+
+/**
+ * Validate every URI-family frontmatter value against the file system.
+ *
+ * @param frontmatter - Parsed frontmatter (or undefined)
+ * @param schema - JSON Schema for the collection
+ * @param sourceFilePath - Absolute path to the source file
+ * @param headingsByFile - Heading trees (for anchor validation)
+ * @param options - Same shape as validateLink (projectRoot, gitTracker, ...)
+ */
+export async function validateFrontmatterLinks(
+  frontmatter: Record<string, unknown> | undefined,
+  schema: object,
+  sourceFilePath: string,
+  headingsByFile: Map<string, HeadingNode[]>,
+  options?: ValidateLinkOptions,
+): Promise<FrontmatterLinkValidationResult> {
+  if (!frontmatter) return { issues: [], externalUrls: [] };
+
+  const captures = walkFrontmatterUriReferences(frontmatter, schema);
+  if (captures.length === 0) return { issues: [], externalUrls: [] };
+
+  const issues: ValidationIssue[] = [];
+  const externalUrls: FrontmatterExternalUrl[] = [];
+
+  for (const capture of captures) {
+    const linkType = classifyLink(capture.value);
+
+    if (linkType === 'external') {
+      externalUrls.push({
+        url: capture.value,
+        sourcePath: sourceFilePath,
+        dottedPath: capture.dottedPath,
+      });
+      continue;
+    }
+    if (linkType === 'email') continue;
+
+    const syntheticLink: ResourceLink = {
+      text: capture.dottedPath,
+      href: capture.value,
+      type: linkType,
+      line: 1, // Frontmatter per-field line numbers are post-v1.
+    };
+
+    const issue = await validateLink(syntheticLink, sourceFilePath, headingsByFile, options);
+    if (!issue) continue;
+
+    issues.push(rewriteIssue(issue, capture.dottedPath));
+  }
+
+  return { issues, externalUrls };
+}
+
+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;
+  }
+}

package/src/link-parser.ts

@@ -169,7 +169,11 @@ function extractLinkText(node: Link | LinkReference): string {
 }
 
 /**
- * Classify a link based on its href.
+ * Classify a link based on its href shape.
+ *
+ * Public so frontmatter-link validation can reuse identical URI classification
+ * logic (markdown links and frontmatter URI-reference values share one
+ * classifier).
  *
  * @param href - The href attribute from the link
  * @returns Classified link type
@@ -183,7 +187,7 @@ function extractLinkText(node: Link | LinkReference): string {
  * classifyLink('./file.md#anchor') // 'local_file'
  * ```
  */
-function classifyLink(href: string): LinkType {
+export function classifyLink(href: string): LinkType {
   if (href.startsWith('http://') || href.startsWith('https://')) {
     return 'external';
   }

package/src/resource-registry.ts

@@ -11,14 +11,18 @@
 import type fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { crawlDirectory, type CrawlOptions as UtilsCrawlOptions, type GitTracker, normalizedTmpdir, toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
+import { crawlDirectory, type CrawlOptions as UtilsCrawlOptions, type GitTracker, normalizedTmpdir, resolveAssetReference, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 
 import { calculateChecksum } from './checksum.js';
 import { getCollectionsForFile } from './collection-matcher.js';
 import { ExternalLinkValidator } from './external-link-validator.js';
+import {
+  validateFrontmatterLinks,
+  type FrontmatterExternalUrl,
+} from './frontmatter-link-validator.js';
 import { validateFrontmatter } from './frontmatter-validator.js';
 import { parseMarkdown } from './link-parser.js';
-import { validateLink } from './link-validator.js';
+import { validateLink, type ValidateLinkOptions } from './link-validator.js';
 import type { ResourceCollectionInterface } from './resource-collection-interface.js';
 import type { SHA256 } from './schemas/checksum.js';
 import type { ProjectConfig } from './schemas/project-config.js';
@@ -150,6 +154,13 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   private readonly resourcesByName: Map<string, ResourceMetadata[]> = new Map();
   private readonly resourcesByChecksum: Map<SHA256, ResourceMetadata[]> = new Map();
 
+  /**
+   * Frontmatter-sourced external URLs keyed by resource absolute path.
+   * Populated during collection-schema validation; consumed by
+   * collectExternalUrls so the URLs feed into the existing health-check pass.
+   */
+  private readonly frontmatterExternalUrlsByResource: Map<string, FrontmatterExternalUrl[]> = new Map();
+
   constructor(options?: ResourceRegistryOptions) {
     if (options?.baseDir !== undefined) {
       this.baseDir = options.baseDir;
@@ -479,7 +490,10 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    * Validate frontmatter against per-collection schemas.
    * @private
    */
-  private async validateCollectionFrontmatter(): Promise<ValidationIssue[]> {
+  private async validateCollectionFrontmatter(
+    headingsByFile: Map<string, HeadingNode[]>,
+    skipGitIgnoreCheck: boolean,
+  ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
 
     // Skip if no config
@@ -498,7 +512,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       // Validate against each collection's schema
       const collectionIssues = await this.validateResourceCollectionSchemas(
         resource,
-        fsPromises
+        fsPromises,
+        headingsByFile,
+        skipGitIgnoreCheck,
       );
       issues.push(...collectionIssues);
     }
@@ -512,7 +528,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    */
   private async validateResourceCollectionSchemas(
     resource: ResourceMetadata,
-    fsModule: typeof fs
+    fsModule: typeof fs,
+    headingsByFile: Map<string, HeadingNode[]>,
+    skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
 
@@ -531,7 +549,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       const collectionIssues = await this.validateAgainstCollectionSchema(
         resource,
         collection.validation,
-        fsModule
+        fsModule,
+        headingsByFile,
+        skipGitIgnoreCheck,
       );
       issues.push(...collectionIssues);
     }
@@ -546,15 +566,17 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   private async validateAgainstCollectionSchema(
     resource: ResourceMetadata,
     validation: NonNullable<NonNullable<ProjectConfig['resources']>['collections']>[string]['validation'],
-    fsModule: typeof fs
+    fsModule: typeof fs,
+    headingsByFile: Map<string, HeadingNode[]>,
+    skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     if (!validation?.frontmatterSchema) {
       return [];
     }
 
-    const schemaPath = safePath.resolve(
+    const schemaPath = resolveAssetReference(
+      validation.frontmatterSchema,
       this.baseDir ?? process.cwd(),
-      validation.frontmatterSchema
     );
 
     try {
@@ -564,14 +586,41 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       // Determine validation mode (default to permissive)
       const mode = validation.mode ?? 'permissive';
 
-      // Validate frontmatter
-      return validateFrontmatter(
+      // Validate frontmatter against JSON Schema
+      const issues = validateFrontmatter(
         resource.frontmatter,
         schema,
         resource.filePath,
         mode,
-        schemaPath
+        schemaPath,
       );
+
+      // New: walk URI-family frontmatter values. Default-on; explicit `false` disables.
+      if (validation.checkFrontmatterLinks !== false && resource.frontmatter) {
+        const linkOptions: ValidateLinkOptions = this.baseDir === undefined
+          ? { skipGitIgnoreCheck }
+          : {
+              projectRoot: this.baseDir,
+              skipGitIgnoreCheck,
+              ...(this.gitTracker !== undefined && { gitTracker: this.gitTracker }),
+            };
+
+        const { issues: linkIssues, externalUrls } = await validateFrontmatterLinks(
+          resource.frontmatter,
+          schema,
+          resource.filePath,
+          headingsByFile,
+          linkOptions,
+        );
+        issues.push(...linkIssues);
+
+        if (externalUrls.length > 0) {
+          const prior = this.frontmatterExternalUrlsByResource.get(resource.filePath) ?? [];
+          this.frontmatterExternalUrlsByResource.set(resource.filePath, [...prior, ...externalUrls]);
+        }
+      }
+
+      return issues;
     } catch (error) {
       // Handle missing or invalid schema files gracefully
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -622,6 +671,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Build headings map for validation
     const headingsByFile = this.buildHeadingsByFileMap();
 
+    // Reset frontmatter external URL state for this validation run
+    this.frontmatterExternalUrlsByResource.clear();
+
     // Collect all validation issues
     const issues: ValidationIssue[] = [];
 
@@ -636,7 +688,10 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     issues.push(...linkIssues);
 
     // Per-collection frontmatter validation
-    const collectionFrontmatterIssues = await this.validateCollectionFrontmatter();
+    const collectionFrontmatterIssues = await this.validateCollectionFrontmatter(
+      headingsByFile,
+      options?.skipGitIgnoreCheck ?? false,
+    );
     issues.push(...collectionFrontmatterIssues);
 
     // Global frontmatter validation (if schema provided)
@@ -743,6 +798,15 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       }
     }
 
+    // Merge frontmatter-sourced external URLs from collection validation
+    for (const [resourcePath, urls] of this.frontmatterExternalUrlsByResource) {
+      for (const fmUrl of urls) {
+        const locations = urlsToValidate.get(fmUrl.url) ?? [];
+        locations.push({ resourcePath });
+        urlsToValidate.set(fmUrl.url, locations);
+      }
+    }
+
     return urlsToValidate;
   }
 

package/src/schema-uri-walker.ts

@@ -0,0 +1,222 @@
+/**
+ * Pure schema/data traversal that captures every string value sitting at a
+ * JSON Schema position whose `format` is in the URI family.
+ *
+ * Handles:
+ *  - `properties` (recursion)
+ *  - `items` (single-schema and tuple)
+ *  - `oneOf` / `anyOf` / `allOf` (every branch walked) AND sibling keywords
+ *    in the same node (JSON Schema AND semantics)
+ *  - `$ref` (resolved against schema root via JSON Pointer; cycle-protected)
+ *  - `definitions` and `$defs` as ref targets
+ *
+ * Does NOT handle (intentional, see spec §"Non-Goals"):
+ *  - `if`/`then`/`else`, `dependentSchemas`
+ *  - `patternProperties`, schema-form `additionalProperties`
+ *  - `prefixItems` (JSON Schema 2020-12)
+ *
+ * Captures are deduplicated by `(pointer, value)` before return so that
+ * multiple matching composite branches don't produce duplicate issues.
+ *
+ * No I/O. No side effects.
+ */
+
+import { decodeJsonPointerSegment, encodeJsonPointerSegment, formatJsonPointerAsDotted } from './utils.js';
+
+const URI_FAMILY_FORMATS = new Set<UriFamilyFormat>([
+  'uri-reference',
+  'uri',
+  'iri-reference',
+  'iri',
+]);
+
+export type UriFamilyFormat = 'uri' | 'uri-reference' | 'iri' | 'iri-reference';
+
+export interface FrontmatterUriCapture {
+  /** Raw string value from frontmatter */
+  value: string;
+  /** RFC 6901 JSON Pointer to the value within the frontmatter document */
+  pointer: string;
+  /** Developer-friendly dotted form (e.g., adr-citations[0].adr) */
+  dottedPath: string;
+  /** The URI-family format keyword present on the schema node */
+  format: UriFamilyFormat;
+}
+
+interface SchemaNode {
+  type?: string | string[];
+  format?: string;
+  properties?: Record<string, SchemaNode>;
+  items?: SchemaNode | SchemaNode[];
+  oneOf?: SchemaNode[];
+  anyOf?: SchemaNode[];
+  allOf?: SchemaNode[];
+  $ref?: string;
+  // $defs / definitions / etc. are arbitrary root-level keys reached via $ref.
+  [key: string]: unknown;
+}
+
+/**
+ * Walk a frontmatter document against a JSON Schema and return every value
+ * whose schema position has a URI-family `format` keyword.
+ */
+export function walkFrontmatterUriReferences(
+  data: unknown,
+  schema: object,
+): FrontmatterUriCapture[] {
+  if (data === undefined || data === null) return [];
+  const captures: FrontmatterUriCapture[] = [];
+  walk(data, schema as SchemaNode, schema as SchemaNode, [], new Set<string>(), captures);
+  return dedupe(captures);
+}
+
+function walkComposites(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  for (const branchList of [node.oneOf, node.anyOf, node.allOf]) {
+    if (Array.isArray(branchList)) {
+      for (const branch of branchList) {
+        walk(data, branch, root, pointerSegments, visitedRefs, captures);
+      }
+    }
+  }
+}
+
+function walkProperties(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  if (!node.properties || data === null || typeof data !== 'object' || Array.isArray(data)) return;
+  const dataObj = data as Record<string, unknown>;
+  for (const [key, propSchema] of Object.entries(node.properties)) {
+    if (key in dataObj) {
+      walk(
+        dataObj[key],
+        propSchema,
+        root,
+        [...pointerSegments, encodeJsonPointerSegment(key)],
+        visitedRefs,
+        captures,
+      );
+    }
+  }
+}
+
+function walkItems(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  if (!node.items || !Array.isArray(data)) return;
+  if (Array.isArray(node.items)) {
+    const tupleSchemas = node.items;
+    for (const [i, itemValue] of data.entries()) {
+      if (i >= tupleSchemas.length) break;
+      walk(itemValue, tupleSchemas[i] as SchemaNode, root, [...pointerSegments, String(i)], visitedRefs, captures);
+    }
+  } else {
+    for (const [i, itemValue] of data.entries()) {
+      walk(itemValue, node.items, root, [...pointerSegments, String(i)], visitedRefs, captures);
+    }
+  }
+}
+
+function walk(
+  data: unknown,
+  node: SchemaNode,
+  root: SchemaNode,
+  pointerSegments: string[],
+  visitedRefs: Set<string>,
+  captures: FrontmatterUriCapture[],
+): void {
+  if (!node || typeof node !== 'object') return;
+
+  // Resolve $ref against schema root. Cycle protection: skip if already on the
+  // recursion stack. Pop after recursion.
+  if (typeof node.$ref === 'string') {
+    if (visitedRefs.has(node.$ref)) return;
+    const resolved = resolveRef(node.$ref, root);
+    if (!resolved) return;
+    visitedRefs.add(node.$ref);
+    walk(data, resolved, root, pointerSegments, visitedRefs, captures);
+    visitedRefs.delete(node.$ref);
+    return;
+  }
+
+  // Composite schemas: walk every branch. CRITICAL: do NOT short-circuit;
+  // sibling `properties`/`items` are AND-combined with the composite.
+  walkComposites(data, node, root, pointerSegments, visitedRefs, captures);
+
+  // URI-family format leaf
+  if (
+    typeof node.format === 'string' &&
+    URI_FAMILY_FORMATS.has(node.format as UriFamilyFormat) &&
+    typeof data === 'string'
+  ) {
+    const pointer = pointerSegments.length === 0 ? '' : '/' + pointerSegments.join('/');
+    captures.push({
+      value: data,
+      pointer,
+      dottedPath: formatJsonPointerAsDotted(pointer),
+      format: node.format as UriFamilyFormat,
+    });
+    // Fall through — schemas with both `format` and sibling object/array
+    // structure are unusual but possible; let recursion proceed.
+  }
+
+  // Object recursion
+  walkProperties(data, node, root, pointerSegments, visitedRefs, captures);
+
+  // Array recursion
+  walkItems(data, node, root, pointerSegments, visitedRefs, captures);
+
+  // Intentionally NOT handled: if/then/else, dependentSchemas, patternProperties,
+  // schema-form additionalProperties, prefixItems (2020-12). See spec §"Non-Goals".
+}
+
+/**
+ * Resolve a local $ref (e.g., "#/$defs/Foo") against the schema root using a
+ * generic JSON Pointer walk. Returns null for unresolvable refs or non-local
+ * refs (no cross-file support in v1).
+ */
+function resolveRef(ref: string, root: SchemaNode): SchemaNode | null {
+  if (!ref.startsWith('#/')) return null;
+  // eslint-disable-next-line local/no-hardcoded-path-split -- RFC 6901 JSON Pointer segment splitting, not a file path
+  const segments = ref.slice(2).split('/').map(decodeJsonPointerSegment);
+  let cursor: unknown = root;
+  for (const seg of segments) {
+    if (cursor === null || typeof cursor !== 'object') return null;
+    cursor = (cursor as Record<string, unknown>)[seg];
+    if (cursor === undefined) return null;
+  }
+  return (cursor as SchemaNode) ?? null;
+}
+
+/**
+ * Remove duplicate captures by (pointer, value). Multiple matching branches
+ * of `oneOf`/`anyOf`/`allOf` can produce duplicates; users should see one
+ * issue per field, not one per branch.
+ */
+function dedupe(captures: FrontmatterUriCapture[]): FrontmatterUriCapture[] {
+  const seen = new Set<string>();
+  const out: FrontmatterUriCapture[] = [];
+  for (const c of captures) {
+    const key = c.pointer + ' ' + c.value;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(c);
+  }
+  return out;
+}

package/src/schemas/project-config.ts

@@ -61,6 +61,8 @@ export const CollectionValidationSchema = z.object({
     .describe('Whether to validate external URL links (default: false)'),
   checkGitIgnored: z.boolean().optional()
     .describe('Whether to check if non-ignored files link to git-ignored files (default: true)'),
+  checkFrontmatterLinks: z.boolean().optional()
+    .describe('Whether to validate frontmatter values at JSON Schema positions with a URI-family format (default: true). Set to false to disable for this collection.'),
   externalUrls: ExternalUrlValidationSchema.optional()
     .describe('External URL validation configuration'),
 }).describe('Validation configuration for a collection');

package/src/types.ts

@@ -110,6 +110,7 @@ export {
 // Link validation
 export type { ValidateLinkOptions } from './link-validator.js';
 export { validateLink } from './link-validator.js';
+export { classifyLink } from './link-parser.js';
 
 // Schema assignment
 export {
@@ -124,3 +125,10 @@ export {
   hasSchemaErrors,
   validateFrontmatterMultiSchema,
 } from './multi-schema-validator.js';
+
+// Frontmatter link validation
+export type {
+  FrontmatterExternalUrl,
+  FrontmatterLinkValidationResult,
+} from './frontmatter-link-validator.js';
+export { validateFrontmatterLinks } from './frontmatter-link-validator.js';

package/src/utils.ts

@@ -156,3 +156,57 @@ export function isWithinProject(filePath: string, projectRoot: string): boolean
   // /project-other starting with /project
   return normalizedFile.startsWith(normalizedRoot + '/') || normalizedFile === normalizedRoot;
 }
+
+/**
+ * Escape a property name as a JSON Pointer segment per RFC 6901:
+ * `~` -> `~0`, `/` -> `~1`. Order matters (escape `~` first).
+ */
+export function encodeJsonPointerSegment(name: string): string {
+  return name.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+/**
+ * Reverse RFC 6901 escapes: `~1` -> `/`, `~0` -> `~`. Order matters
+ * (unescape `~1` first).
+ */
+export function decodeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+/**
+ * Format a JSON Pointer (RFC 6901) as developer-friendly dotted notation.
+ *
+ * Numeric segments become bracketed array indices (`0` → `[0]`); non-numeric
+ * segments are dot-joined. Reverses RFC 6901 escapes inside segments.
+ *
+ * @example
+ *   formatJsonPointerAsDotted('/adr-citations/0/adr')  // 'adr-citations[0].adr'
+ *   formatJsonPointerAsDotted('')                       // ''
+ */
+export function formatJsonPointerAsDotted(pointer: string): string {
+  if (pointer === '') return '';
+  // eslint-disable-next-line local/no-hardcoded-path-split -- JSON Pointer RFC 6901 delimiter, not a file path
+  const segments = pointer.slice(1).split('/').map(decodeJsonPointerSegment);
+
+  let out = '';
+  for (const seg of segments) {
+    if (isCanonicalArrayIndex(seg)) {
+      out += `[${seg}]`;
+    } else {
+      out += out === '' ? seg : `.${seg}`;
+    }
+  }
+  return out;
+}
+
+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;
+  if (s === '0') return true;
+  if (s.startsWith('0')) return false;
+  for (const ch of s) {
+    if (ch < '0' || ch > '9') return false;
+  }
+  return true;
+}