@principal-ai/subsystems-core 0.29.0

package/dist/rules/types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Rules Engine Type Definitions
+ * Provides types for configuration validation rules
+ */
+/**
+ * Severity levels following ESLint convention
+ * - "off" or 0: Disable rule
+ * - "warn" or 1: Warning (doesn't affect exit code)
+ * - "error" or 2: Error (exit code 1)
+ */
+export type RuleSeverity = 'off' | 'warn' | 'error' | 0 | 1 | 2;
+/**
+ * Normalized severity (string form only)
+ */
+export type NormalizedSeverity = 'off' | 'warn' | 'error';
+/**
+ * Rule categories for grouping and filtering
+ */
+export type RuleCategory = 'schema' | 'reference' | 'structure' | 'pattern' | 'library';
+/**
+ * Full rule configuration object
+ */
+export interface RuleConfig {
+    /**
+     * Rule severity
+     * @default "error"
+     */
+    severity?: RuleSeverity;
+    /**
+     * Rule-specific options
+     */
+    options?: Record<string, unknown>;
+}
+/**
+ * VGC Configuration file schema
+ */
+export interface PrivuConfig {
+    /**
+     * Schema version for forward compatibility
+     */
+    $schema?: string;
+    /**
+     * Extend from a shared configuration
+     * Can be a package name or relative path
+     */
+    extends?: string | string[];
+    /**
+     * Root flag - stop searching parent directories
+     * @default false
+     */
+    root?: boolean;
+    /**
+     * Path to default component library
+     * Used by library-node-type-match rule
+     */
+    library?: string;
+    /**
+     * Glob patterns for configuration files to lint
+     * @default [".principal-views/**\/*.yaml", ".principal-views/**\/*.yml", ".principal-views/**\/*.json"]
+     */
+    include?: string[];
+    /**
+     * Glob patterns to exclude from linting
+     * @default ["**\/node_modules/**", "**\/*.test.*"]
+     */
+    exclude?: string[];
+    /**
+     * Rule configurations
+     */
+    rules?: {
+        [ruleId: string]: RuleConfig | RuleSeverity | false;
+    };
+}
+/**
+ * Rule-specific options type (varies per rule)
+ */
+export type RuleOptions = Record<string, unknown>;
+/**
+ * Definition of a validation rule
+ */
+export interface GraphRule<TOptions extends RuleOptions = RuleOptions> {
+    /**
+     * Unique rule identifier (kebab-case)
+     */
+    id: string;
+    /**
+     * Human-readable rule name
+     */
+    name: string;
+    /**
+     * Brief description of what the rule checks
+     */
+    description: string;
+    /**
+     * Explanation of why this rule matters
+     */
+    impact: string;
+    /**
+     * Default severity level
+     * @default "error"
+     */
+    severity: NormalizedSeverity;
+    /**
+     * Rule category for grouping
+     */
+    category: RuleCategory;
+    /**
+     * Whether the rule is enabled by default
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Whether the rule supports auto-fix
+     * @default false
+     */
+    fixable: boolean;
+    /**
+     * Default options for this rule
+     */
+    defaultOptions?: TOptions;
+    /**
+     * Execute the rule check
+     */
+    check: (context: GraphRuleContext<TOptions>) => Promise<GraphRuleViolation[]>;
+    /**
+     * Optional auto-fix implementation
+     */
+    fix?: (violation: GraphRuleViolation, context: GraphRuleContext<TOptions>) => Promise<FixResult>;
+}
+import type { GraphConfiguration } from '../types';
+import type { ComponentLibrary } from '../types/library';
+/**
+ * Context passed to rules during evaluation
+ */
+export interface GraphRuleContext<TOptions extends RuleOptions = RuleOptions> {
+    /**
+     * The configuration being validated
+     */
+    configuration: GraphConfiguration;
+    /**
+     * Optional component library for library rules
+     */
+    library?: ComponentLibrary;
+    /**
+     * Path to the configuration file (for error reporting)
+     */
+    configPath?: string;
+    /**
+     * Path to the library file (for error reporting)
+     */
+    libraryPath?: string;
+    /**
+     * Raw YAML/JSON string (for line number lookup)
+     */
+    rawContent?: string;
+    /**
+     * Rule-specific options (merged with defaults)
+     */
+    options: TOptions;
+    /**
+     * All rule options from config (for cross-rule access if needed)
+     */
+    allRuleOptions?: Map<string, RuleOptions>;
+}
+/**
+ * A violation detected by a rule
+ */
+export interface GraphRuleViolation {
+    /**
+     * ID of the rule that detected this violation
+     */
+    ruleId: string;
+    /**
+     * Severity of this violation
+     */
+    severity: NormalizedSeverity;
+    /**
+     * Path to the file containing the violation
+     */
+    file?: string;
+    /**
+     * Line number in the file (1-indexed)
+     */
+    line?: number;
+    /**
+     * Column number in the file (1-indexed)
+     */
+    column?: number;
+    /**
+     * JSON path to the problematic field (e.g., "nodeTypes.service.shape")
+     */
+    path?: string;
+    /**
+     * Clear, actionable error message
+     */
+    message: string;
+    /**
+     * Explanation of why this matters
+     */
+    impact: string;
+    /**
+     * Suggestion for how to fix
+     */
+    suggestion?: string;
+    /**
+     * Whether this violation can be auto-fixed
+     */
+    fixable: boolean;
+    /**
+     * Data needed for auto-fix
+     */
+    fixData?: Record<string, unknown>;
+}
+/**
+ * Result of running all rules
+ */
+export interface GraphLintResult {
+    /**
+     * All violations found
+     */
+    violations: GraphRuleViolation[];
+    /**
+     * Count of error-level violations
+     */
+    errorCount: number;
+    /**
+     * Count of warning-level violations
+     */
+    warningCount: number;
+    /**
+     * Count of fixable violations
+     */
+    fixableCount: number;
+    /**
+     * Violations grouped by category
+     */
+    byCategory: Record<RuleCategory, number>;
+    /**
+     * Violations grouped by rule ID
+     */
+    byRule: Record<string, number>;
+}
+/**
+ * Result of attempting to fix a violation
+ */
+export interface FixResult {
+    /**
+     * Whether the fix was successful
+     */
+    success: boolean;
+    /**
+     * Description of what was fixed
+     */
+    message?: string;
+    /**
+     * New content after fix (if applicable)
+     */
+    newContent?: string;
+    /**
+     * Error message if fix failed
+     */
+    error?: string;
+}
+/**
+ * Options for the lint operation
+ */
+export interface LintOptions {
+    /**
+     * Only run these rules (by ID)
+     */
+    enabledRules?: string[];
+    /**
+     * Skip these rules (by ID)
+     */
+    disabledRules?: string[];
+    /**
+     * Override severity for specific rules
+     */
+    severityOverrides?: Map<string, NormalizedSeverity>;
+    /**
+     * Component library for library rules
+     */
+    library?: ComponentLibrary;
+    /**
+     * Path to config file (for error reporting)
+     */
+    configPath?: string;
+    /**
+     * Path to library file (for error reporting)
+     */
+    libraryPath?: string;
+    /**
+     * Raw content for line number reporting
+     */
+    rawContent?: string;
+    /**
+     * Rule-specific options
+     */
+    ruleOptions?: Map<string, RuleOptions>;
+}
+/**
+ * Normalize severity to string form
+ */
+export declare function normalizeSeverity(severity: RuleSeverity): NormalizedSeverity;
+/**
+ * Check if a severity means the rule is disabled
+ */
+export declare function isRuleDisabled(severity: RuleSeverity | false | undefined): boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/rules/types.d.ts.map

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

package/dist/rules/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Rules Engine Type Definitions
+ * Provides types for configuration validation rules
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRuleDisabled = exports.normalizeSeverity = void 0;
+// ============================================================================
+// Utility Types
+// ============================================================================
+/**
+ * Normalize severity to string form
+ */
+function normalizeSeverity(severity) {
+    if (typeof severity === 'number') {
+        switch (severity) {
+            case 0:
+                return 'off';
+            case 1:
+                return 'warn';
+            case 2:
+                return 'error';
+            default:
+                return 'error';
+        }
+    }
+    return severity;
+}
+exports.normalizeSeverity = normalizeSeverity;
+/**
+ * Check if a severity means the rule is disabled
+ */
+function isRuleDisabled(severity) {
+    if (severity === false || severity === 'off' || severity === 0) {
+        return true;
+    }
+    return false;
+}
+exports.isRuleDisabled = isRuleDisabled;
+//# sourceMappingURL=types.js.map

package/dist/rules/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rules/types.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAuYH,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;GAEG;AACH,SAAgB,iBAAiB,CAAC,QAAsB;IACtD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE;QAChC,QAAQ,QAAQ,EAAE;YAChB,KAAK,CAAC;gBACJ,OAAO,KAAK,CAAC;YACf,KAAK,CAAC;gBACJ,OAAO,MAAM,CAAC;YAChB,KAAK,CAAC;gBACJ,OAAO,OAAO,CAAC;YACjB;gBACE,OAAO,OAAO,CAAC;SAClB;KACF;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAdD,8CAcC;AAED;;GAEG;AACH,SAAgB,cAAc,CAAC,QAA0C;IACvE,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,CAAC,EAAE;QAC9D,OAAO,IAAI,CAAC;KACb;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AALD,wCAKC"}

package/dist/scopes/ScopePathIndex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Scope Path Index
+ *
+ * Maps a filepath to the `otel-scope` that owns it, using the `paths` field
+ * declared on `otel-scope` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple scopes
+ * have paths covering the same file, the one whose matched path is the most
+ * specific (longest after normalization) wins. This naturally supports nested
+ * scopes by dotted-name (e.g. `principal-ai.core` and
+ * `principal-ai.core.validation`), where the child claims its subtree without
+ * stealing the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+/**
+ * One declared scope/paths tuple. Multiple entries may share the same scope
+ * if a scope canvas needs to declare more than one region (generated code,
+ * platform splits, migration periods).
+ */
+export interface ScopePathEntry {
+    scope: string;
+    paths: string[];
+    /** Optional — useful for surfacing where a match came from in diagnostics. */
+    sourceCanvasPath?: string;
+}
+/**
+ * Result of resolving a file against the index.
+ */
+export interface ScopePathMatch {
+    /** The winning entry (by longest-prefix). */
+    entry: ScopePathEntry;
+    /** Which of the entry's paths covered the file — the one that won. */
+    matchedPath: string;
+}
+export declare class ScopePathIndex {
+    private entries;
+    /** Register a single scope/paths entry. */
+    add(entry: ScopePathEntry): void;
+    /** Register many entries at once. */
+    addAll(entries: readonly ScopePathEntry[]): void;
+    /**
+     * Resolve a filepath to its owning scope.
+     * Returns null if no entry has a path covering the file.
+     */
+    resolve(filepath: string): ScopePathMatch | null;
+    /**
+     * Look up the entry for a specific scope. Returns null when the scope
+     * isn't registered — either because its scopes-canvas node omits `paths`
+     * (opt-out of enforcement) or because no such scope is declared.
+     */
+    getEntry(scope: string): ScopePathEntry | null;
+    /** All scopes present in the index. */
+    getScopes(): readonly string[];
+}
+//# sourceMappingURL=ScopePathIndex.d.ts.map

package/dist/scopes/ScopePathIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopePathIndex.d.ts","sourceRoot":"","sources":["../../src/scopes/ScopePathIndex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,KAAK,EAAE,cAAc,CAAC;IACtB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IAEvC,2CAA2C;IAC3C,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIhC,qCAAqC;IACrC,MAAM,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAIhD;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAkBhD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI9C,uCAAuC;IACvC,SAAS,IAAI,SAAS,MAAM,EAAE;CAG/B"}

package/dist/scopes/ScopePathIndex.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Scope Path Index
+ *
+ * Maps a filepath to the `otel-scope` that owns it, using the `paths` field
+ * declared on `otel-scope` nodes.
+ *
+ * Resolution uses the longest-prefix partitioning rule: when multiple scopes
+ * have paths covering the same file, the one whose matched path is the most
+ * specific (longest after normalization) wins. This naturally supports nested
+ * scopes by dotted-name (e.g. `principal-ai.core` and
+ * `principal-ai.core.validation`), where the child claims its subtree without
+ * stealing the parent's.
+ *
+ * Pure/browser-safe — no filesystem access, just string comparison.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopePathIndex = void 0;
+const path_helpers_1 = require("../events/path-helpers");
+class ScopePathIndex {
+    constructor() {
+        this.entries = [];
+    }
+    /** Register a single scope/paths entry. */
+    add(entry) {
+        this.entries.push(entry);
+    }
+    /** Register many entries at once. */
+    addAll(entries) {
+        for (const e of entries)
+            this.add(e);
+    }
+    /**
+     * Resolve a filepath to its owning scope.
+     * Returns null if no entry has a path covering the file.
+     */
+    resolve(filepath) {
+        const normalizedFile = (0, path_helpers_1.normalizePath)(filepath);
+        let best = null;
+        for (const entry of this.entries) {
+            for (const declared of entry.paths) {
+                if (!(0, path_helpers_1.pathCovers)(declared, normalizedFile))
+                    continue;
+                const normalizedDeclared = (0, path_helpers_1.normalizePath)(declared);
+                const length = normalizedDeclared.length;
+                if (best === null || length > best.length) {
+                    best = { entry, matchedPath: declared, length };
+                }
+            }
+        }
+        return best ? { entry: best.entry, matchedPath: best.matchedPath } : null;
+    }
+    /**
+     * Look up the entry for a specific scope. Returns null when the scope
+     * isn't registered — either because its scopes-canvas node omits `paths`
+     * (opt-out of enforcement) or because no such scope is declared.
+     */
+    getEntry(scope) {
+        return this.entries.find((e) => e.scope === scope) ?? null;
+    }
+    /** All scopes present in the index. */
+    getScopes() {
+        return Array.from(new Set(this.entries.map((e) => e.scope)));
+    }
+}
+exports.ScopePathIndex = ScopePathIndex;
+//# sourceMappingURL=ScopePathIndex.js.map

package/dist/scopes/ScopePathIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopePathIndex.js","sourceRoot":"","sources":["../../src/scopes/ScopePathIndex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,yDAAmE;AAwBnE,MAAa,cAAc;IAA3B;QACU,YAAO,GAAqB,EAAE,CAAC;IA+CzC,CAAC;IA7CC,2CAA2C;IAC3C,GAAG,CAAC,KAAqB;QACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,qCAAqC;IACrC,MAAM,CAAC,OAAkC;QACvC,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,QAAgB;QACtB,MAAM,cAAc,GAAG,IAAA,4BAAa,EAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,IAAI,GAA0E,IAAI,CAAC;QAEvF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE;YAChC,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,KAAK,EAAE;gBAClC,IAAI,CAAC,IAAA,yBAAU,EAAC,QAAQ,EAAE,cAAc,CAAC;oBAAE,SAAS;gBACpD,MAAM,kBAAkB,GAAG,IAAA,4BAAa,EAAC,QAAQ,CAAC,CAAC;gBACnD,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC;gBACzC,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE;oBACzC,IAAI,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;iBACjD;aACF;SACF;QAED,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAa;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC;IAC7D,CAAC;IAED,uCAAuC;IACvC,SAAS;QACP,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;CACF;AAhDD,wCAgDC"}

package/dist/scopes/ScopesCanvasValidator.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Scopes Canvas Validator
+ *
+ * Validates that a .scopes.canvas file exists and properly documents
+ * all instrumentation scopes declared in library.yaml.
+ */
+import type { FileSystemAdapter } from '@principal-ai/repository-abstraction';
+import type { ExtendedCanvas } from '../types/canvas';
+/**
+ * Scopes canvas validation context
+ */
+export interface ScopesCanvasValidationContext {
+    /** The scopes canvas (if found) */
+    scopesCanvas?: ExtendedCanvas;
+    /** Path to the scopes canvas file */
+    scopesCanvasPath?: string;
+    /** Owned scopes from library.yaml */
+    ownedScopes: string[];
+    /** Base path for resolving relative paths */
+    basePath: string;
+}
+/**
+ * Scopes canvas validation violation
+ */
+export interface ScopesCanvasViolation {
+    /** Rule ID that detected this violation */
+    ruleId: string;
+    /** Severity level */
+    severity: 'error' | 'warn';
+    /** File path where violation occurred */
+    file: string;
+    /** JSON path within file (optional) */
+    path?: string;
+    /** Human-readable description of what's wrong */
+    message: string;
+    /** Why this matters */
+    impact: string;
+    /** How to fix it */
+    suggestion: string;
+}
+/**
+ * Scopes canvas validation result
+ */
+export interface ScopesCanvasValidationResult {
+    /** Whether validation passed (no errors) */
+    valid: boolean;
+    /** List of violations found */
+    violations: ScopesCanvasViolation[];
+    /** Summary of scopes coverage */
+    coverage: {
+        /** Total owned scopes from library.yaml */
+        totalOwnedScopes: number;
+        /** Scopes documented in canvas */
+        documentedScopes: string[];
+        /** Scopes missing from canvas */
+        missingScopes: string[];
+        /** Scopes in canvas but not in owned-scopes */
+        extraScopes: string[];
+    };
+}
+/**
+ * Validates scopes canvas files
+ */
+export declare class ScopesCanvasValidator {
+    private fsAdapter;
+    constructor(fsAdapter: FileSystemAdapter);
+    /**
+     * Validate a scopes canvas against library.yaml owned-scopes
+     */
+    validate(context: ScopesCanvasValidationContext): Promise<ScopesCanvasValidationResult>;
+    /**
+     * Extract scope information from canvas nodes (otel-scope nodes only)
+     */
+    private extractScopesFromCanvas;
+}
+//# sourceMappingURL=ScopesCanvasValidator.d.ts.map

package/dist/scopes/ScopesCanvasValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopesCanvasValidator.d.ts","sourceRoot":"","sources":["../../src/scopes/ScopesCanvasValidator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAsD,MAAM,iBAAiB,CAAC;AAI1G;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,mCAAmC;IACnC,YAAY,CAAC,EAAE,cAAc,CAAC;IAE9B,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,qCAAqC;IACrC,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IAEf,qBAAqB;IACrB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAE3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAEhB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IAEf,oBAAoB;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,4CAA4C;IAC5C,KAAK,EAAE,OAAO,CAAC;IAEf,+BAA+B;IAC/B,UAAU,EAAE,qBAAqB,EAAE,CAAC;IAEpC,iCAAiC;IACjC,QAAQ,EAAE;QACR,2CAA2C;QAC3C,gBAAgB,EAAE,MAAM,CAAC;QACzB,kCAAkC;QAClC,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,iCAAiC;QACjC,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,+CAA+C;QAC/C,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,qBAAqB;IACpB,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,iBAAiB;IAEhD;;OAEG;IACG,QAAQ,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,4BAA4B,CAAC;IAgM7F;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAsBhC"}