@vibe-agent-toolkit/resources 0.1.2 → 0.1.4

package/README.md

@@ -6,6 +6,7 @@ Markdown resource parsing, validation, and link integrity checking for AI agent
 
 - **Parse markdown files** - Extract links, headings, and metadata using unified/remark
 - **Validate link integrity** - Check local file links, anchor links, and detect broken references
+- **Frontmatter support** - Parse YAML frontmatter, optionally validate against JSON Schemas
 - **Track resource collections** - Manage multiple markdown files with automatic ID generation
 - **Resolve cross-references** - Link resources together and track dependencies
 - **Query capabilities** - Find resources by path, ID, or glob patterns with lazy evaluation
@@ -62,9 +63,6 @@ Main class for managing collections of markdown resources.
 new ResourceRegistry(options?: ResourceRegistryOptions)
 ```
 
-**Options:**
-- `validateOnAdd?: boolean` - Validate resources immediately when added (default: `false`)
-
 #### Methods
 
 ##### addResource(filePath: string): Promise<ResourceMetadata>
@@ -570,6 +568,260 @@ type ValidationSeverity = 'error' | 'warning' | 'info';
 - `warning` - Non-critical issue that should be addressed (e.g., questionable link format)
 - `info` - Informational message (e.g., external URL not validated)
 
+## Frontmatter Support
+
+The resources package parses YAML frontmatter from markdown files and stores it in `ResourceMetadata.frontmatter`. You can optionally validate frontmatter against JSON Schemas.
+
+### Basic Frontmatter Parsing
+
+Frontmatter is automatically parsed when resources are added:
+
+```typescript
+import { ResourceRegistry } from '@vibe-agent-toolkit/resources';
+
+const registry = new ResourceRegistry();
+await registry.addResource('./docs/guide.md');
+
+const resource = registry.getResource('./docs/guide.md');
+console.log('Frontmatter:', resource.frontmatter);
+// { title: 'User Guide', category: 'tutorial', tags: ['api', 'getting-started'] }
+```
+
+**Supported format**: YAML frontmatter between `---` delimiters at the start of the file:
+
+```markdown
+---
+title: User Guide
+category: tutorial
+tags:
+  - api
+  - getting-started
+---
+
+# Content starts here
+```
+
+### Frontmatter Validation
+
+Validate frontmatter against JSON Schema to enforce required fields and data types:
+
+```typescript
+import { FrontmatterValidator } from '@vibe-agent-toolkit/resources';
+
+// Create validator with JSON Schema
+const validator = new FrontmatterValidator({
+  type: 'object',
+  required: ['title', 'description'],
+  properties: {
+    title: { type: 'string', minLength: 1 },
+    description: { type: 'string' },
+    category: { enum: ['guide', 'reference', 'tutorial', 'api'] },
+    tags: { type: 'array', items: { type: 'string' } }
+  }
+});
+
+// Validate a resource
+const resource = registry.getResource('./docs/guide.md');
+const result = validator.validate(resource);
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+### Schema Design Patterns
+
+#### Pattern 1: Required Fields, Allow Extras
+
+Most projects have files (README.md, etc.) without frontmatter. Use `required` for must-have fields but allow custom fields:
+
+```json
+{
+  "type": "object",
+  "required": ["title", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "category": { "enum": ["guide", "reference", "tutorial", "api"] }
+  }
+}
+```
+
+**Behavior**:
+- Files without frontmatter: **Error** (missing required fields)
+- Files with partial frontmatter: **Error** (missing required fields)
+- Files with complete frontmatter: **Valid**
+- Extra fields allowed: **Yes**
+
+#### Pattern 2: Optional Fields Only
+
+For projects where frontmatter is optional:
+
+```json
+{
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "category": { "enum": ["guide", "reference", "tutorial", "api"] }
+  }
+}
+```
+
+**Behavior**:
+- Files without frontmatter: **Valid** (all fields optional)
+- Files with frontmatter: **Validated** (fields must match schema types)
+- Extra fields allowed: **Yes**
+
+#### Pattern 3: Strict Schema
+
+For knowledge bases where all metadata is required:
+
+```json
+{
+  "type": "object",
+  "required": ["title", "description", "category", "keywords"],
+  "additionalProperties": false,
+  "properties": {
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "category": { "enum": ["guide", "reference", "tutorial", "api"] },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "source_url": { "type": "string", "format": "uri" }
+  }
+}
+```
+
+**Behavior**:
+- Files without frontmatter: **Error** (missing required fields)
+- Extra fields: **Error** (`additionalProperties: false`)
+- All fields must match types: **Yes**
+
+### CLI Usage
+
+The `vat resources validate` command supports frontmatter validation:
+
+```bash
+# Parse frontmatter, report YAML errors only
+vat resources validate docs/
+
+# Validate against JSON Schema
+vat resources validate docs/ --frontmatter-schema schema.json
+
+# Example output with schema validation
+vat resources validate docs/ --frontmatter-schema schema.json
+# Resources validated: 42
+# Links validated: 156
+# Frontmatter errors:
+#   docs/guide.md: Missing required property 'description'
+#   docs/api.md: Property 'category' must be one of: guide, reference, tutorial, api
+```
+
+### Validation Result
+
+Frontmatter validation results are included in `ValidationResult`:
+
+```typescript
+interface ValidationResult {
+  // ... existing fields
+  frontmatterValidation?: {
+    valid: boolean;
+    errors: Array<{
+      resourcePath: string;
+      message: string;
+      field?: string;
+    }>;
+  };
+}
+```
+
+### Example Schemas
+
+#### Knowledge Base Schema
+
+```json
+{
+  "type": "object",
+  "required": ["title", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string" },
+    "category": { "enum": ["guide", "reference", "tutorial", "api"] },
+    "keywords": { "type": "array", "items": { "type": "string" } },
+    "source_url": { "type": "string", "format": "uri" },
+    "author": { "type": "string" },
+    "last_updated": { "type": "string", "format": "date" }
+  }
+}
+```
+
+#### Blog Post Schema
+
+```json
+{
+  "type": "object",
+  "required": ["title", "date", "author"],
+  "additionalProperties": false,
+  "properties": {
+    "title": { "type": "string", "minLength": 1 },
+    "date": { "type": "string", "format": "date" },
+    "author": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "excerpt": { "type": "string" },
+    "featured": { "type": "boolean" }
+  }
+}
+```
+
+#### API Documentation Schema
+
+```json
+{
+  "type": "object",
+  "required": ["title", "api_version"],
+  "additionalProperties": true,
+  "properties": {
+    "title": { "type": "string", "minLength": 1 },
+    "api_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "endpoint": { "type": "string" },
+    "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+    "deprecated": { "type": "boolean" }
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+const validator = new FrontmatterValidator(schema);
+
+for (const resource of registry.getAllResources()) {
+  const result = validator.validate(resource);
+
+  if (!result.valid) {
+    console.error(`\n${resource.filePath}:`);
+    for (const error of result.errors) {
+      console.error(`  - ${error.message}`);
+      if (error.field) {
+        console.error(`    Field: ${error.field}`);
+      }
+    }
+  }
+}
+```
+
+### Common Validation Errors
+
+- **Missing required property**: Field specified in `required` array is missing
+- **Invalid type**: Field value doesn't match the type (e.g., number instead of string)
+- **Invalid enum value**: Field value is not in the allowed enum values
+- **Invalid format**: String doesn't match the format constraint (e.g., "uri", "date")
+- **Additional property not allowed**: Extra field present when `additionalProperties: false`
+- **YAML parsing error**: Invalid YAML syntax in frontmatter
+
 ## Schemas
 
 All types are backed by Zod schemas for runtime validation. You can import schemas for advanced use cases:
@@ -651,20 +903,6 @@ for (const [path, issues] of issuesByResource) {
 }
 ```
 
-### Validate on Add
-
-Enable strict validation mode to fail fast on broken links:
-
-```typescript
-const registry = new ResourceRegistry({ validateOnAdd: true });
-
-try {
-  await registry.addResource('./docs/broken.md');
-} catch (error) {
-  console.error('Validation failed:', error.message);
-}
-```
-
 ## Examples
 
 ### Validate Project Documentation

package/dist/collection-matcher.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Collection matching utilities for determining which collections a file belongs to.
+ *
+ * Applies include/exclude pattern rules with precedence (exclude wins).
+ */
+import type { CollectionConfig } from './schemas/project-config.js';
+/**
+ * Check if a file path matches a collection's include/exclude rules.
+ *
+ * Rules:
+ * - File must match at least one include pattern
+ * - File must NOT match any exclude pattern
+ * - Exclude always wins over include
+ * - Pattern order does not matter
+ *
+ * Special handling for root-level patterns (*.md, *.json):
+ * - These match against the basename only, not the full path
+ * - Allows matching root-level files regardless of their absolute path
+ *
+ * Paths are normalized to forward slashes before matching for cross-platform consistency.
+ *
+ * @param filePath - Absolute file path to check
+ * @param collection - Collection configuration with include/exclude patterns
+ * @returns True if file belongs to collection
+ *
+ * @example
+ * ```typescript
+ * const collection = {
+ *   include: ['docs'],
+ *   exclude: ['**\/README.md']
+ * };
+ *
+ * matchesCollection('/project/docs/guide.md', collection)    // true
+ * matchesCollection('/project/docs/README.md', collection)   // false (excluded)
+ * matchesCollection('/project/src/index.ts', collection)     // false (not included)
+ * ```
+ */
+export declare function matchesCollection(filePath: string, collection: CollectionConfig): boolean;
+/**
+ * Find all collections that a file belongs to.
+ *
+ * A file can belong to multiple collections if it matches their rules.
+ *
+ * @param filePath - Absolute file path to check
+ * @param collections - Map of collection name to collection config
+ * @returns Array of collection names the file belongs to
+ *
+ * @example
+ * ```typescript
+ * const collections = {
+ *   'rag-kb': { include: ['docs'], exclude: ['**\/README.md'] },
+ *   'skills': { include: ['**\/SKILL.md'] }
+ * };
+ *
+ * getCollectionsForFile('/project/docs/guide.md', collections)
+ * // ['rag-kb']
+ *
+ * getCollectionsForFile('/project/docs/SKILL.md', collections)
+ * // ['rag-kb', 'skills']
+ * ```
+ */
+export declare function getCollectionsForFile(filePath: string, collections: Record<string, CollectionConfig>): string[];
+//# sourceMappingURL=collection-matcher.d.ts.map

package/dist/collection-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-matcher.d.ts","sourceRoot":"","sources":["../src/collection-matcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAWpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAuDzF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC5C,MAAM,EAAE,CAUV"}

package/dist/collection-matcher.js

@@ -0,0 +1,127 @@
+/**
+ * Collection matching utilities for determining which collections a file belongs to.
+ *
+ * Applies include/exclude pattern rules with precedence (exclude wins).
+ */
+import { basename as getBasename } from 'node:path';
+import { toForwardSlash } from '@vibe-agent-toolkit/utils';
+import picomatch from 'picomatch';
+import { expandPatterns } from './pattern-expander.js';
+/**
+ * Check if a pattern is a root-level pattern (e.g., *.md, *.json).
+ *
+ * Root-level patterns start with * but not **.
+ */
+function isRootLevelPattern(pattern) {
+    return pattern.startsWith('*') && !pattern.startsWith('**');
+}
+/**
+ * Check if a file path matches a collection's include/exclude rules.
+ *
+ * Rules:
+ * - File must match at least one include pattern
+ * - File must NOT match any exclude pattern
+ * - Exclude always wins over include
+ * - Pattern order does not matter
+ *
+ * Special handling for root-level patterns (*.md, *.json):
+ * - These match against the basename only, not the full path
+ * - Allows matching root-level files regardless of their absolute path
+ *
+ * Paths are normalized to forward slashes before matching for cross-platform consistency.
+ *
+ * @param filePath - Absolute file path to check
+ * @param collection - Collection configuration with include/exclude patterns
+ * @returns True if file belongs to collection
+ *
+ * @example
+ * ```typescript
+ * const collection = {
+ *   include: ['docs'],
+ *   exclude: ['**\/README.md']
+ * };
+ *
+ * matchesCollection('/project/docs/guide.md', collection)    // true
+ * matchesCollection('/project/docs/README.md', collection)   // false (excluded)
+ * matchesCollection('/project/src/index.ts', collection)     // false (not included)
+ * ```
+ */
+export function matchesCollection(filePath, collection) {
+    // Normalize to forward slashes for cross-platform consistency
+    const normalizedPath = toForwardSlash(filePath);
+    // Extract basename for root-level pattern matching
+    const basename = getBasename(filePath);
+    // Expand patterns (paths → globs)
+    const includePatterns = expandPatterns(collection.include);
+    const excludePatterns = collection.exclude ? expandPatterns(collection.exclude) : [];
+    // Separate root-level patterns from other patterns
+    const includeRootPatterns = includePatterns.filter(isRootLevelPattern);
+    const includeNonRootPatterns = includePatterns.filter((p) => !isRootLevelPattern(p));
+    const excludeRootPatterns = excludePatterns.filter(isRootLevelPattern);
+    const excludeNonRootPatterns = excludePatterns.filter((p) => !isRootLevelPattern(p));
+    // Check excludes first (exclude wins)
+    // Check non-root excludes against full path
+    if (excludeNonRootPatterns.length > 0) {
+        const excludeMatcher = picomatch(excludeNonRootPatterns);
+        if (excludeMatcher(normalizedPath)) {
+            return false;
+        }
+    }
+    // Check root-level excludes against basename
+    if (excludeRootPatterns.length > 0) {
+        const excludeRootMatcher = picomatch(excludeRootPatterns);
+        if (excludeRootMatcher(basename)) {
+            return false;
+        }
+    }
+    // Check includes (need to match at least one)
+    let matched = false;
+    // Check non-root includes against full path
+    if (includeNonRootPatterns.length > 0) {
+        const includeMatcher = picomatch(includeNonRootPatterns);
+        if (includeMatcher(normalizedPath)) {
+            matched = true;
+        }
+    }
+    // Check root-level includes against basename
+    if (!matched && includeRootPatterns.length > 0) {
+        const includeRootMatcher = picomatch(includeRootPatterns);
+        if (includeRootMatcher(basename)) {
+            matched = true;
+        }
+    }
+    return matched;
+}
+/**
+ * Find all collections that a file belongs to.
+ *
+ * A file can belong to multiple collections if it matches their rules.
+ *
+ * @param filePath - Absolute file path to check
+ * @param collections - Map of collection name to collection config
+ * @returns Array of collection names the file belongs to
+ *
+ * @example
+ * ```typescript
+ * const collections = {
+ *   'rag-kb': { include: ['docs'], exclude: ['**\/README.md'] },
+ *   'skills': { include: ['**\/SKILL.md'] }
+ * };
+ *
+ * getCollectionsForFile('/project/docs/guide.md', collections)
+ * // ['rag-kb']
+ *
+ * getCollectionsForFile('/project/docs/SKILL.md', collections)
+ * // ['rag-kb', 'skills']
+ * ```
+ */
+export function getCollectionsForFile(filePath, collections) {
+    const matchingCollections = [];
+    for (const [name, config] of Object.entries(collections)) {
+        if (matchesCollection(filePath, config)) {
+            matchingCollections.push(name);
+        }
+    }
+    return matchingCollections;
+}
+//# sourceMappingURL=collection-matcher.js.map

package/dist/collection-matcher.js.map

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

package/dist/config-parser.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Configuration file parser for vibe-agent-toolkit.config.yaml
+ *
+ * Discovers and parses project configuration files with directory tree walk-up.
+ */
+import { type ProjectConfig } from './schemas/project-config.js';
+/**
+ * Find the config file by walking up the directory tree.
+ *
+ * Starts from the current directory and walks up until the config file is found
+ * or the root directory is reached.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Absolute path to config file, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const configPath = await findConfigFile();
+ * if (configPath) {
+ *   console.log(`Found config: ${configPath}`);
+ * }
+ * ```
+ */
+export declare function findConfigFile(startDir?: string): Promise<string | undefined>;
+/**
+ * Parse a project configuration file.
+ *
+ * Reads the YAML file, parses it, and validates against the schema.
+ *
+ * @param configPath - Absolute path to config file
+ * @returns Parsed and validated configuration
+ * @throws Error if file cannot be read, YAML is invalid, or validation fails
+ *
+ * @example
+ * ```typescript
+ * const config = await parseConfigFile('/project/vibe-agent-toolkit.config.yaml');
+ * console.log(`Version: ${config.version}`);
+ * console.log(`Collections: ${Object.keys(config.resources?.collections ?? {}).join(', ')}`);
+ * ```
+ */
+export declare function parseConfigFile(configPath: string): Promise<ProjectConfig>;
+/**
+ * Load project configuration by discovering and parsing config file.
+ *
+ * Walks up the directory tree from startDir to find the config file,
+ * then parses and validates it.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Parsed configuration, or undefined if no config file found
+ * @throws Error if config file is found but cannot be parsed or is invalid
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ * if (config) {
+ *   console.log('Using project config');
+ * } else {
+ *   console.log('No config found, using defaults');
+ * }
+ * ```
+ */
+export declare function loadConfig(startDir?: string): Promise<ProjectConfig | undefined>;
+//# sourceMappingURL=config-parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config-parser.d.ts","sourceRoot":"","sources":["../src/config-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAItF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwBlG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqBhF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAOrG"}

package/dist/config-parser.js

@@ -0,0 +1,113 @@
+/**
+ * Configuration file parser for vibe-agent-toolkit.config.yaml
+ *
+ * Discovers and parses project configuration files with directory tree walk-up.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { load as loadYaml } from 'js-yaml';
+import { ProjectConfigSchema } from './schemas/project-config.js';
+const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
+/**
+ * Find the config file by walking up the directory tree.
+ *
+ * Starts from the current directory and walks up until the config file is found
+ * or the root directory is reached.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Absolute path to config file, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const configPath = await findConfigFile();
+ * if (configPath) {
+ *   console.log(`Found config: ${configPath}`);
+ * }
+ * ```
+ */
+export async function findConfigFile(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    const { root } = path.parse(currentDir);
+    while (true) {
+        const configPath = path.join(currentDir, CONFIG_FILENAME);
+        try {
+            // Check if file exists by attempting to read metadata
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- constructing path during tree walk
+            await readFile(configPath, 'utf-8');
+            return configPath;
+        }
+        catch {
+            // File doesn't exist, continue walking up
+        }
+        // Check if we've reached the root
+        if (currentDir === root) {
+            return undefined;
+        }
+        // Move up one directory
+        currentDir = path.dirname(currentDir);
+    }
+}
+/**
+ * Parse a project configuration file.
+ *
+ * Reads the YAML file, parses it, and validates against the schema.
+ *
+ * @param configPath - Absolute path to config file
+ * @returns Parsed and validated configuration
+ * @throws Error if file cannot be read, YAML is invalid, or validation fails
+ *
+ * @example
+ * ```typescript
+ * const config = await parseConfigFile('/project/vibe-agent-toolkit.config.yaml');
+ * console.log(`Version: ${config.version}`);
+ * console.log(`Collections: ${Object.keys(config.resources?.collections ?? {}).join(', ')}`);
+ * ```
+ */
+export async function parseConfigFile(configPath) {
+    // Read file content
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is from findConfigFile() walk-up
+    const content = await readFile(configPath, 'utf-8');
+    // Parse YAML
+    let parsed;
+    try {
+        parsed = loadYaml(content);
+    }
+    catch (error) {
+        throw new Error(`Invalid YAML in config file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Validate against schema
+    const result = ProjectConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const errors = result.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ');
+        throw new Error(`Invalid config file: ${errors}`);
+    }
+    return result.data;
+}
+/**
+ * Load project configuration by discovering and parsing config file.
+ *
+ * Walks up the directory tree from startDir to find the config file,
+ * then parses and validates it.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Parsed configuration, or undefined if no config file found
+ * @throws Error if config file is found but cannot be parsed or is invalid
+ *
+ * @example
+ * ```typescript
+ * const config = await loadConfig();
+ * if (config) {
+ *   console.log('Using project config');
+ * } else {
+ *   console.log('No config found, using defaults');
+ * }
+ * ```
+ */
+export async function loadConfig(startDir = process.cwd()) {
+    const configPath = await findConfigFile(startDir);
+    if (!configPath) {
+        return undefined;
+    }
+    return await parseConfigFile(configPath);
+}
+//# sourceMappingURL=config-parser.js.map

package/dist/config-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-parser.js","sourceRoot":"","sources":["../src/config-parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAAE,mBAAmB,EAAsB,MAAM,6BAA6B,CAAC;AAEtF,MAAM,eAAe,GAAG,gCAAgC,CAAC;AAEzD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IACnE,IAAI,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAExC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;QAE1D,IAAI,CAAC;YACH,sDAAsD;YACtD,yGAAyG;YACzG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,UAAU,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,0CAA0C;QAC5C,CAAC;QAED,kCAAkC;QAClC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,wBAAwB;QACxB,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,UAAkB;IACtD,oBAAoB;IACpB,kHAAkH;IAClH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAEpD,aAAa;IACb,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5G,CAAC;IAED,0BAA0B;IAC1B,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,WAAmB,OAAO,CAAC,GAAG,EAAE;IAC/D,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;AAC3C,CAAC"}