maestro-flow 0.4.3 → 0.4.4

package/dist/src/hooks/spec-analytics.js

@@ -0,0 +1,311 @@
+/**
+ * Spec Analytics — Injection logging and statistics
+ *
+ * Records every spec injection call (spec-injector, keyword-spec-injector,
+ * spec-injection-plugin) and CLI endpoint usage. Provides aggregated
+ * statistics for improvement analysis.
+ *
+ * Design:
+ * - Reuses jsonl-log.ts (appendLine, readAll, tailLast, rotateIfLarge)
+ * - Synchronous, never throws — safe for hot-path hooks
+ * - Config cached with 30s TTL to avoid repeated file reads
+ * - Auto-rotation at configurable max file size
+ */
+import { join } from 'node:path';
+import { statSync } from 'node:fs';
+import { appendLine, readAll, tailLast, rotateIfLarge } from '../utils/jsonl-log.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_LOG_PATH = '.workflow/spec-analytics.jsonl';
+const DEFAULT_MAX_SIZE = 5 * 1024 * 1024; // 5MB
+const DEFAULT_ARCHIVE_DIR = '.workflow/archive';
+const ROTATION_CHECK_INTERVAL = 50;
+const CONFIG_CACHE_TTL_MS = 30_000;
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+let _seq = 0;
+let _writeCount = 0;
+let _cachedConfig = null;
+// ---------------------------------------------------------------------------
+// Config resolution
+// ---------------------------------------------------------------------------
+function resolveConfig(projectPath, explicit) {
+    if (explicit)
+        return explicit;
+    const now = Date.now();
+    if (_cachedConfig && _cachedConfig.projectPath === projectPath && (now - _cachedConfig.timestamp) < CONFIG_CACHE_TTL_MS) {
+        return _cachedConfig.config;
+    }
+    try {
+        // Lazy import to avoid circular dependency
+        const { readFileSync, existsSync } = require('node:fs');
+        const configPath = join(projectPath, '.workflow', 'config.json');
+        if (!existsSync(configPath)) {
+            const defaultConfig = { enabled: true };
+            _cachedConfig = { config: defaultConfig, projectPath, timestamp: now };
+            return defaultConfig;
+        }
+        const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+        const config = raw?.specInjection?.analytics ?? { enabled: true };
+        _cachedConfig = { config, projectPath, timestamp: now };
+        return config;
+    }
+    catch {
+        return { enabled: true };
+    }
+}
+function resolveLogPath(projectPath, config) {
+    return join(projectPath, config.logPath ?? DEFAULT_LOG_PATH);
+}
+function resolveArchiveDir(projectPath) {
+    return join(projectPath, DEFAULT_ARCHIVE_DIR);
+}
+// ---------------------------------------------------------------------------
+// Auto-rotation
+// ---------------------------------------------------------------------------
+function maybeRotate(logPath, archiveDir, maxSize) {
+    _writeCount++;
+    if (_writeCount % ROTATION_CHECK_INTERVAL !== 0)
+        return;
+    rotateIfLarge(logPath, maxSize, archiveDir);
+}
+// ---------------------------------------------------------------------------
+// Public API — Logging
+// ---------------------------------------------------------------------------
+/**
+ * Log a spec injection event. Synchronous, never throws.
+ */
+export function logInjectionEvent(projectPath, entry, config) {
+    try {
+        const resolved = resolveConfig(projectPath, config);
+        if (!resolved.enabled)
+            return;
+        const logPath = resolveLogPath(projectPath, resolved);
+        const archiveDir = resolveArchiveDir(projectPath);
+        const fullEntry = {
+            type: 'injection',
+            id: `SINJ-${Date.now()}-${++_seq}`,
+            timestamp: new Date().toISOString(),
+            ...entry,
+        };
+        appendLine(logPath, fullEntry);
+        maybeRotate(logPath, archiveDir, resolved.maxFileSize ?? DEFAULT_MAX_SIZE);
+    }
+    catch {
+        // Swallow — hot path, never fail the host hook
+    }
+}
+/**
+ * Log a CLI endpoint call. Synchronous, never throws.
+ */
+export function logCliEndpoint(projectPath, command, args, config) {
+    try {
+        const resolved = resolveConfig(projectPath, config);
+        if (!resolved.enabled)
+            return;
+        const logPath = resolveLogPath(projectPath, resolved);
+        const archiveDir = resolveArchiveDir(projectPath);
+        const fullEntry = {
+            type: 'cli',
+            id: `CLI-${Date.now()}-${++_seq}`,
+            timestamp: new Date().toISOString(),
+            command,
+            args,
+        };
+        appendLine(logPath, fullEntry);
+        maybeRotate(logPath, archiveDir, resolved.maxFileSize ?? DEFAULT_MAX_SIZE);
+    }
+    catch {
+        // Swallow
+    }
+}
+/**
+ * Log a workflow hook invocation. Synchronous, never throws.
+ */
+export function logHookInvocation(projectPath, entry, config) {
+    try {
+        const resolved = resolveConfig(projectPath, config);
+        if (!resolved.enabled)
+            return;
+        const logPath = resolveLogPath(projectPath, resolved);
+        const archiveDir = resolveArchiveDir(projectPath);
+        const fullEntry = {
+            type: 'hook',
+            id: `HOOK-${Date.now()}-${++_seq}`,
+            timestamp: new Date().toISOString(),
+            ...entry,
+        };
+        appendLine(logPath, fullEntry);
+        maybeRotate(logPath, archiveDir, resolved.maxFileSize ?? DEFAULT_MAX_SIZE);
+    }
+    catch {
+        // Swallow
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API — Reading
+// ---------------------------------------------------------------------------
+/**
+ * Read all analytics entries.
+ */
+export function readAnalytics(projectPath, config) {
+    const resolved = resolveConfig(projectPath, config);
+    const logPath = resolveLogPath(projectPath, resolved);
+    return readAll(logPath);
+}
+/**
+ * Read last N analytics entries (efficient tail).
+ */
+export function readRecentAnalytics(projectPath, n, config) {
+    const resolved = resolveConfig(projectPath, config);
+    const logPath = resolveLogPath(projectPath, resolved);
+    return tailLast(logPath, n);
+}
+/**
+ * Get log file size in bytes. Returns 0 if file doesn't exist.
+ */
+export function getLogFileSize(projectPath, config) {
+    try {
+        const resolved = resolveConfig(projectPath, config);
+        const logPath = resolveLogPath(projectPath, resolved);
+        return statSync(logPath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Clear analytics log by rotating it to archive.
+ */
+export function clearAnalyticsLog(projectPath, config) {
+    const resolved = resolveConfig(projectPath, config);
+    const logPath = resolveLogPath(projectPath, resolved);
+    const archiveDir = resolveArchiveDir(projectPath);
+    // Force rotation regardless of size
+    return rotateIfLarge(logPath, 0, archiveDir);
+}
+// ---------------------------------------------------------------------------
+// Public API — Statistics
+// ---------------------------------------------------------------------------
+/**
+ * Compute aggregated statistics from log entries. Pure function, no IO.
+ */
+export function computeStats(entries, logFileSize = 0) {
+    const bySource = {};
+    const byAgentType = {};
+    const byCategory = {};
+    const byBudgetAction = {};
+    const keywordCounts = {};
+    const cliCounts = {};
+    const hookByName = {};
+    const hookByPlugin = {};
+    let totalInjections = 0;
+    let successfulInjections = 0;
+    let totalKeywordMatches = 0;
+    let totalPromptKeywordsSum = 0;
+    let dedupFilteredSum = 0;
+    let keywordEvents = 0;
+    let hookInvocations = 0;
+    let hookDurationSum = 0;
+    let hookDurationCount = 0;
+    let earliest = '';
+    let latest = '';
+    for (const entry of entries) {
+        // Track time range
+        if (!earliest || entry.timestamp < earliest)
+            earliest = entry.timestamp;
+        if (!latest || entry.timestamp > latest)
+            latest = entry.timestamp;
+        if (entry.type === 'injection') {
+            totalInjections++;
+            if (entry.inject)
+                successfulInjections++;
+            // By source
+            const src = entry.source;
+            if (!bySource[src])
+                bySource[src] = { total: 0, injected: 0 };
+            bySource[src].total++;
+            if (entry.inject)
+                bySource[src].injected++;
+            // By agent type (fall back to source name for keyword/plugin entries)
+            const agent = entry.agentType ?? entry.inferredCategory ?? `(${entry.source})`;
+            if (!byAgentType[agent])
+                byAgentType[agent] = { total: 0, injected: 0 };
+            byAgentType[agent].total++;
+            if (entry.inject)
+                byAgentType[agent].injected++;
+            // By category
+            if (entry.categories) {
+                for (const cat of entry.categories) {
+                    byCategory[cat] = (byCategory[cat] ?? 0) + 1;
+                }
+            }
+            // By budget action
+            if (entry.budgetAction) {
+                byBudgetAction[entry.budgetAction] = (byBudgetAction[entry.budgetAction] ?? 0) + 1;
+            }
+            // Keyword stats
+            if (entry.matchedKeywords) {
+                keywordEvents++;
+                totalKeywordMatches += entry.matchedKeywords.length;
+                for (const kw of entry.matchedKeywords) {
+                    keywordCounts[kw] = (keywordCounts[kw] ?? 0) + 1;
+                }
+            }
+            if (entry.totalPromptKeywords != null) {
+                totalPromptKeywordsSum += entry.totalPromptKeywords;
+            }
+            if (entry.dedupFilteredCount != null) {
+                dedupFilteredSum += entry.dedupFilteredCount;
+            }
+        }
+        else if (entry.type === 'cli') {
+            cliCounts[entry.command] = (cliCounts[entry.command] ?? 0) + 1;
+        }
+        else if (entry.type === 'hook') {
+            hookInvocations++;
+            hookByName[entry.hookName] = (hookByName[entry.hookName] ?? 0) + 1;
+            if (entry.pluginName) {
+                hookByPlugin[entry.pluginName] = (hookByPlugin[entry.pluginName] ?? 0) + 1;
+            }
+            if (entry.durationMs != null) {
+                hookDurationSum += entry.durationMs;
+                hookDurationCount++;
+            }
+        }
+    }
+    // Top keywords (sorted descending, top 20)
+    const topKeywords = Object.entries(keywordCounts)
+        .map(([keyword, count]) => ({ keyword, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 20);
+    return {
+        totalInjections,
+        successfulInjections,
+        failedInjections: totalInjections - successfulInjections,
+        hitRate: totalInjections > 0 ? (successfulInjections / totalInjections) * 100 : 0,
+        bySource,
+        byAgentType,
+        byCategory,
+        byBudgetAction,
+        keywordStats: {
+            totalMatches: totalKeywordMatches,
+            topKeywords,
+            avgMatchedPerPrompt: keywordEvents > 0 ? totalKeywordMatches / keywordEvents : 0,
+            dedupFilteredTotal: dedupFilteredSum,
+        },
+        cliStats: cliCounts,
+        hookStats: {
+            totalInvocations: hookInvocations,
+            byHook: hookByName,
+            byPlugin: hookByPlugin,
+            avgDurationMs: hookDurationCount > 0 ? hookDurationSum / hookDurationCount : 0,
+        },
+        timeRange: { earliest, latest },
+        totalEntries: entries.length,
+        logFileSize,
+    };
+}
+//# sourceMappingURL=spec-analytics.js.map

package/dist/src/hooks/spec-analytics.js.map

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

package/dist/src/hooks/spec-injector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec-injector.d.ts","sourceRoot":"","sources":["../../../src/hooks/spec-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAM7D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,MAAM,GACX,mBAAmB,CA2CrB"}
+{"version":3,"file":"spec-injector.d.ts","sourceRoot":"","sources":["../../../src/hooks/spec-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAO7D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,mBAAmB,EAC5B,GAAG,CAAC,EAAE,MAAM,GACX,mBAAmB,CA2JrB"}

package/dist/src/hooks/spec-injector.js

@@ -8,10 +8,11 @@
  * Design: Uses `additionalContext` (advisory) rather than rewriting
  * the prompt — safer and non-destructive.
  */
-import { loadSpecs } from '../tools/spec-loader.js';
+import { loadSpecs, loadExtraDocs } from '../tools/spec-loader.js';
 import { evaluateContextBudget } from './context-budget.js';
 import { resolveSelf } from '../tools/team-members.js';
 import { loadWikiByCategory } from './wiki-role-loader.js';
+import { logInjectionEvent } from './spec-analytics.js';
 // ---------------------------------------------------------------------------
 // Agent-type → spec categories mapping (single source of truth)
 // ---------------------------------------------------------------------------
@@ -48,20 +49,48 @@ const AGENT_CATEGORY_MAP = {
  */
 export function evaluateSpecInjection(agentType, projectPath, sessionId, config, uid) {
     const categories = resolveCategories(agentType, config);
-    if (!categories || categories.length === 0)
+    if (!categories || categories.length === 0) {
+        logInjectionEvent(projectPath, {
+            source: 'spec-injector',
+            agentType,
+            categories: [],
+            specCount: 0,
+            contentLength: 0,
+            inject: false,
+            reason: 'no-categories',
+        }, config?.analytics);
         return { inject: false };
+    }
     const resolvedUid = uid ?? resolveUidSafe();
+    const kwFilters = resolveKeywordFilters(agentType, config);
     const sections = [];
     const allCategories = [];
     let totalCount = 0;
     for (const category of categories) {
+        // Build loader options with keyword filters and extra spec files
+        const loaderOpts = {};
+        if (kwFilters.include?.length)
+            loaderOpts.includeKeywords = kwFilters.include;
+        if (kwFilters.exclude?.length)
+            loaderOpts.excludeKeywords = kwFilters.exclude;
+        const catDocConfig = config?.categoryDocs?.[category];
+        if (catDocConfig?.specFiles?.length)
+            loaderOpts.extraSpecFiles = catDocConfig.specFiles;
         // Load specs by category (primary doc + keyword cross-match + tool discovery)
-        const specResult = loadSpecs(projectPath, category, resolvedUid);
+        const specResult = loadSpecs(projectPath, category, resolvedUid, undefined, undefined, loaderOpts);
         if (specResult.content) {
             sections.push(specResult.content);
             allCategories.push(category);
             totalCount += specResult.totalLoaded;
         }
+        // Load category-level extra documents
+        if (catDocConfig?.docs?.length) {
+            const docsResult = loadExtraDocs(projectPath, catDocConfig.docs);
+            if (docsResult.content) {
+                sections.push(docsResult.content);
+                totalCount += docsResult.count;
+            }
+        }
         // Wiki category knowledge injection
         const wikiResult = loadWikiByCategory(projectPath, category);
         if (wikiResult) {
@@ -69,13 +98,88 @@ export function evaluateSpecInjection(agentType, projectPath, sessionId, config,
             totalCount += wikiResult.entryCount;
         }
     }
-    if (sections.length === 0)
+    // Agent-specific extra documents
+    const agentExtras = config?.mapping?.[agentType]?.extras;
+    if (agentExtras?.length) {
+        const extrasResult = loadExtraDocs(projectPath, agentExtras);
+        if (extrasResult.content) {
+            sections.push(extrasResult.content);
+            totalCount += extrasResult.count;
+        }
+    }
+    // Always-inject (session start): documents, keyword-matched entries, and categories
+    if (config?.always) {
+        const always = config.always;
+        // Always-inject documents
+        if (always.docs?.length) {
+            const alwaysResult = loadExtraDocs(projectPath, always.docs);
+            if (alwaysResult.content) {
+                sections.push(alwaysResult.content);
+                totalCount += alwaysResult.count;
+            }
+        }
+        // Always-inject keyword-matched entries (load from all specs, filter by keywords)
+        if (always.keywords?.length) {
+            const kwOpts = { includeKeywords: always.keywords };
+            const kwResult = loadSpecs(projectPath, undefined, resolvedUid, undefined, undefined, kwOpts);
+            if (kwResult.content) {
+                sections.push(kwResult.content);
+                totalCount += kwResult.totalLoaded;
+            }
+        }
+        // Always-inject full categories
+        if (always.categories?.length) {
+            for (const cat of always.categories) {
+                if (allCategories.includes(cat))
+                    continue; // Already loaded above
+                const catResult = loadSpecs(projectPath, cat, resolvedUid);
+                if (catResult.content) {
+                    sections.push(catResult.content);
+                    totalCount += catResult.totalLoaded;
+                }
+            }
+        }
+    }
+    if (sections.length === 0) {
+        logInjectionEvent(projectPath, {
+            source: 'spec-injector',
+            agentType,
+            categories: allCategories,
+            specCount: totalCount,
+            contentLength: 0,
+            inject: false,
+            reason: 'no-content',
+        }, config?.analytics);
         return { inject: false };
-    const rawContent = sections.join('\n\n---\n\n');
+    }
+    let rawContent = sections.join('\n\n---\n\n');
+    // Apply maxContentLength before context budget
+    if (config?.maxContentLength && rawContent.length > config.maxContentLength) {
+        rawContent = rawContent.slice(0, config.maxContentLength);
+    }
     const budget = evaluateContextBudget(rawContent, sessionId);
     if (budget.action === 'skip') {
+        logInjectionEvent(projectPath, {
+            source: 'spec-injector',
+            agentType,
+            categories: allCategories,
+            specCount: totalCount,
+            budgetAction: 'skip',
+            contentLength: rawContent.length,
+            inject: false,
+            reason: 'budget-skip',
+        }, config?.analytics);
         return { inject: false, budgetAction: 'skip' };
     }
+    logInjectionEvent(projectPath, {
+        source: 'spec-injector',
+        agentType,
+        categories: allCategories,
+        specCount: totalCount,
+        budgetAction: budget.action,
+        contentLength: budget.content?.length ?? 0,
+        inject: true,
+    }, config?.analytics);
     return {
         inject: true,
         content: budget.content,
@@ -110,4 +214,22 @@ function resolveCategories(agentType, config) {
     }
     return AGENT_CATEGORY_MAP[agentType] ?? null;
 }
+/**
+ * Merge keyword filters from agent-level and global-level config.
+ * Agent-level include replaces global include; excludes are merged.
+ */
+function resolveKeywordFilters(agentType, config) {
+    if (!config)
+        return {};
+    const agentMapping = config.mapping?.[agentType];
+    const globalFilters = config.keywordFilters;
+    const include = agentMapping?.includeKeywords ?? globalFilters?.include;
+    const agentExclude = agentMapping?.excludeKeywords ?? [];
+    const globalExclude = globalFilters?.exclude ?? [];
+    const mergedExclude = [...agentExclude, ...globalExclude];
+    return {
+        include: include?.length ? include : undefined,
+        exclude: mergedExclude.length > 0 ? mergedExclude : undefined,
+    };
+}
 //# sourceMappingURL=spec-injector.js.map

package/dist/src/hooks/spec-injector.js.map

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

package/dist/src/tools/spec-loader.d.ts

@@ -47,6 +47,26 @@ export declare function resolveSpecDir(projectPath: string, scope: SpecScope, ui
 export interface LoadSpecsOptions {
     /** Override global specs directory (for testing). Defaults to ~/.maestro/specs/ */
     globalDir?: string;
+    /** Keyword whitelist: only include entries matching at least one keyword */
+    includeKeywords?: string[];
+    /** Keyword blacklist: exclude entries matching any of these keywords */
+    excludeKeywords?: string[];
+    /** Extra spec filenames to include for the category (dynamic CATEGORY_MAP extension) */
+    extraSpecFiles?: string[];
 }
 export declare function loadSpecs(projectPath: string, category?: SpecCategory, uid?: string, keyword?: string, scope?: SpecScope, options?: LoadSpecsOptions): SpecLoadResult;
+export interface ExtraDocsResult {
+    content: string;
+    count: number;
+}
+/**
+ * Load additional documents from arbitrary paths.
+ *
+ * Path resolution:
+ *   - Starts with `knowhow/` → resolved from `.workflow/knowhow/`
+ *   - Otherwise → resolved relative to projectPath
+ *
+ * Returns concatenated markdown content and loaded count.
+ */
+export declare function loadExtraDocs(projectPath: string, docPaths?: string[]): ExtraDocsResult;
 //# sourceMappingURL=spec-loader.d.ts.map

package/dist/src/tools/spec-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spec-loader.d.ts","sourceRoot":"","sources":["../../../src/tools/spec-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAC;AAE/F,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CASrD,CAAC;AAGF,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAcvD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAW1F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAqDrK"}
+{"version":3,"file":"spec-loader.d.ts","sourceRoot":"","sources":["../../../src/tools/spec-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAC;AAE/F,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CASrD,CAAC;AAGF,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAcvD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAW1F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAqDrK;AA6WD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,eAAe,CA0BvF"}