@functional-examples/devkit 0.0.0-alpha.1

package/dist/types/index.d.ts

@@ -0,0 +1,463 @@
+/**
+ * Core type definitions for functional-examples
+ */
+import type { CLI } from 'cli-forge';
+import type { Dirent } from 'node:fs';
+/**
+ * A single validation error.
+ */
+export interface ValidationError {
+    /** JSON path to the invalid value (e.g., "metadata.tags[0]") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Result of a validation operation.
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    success: boolean;
+    /** Validation errors (empty if success is true) */
+    errors: ValidationError[];
+}
+/**
+ * Base metadata that all examples should have.
+ * Used for type constraints when users want stricter typing.
+ */
+export interface BaseMetadata {
+    /** Unique identifier for the example */
+    id: string;
+    /** Human-readable title */
+    title: string;
+    /** Description of what the example demonstrates */
+    description?: string;
+}
+/**
+ * Augmentable registry for example metadata typing.
+ *
+ * Run `functional-examples generate` to create a declaration file that
+ * augments this interface, providing type-safe metadata for your examples.
+ *
+ * @example Manual augmentation (or use `generate` command):
+ * ```typescript
+ * declare module '@functional-examples/devkit' {
+ *   interface ExampleMetadataRegistry {
+ *     metadata: {
+ *       id: string;
+ *       title: string;
+ *       tags?: string[];
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface ExampleMetadataRegistry {
+}
+/**
+ * Resolved example metadata type.
+ *
+ * If `ExampleMetadataRegistry` has been augmented with a `metadata` property,
+ * this resolves to that type. Otherwise, falls back to `Record<string, unknown>`.
+ *
+ * This allows the `generate` command to provide project-specific types that
+ * automatically apply to all `Example` types without explicit generic parameters.
+ */
+export type ExampleMetadata = ExampleMetadataRegistry extends {
+    metadata: infer T;
+} ? T : Record<string, unknown>;
+/**
+ * Parsed code region from #region markers.
+ */
+export interface ParsedRegion {
+    /** Region identifier from #region <id> */
+    id: string;
+    /** Content between region markers (markers stripped) */
+    content: string;
+    /** Line number where #region marker appears (1-based) */
+    startLine: number;
+    /** Line number where #endregion marker appears (1-based) */
+    endLine: number;
+}
+/**
+ * A file within an example, with optional processed content.
+ */
+export interface ExampleFile {
+    /** Absolute path to the file */
+    absolutePath: string;
+    /** Path relative to example root */
+    relativePath: string;
+    /** @deprecated Use absolutePath instead */
+    path?: string;
+    /** Raw file contents (may be lazy-loaded) */
+    raw?: string;
+    /** Parsed content with metadata/markers stripped */
+    parsed?: string;
+    /** Extracted code regions */
+    hunks?: ParsedRegion[];
+}
+/**
+ * A discovered example with metadata and files.
+ * This is the base type returned by extractors.
+ *
+ * Metadata is typed via `ExampleMetadata` by default, which can be augmented
+ * by running `functional-examples generate`. You can also pass an explicit
+ * generic parameter for custom typing.
+ */
+export interface Example<TMetadata = ExampleMetadata> {
+    /** Unique identifier for this example */
+    id: string;
+    /** Human-readable title */
+    title: string;
+    /** Optional description */
+    description?: string;
+    /** Absolute path to the example root (file or directory) */
+    rootPath: string;
+    /** All files belonging to this example */
+    files: ExampleFile[];
+    /** Additional metadata (loosely typed unless user provides schema) */
+    metadata: TMetadata;
+    /** Which extractor produced this example */
+    extractorName: string;
+}
+/**
+ * An example after processing by the scanner.
+ * Includes computed fields like displayPath that are added during scanning.
+ */
+export interface ScannedExample<TMetadata = ExampleMetadata> extends Example<TMetadata> {
+    /**
+     * Path relative to the config/scan root, useful for display in errors
+     * and snapshots (avoids machine-specific absolute paths).
+     */
+    displayPath: string;
+}
+/**
+ * Error encountered during extraction
+ */
+export interface ExtractorError {
+    /** Path where error occurred */
+    path: string;
+    /** Error message */
+    message: string;
+    /** Original error if available */
+    cause?: Error;
+}
+/**
+ * Options passed to extractor during extraction
+ */
+export interface ExtractorOptions {
+    /** Absolute path to the config root (for context/relative paths) */
+    rootPath: string;
+    /** Glob patterns to exclude (for internal filtering within directories) */
+    exclude?: string[];
+    /** Signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Result from a candidate-based extractor
+ */
+export interface ExtractorResult<TMetadata = Record<string, unknown>> {
+    /** All examples found by this extractor */
+    examples: Example<TMetadata>[];
+    /** Errors encountered during extraction */
+    errors: ExtractorError[];
+    /** Files claimed by this extractor (absolute paths, for conflict detection) */
+    claimedFiles: Set<string>;
+}
+/**
+ * Candidate-based extractor interface.
+ * Called with pre-filtered candidates (files and/or directories).
+ * Extractor decides which candidates it can handle.
+ */
+export interface Extractor<TMetadata = Record<string, unknown>> {
+    /** Unique name for this extractor */
+    readonly name: string;
+    /**
+     * Extract examples from the provided candidates.
+     * Candidates are pre-filtered by include/exclude patterns.
+     *
+     * @param candidates - Dirent entries (files and/or directories) to consider
+     * @param options - Extraction options including rootPath for context
+     * @returns All examples found and files claimed
+     */
+    extract(candidates: Dirent[], options: ExtractorOptions): Promise<ExtractorResult<TMetadata>>;
+}
+/**
+ * Factory function to create an extractor with options
+ */
+export type ExtractorFactory<TOptions = Record<string, unknown>, TMetadata = Record<string, unknown>> = (options?: TOptions) => Extractor<TMetadata>;
+/**
+ * Context passed through the FileContentsParser pipeline.
+ * Each parser receives this, transforms it, and returns an updated version.
+ */
+export interface FileParseContext {
+    /** Original file content, never modified */
+    raw: string;
+    /** Transformed content (frontmatter/markers stripped) */
+    parsed: string;
+    /** Extracted code regions (only explicit #region blocks) */
+    hunks: ParsedRegion[];
+    /** Metadata extracted by parsers */
+    metadata: Record<string, unknown>;
+    /** Absolute path to the file */
+    filePath: string;
+}
+/**
+ * Parser that processes file contents in a pipeline.
+ * Receives accumulated context, transforms it, returns updated context.
+ */
+export interface FileContentsParser {
+    /** Unique parser name for debugging/logging */
+    readonly name: string;
+    /**
+     * Process file content and return updated context.
+     * @param context - Current accumulated parse context
+     * @returns Updated context (should not mutate input)
+     */
+    parse(context: FileParseContext): FileParseContext | Promise<FileParseContext>;
+}
+/**
+ * Schema definitions for a plugin (JSON Schema format).
+ * Used for IDE autocomplete and documentation generation.
+ */
+export interface PluginSchemas {
+    /**
+     * JSON Schema for plugin options (passed to createPlugin()).
+     * Used to generate config file schema for IDE autocomplete.
+     */
+    options?: string;
+    /**
+     * JSON Schema for metadata this plugin produces or expects.
+     * Used for metadata.d.ts generation and documentation.
+     */
+    metadata?: string;
+}
+/**
+ * Validator functions for a plugin.
+ * Allows plugins to use any validation library (Zod, TypeBox, etc.)
+ */
+export interface PluginValidators<TMetadata = Record<string, unknown>> {
+    /**
+     * Validates plugin options before extraction begins.
+     * Called during config resolution.
+     * @param options - The options passed to the plugin factory
+     */
+    options?: (options: unknown) => ValidationResult;
+    /**
+     * Validates extracted metadata after all extractors complete.
+     * Called for each example's metadata.
+     * @param metadata - The metadata from an extracted example
+     */
+    metadata?: (metadata: TMetadata) => ValidationResult;
+}
+/**
+ * Scan configuration options.
+ */
+export interface ScanConfig {
+    /** Include patterns (applied after extraction) */
+    include?: string[];
+    /** Exclude patterns (applied after extraction) */
+    exclude?: string[];
+    /** Base Path for scan. Differs from `root` in that it only impacts scanning. */
+    root?: string;
+}
+/**
+ * Path-to-extractor mapping for conflict resolution.
+ */
+export interface PathMapping {
+    /** Glob pattern for paths */
+    pattern: string;
+    /** Extractor name that wins for matching paths */
+    extractor: string;
+}
+/**
+ * Error from config validation.
+ */
+export interface ConfigValidationError {
+    /** JSON path to the invalid value */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Location code (e.g., Zod issue code) */
+    location?: string;
+    /** Suggested fix for the error */
+    fix?: string;
+}
+/**
+ * Wrapper for a plugin's validator function with plugin name context.
+ */
+export interface PluginValidatorEntry<T = unknown> {
+    pluginName: string;
+    validate: (value: T) => ValidationResult;
+}
+/**
+ * Schema entry from a plugin with plugin name context.
+ */
+export interface PluginSchemaEntry {
+    pluginName: string;
+    options?: string;
+    metadata?: string;
+}
+/**
+ * Plugin registry interface for accessing validators/schemas.
+ * Full implementation is in plugins/registry.ts.
+ */
+export interface PluginRegistryInterface {
+    /** Register a plugin */
+    register(plugin: Plugin): void;
+    /** Get all registered plugins */
+    getPlugins(): readonly Plugin[];
+    /** Get plugins for a file extension */
+    getPluginsForExtension(extension: string): Plugin[];
+    /** Get all extractors from plugins */
+    getExtractors(): Extractor[];
+    /** Get parsers for a file extension */
+    getParsersForExtension(extension: string): FileContentsParser[];
+    /** Get all options validators */
+    getOptionsValidators(): PluginValidatorEntry<unknown>[];
+    /** Get all metadata validators */
+    getMetadataValidators(): PluginValidatorEntry[];
+    /** Get all schemas from plugins */
+    getSchemas(): PluginSchemaEntry[];
+}
+/**
+ * Reference to an extractor package (for config files)
+ */
+export interface ExtractorConfig {
+    /** Package name */
+    name: string;
+    /** Module specifier (package name or path) */
+    module: string;
+    /** Options to pass to the extractor factory */
+    options?: Record<string, unknown>;
+}
+/**
+ * Extractor can be specified as string (package name) or full config
+ */
+export type ExtractorReference = string | ExtractorConfig;
+/**
+ * An extractor can be a reference (to load) or an instance
+ */
+export type ExtractorConfigOrFunction<TMetadata = Record<string, unknown>> = ExtractorReference | Extractor<TMetadata>;
+/**
+ * JSON Schema object for metadata validation.
+ * Subset of JSON Schema spec used for config files.
+ */
+export interface JSONSchemaObject {
+    type?: string;
+    properties?: Record<string, JSONSchemaObject>;
+    required?: string[];
+    items?: JSONSchemaObject;
+    enum?: unknown[];
+    const?: unknown;
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration for the generate command output.
+ */
+export interface GenerateConfig {
+    /** Output directory for generated files (default: .functional-examples) */
+    outputDir?: string;
+}
+export interface Config<TMetadata = Record<string, unknown>> {
+    /** Plugins to use for scanning and parsing (recommended) */
+    plugins?: Plugin<TMetadata>[];
+    /** Scan options */
+    scan?: ScanConfig;
+    /** Path mappings for conflict resolution */
+    pathMappings?: PathMapping[];
+    /**
+     * JSON Schema defining the expected metadata structure for examples.
+     * This is the user's base metadata contract - all examples must conform to it.
+     * Overrides plugin metadata schemas on conflict.
+     *
+     * @example
+     * ```typescript
+     * metadata: {
+     *   type: 'object',
+     *   properties: {
+     *     id: { type: 'string' },
+     *     title: { type: 'string' },
+     *     category: { type: 'string', enum: ['tutorial', 'recipe', 'reference'] },
+     *   },
+     *   required: ['id', 'title', 'category'],
+     * }
+     * ```
+     */
+    metadata?: JSONSchemaObject;
+    /** Configuration for schema/type generation */
+    generate?: GenerateConfig;
+    /**
+     * Root path used for scanning + more
+     */
+    root?: string;
+}
+/**
+ * Full configuration (alias for BaseConfig)
+ */
+export type ConfigWithRoot<TMetadata = Record<string, unknown>> = Config<TMetadata> & {
+    root: string;
+};
+/**
+ * Resolved configuration with actual extractor instances.
+ * This is the runtime-ready configuration after all plugins are loaded.
+ */
+export interface ResolvedConfig<TMetadata = Record<string, unknown>> extends ConfigWithRoot<TMetadata> {
+    /** Resolved extractor instances */
+    extractors: Extractor<TMetadata>[];
+    /** Resolved plugins */
+    plugins: Plugin<TMetadata>[];
+    /** Plugin registry for accessing validators/schemas */
+    registry: PluginRegistryInterface;
+    /** Path mappings for conflict resolution */
+    pathMappings: PathMapping[];
+    /** Scan configuration with defaults applied */
+    scan: Required<ScanConfig>;
+    /** Config validation errors (options validation failures) */
+    validationErrors: ConfigValidationError[];
+    /** Root Path of Config File */
+    root: string;
+}
+/**
+ * Plugin commands can be a static array or a function that receives
+ * the resolved config and returns commands (sync or async).
+ */
+export type PluginCommands<TMetadata = Record<string, unknown>> = CLI[] | ((config: ResolvedConfig<TMetadata>) => CLI[] | Promise<CLI[]>);
+/**
+ * Plugin containing optional extractors, parsers, schemas, and validators.
+ * Auto-registers for declared file extensions.
+ */
+export interface Plugin<TMetadata = Record<string, unknown>> {
+    /** Unique plugin name */
+    readonly name: string;
+    /** File extensions this plugin handles (e.g., ['.ts', '.tsx', '.js', '.jsx']) */
+    readonly extensions?: string[];
+    /** Extractor that finds examples in a directory tree */
+    readonly extractor?: Extractor<TMetadata>;
+    /** Parser that processes file contents (runs in pipeline order) */
+    readonly fileContentsParser?: FileContentsParser;
+    /**
+     * JSON Schema definitions for IDE tooling.
+     * @see PluginSchemas
+     */
+    readonly schemas?: PluginSchemas;
+    /**
+     * Runtime validators for options and metadata.
+     * @see PluginValidators
+     */
+    readonly validators?: PluginValidators<TMetadata>;
+    /**
+     * CLI commands provided by this plugin.
+     * Can be static commands or a function that receives the resolved config.
+     * @see PluginCommands
+     */
+    readonly commands?: PluginCommands<TMetadata>;
+    /**
+     * Options passed to the plugin factory (for validation introspection).
+     * Plugin factories should set this to enable options validation.
+     * @internal
+     */
+    readonly _options?: unknown;
+}
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Core type definitions for functional-examples
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/yaml/index.d.ts

@@ -0,0 +1,2 @@
+export { YamlParseError, parseYaml, tryParseYaml } from './parse.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/yaml/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/yaml/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/yaml/index.js

@@ -0,0 +1,2 @@
+export { YamlParseError, parseYaml, tryParseYaml } from './parse.js';
+//# sourceMappingURL=index.js.map

package/dist/yaml/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/yaml/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/yaml/parse.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resets the cached import promise. Used for testing only.
+ * @internal
+ */
+export declare function _resetYamlImportCache(): void;
+/**
+ * Error thrown when YAML parsing fails.
+ * Includes optional position information for diagnostics.
+ */
+export declare class YamlParseError extends Error {
+    readonly line?: number;
+    readonly column?: number;
+    readonly filePath?: string;
+    constructor(message: string, options?: {
+        line?: number;
+        column?: number;
+        filePath?: string;
+    });
+}
+/**
+ * Parse a YAML string into a typed value.
+ *
+ * Requires the `yaml` peer dependency to be installed.
+ *
+ * @param content - The YAML string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns The parsed value
+ * @throws {YamlParseError} If parsing fails
+ */
+export declare function parseYaml<T = unknown>(content: string, filePath?: string): Promise<T>;
+/**
+ * Try to parse a YAML string, returning a discriminated union result
+ * instead of throwing.
+ *
+ * Requires the `yaml` peer dependency to be installed.
+ *
+ * @param content - The YAML string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns A result with either `{ success: true, data }` or `{ success: false, error }`
+ */
+export declare function tryParseYaml<T = unknown>(content: string, filePath?: string): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: YamlParseError;
+}>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/yaml/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/yaml/parse.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;CAQlE;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CACR;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CACvE,CAaA"}

package/dist/yaml/parse.js

@@ -0,0 +1,84 @@
+let yamlPromise = null;
+function importYaml() {
+    if (!yamlPromise) {
+        yamlPromise = import('yaml').catch(() => {
+            yamlPromise = null;
+            throw new Error('yaml is required to use @functional-examples/devkit/yaml. ' +
+                'Install it with: pnpm add yaml');
+        });
+    }
+    return yamlPromise;
+}
+/**
+ * Resets the cached import promise. Used for testing only.
+ * @internal
+ */
+export function _resetYamlImportCache() {
+    yamlPromise = null;
+}
+/**
+ * Error thrown when YAML parsing fails.
+ * Includes optional position information for diagnostics.
+ */
+export class YamlParseError extends Error {
+    line;
+    column;
+    filePath;
+    constructor(message, options) {
+        super(message);
+        this.name = 'YamlParseError';
+        this.line = options?.line;
+        this.column = options?.column;
+        this.filePath = options?.filePath;
+    }
+}
+/**
+ * Parse a YAML string into a typed value.
+ *
+ * Requires the `yaml` peer dependency to be installed.
+ *
+ * @param content - The YAML string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns The parsed value
+ * @throws {YamlParseError} If parsing fails
+ */
+export async function parseYaml(content, filePath) {
+    const { parse } = await importYaml();
+    try {
+        return parse(content);
+    }
+    catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        const posMatch = err.message.match(/at line (\d+), column (\d+)/);
+        throw new YamlParseError(err.message, {
+            line: posMatch ? Number(posMatch[1]) : undefined,
+            column: posMatch ? Number(posMatch[2]) : undefined,
+            filePath,
+        });
+    }
+}
+/**
+ * Try to parse a YAML string, returning a discriminated union result
+ * instead of throwing.
+ *
+ * Requires the `yaml` peer dependency to be installed.
+ *
+ * @param content - The YAML string to parse
+ * @param filePath - Optional file path for error messages
+ * @returns A result with either `{ success: true, data }` or `{ success: false, error }`
+ */
+export async function tryParseYaml(content, filePath) {
+    try {
+        const data = await parseYaml(content, filePath);
+        return { success: true, data };
+    }
+    catch (e) {
+        const error = e instanceof YamlParseError
+            ? e
+            : new YamlParseError(e instanceof Error ? e.message : String(e), {
+                filePath,
+            });
+        return { success: false, error };
+    }
+}
+//# sourceMappingURL=parse.js.map

package/dist/yaml/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/yaml/parse.ts"],"names":[],"mappings":"AAAA,IAAI,WAAW,GAA0C,IAAI,CAAC;AAE9D,SAAS,UAAU;IACjB,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACtC,WAAW,GAAG,IAAI,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,4DAA4D;gBAC1D,gCAAgC,CACnC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAU;IACd,MAAM,CAAU;IAChB,QAAQ,CAAU;IAE3B,YACE,OAAe,EACf,OAA+D;QAE/D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAe,EACf,QAAiB;IAEjB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,UAAU,EAAE,CAAC;IACrC,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAM,CAAC;IAC7B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;QAClE,MAAM,IAAI,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE;YACpC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;YAChD,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;YAClD,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,QAAiB;IAIjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAI,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,KAAK,GACT,CAAC,YAAY,cAAc;YACzB,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;gBAC7D,QAAQ;aACT,CAAC,CAAC;QACT,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;AACH,CAAC"}