@vibe-agent-toolkit/resources 0.1.3 → 0.1.5

package/src/resource-registry.ts

@@ -8,16 +8,19 @@
  * - Query capabilities (by path, ID, or glob pattern)
  */
 
+import type fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { crawlDirectory, type CrawlOptions as UtilsCrawlOptions } from '@vibe-agent-toolkit/utils';
+import { crawlDirectory, type CrawlOptions as UtilsCrawlOptions, type GitTracker } from '@vibe-agent-toolkit/utils';
 
 import { calculateChecksum } from './checksum.js';
+import { getCollectionsForFile } from './collection-matcher.js';
 import { validateFrontmatter } from './frontmatter-validator.js';
 import { parseMarkdown } from './link-parser.js';
 import { validateLink } 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';
 import type { HeadingNode, ResourceMetadata } from './schemas/resource-metadata.js';
 import type { ValidationIssue, ValidationResult } from './schemas/validation-result.js';
 import { matchesGlobPattern, splitHrefAnchor } from './utils.js';
@@ -42,8 +45,10 @@ export interface CrawlOptions {
 export interface ResourceRegistryOptions {
   /** Root directory for resources (optional) */
   rootDir?: string;
-  /** Validate resources when they are added (default: false) */
-  validateOnAdd?: boolean;
+  /** Project configuration (optional, enables collection support) */
+  config?: ProjectConfig;
+  /** Git tracker for efficient git-ignore checking (optional, improves performance) */
+  gitTracker?: GitTracker;
 }
 
 /**
@@ -52,6 +57,10 @@ export interface ResourceRegistryOptions {
 export interface ValidateOptions {
   /** Optional JSON Schema to validate frontmatter against */
   frontmatterSchema?: object;
+  /** Skip git-ignore checks (default: false) */
+  skipGitIgnoreCheck?: boolean;
+  /** Validation mode for schemas: strict (default) or permissive */
+  validationMode?: 'strict' | 'permissive';
 }
 
 /**
@@ -63,6 +72,30 @@ export interface RegistryStats {
   linksByType: Record<string, number>;
 }
 
+/**
+ * Statistics for a single collection.
+ */
+export interface CollectionStat {
+  /** Number of resources in this collection */
+  resourceCount: number;
+  /** Whether this collection has a frontmatter schema configured */
+  hasSchema: boolean;
+  /** Validation mode for this collection's schema */
+  validationMode?: 'strict' | 'permissive';
+}
+
+/**
+ * Statistics about all collections in the registry.
+ */
+export interface CollectionStats {
+  /** Total number of configured collections */
+  totalCollections: number;
+  /** Total number of resources that belong to at least one collection */
+  resourcesInCollections: number;
+  /** Statistics per collection ID */
+  collections: Record<string, CollectionStat>;
+}
+
 /**
  * Resource registry for managing collections of markdown resources.
  *
@@ -96,17 +129,27 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   /** Optional root directory for resources */
   readonly rootDir?: string;
 
+  /** Optional project configuration (enables collection support) */
+  readonly config?: ProjectConfig;
+
+  /** Optional git tracker for efficient git-ignore checking */
+  readonly gitTracker?: GitTracker;
+
   private readonly resourcesByPath: Map<string, ResourceMetadata> = new Map();
   private readonly resourcesById: Map<string, ResourceMetadata> = new Map();
   private readonly resourcesByName: Map<string, ResourceMetadata[]> = new Map();
   private readonly resourcesByChecksum: Map<SHA256, ResourceMetadata[]> = new Map();
-  private readonly validateOnAdd: boolean;
 
   constructor(options?: ResourceRegistryOptions) {
     if (options?.rootDir !== undefined) {
       this.rootDir = options.rootDir;
     }
-    this.validateOnAdd = options?.validateOnAdd ?? false;
+    if (options?.config !== undefined) {
+      this.config = options.config;
+    }
+    if (options?.gitTracker !== undefined) {
+      this.gitTracker = options.gitTracker;
+    }
   }
 
   /**
@@ -204,7 +247,6 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    * Add a single resource to the registry.
    *
    * Parses the markdown file, generates a unique ID, and stores the resource.
-   * If validateOnAdd is true, validates the resource immediately.
    *
    * @param filePath - Path to the markdown file (will be normalized to absolute)
    * @returns The parsed resource metadata
@@ -233,6 +275,11 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Calculate checksum eagerly
     const checksum = await calculateChecksum(absolutePath);
 
+    // Determine collections if config is present
+    const collections = this.config?.resources?.collections
+      ? getCollectionsForFile(absolutePath, this.config.resources.collections)
+      : undefined;
+
     // Create resource metadata
     const resource: ResourceMetadata = {
       id,
@@ -245,22 +292,12 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       estimatedTokenCount: parseResult.estimatedTokenCount,
       modifiedAt: stats.mtime,
       checksum,
+      ...(collections !== undefined && collections.length > 0 && { collections }),
     };
 
     // Index the resource
     this.indexResource(resource);
 
-    // Validate if requested
-    if (this.validateOnAdd) {
-      const headingsByFile = this.buildHeadingsByFileMap();
-      for (const link of resource.links) {
-        const issue = await validateLink(link, absolutePath, headingsByFile);
-        if (issue) {
-          throw new Error(`Validation failed: ${issue.message}`);
-        }
-      }
-    }
-
     return resource;
   }
 
@@ -323,6 +360,188 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     return await this.addResources(files);
   }
 
+  /**
+   * Check for YAML parsing errors in all resources.
+   * @private
+   */
+  private collectYamlErrors(): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    for (const resource of this.resourcesByPath.values()) {
+      if (resource.frontmatterError) {
+        issues.push({
+          resourcePath: resource.filePath,
+          line: 1,
+          type: 'frontmatter_invalid_yaml',
+          link: '',
+          message: `Invalid YAML syntax in frontmatter: ${resource.frontmatterError}`,
+        });
+      }
+    }
+    return issues;
+  }
+
+  /**
+   * Validate all links in all resources.
+   * @private
+   */
+  private async validateAllLinks(
+    headingsByFile: Map<string, HeadingNode[]>,
+    skipGitIgnoreCheck: boolean
+  ): Promise<ValidationIssue[]> {
+    const issues: ValidationIssue[] = [];
+
+    for (const resource of this.resourcesByPath.values()) {
+      for (const link of resource.links) {
+        // Only pass options if projectRoot is defined (exactOptionalPropertyTypes requirement)
+        const validateOptions = this.rootDir === undefined
+          ? { skipGitIgnoreCheck }
+          : {
+              projectRoot: this.rootDir,
+              skipGitIgnoreCheck,
+              ...(this.gitTracker !== undefined && { gitTracker: this.gitTracker })
+            };
+
+        const issue = await validateLink(link, resource.filePath, headingsByFile, validateOptions);
+        if (issue) {
+          issues.push(issue);
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  /**
+   * Validate frontmatter against a JSON Schema.
+   * @private
+   */
+  private validateAllFrontmatter(
+    schema: object,
+    mode: 'strict' | 'permissive' = 'strict'
+  ): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    for (const resource of this.resourcesByPath.values()) {
+      const frontmatterIssues = validateFrontmatter(
+        resource.frontmatter,
+        schema,
+        resource.filePath,
+        mode
+      );
+      issues.push(...frontmatterIssues);
+    }
+    return issues;
+  }
+
+  /**
+   * Validate frontmatter against per-collection schemas.
+   * @private
+   */
+  private async validateCollectionFrontmatter(): Promise<ValidationIssue[]> {
+    const issues: ValidationIssue[] = [];
+
+    // Skip if no config
+    if (!this.config?.resources?.collections) {
+      return issues;
+    }
+
+    const fsPromises = await import('node:fs/promises');
+
+    for (const resource of this.resourcesByPath.values()) {
+      // Skip if resource has no collections
+      if (!resource.collections || resource.collections.length === 0) {
+        continue;
+      }
+
+      // Validate against each collection's schema
+      const collectionIssues = await this.validateResourceCollectionSchemas(
+        resource,
+        fsPromises
+      );
+      issues.push(...collectionIssues);
+    }
+
+    return issues;
+  }
+
+  /**
+   * Validate a single resource against its collection schemas.
+   * @private
+   */
+  private async validateResourceCollectionSchemas(
+    resource: ResourceMetadata,
+    fsModule: typeof fs
+  ): Promise<ValidationIssue[]> {
+    const issues: ValidationIssue[] = [];
+
+    if (!resource.collections || !this.config?.resources?.collections) {
+      return issues;
+    }
+
+    for (const collectionId of resource.collections) {
+      const collection = this.config.resources.collections[collectionId];
+
+      // Skip if collection has no validation or no schema
+      if (!collection?.validation?.frontmatterSchema) {
+        continue;
+      }
+
+      const collectionIssues = await this.validateAgainstCollectionSchema(
+        resource,
+        collection.validation,
+        fsModule
+      );
+      issues.push(...collectionIssues);
+    }
+
+    return issues;
+  }
+
+  /**
+   * Validate resource frontmatter against a specific collection schema.
+   * @private
+   */
+  private async validateAgainstCollectionSchema(
+    resource: ResourceMetadata,
+    validation: NonNullable<ProjectConfig['resources']>['collections'][string]['validation'],
+    fsModule: typeof fs
+  ): Promise<ValidationIssue[]> {
+    if (!validation?.frontmatterSchema) {
+      return [];
+    }
+
+    const schemaPath = path.resolve(
+      this.rootDir ?? process.cwd(),
+      validation.frontmatterSchema
+    );
+
+    try {
+      const schemaContent = await fsModule.readFile(schemaPath, 'utf-8');
+      const schema = JSON.parse(schemaContent) as object;
+
+      // Determine validation mode (default to permissive)
+      const mode = validation.mode ?? 'permissive';
+
+      // Validate frontmatter
+      return validateFrontmatter(
+        resource.frontmatter,
+        schema,
+        resource.filePath,
+        mode,
+        schemaPath
+      );
+    } catch (error) {
+      // Handle missing or invalid schema files gracefully
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return [{
+        resourcePath: resource.filePath,
+        line: 1,
+        type: 'frontmatter_schema_error',
+        link: '',
+        message: `Failed to load or parse frontmatter schema '${validation.frontmatterSchema}': ${errorMessage}`,
+      }];
+    }
+  }
+
   /**
    * Validate all links and optionally frontmatter in all resources in the registry.
    *
@@ -348,10 +567,9 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    *
    * console.log(`Passed: ${result.passed}`);
    * console.log(`Errors: ${result.errorCount}`);
-   * console.log(`Warnings: ${result.warningCount}`);
    * console.log(`Total resources: ${result.totalResources}`);
    * for (const issue of result.issues) {
-   *   console.log(`${issue.severity}: ${issue.message}`);
+   *   console.log(`${issue.message}`);
    * }
    * ```
    */
@@ -365,45 +583,27 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     const issues: ValidationIssue[] = [];
 
     // Check for YAML parsing errors first
-    for (const resource of this.resourcesByPath.values()) {
-      if (resource.frontmatterError) {
-        issues.push({
-          severity: 'error',
-          resourcePath: resource.filePath,
-          line: 1,
-          type: 'frontmatter_invalid_yaml',
-          link: '',
-          message: `Invalid YAML syntax in frontmatter: ${resource.frontmatterError}`,
-        });
-      }
-    }
+    issues.push(...this.collectYamlErrors());
 
     // Validate each link in each resource
-    for (const resource of this.resourcesByPath.values()) {
-      for (const link of resource.links) {
-        const issue = await validateLink(link, resource.filePath, headingsByFile);
-        if (issue) {
-          issues.push(issue);
-        }
-      }
-    }
+    const linkIssues = await this.validateAllLinks(
+      headingsByFile,
+      options?.skipGitIgnoreCheck ?? false
+    );
+    issues.push(...linkIssues);
+
+    // Per-collection frontmatter validation
+    const collectionFrontmatterIssues = await this.validateCollectionFrontmatter();
+    issues.push(...collectionFrontmatterIssues);
 
-    // Frontmatter validation (if schema provided)
+    // Global frontmatter validation (if schema provided)
     if (options?.frontmatterSchema) {
-      for (const resource of this.resourcesByPath.values()) {
-        const frontmatterIssues = validateFrontmatter(
-          resource.frontmatter,
-          options.frontmatterSchema,
-          resource.filePath
-        );
-        issues.push(...frontmatterIssues);
-      }
+      const mode = options.validationMode ?? 'strict';
+      issues.push(...this.validateAllFrontmatter(options.frontmatterSchema, mode));
     }
 
-    // Count issues by severity
-    const errorCount = issues.filter((i) => i.severity === 'error').length;
-    const warningCount = issues.filter((i) => i.severity === 'warning').length;
-    const infoCount = issues.filter((i) => i.severity === 'info').length;
+    // Count issues (all are errors now)
+    const errorCount = issues.length;
 
     // Count links by type
     const linksByType: Record<string, number> = {};
@@ -424,8 +624,6 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       linksByType,
       issues,
       errorCount,
-      warningCount,
-      infoCount,
       passed: errorCount === 0,
       durationMs,
       timestamp: new Date(),
@@ -717,6 +915,76 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     };
   }
 
+  /**
+   * Get collection-level statistics.
+   *
+   * Returns undefined if collections are not configured in the project config.
+   *
+   * @returns Collection statistics or undefined if no collections configured
+   *
+   * @example
+   * ```typescript
+   * const collectionStats = registry.getCollectionStats();
+   * if (collectionStats) {
+   *   console.log(`Total collections: ${collectionStats.totalCollections}`);
+   *   console.log(`Resources in collections: ${collectionStats.resourcesInCollections}`);
+   *   for (const [id, stat] of Object.entries(collectionStats.collections)) {
+   *     console.log(`${id}: ${stat.resourceCount} resources`);
+   *   }
+   * }
+   * ```
+   */
+  getCollectionStats(): CollectionStats | undefined {
+    if (!this.config?.resources?.collections) {
+      return undefined;
+    }
+
+    // Group resources by collection
+    const collectionMap = new Map<string, ResourceMetadata[]>();
+
+    for (const resource of this.resourcesByPath.values()) {
+      if (resource.collections) {
+        for (const collectionId of resource.collections) {
+          const resources = collectionMap.get(collectionId) ?? [];
+          resources.push(resource);
+          collectionMap.set(collectionId, resources);
+        }
+      }
+    }
+
+    // Build stats per collection
+    const collections: Record<string, CollectionStat> = {};
+
+    for (const [id, resources] of collectionMap.entries()) {
+      const collection = this.config.resources.collections[id];
+      const stat: CollectionStat = {
+        resourceCount: resources.length,
+        hasSchema: !!collection?.validation?.frontmatterSchema,
+      };
+
+      // Only add validationMode if it's defined (exactOptionalPropertyTypes requirement)
+      if (collection?.validation?.mode !== undefined) {
+        stat.validationMode = collection.validation.mode;
+      }
+
+      collections[id] = stat;
+    }
+
+    // Calculate total unique resources in collections (a resource may be in multiple collections)
+    const uniqueResourcesInCollections = new Set<string>();
+    for (const resource of this.resourcesByPath.values()) {
+      if (resource.collections && resource.collections.length > 0) {
+        uniqueResourcesInCollections.add(resource.filePath);
+      }
+    }
+
+    return {
+      totalCollections: Object.keys(this.config.resources.collections).length,
+      resourcesInCollections: uniqueResourcesInCollections.size,
+      collections,
+    };
+  }
+
   /**
    * Generate a unique ID from a file path.
    *

package/src/schema-assignment.ts

@@ -0,0 +1,119 @@
+/**
+ * Schema assignment pipeline for resources
+ *
+ * Handles the multi-source schema assignment:
+ * 1. Self-asserted schemas (from $schema field in frontmatter)
+ * 2. Collection-imposed schemas (from collection config)
+ * 3. CLI-imposed schemas (from --frontmatter-schema flag)
+ *
+ * Each resource can have multiple schemas from different sources,
+ * and each is validated independently.
+ */
+
+import type { CollectionConfig } from './schemas/project-config.js';
+import type { SchemaReference } from './types/resources.js';
+
+/**
+ * Add collection-imposed schema to a resource's schema list
+ *
+ * @param existingSchemas - Current schemas (including self-asserted)
+ * @param collectionName - Name of the collection
+ * @param collectionConfig - Collection configuration
+ * @returns Updated schema list with collection schema added (if defined)
+ */
+export function addCollectionSchema(
+  existingSchemas: SchemaReference[],
+  collectionName: string,
+  collectionConfig: CollectionConfig,
+): SchemaReference[] {
+  const schemaPath = collectionConfig.validation?.frontmatterSchema;
+
+  if (!schemaPath) {
+    return existingSchemas;
+  }
+
+  // Check if this schema is already present from any source
+  const alreadyExists = existingSchemas.some((ref) => ref.schema === schemaPath);
+  if (alreadyExists) {
+    return existingSchemas;
+  }
+
+  // Add collection-imposed schema
+  return [
+    ...existingSchemas,
+    {
+      schema: schemaPath,
+      source: collectionName,
+      applied: false,
+    },
+  ];
+}
+
+/**
+ * Add CLI-imposed schema to a resource's schema list
+ *
+ * @param existingSchemas - Current schemas (including self-asserted and collection)
+ * @param schemaPath - Path to schema from CLI flag
+ * @returns Updated schema list with CLI schema added
+ */
+export function addCLISchema(
+  existingSchemas: SchemaReference[],
+  schemaPath: string,
+): SchemaReference[] {
+  // Check if this schema is already present from any source
+  const alreadyExists = existingSchemas.some((ref) => ref.schema === schemaPath);
+  if (alreadyExists) {
+    return existingSchemas;
+  }
+
+  // Add CLI-imposed schema
+  return [
+    ...existingSchemas,
+    {
+      schema: schemaPath,
+      source: 'cli',
+      applied: false,
+    },
+  ];
+}
+
+/**
+ * Apply schema assignments to a resource
+ *
+ * Pipeline order:
+ * 1. Self-asserted (already in resource.schemas from parser)
+ * 2. Collection-imposed (from each collection the resource belongs to)
+ * 3. CLI-imposed (from --frontmatter-schema flag)
+ *
+ * Deduplicates schemas by path - same schema from multiple sources
+ * only appears once (first source wins).
+ *
+ * @param resourceSchemas - Current schemas (from parser)
+ * @param collections - Collections this resource belongs to
+ * @param collectionsConfig - Collection configurations
+ * @param cliSchema - Optional CLI-imposed schema
+ * @returns Complete list of schemas to validate
+ */
+export function assignSchemas(
+  resourceSchemas: SchemaReference[],
+  collections: string[],
+  collectionsConfig: Record<string, CollectionConfig>,
+  cliSchema?: string,
+): SchemaReference[] {
+  let schemas = resourceSchemas;
+
+  // Add collection-imposed schemas
+  for (const collectionName of collections) {
+    const collectionConfig = collectionsConfig[collectionName];
+    if (collectionConfig) {
+      schemas = addCollectionSchema(schemas, collectionName, collectionConfig);
+    }
+  }
+
+  // Add CLI-imposed schema
+  if (cliSchema) {
+    schemas = addCLISchema(schemas, cliSchema);
+  }
+
+  return schemas;
+}

package/src/schemas/project-config.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+
+/**
+ * Validation mode for frontmatter schema validation.
+ *
+ * - `strict`: Enforce schema exactly (respect additionalProperties: false)
+ * - `permissive`: Allow extra fields (ignore additionalProperties: false)
+ */
+export const ValidationModeSchema = z.enum(['strict', 'permissive'])
+  .describe('Validation mode for frontmatter schema validation');
+
+export type ValidationMode = z.infer<typeof ValidationModeSchema>;
+
+/**
+ * Validation configuration for a collection.
+ */
+export const CollectionValidationSchema = z.object({
+  frontmatterSchema: z.string().optional()
+    .describe('Path to JSON Schema file for frontmatter validation (relative to config file or package reference like @vibe-agent-toolkit/schemas/skill.v1.json)'),
+  mode: ValidationModeSchema.optional()
+    .describe('Validation mode (default: strict)'),
+  checkUrlLinks: z.boolean().optional()
+    .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)'),
+}).describe('Validation configuration for a collection');
+
+export type CollectionValidation = z.infer<typeof CollectionValidationSchema>;
+
+/**
+ * Configuration for a named collection of resources.
+ *
+ * Collections define include/exclude patterns and validation rules.
+ * A file can belong to multiple collections.
+ */
+export const CollectionConfigSchema = z.object({
+  include: z.array(z.string()).min(1)
+    .describe('Include patterns (paths or globs like docs/**/*.md)'),
+  exclude: z.array(z.string()).optional()
+    .describe('Exclude patterns (globs)'),
+  validation: CollectionValidationSchema.optional()
+    .describe('Validation configuration for this collection'),
+}).describe('Configuration for a named collection of resources');
+
+export type CollectionConfig = z.infer<typeof CollectionConfigSchema>;
+
+/**
+ * Resources section of project configuration.
+ */
+export const ResourcesConfigSchema = z.object({
+  include: z.array(z.string()).optional()
+    .describe('Global default include patterns (not used by collections in Phase 2)'),
+  exclude: z.array(z.string()).optional()
+    .describe('Global default exclude patterns (not used by collections in Phase 2)'),
+  collections: z.record(z.string(), CollectionConfigSchema)
+    .describe('Named collections of resources'),
+}).describe('Resources section of project configuration');
+
+export type ResourcesConfig = z.infer<typeof ResourcesConfigSchema>;
+
+/**
+ * Complete project configuration schema.
+ */
+export const ProjectConfigSchema = z.object({
+  version: z.literal(1)
+    .describe('Config file version (must be 1)'),
+  resources: ResourcesConfigSchema.optional()
+    .describe('Resources configuration'),
+}).describe('vibe-agent-toolkit project configuration');
+
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;

package/src/schemas/resource-metadata.ts

@@ -88,6 +88,8 @@ export const ResourceMetadataSchema = z.object({
   estimatedTokenCount: z.number().int().nonnegative().describe('Estimated token count for LLM context (roughly 1 token per 4 chars)'),
   modifiedAt: z.date().describe('Last modified timestamp'),
   checksum: SHA256Schema.describe('SHA-256 checksum of file content'),
+  collections: z.array(z.string()).optional()
+    .describe('Collection names this resource belongs to (populated when using config-based discovery)'),
 }).describe('Complete metadata for a markdown resource');
 
 export type ResourceMetadata = z.infer<typeof ResourceMetadataSchema>;