@vibe-agent-toolkit/resources 0.1.2 → 0.1.4

package/src/frontmatter-validator.ts

@@ -0,0 +1,279 @@
+/**
+ * Frontmatter validation using JSON Schema.
+ *
+ * IMPORTANT: This module uses AJV specifically for validating arbitrary
+ * user-provided JSON Schemas against frontmatter data. For all TypeScript
+ * validation and internal schemas, use Zod instead.
+ *
+ * Why AJV here?
+ * - Users provide standard JSON Schema files for frontmatter validation
+ * - AJV is the industry standard JSON Schema validator
+ * - Zod is for TypeScript type safety + runtime validation
+ *
+ * This is the ONLY place in the codebase that should use AJV.
+ */
+
+import { Ajv } from 'ajv';
+
+import type { ValidationMode } from './schemas/project-config.js';
+import type { ValidationIssue } from './schemas/validation-result.js';
+
+/**
+ * Validate frontmatter against a JSON Schema.
+ *
+ * Behavior:
+ * - Missing frontmatter: Error only if schema has required fields
+ * - Extra fields: Allowed by default (unless schema sets additionalProperties: false)
+ * - Type mismatches: Always reported as errors
+ * - Permissive mode: Ignores additionalProperties: false (allows schema layering)
+ *
+ * @param frontmatter - Parsed frontmatter object (or undefined if no frontmatter)
+ * @param schema - JSON Schema object
+ * @param resourcePath - File path for error reporting
+ * @param mode - Validation mode: 'strict' (default) or 'permissive'
+ * @param schemaPath - Path to schema file (for error context)
+ * @returns Array of validation issues (empty if valid)
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   required: ['title'],
+ *   properties: { title: { type: 'string' } }
+ * };
+ * const issues = validateFrontmatter(
+ *   frontmatter,
+ *   schema,
+ *   '/docs/guide.md',
+ *   'strict',
+ *   '/schema.json'
+ * );
+ * ```
+ */
+export function validateFrontmatter(
+  frontmatter: Record<string, unknown> | undefined,
+  schema: object,
+  resourcePath: string,
+  mode: ValidationMode = 'strict',
+  schemaPath?: string
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // In permissive mode, clone schema and set additionalProperties: true
+  let effectiveSchema = schema;
+  if (mode === 'permissive') {
+    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
+  });
+
+  const validate = ajv.compile(effectiveSchema);
+
+  // Case 1: No frontmatter present
+  if (!frontmatter) {
+    // Check if schema requires any fields
+    const schemaRequires = (schema as { required?: string[] }).required;
+    if (schemaRequires && schemaRequires.length > 0) {
+      // Build context message with schema path and validation mode
+      const schemaContext = schemaPath ? ` (schema: ${schemaPath}, mode: ${mode})` : '';
+      const requiredFields = schemaRequires.join(', ');
+
+      issues.push({
+        resourcePath,
+        line: 1,
+        type: 'frontmatter_missing',
+        link: '',
+        message: `No frontmatter found in file. Schema requires: ${requiredFields}${schemaContext}`,
+      });
+    }
+    return issues;
+  }
+
+  // Case 2: Frontmatter present, validate against schema
+  const valid = validate(frontmatter);
+
+  if (valid || !validate.errors) {
+    return issues;
+  }
+
+  // Format validation errors with helpful messages
+  for (const error of validate.errors) {
+    const message = formatValidationError(error, frontmatter, mode, schemaPath);
+    issues.push({
+      resourcePath,
+      line: 1,
+      type: 'frontmatter_schema_error',
+      link: '',
+      message,
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Format AJV validation error into helpful message
+ *
+ * @param error - AJV error object
+ * @param frontmatter - Frontmatter data
+ * @param mode - Validation mode (strict/permissive)
+ * @param schemaPath - Path to schema file (for error context)
+ * @returns Formatted error message
+ */
+function formatValidationError(
+  error: { instancePath: string; keyword: string; message?: string; params?: Record<string, unknown> },
+  frontmatter: Record<string, unknown>,
+  mode: ValidationMode,
+  schemaPath?: string
+): string {
+  const field = error.instancePath.replace(/^\//, '') || 'root';
+  const fieldName = field === 'root' ? '(root)' : field;
+
+  // Get the actual invalid value
+  const actualValue = field === 'root' ? frontmatter : getNestedValue(frontmatter, field);
+  const actualValueStr = actualValue === undefined ? 'undefined' : JSON.stringify(actualValue);
+
+  let message = `Frontmatter validation failed for '${fieldName}' (got: ${actualValueStr})`;
+
+  // Add context based on error type
+  if (error.keyword === 'enum' && error.params?.['allowedValues']) {
+    const allowed = (error.params['allowedValues'] as unknown[])
+      .map((v: unknown) => JSON.stringify(v))
+      .join(', ');
+    message += `. Expected one of: ${allowed}`;
+  } else if (error.keyword === 'pattern' && error.params?.['pattern']) {
+    // Convert to string directly in template to avoid SonarQube warning
+    message += `. Must match pattern: ${JSON.stringify(error.params['pattern'])}`;
+  } else if (error.keyword === 'type' && error.params?.['type']) {
+    // Convert to string directly in template to avoid SonarQube warning
+    message += `. Expected type: ${JSON.stringify(error.params['type'])}`;
+  } else if (error.keyword === 'required' && error.params?.['missingProperty']) {
+    // Convert to string directly in template to avoid SonarQube warning
+    message += `. Missing required property: ${JSON.stringify(error.params['missingProperty'])}`;
+  } else if (error.message) {
+    message += `. ${error.message}`;
+  }
+
+  // Add schema context to help users understand the requirement
+  const schemaContext = schemaPath ? ` (schema: ${schemaPath}, mode: ${mode})` : '';
+  message += schemaContext;
+
+  return message;
+}
+
+/**
+ * Get nested value from object using dot-separated path
+ *
+ * @param obj - Object to get value from
+ * @param path - Dot-separated path (e.g., "user.name")
+ * @returns Value at path or undefined
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  // eslint-disable-next-line local/no-hardcoded-path-split -- JSON Schema instancePath uses forward slashes (not file paths)
+  const parts = path.split('/').filter(Boolean);
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (typeof current !== 'object' || current === null) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Clone schema and recursively set additionalProperties: true
+ *
+ * Used in permissive mode to allow extra fields for schema layering.
+ * Handles nested objects and properties recursively.
+ *
+ * @param schema - Original JSON Schema
+ * @returns Cloned schema with additionalProperties: true
+ */
+function makeSchemaPermissive(schema: object): object {
+  // Deep clone to avoid mutating original
+  const cloned = structuredClone(schema) as Record<string, unknown>;
+
+  // Recursively process schema to set additionalProperties: true
+  processSchemaRecursively(cloned);
+
+  return cloned;
+}
+
+/**
+ * Recursively process schema object to set additionalProperties: true
+ *
+ * @param obj - Schema object or nested schema fragment
+ */
+function processSchemaRecursively(obj: Record<string, unknown>): void {
+  // eslint-disable-next-line sonarjs/different-types-comparison
+  if (typeof obj !== 'object' || obj === null) {
+    return;
+  }
+
+  // Set additionalProperties: true if this is an object schema
+  const typeValue = obj['type'];
+  const isObjectType = typeValue === 'object';
+  const hasProperties = 'properties' in obj;
+
+  if (isObjectType || hasProperties) {
+    obj['additionalProperties'] = true;
+  }
+
+  // Recurse into properties
+  processSchemaProperties(obj);
+
+  // Recurse into nested schemas (allOf, anyOf, oneOf, items)
+  processNestedSchemas(obj);
+}
+
+/**
+ * Process properties field of a schema
+ *
+ * @param obj - Schema object
+ */
+function processSchemaProperties(obj: Record<string, unknown>): void {
+  if (obj['properties'] === undefined || typeof obj['properties'] !== 'object') {
+    return;
+  }
+
+  const properties = obj['properties'] as Record<string, unknown>;
+  for (const value of Object.values(properties)) {
+    if (typeof value === 'object' && value !== null) {
+      processSchemaRecursively(value as Record<string, unknown>);
+    }
+  }
+}
+
+/**
+ * Process nested schema keywords (allOf, anyOf, oneOf, items)
+ *
+ * @param obj - Schema object
+ */
+function processNestedSchemas(obj: Record<string, unknown>): void {
+  const nestedKeys = ['allOf', 'anyOf', 'oneOf', 'items'];
+
+  for (const key of nestedKeys) {
+    const value = obj[key];
+    if (value === undefined) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === 'object' && item !== null) {
+          processSchemaRecursively(item as Record<string, unknown>);
+        }
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      processSchemaRecursively(value as Record<string, unknown>);
+    }
+  }
+}

package/src/index.ts

@@ -32,6 +32,8 @@ export {
   type CrawlOptions,
   type ResourceRegistryOptions,
   type RegistryStats,
+  type CollectionStats,
+  type CollectionStat,
 } from './resource-registry.js';
 
 // Export ResourceQuery for lazy evaluation and filtering
@@ -49,9 +51,13 @@ export type {
   HeadingNode,
   ResourceLink,
   ResourceMetadata,
-  ValidationSeverity,
   ValidationIssue,
   ValidationResult,
+  ProjectConfig,
+  ResourcesConfig,
+  CollectionConfig,
+  CollectionValidation,
+  ValidationMode,
 } from './types.js';
 
 // Export schemas for external use (e.g., JSON Schema generation, runtime validation)
@@ -63,7 +69,6 @@ export {
 } from './schemas/resource-metadata.js';
 
 export {
-  ValidationSeveritySchema,
   ValidationIssueSchema,
   ValidationResultSchema,
 } from './schemas/validation-result.js';
@@ -71,5 +76,8 @@ export {
 // Export parser interface for advanced use cases
 export { parseMarkdown, type ParseResult } from './link-parser.js';
 
+// Export frontmatter validation
+export { validateFrontmatter } from './frontmatter-validator.js';
+
 // Note: link-parser and link-validator internals are NOT exported
 // They are implementation details. Users should use ResourceRegistry API.

package/src/link-parser.ts

@@ -11,6 +11,7 @@
 
 import { readFile, stat } from 'node:fs/promises';
 
+import * as yaml from 'js-yaml';
 import type { Heading, Link, LinkReference, Root } from 'mdast';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
@@ -26,6 +27,8 @@ import type { HeadingNode, LinkType, ResourceLink } from './types.js';
 export interface ParseResult {
   links: ResourceLink[];
   headings: HeadingNode[];
+  frontmatter?: Record<string, unknown>;
+  frontmatterError?: string;
   content: string;
   sizeBytes: number;
   estimatedTokenCount: number;
@@ -71,9 +74,16 @@ export async function parseMarkdown(filePath: string): Promise<ParseResult> {
   // Extract headings with tree structure
   const headings = extractHeadings(tree);
 
+  // Extract frontmatter
+  const { frontmatter, error: frontmatterError } = extractFrontmatter(tree);
+
+  // With exactOptionalPropertyTypes: true, we must conditionally include the property
+  // rather than assigning undefined to it
   return {
     links,
     headings,
+    ...(frontmatter !== undefined && { frontmatter }),
+    ...(frontmatterError !== undefined && { frontmatterError }),
     content,
     sizeBytes,
     estimatedTokenCount,
@@ -369,3 +379,43 @@ function cleanupEmptyChildren(headings: HeadingNode[]): void {
     }
   }
 }
+
+/**
+ * Extract and parse frontmatter from the markdown AST.
+ *
+ * Uses remark-frontmatter which creates 'yaml' nodes for frontmatter blocks.
+ * Parses YAML content and returns as plain object.
+ *
+ * @param tree - Markdown AST from unified/remark
+ * @returns Object with parsed frontmatter and any error message
+ */
+function extractFrontmatter(tree: Root): {
+  frontmatter?: Record<string, unknown>;
+  error?: string;
+} {
+  let frontmatterData: Record<string, unknown> | undefined;
+  let errorMessage: string | undefined;
+
+  visit(tree, 'yaml', (node: { value: string }) => {
+    if (node.value.trim() === '') {
+      // Empty frontmatter block
+      return;
+    }
+
+    try {
+      const parsed = yaml.load(node.value);
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        frontmatterData = parsed as Record<string, unknown>;
+      }
+    } catch (error) {
+      // Capture YAML parsing error for validation reporting
+      errorMessage = error instanceof Error ? error.message : String(error);
+    }
+  });
+
+  // With exactOptionalPropertyTypes: true, we must conditionally include properties
+  return {
+    ...(frontmatterData !== undefined && { frontmatter: frontmatterData }),
+    ...(errorMessage !== undefined && { error: errorMessage }),
+  };
+}

package/src/link-validator.ts

@@ -2,21 +2,39 @@
  * Link validation for markdown resources.
  *
  * Validates different types of links:
- * - local_file: Checks if file exists, validates anchors if present
+ * - local_file: Checks if file exists, validates anchors if present, checks git-ignore safety
  * - anchor: Validates heading exists in current or target file
  * - external: Returns info (not validated)
  * - email: Returns null (valid by default)
  * - unknown: Returns warning
+ *
+ * Git-ignore safety (Phase 3):
+ * - Non-ignored files cannot link to ignored files (error: link_to_gitignored)
+ * - Ignored files CAN link to ignored files (no error)
+ * - Ignored files CAN link to non-ignored files (no error)
+ * - External resources (outside project) skip git-ignore checks
  */
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { isGitignored } from '@vibe-agent-toolkit/utils';
+import { isGitIgnored, type GitTracker } from '@vibe-agent-toolkit/utils';
 
 import type { ValidationIssue } from './schemas/validation-result.js';
 import type { HeadingNode, ResourceLink } from './types.js';
-import { splitHrefAnchor } from './utils.js';
+import { isWithinProject, splitHrefAnchor } from './utils.js';
+
+/**
+ * Options for link validation.
+ */
+export interface ValidateLinkOptions {
+  /** Project root directory (for git-ignore checking) */
+  projectRoot?: string;
+  /** Skip git-ignore checks (optimization when checkGitIgnored is false) */
+  skipGitIgnoreCheck?: boolean;
+  /** Git tracker for efficient git-ignore checking (optional, improves performance) */
+  gitTracker?: GitTracker;
+}
 
 /**
  * Validate a single link in a markdown resource.
@@ -24,11 +42,15 @@ import { splitHrefAnchor } from './utils.js';
  * @param link - The link to validate
  * @param sourceFilePath - Absolute path to the file containing the link
  * @param headingsByFile - Map of file paths to their heading trees
+ * @param options - Validation options (projectRoot, skipGitIgnoreCheck)
  * @returns ValidationIssue if link is broken, null if valid
  *
  * @example
  * ```typescript
- * const issue = await validateLink(link, '/project/docs/guide.md', headingsMap);
+ * const issue = await validateLink(link, '/project/docs/guide.md', headingsMap, {
+ *   projectRoot: '/project',
+ *   skipGitIgnoreCheck: false
+ * });
  * if (issue) {
  *   console.log(`${issue.severity}: ${issue.message}`);
  * }
@@ -37,25 +59,19 @@ import { splitHrefAnchor } from './utils.js';
 export async function validateLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>
+  headingsByFile: Map<string, HeadingNode[]>,
+  options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
   switch (link.type) {
     case 'local_file':
-      return await validateLocalFileLink(link, sourceFilePath, headingsByFile);
+      return await validateLocalFileLink(link, sourceFilePath, headingsByFile, options);
 
     case 'anchor':
       return await validateAnchorLink(link, sourceFilePath, headingsByFile);
 
     case 'external':
-      // External URLs are not validated - return info
-      return {
-        severity: 'info',
-        resourcePath: sourceFilePath,
-        line: link.line,
-        type: 'external_url',
-        link: link.href,
-        message: 'External URL not validated',
-      };
+      // External URLs are not validated - don't report them
+      return null;
 
     case 'email':
       // Email links are valid by default
@@ -63,7 +79,6 @@ export async function validateLink(
 
     case 'unknown':
       return {
-        severity: 'warning',
         resourcePath: sourceFilePath,
         line: link.line,
         type: 'unknown_link',
@@ -85,7 +100,8 @@ export async function validateLink(
 async function validateLocalFileLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>
+  headingsByFile: Map<string, HeadingNode[]>,
+  options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
   // Extract file path and anchor from href
   const [filePath, anchor] = splitHrefAnchor(link.href);
@@ -95,28 +111,44 @@ async function validateLocalFileLink(
 
   if (!fileResult.exists) {
     return {
-      severity: 'error',
       resourcePath: sourceFilePath,
       line: link.line,
       type: 'broken_file',
       link: link.href,
       message: `File not found: ${fileResult.resolvedPath}`,
-      suggestion: 'Check that the file path is correct and the file exists',
+      suggestion: '',
     };
   }
 
-  // Check if the file is gitignored
-  if (fileResult.isGitignored) {
-    return {
-      severity: 'error',
-      resourcePath: sourceFilePath,
-      line: link.line,
-      type: 'broken_file',
-      link: link.href,
-      message: `File is gitignored: ${fileResult.resolvedPath}`,
-      suggestion:
-        'Gitignored files are local-only and will not exist in the repository. Remove this link or unignore the target 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)
+  ) {
+    // Use GitTracker if available (cached), otherwise fall back to isGitIgnored
+    const sourceIsIgnored = options.gitTracker
+      ? options.gitTracker.isIgnored(sourceFilePath)
+      : isGitIgnored(sourceFilePath, options.projectRoot);
+    const targetIsIgnored = options.gitTracker
+      ? options.gitTracker.isIgnored(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
@@ -129,13 +161,12 @@ async function validateLocalFileLink(
 
     if (!anchorValid) {
       return {
-        severity: 'error',
         resourcePath: sourceFilePath,
         line: link.line,
         type: 'broken_anchor',
         link: link.href,
         message: `Anchor not found: #${anchor} in ${fileResult.resolvedPath}`,
-        suggestion: 'Check that the heading exists in the target file',
+        suggestion: '',
       };
     }
   }
@@ -159,13 +190,12 @@ async function validateAnchorLink(
 
   if (!isValid) {
     return {
-      severity: 'error',
       resourcePath: sourceFilePath,
       line: link.line,
       type: 'broken_anchor',
       link: link.href,
       message: `Anchor not found: ${link.href}`,
-      suggestion: 'Check that the heading exists in this file',
+      suggestion: '',
     };
   }
 
@@ -174,16 +204,16 @@ async function validateAnchorLink(
 
 
 /**
- * Validate that a local file exists and is not gitignored.
+ * Validate that a local file exists.
  *
  * @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 gitignored flag
+ * @returns Object with exists flag and resolved absolute path
  *
  * @example
  * ```typescript
  * const result = await validateLocalFile('./docs/guide.md', '/project/README.md');
- * if (result.exists && !result.isGitignored) {
+ * if (result.exists) {
  *   console.log('File exists at:', result.resolvedPath);
  * }
  * ```
@@ -191,7 +221,7 @@ async function validateAnchorLink(
 async function validateLocalFile(
   href: string,
   sourceFilePath: string
-): Promise<{ exists: boolean; resolvedPath: string; isGitignored: boolean }> {
+): Promise<{ exists: boolean; resolvedPath: string }> {
   // Resolve the path relative to the source file's directory
   const sourceDir = path.dirname(sourceFilePath);
   const resolvedPath = path.resolve(sourceDir, href);
@@ -205,10 +235,7 @@ async function validateLocalFile(
     exists = false;
   }
 
-  // Check if file is gitignored (only if it exists)
-  const gitignored = exists && isGitignored(resolvedPath);
-
-  return { exists, resolvedPath, isGitignored: gitignored };
+  return { exists, resolvedPath };
 }
 
 /**