@vibe-agent-toolkit/resources 0.1.2 → 0.1.4

package/dist/frontmatter-validator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 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 declare function validateFrontmatter(frontmatter: Record<string, unknown> | undefined, schema: object, resourcePath: string, mode?: ValidationMode, schemaPath?: string): ValidationIssue[];
+//# sourceMappingURL=frontmatter-validator.d.ts.map

package/dist/frontmatter-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-validator.d.ts","sourceRoot":"","sources":["../src/frontmatter-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAChD,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,cAAyB,EAC/B,UAAU,CAAC,EAAE,MAAM,GAClB,eAAe,EAAE,CA0DnB"}

package/dist/frontmatter-validator.js

@@ -0,0 +1,238 @@
+/**
+ * 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';
+/**
+ * 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, schema, resourcePath, mode = 'strict', schemaPath) {
+    const issues = [];
+    // 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.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, frontmatter, mode, schemaPath) {
+    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']
+            .map((v) => 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, path) {
+    // 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 = obj;
+    for (const part of parts) {
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        current = current[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) {
+    // Deep clone to avoid mutating original
+    const cloned = structuredClone(schema);
+    // 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) {
+    // 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) {
+    if (obj['properties'] === undefined || typeof obj['properties'] !== 'object') {
+        return;
+    }
+    const properties = obj['properties'];
+    for (const value of Object.values(properties)) {
+        if (typeof value === 'object' && value !== null) {
+            processSchemaRecursively(value);
+        }
+    }
+}
+/**
+ * Process nested schema keywords (allOf, anyOf, oneOf, items)
+ *
+ * @param obj - Schema object
+ */
+function processNestedSchemas(obj) {
+    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);
+                }
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            processSchemaRecursively(value);
+        }
+    }
+}
+//# sourceMappingURL=frontmatter-validator.js.map

package/dist/frontmatter-validator.js.map

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

package/dist/index.d.ts

@@ -25,12 +25,13 @@
  * }
  * ```
  */
-export { ResourceRegistry, type CrawlOptions, type ResourceRegistryOptions, type RegistryStats, } from './resource-registry.js';
+export { ResourceRegistry, type CrawlOptions, type ResourceRegistryOptions, type RegistryStats, type CollectionStats, type CollectionStat, } from './resource-registry.js';
 export { ResourceQuery } from './resource-query.js';
 export { ResourceCollection } from './resource-collection.js';
 export type { ResourceCollectionInterface } from './resource-collection-interface.js';
-export type { LinkType, HeadingNode, ResourceLink, ResourceMetadata, ValidationSeverity, ValidationIssue, ValidationResult, } from './types.js';
+export type { LinkType, HeadingNode, ResourceLink, ResourceMetadata, ValidationIssue, ValidationResult, ProjectConfig, ResourcesConfig, CollectionConfig, CollectionValidation, ValidationMode, } from './types.js';
 export { LinkTypeSchema, HeadingNodeSchema, ResourceLinkSchema, ResourceMetadataSchema, } from './schemas/resource-metadata.js';
-export { ValidationSeveritySchema, ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';
+export { ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';
 export { parseMarkdown, type ParseResult } from './link-parser.js';
+export { validateFrontmatter } from './frontmatter-validator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,YAAY,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAGtF,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EACL,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG9D,YAAY,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAGtF,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -33,9 +33,11 @@ export { ResourceQuery } from './resource-query.js';
 export { ResourceCollection } from './resource-collection.js';
 // Export schemas for external use (e.g., JSON Schema generation, runtime validation)
 export { LinkTypeSchema, HeadingNodeSchema, ResourceLinkSchema, ResourceMetadataSchema, } from './schemas/resource-metadata.js';
-export { ValidationSeveritySchema, ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';
+export { ValidationIssueSchema, ValidationResultSchema, } from './schemas/validation-result.js';
 // Export parser interface for advanced use cases
 export { parseMarkdown } 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.
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EACL,gBAAgB,GAIjB,MAAM,wBAAwB,CAAC;AAEhC,yDAAyD;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,oFAAoF;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAgB9D,qFAAqF;AACrF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,iDAAiD;AACjD,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,kEAAkE;AAClE,0EAA0E"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qCAAqC;AACrC,OAAO,EACL,gBAAgB,GAMjB,MAAM,wBAAwB,CAAC;AAEhC,yDAAyD;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,oFAAoF;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAoB9D,qFAAqF;AACrF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,gCAAgC,CAAC;AAExC,iDAAiD;AACjD,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,gCAAgC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,kEAAkE;AAClE,0EAA0E"}

package/dist/link-parser.d.ts

@@ -15,6 +15,8 @@ import type { HeadingNode, ResourceLink } from './types.js';
 export interface ParseResult {
     links: ResourceLink[];
     headings: HeadingNode[];
+    frontmatter?: Record<string, unknown>;
+    frontmatterError?: string;
     content: string;
     sizeBytes: number;
     estimatedTokenCount: number;

package/dist/link-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"link-parser.d.ts","sourceRoot":"","sources":["../src/link-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,KAAK,EAAE,WAAW,EAAY,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiC1E"}
+{"version":3,"file":"link-parser.d.ts","sourceRoot":"","sources":["../src/link-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAY,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwC1E"}

package/dist/link-parser.js

@@ -9,6 +9,7 @@
  * Uses unified/remark for robust markdown parsing with GFM support.
  */
 import { readFile, stat } from 'node:fs/promises';
+import * as yaml from 'js-yaml';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
@@ -48,9 +49,15 @@ export async function parseMarkdown(filePath) {
     const links = extractLinks(tree);
     // 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,
@@ -324,4 +331,38 @@ function cleanupEmptyChildren(headings) {
         }
     }
 }
+/**
+ * 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) {
+    let frontmatterData;
+    let errorMessage;
+    visit(tree, 'yaml', (node) => {
+        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;
+            }
+        }
+        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 }),
+    };
+}
 //# sourceMappingURL=link-parser.js.map

package/dist/link-parser.js.map

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

package/dist/link-validator.d.ts

@@ -2,29 +2,51 @@
  * 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 { type GitTracker } from '@vibe-agent-toolkit/utils';
 import type { ValidationIssue } from './schemas/validation-result.js';
 import type { HeadingNode, ResourceLink } from './types.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.
  *
  * @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}`);
  * }
  * ```
  */
-export declare function validateLink(link: ResourceLink, sourceFilePath: string, headingsByFile: Map<string, HeadingNode[]>): Promise<ValidationIssue | null>;
+export declare function validateLink(link: ResourceLink, sourceFilePath: string, headingsByFile: Map<string, HeadingNode[]>, options?: ValidateLinkOptions): Promise<ValidationIssue | null>;
 //# sourceMappingURL=link-validator.d.ts.map

package/dist/link-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"link-validator.d.ts","sourceRoot":"","sources":["../src/link-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,GACzC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAuCjC"}
+{"version":3,"file":"link-validator.d.ts","sourceRoot":"","sources":["../src/link-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAC1C,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA+BjC"}