@vibe-agent-toolkit/resources 0.1.3 → 0.1.5

package/src/link-validator.ts

@@ -2,21 +2,42 @@
  * 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,
+  verifyCaseSensitiveFilename,
+} 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 +45,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 +62,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 +82,6 @@ export async function validateLink(
 
     case 'unknown':
       return {
-        severity: 'warning',
         resourcePath: sourceFilePath,
         line: link.line,
         type: 'unknown_link',
@@ -85,7 +103,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);
@@ -94,29 +113,58 @@ async function validateLocalFileLink(
   const fileResult = await validateLocalFile(filePath, 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}"`,
+      };
+    }
+
     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 +177,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 +206,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,41 +220,44 @@ async function validateAnchorLink(
 
 
 /**
- * Validate that a local file exists and is not gitignored.
+ * 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 gitignored flag
+ * @returns Object with exists flag, resolved absolute path, and optional case mismatch info
  *
  * @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);
+ * } else if (result.actualName) {
+ *   console.log('Case mismatch:', result.actualName);
  * }
  * ```
  */
 async function validateLocalFile(
   href: string,
   sourceFilePath: string
-): Promise<{ exists: boolean; resolvedPath: string; isGitignored: boolean }> {
+): Promise<{ exists: boolean; resolvedPath: string; actualName?: string }> {
   // Resolve the path relative to the source file's directory
   const sourceDir = path.dirname(sourceFilePath);
   const resolvedPath = path.resolve(sourceDir, href);
 
-  // Check if file exists
-  let exists = false;
-  try {
-    await fs.access(resolvedPath, fs.constants.F_OK);
-    exists = true;
-  } catch {
-    exists = false;
-  }
+  // Check if file exists with correct case
+  const verification = await verifyCaseSensitiveFilename(resolvedPath);
 
-  // Check if file is gitignored (only if it exists)
-  const gitignored = exists && isGitignored(resolvedPath);
+  // Build result with optional actualName (only include if present)
+  const result: { exists: boolean; resolvedPath: string; actualName?: string } = {
+    exists: verification.exists,
+    resolvedPath,
+  };
+
+  if (verification.actualName) {
+    result.actualName = verification.actualName;
+  }
 
-  return { exists, resolvedPath, isGitignored: gitignored };
+  return result;
 }
 
 /**

package/src/multi-schema-validator.ts

@@ -0,0 +1,128 @@
+/**
+ * Multi-schema validation for resources
+ *
+ * Validates a resource against multiple schemas from different sources,
+ * tracking validation results per schema.
+ *
+ * Supports validation modes:
+ * - strict: Enforce schema exactly (respect additionalProperties: false)
+ * - permissive: Allow extra fields (schema layering use case)
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { validateFrontmatter } from './frontmatter-validator.js';
+import type { ValidationMode } from './schemas/project-config.js';
+import type { ValidationIssue } from './schemas/validation-result.js';
+import type { SchemaReference } from './types/resources.js';
+
+/**
+ * Load a JSON Schema from a file path
+ *
+ * @param schemaPath - Path to JSON Schema file
+ * @param projectRoot - Optional project root for resolving relative paths
+ * @returns Parsed JSON Schema object
+ */
+async function loadSchema(schemaPath: string, projectRoot?: string): Promise<object> {
+  let resolvedPath = schemaPath;
+
+  // If path is relative and we have a project root, resolve it
+  if (!path.isAbsolute(schemaPath) && projectRoot) {
+    resolvedPath = path.join(projectRoot, schemaPath);
+  }
+
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const content = await fs.readFile(resolvedPath, 'utf-8');
+  return JSON.parse(content) as object;
+}
+
+/**
+ * Validate frontmatter against multiple schemas
+ *
+ * Each schema is validated independently and results are tracked separately.
+ * The resource-level validation status: fails if ANY schema fails.
+ *
+ * @param frontmatter - Parsed frontmatter object (or undefined if no frontmatter)
+ * @param schemas - Schema references to validate against
+ * @param resourcePath - File path for error reporting
+ * @param mode - Validation mode (strict or permissive)
+ * @param projectRoot - Optional project root for resolving relative schema paths
+ * @returns Updated schema references with validation results
+ */
+export async function validateFrontmatterMultiSchema(
+  frontmatter: Record<string, unknown> | undefined,
+  schemas: SchemaReference[],
+  resourcePath: string,
+  mode: ValidationMode,
+  projectRoot?: string,
+): Promise<SchemaReference[]> {
+  const results: SchemaReference[] = [];
+
+  for (const schemaRef of schemas) {
+    try {
+      // Load schema
+      const schema = await loadSchema(schemaRef.schema, projectRoot);
+
+      // Validate frontmatter
+      const issues = validateFrontmatter(frontmatter, schema, resourcePath, mode);
+
+      // Update schema reference with results
+      const result: SchemaReference = {
+        ...schemaRef,
+        applied: true,
+        valid: issues.length === 0,
+      };
+
+      // Only set errors if there are any (exactOptionalPropertyTypes)
+      if (issues.length > 0) {
+        result.errors = issues;
+      }
+
+      results.push(result);
+    } catch (error) {
+      // Schema loading or validation failed
+      const message = error instanceof Error ? error.message : String(error);
+      results.push({
+        ...schemaRef,
+        applied: true,
+        valid: false,
+        errors: [{
+          resourcePath,
+          line: 1,
+          type: 'frontmatter_schema_error',
+          link: '',
+          message: `Failed to load or validate schema ${schemaRef.schema}: ${message}`,
+        }],
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Check if any schema validation failed
+ *
+ * @param schemas - Schema references with validation results
+ * @returns True if any schema failed validation
+ */
+export function hasSchemaErrors(schemas: SchemaReference[]): boolean {
+  return schemas.some((ref) => ref.valid === false);
+}
+
+/**
+ * Get all validation errors from all schemas
+ *
+ * @param schemas - Schema references with validation results
+ * @returns Flat array of all validation issues
+ */
+export function getAllSchemaErrors(schemas: SchemaReference[]): ValidationIssue[] {
+  const allErrors: ValidationIssue[] = [];
+  for (const ref of schemas) {
+    if (ref.errors) {
+      allErrors.push(...ref.errors);
+    }
+  }
+  return allErrors;
+}

package/src/pattern-expander.ts

@@ -0,0 +1,100 @@
+/**
+ * Pattern expansion utilities for converting paths to glob patterns.
+ *
+ * Expands directory paths to glob patterns while preserving explicit glob patterns.
+ */
+
+const DEFAULT_EXTENSIONS = '**/*.{md,json}';
+
+/**
+ * Check if a string is a glob pattern or a plain path.
+ *
+ * A string is considered a glob pattern if it contains glob metacharacters.
+ *
+ * @param pattern - String to check
+ * @returns True if string contains glob metacharacters
+ *
+ * @example
+ * ```typescript
+ * isGlobPattern('docs')                    // false
+ * isGlobPattern('docs/**\/*.md')           // true
+ * isGlobPattern('**\/*.json')              // true
+ * isGlobPattern('path/to/file.md')         // false
+ * ```
+ */
+export function isGlobPattern(pattern: string): boolean {
+  return /[*?[\]{}]/.test(pattern);
+}
+
+/**
+ * Expand a path to a glob pattern.
+ *
+ * - If input already starts with **\/ or is absolute (starts with /), return as-is
+ * - If input is a glob pattern without **\/, prepend **\/ to match absolute paths
+ * - If input is a path, expand to **\/path/**\/*.{md,json}
+ * - Trailing slashes are stripped before expansion
+ * - The **\/ prefix ensures patterns match absolute paths from any location
+ *
+ * Note: Patterns are expected to use forward slashes. Use toForwardSlash() on paths before
+ * passing to this function if they might contain backslashes (Windows).
+ *
+ * @param pathOrPattern - Path or glob pattern (with forward slashes)
+ * @returns Expanded glob pattern
+ *
+ * @example
+ * ```typescript
+ * expandPattern('docs')                    // '**\/docs/**\/*.{md,json}'
+ * expandPattern('docs/')                   // '**\/docs/**\/*.{md,json}'
+ * expandPattern('docs/**\/*.md')           // '**\/docs/**\/*.md' (prepend **\/)
+ * expandPattern('**\/*.schema.json')       // '**\/*.schema.json' (unchanged)
+ * expandPattern('*.md')                    // '*.md' (root-level pattern, no prefix)
+ * ```
+ */
+export function expandPattern(pathOrPattern: string): string {
+  // Note: This function expects pattern strings (from config), not file paths.
+  // Pattern strings from YAML config should already use forward slashes (YAML standard).
+  // This function doesn't normalize because it operates on pattern syntax, not paths.
+
+  // If already starts with **/ or is absolute, return as-is
+  // Pattern strings are always forward-slash based (YAML/config standard)
+  // eslint-disable-next-line local/no-path-startswith -- checking pattern syntax, not paths
+  if (pathOrPattern.startsWith('**/') || pathOrPattern.startsWith('/')) {
+    return pathOrPattern;
+  }
+
+  // If it's a glob pattern
+  if (isGlobPattern(pathOrPattern)) {
+    // Root-level patterns (*.md, *.json) should match only root level
+    // These are purely glob metacharacters, not paths
+    // eslint-disable-next-line local/no-path-startswith -- checking pattern syntax, not paths
+    if (pathOrPattern.startsWith('*')) {
+      return pathOrPattern;
+    }
+    // Other glob patterns need **/ prefix to match absolute paths
+    return `**/${pathOrPattern}`;
+  }
+
+  // Strip trailing slash for plain paths
+  const normalizedPath = pathOrPattern.replace(/\/$/, '');
+
+  // Expand path to pattern with **/ prefix for absolute path matching
+  return `**/${normalizedPath}/${DEFAULT_EXTENSIONS}`;
+}
+
+/**
+ * Expand an array of paths/patterns to glob patterns.
+ *
+ * Each item is processed individually using expandPattern().
+ *
+ * @param patterns - Array of paths or glob patterns
+ * @returns Array of expanded glob patterns
+ *
+ * @example
+ * ```typescript
+ * expandPatterns(['docs', 'src/**\/*.ts', 'README.md'])
+ * // ['docs/**\/*.{md,json}', 'src/**\/*.ts', 'README.md/**\/*.{md,json}']
+ * ```
+ */
+export function expandPatterns(patterns: string[]): string[] {
+  return patterns.map(expandPattern);
+}