@aperturesyndicate/synx-format 3.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 APERTURESyndicate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# SYNX for JS/TS — @aperturesyndicate/synx
+
+The official JavaScript & TypeScript parser for the SYNX format.
+
+## Install
+
+```bash
+npm install @aperturesyndicate/synx
+```
+
+## Usage
+
+```javascript
+const Synx = require('@aperturesyndicate/synx');
+
+// Load from file
+const data = Synx.loadSync('config.synx');
+console.log(data.server.port); // 8080
+
+// Parse from string
+const data2 = Synx.parse('name Wario\nage 30');
+console.log(data2.name); // "Wario"
+```
+
+### TypeScript
+
+```typescript
+import Synx from '@aperturesyndicate/synx';
+
+interface Config {
+  server: { port: number; host: string };
+  app_name: string;
+}
+
+const data = Synx.loadSync<Config>('config.synx');
+console.log(data.server.port); // typed as number
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `Synx.parse<T>(text, options?)` | Parse a .synx string → object |
+| `Synx.loadSync<T>(path, options?)` | Load & parse file (sync) |
+| `Synx.load<T>(path, options?)` | Load & parse file (async, returns Promise) |
+| `Synx.stringify(obj, active?)` | Serialize object → .synx string |
+
+### Options
+
+```typescript
+{
+  basePath?: string;                 // For :include resolution
+  env?: Record<string, string>;      // Override env vars
+  region?: string;                   // For :geo ("RU", "US", etc.)
+  strict?: boolean;                  // Throw on INCLUDE_ERR/WATCH_ERR/CALC_ERR/CONSTRAINT_ERR
+}
+```
+
+`strict: true` enables fail-fast behavior for production: marker runtime errors throw instead of silently remaining in the output object as error strings.
+
+## CLI
+
+Install globally:
+
+```bash
+npm install -g @aperturesyndicate/synx
+```
+
+### Commands
+
+```bash
+# Convert to JSON/YAML/TOML/.env
+synx convert config.synx --format json
+synx convert config.synx --format yaml > values.yaml
+synx convert config.synx --format toml
+synx convert config.synx --format env > .env
+
+# Validate (strict mode, for CI/CD)
+synx validate config.synx --strict
+
+# Watch for changes
+synx watch config.synx --format json
+synx watch config.synx --exec "nginx -s reload"
+
+# Extract JSON Schema from constraints
+synx schema config.synx
+```
+
+## Export Formats
+
+Convert parsed SYNX to other formats programmatically:
+
+```typescript
+const config = Synx.loadSync('config.synx');
+
+Synx.toJSON(config);           // JSON (pretty)
+Synx.toJSON(config, false);    // JSON (compact)
+Synx.toYAML(config);           // YAML
+Synx.toTOML(config);           // TOML
+Synx.toEnv(config);            // KEY=VALUE
+Synx.toEnv(config, 'PREFIX');  // PREFIX_KEY=VALUE
+```
+
+## File Watcher
+
+```typescript
+const handle = Synx.watch('config.synx', (config, error) => {
+  if (error) return console.error(error);
+  console.log('Config reloaded:', config);
+}, { strict: true });
+
+handle.close(); // stop watching
+```
+
+## Schema Export
+
+Extract constraints as JSON Schema:
+
+```typescript
+const schema = Synx.schema(`
+!active
+app_name[required, min:3, max:30] TotalWario
+volume[min:0, max:100, type:int] 75
+`);
+// { "$schema": "...", "properties": { "app_name": { ... } }, "required": ["app_name"] }
+```
+
+## Other Languages
+
+- **Python** — [synx-format](https://pypi.org/project/synx-format/) on PyPI
+- **Rust** — [synx](https://crates.io/crates/synx) on crates.io
+  ```bash
+  cargo add synx
+  ```
+  ```rust
+  use synx::Synx;
+  
+  let data = Synx::load("config.synx")?;
+  println!("{}", &data["server"]["port"]);
+  ```
+
+## License
+
+MIT — © APERTURESyndicate

package/SPECIFICATION.md

@@ -0,0 +1,6 @@
+# SYNX specification
+
+The normative specification files live in the monorepo (not duplicated here for npm):
+
+- English: [`docs/spec/SPECIFICATION_EN.md`](https://github.com/kaiserrberg/synx-format/blob/main/docs/spec/SPECIFICATION_EN.md)
+- Russian: [`docs/spec/SPECIFICATION_RU.md`](https://github.com/kaiserrberg/synx-format/blob/main/docs/spec/SPECIFICATION_RU.md)

package/bin/synx.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Synx = require('../dist/index');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function usage() {
+  console.log(`
+SYNX CLI — The Active Data Format (v3.6.0)
+
+DEPRECATED: This Node.js CLI is superseded by the native Rust CLI.
+            Install: cargo install synx-cli
+            Docs:    https://github.com/kaiserrberg/synx-format#cli-rust
+
+Usage:
+  synx convert <file.synx> [--format json|yaml|toml|env]  [--strict] [--active]
+  synx validate <file.synx>  [--strict]
+  synx watch <file.synx> [--format json] [--exec <command>]
+  synx schema <file.synx>
+
+Commands:
+  convert    Parse .synx and output in another format (default: json)
+  validate   Parse with strict mode — exits 1 on any marker error
+  watch      Watch file for changes, re-parse and print or exec command
+  schema     Extract constraints as JSON Schema
+
+Options:
+  --format, -f   Output format: json (default), yaml, toml, env
+  --strict       Throw on INCLUDE_ERR / WATCH_ERR / CALC_ERR / CONSTRAINT_ERR
+  --active       Force active mode resolution
+  --exec, -e     Command to run after each re-parse (watch mode)
+  --help, -h     Show this help
+`);
+  process.exit(0);
+}
+
+function getFlag(flag, alias) {
+  const idx = args.indexOf(flag);
+  const aidx = alias ? args.indexOf(alias) : -1;
+  return idx !== -1 || aidx !== -1;
+}
+
+function getFlagValue(flag, alias, defaultVal) {
+  let idx = args.indexOf(flag);
+  if (idx === -1 && alias) idx = args.indexOf(alias);
+  if (idx === -1 || idx + 1 >= args.length) return defaultVal;
+  return args[idx + 1];
+}
+
+if (!command || command === '--help' || command === '-h') usage();
+
+const file = args[1];
+if (!file) {
+  console.error('Error: no file specified');
+  process.exit(1);
+}
+
+const absPath = path.resolve(file);
+if (!fs.existsSync(absPath)) {
+  console.error(`Error: file not found: ${absPath}`);
+  process.exit(1);
+}
+
+const format = getFlagValue('--format', '-f', 'json');
+const strict = getFlag('--strict');
+const execCmd = getFlagValue('--exec', '-e', null);
+
+function parseFile(filePath) {
+  const text = fs.readFileSync(filePath, 'utf-8');
+  return Synx.parse(text, {
+    basePath: path.dirname(filePath),
+    strict,
+  });
+}
+
+function formatOutput(obj) {
+  switch (format) {
+    case 'json': return Synx.toJSON(obj);
+    case 'yaml': return Synx.toYAML(obj);
+    case 'toml': return Synx.toTOML(obj);
+    case 'env':  return Synx.toEnv(obj);
+    default:
+      console.error(`Unknown format: ${format}. Use json, yaml, toml, or env.`);
+      process.exit(1);
+  }
+}
+
+switch (command) {
+  case 'convert': {
+    try {
+      const obj = parseFile(absPath);
+      process.stdout.write(formatOutput(obj));
+    } catch (e) {
+      console.error(e.message);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case 'validate': {
+    try {
+      const text = fs.readFileSync(absPath, 'utf-8');
+      Synx.parse(text, { basePath: path.dirname(absPath), strict: true });
+      console.log('OK');
+    } catch (e) {
+      console.error('FAIL:', e.message);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case 'watch': {
+    console.error(`[synx] watching ${absPath}`);
+    const handle = Synx.watch(absPath, (config, error) => {
+      if (error) {
+        console.error(`[synx] error: ${error.message}`);
+        return;
+      }
+      if (execCmd) {
+        const { execSync } = require('child_process');
+        try {
+          execSync(execCmd, { stdio: 'inherit' });
+        } catch { /* command failed */ }
+      } else {
+        process.stdout.write(formatOutput(config));
+      }
+    }, { basePath: path.dirname(absPath), strict });
+    process.on('SIGINT', () => { handle.close(); process.exit(0); });
+    break;
+  }
+
+  case 'schema': {
+    const text = fs.readFileSync(absPath, 'utf-8');
+    const schema = Synx.schema(text);
+    console.log(JSON.stringify(schema, null, 2));
+    break;
+  }
+
+  default:
+    console.error(`Unknown command: ${command}`);
+    usage();
+}

package/dist/browser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SYNX Browser Bundle — @aperturesyndicate/synx
+ *
+ * Lightweight browser-compatible build.
+ * No Node.js dependencies (fs, path).
+ * Provides: parse, stringify.
+ */
+import type { SynxObject, SynxOptions } from './types';
+export type { SynxObject, SynxOptions, SynxValue, SynxArray, SynxPrimitive } from './types';
+export { SynxError } from './types';
+declare class Synx {
+    static parse<T extends SynxObject = SynxObject>(text: string, options?: SynxOptions): T;
+    static stringify(obj: SynxObject, active?: boolean): string;
+}
+export default Synx;
+export { Synx };
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,cAAM,IAAI;IACR,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,CAAC;IAQ3F,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,UAAQ,GAAG,MAAM;CAQ1D;AAuCD,eAAe,IAAI,CAAC;AACpB,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/browser.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * SYNX Browser Bundle — @aperturesyndicate/synx
+ *
+ * Lightweight browser-compatible build.
+ * No Node.js dependencies (fs, path).
+ * Provides: parse, stringify.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Synx = exports.SynxError = void 0;
+const parser_1 = require("./parser");
+const engine_1 = require("./engine");
+var types_1 = require("./types");
+Object.defineProperty(exports, "SynxError", { enumerable: true, get: function () { return types_1.SynxError; } });
+class Synx {
+    static parse(text, options = {}) {
+        const { root, mode } = (0, parser_1.parseData)(text);
+        if (mode === 'active') {
+            (0, engine_1.resolve)(root, options);
+        }
+        return root;
+    }
+    static stringify(obj, active = false) {
+        let out = '';
+        if (active) {
+            out += '!active\n';
+        }
+        out += serializeObject(obj, 0);
+        return out;
+    }
+}
+exports.Synx = Synx;
+function serializeObject(obj, indent) {
+    let out = '';
+    const spaces = ' '.repeat(indent);
+    for (const [key, val] of Object.entries(obj)) {
+        if (Array.isArray(val)) {
+            out += `${spaces}${key}\n`;
+            for (const item of val) {
+                if (item && typeof item === 'object' && !Array.isArray(item)) {
+                    const entries = Object.entries(item);
+                    if (entries.length > 0) {
+                        const [firstKey, firstVal] = entries[0];
+                        out += `${spaces}  - ${firstKey} ${firstVal}\n`;
+                        for (let i = 1; i < entries.length; i++) {
+                            out += `${spaces}    ${entries[i][0]} ${entries[i][1]}\n`;
+                        }
+                    }
+                }
+                else {
+                    out += `${spaces}  - ${item}\n`;
+                }
+            }
+        }
+        else if (val && typeof val === 'object') {
+            out += `${spaces}${key}\n`;
+            out += serializeObject(val, indent + 2);
+        }
+        else if (typeof val === 'string' && val.includes('\n')) {
+            out += `${spaces}${key} |\n`;
+            for (const line of val.split('\n')) {
+                out += `${spaces}  ${line}\n`;
+            }
+        }
+        else {
+            out += `${spaces}${key} ${val}\n`;
+        }
+    }
+    return out;
+}
+exports.default = Synx;
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/calc.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SYNX Safe Calculator — @aperturesyndicate/synx
+ *
+ * Evaluates arithmetic expressions WITHOUT eval() or new Function().
+ * Supports: +, -, *, /, %, parentheses, and numeric literals.
+ * Variable references are resolved before this stage.
+ */
+/**
+ * Safely evaluate an arithmetic expression.
+ * All variable names must be substituted with numbers before calling this.
+ *
+ * @param expr - e.g. "100 * 5 + (20 / 4)"
+ * @returns The computed number
+ */
+export declare function safeCalc(expr: string): number;
+//# sourceMappingURL=calc.d.ts.map

package/dist/calc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calc.d.ts","sourceRoot":"","sources":["../src/calc.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8IH;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7C"}

package/dist/calc.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * SYNX Safe Calculator — @aperturesyndicate/synx
+ *
+ * Evaluates arithmetic expressions WITHOUT eval() or new Function().
+ * Supports: +, -, *, /, %, parentheses, and numeric literals.
+ * Variable references are resolved before this stage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeCalc = safeCalc;
+/**
+ * Tokenize an arithmetic expression string.
+ */
+function tokenize(expr) {
+    const tokens = [];
+    let i = 0;
+    while (i < expr.length) {
+        const ch = expr[i];
+        // Skip whitespace
+        if (ch === ' ' || ch === '\t') {
+            i++;
+            continue;
+        }
+        // Number (integer or float, including negative after operator/start)
+        if ((ch >= '0' && ch <= '9') ||
+            (ch === '.' && i + 1 < expr.length && expr[i + 1] >= '0' && expr[i + 1] <= '9') ||
+            (ch === '-' && (tokens.length === 0 || tokens[tokens.length - 1].type === 'op' || (tokens[tokens.length - 1].type === 'paren' && tokens[tokens.length - 1].value === '(')))) {
+            let num = '';
+            if (ch === '-') {
+                num += '-';
+                i++;
+            }
+            while (i < expr.length && ((expr[i] >= '0' && expr[i] <= '9') || expr[i] === '.')) {
+                num += expr[i];
+                i++;
+            }
+            tokens.push({ type: 'number', value: parseFloat(num) });
+            continue;
+        }
+        // Operators
+        if ('+-*/%'.includes(ch)) {
+            tokens.push({ type: 'op', value: ch });
+            i++;
+            continue;
+        }
+        // Parentheses
+        if (ch === '(' || ch === ')') {
+            tokens.push({ type: 'paren', value: ch });
+            i++;
+            continue;
+        }
+        throw new Error(`SYNX :calc — unexpected character: '${ch}' in expression "${expr}"`);
+    }
+    return tokens;
+}
+/**
+ * Recursive descent parser for arithmetic.
+ * Grammar:
+ *   expr       → term (('+' | '-') term)*
+ *   term       → factor (('*' | '/' | '%') factor)*
+ *   factor     → NUMBER | '(' expr ')'
+ */
+class ExprParser {
+    constructor(tokens) {
+        this.tokens = tokens;
+        this.pos = 0;
+    }
+    parse() {
+        const result = this.expr();
+        if (this.pos < this.tokens.length) {
+            throw new Error(`SYNX :calc — unexpected token at position ${this.pos}`);
+        }
+        return result;
+    }
+    expr() {
+        let left = this.term();
+        while (this.pos < this.tokens.length && this.tokens[this.pos].type === 'op' && (this.tokens[this.pos].value === '+' || this.tokens[this.pos].value === '-')) {
+            const op = this.tokens[this.pos].value;
+            this.pos++;
+            const right = this.term();
+            left = op === '+' ? left + right : left - right;
+        }
+        return left;
+    }
+    term() {
+        let left = this.factor();
+        while (this.pos < this.tokens.length && this.tokens[this.pos].type === 'op' && ('*/%'.includes(this.tokens[this.pos].value))) {
+            const op = this.tokens[this.pos].value;
+            this.pos++;
+            const right = this.factor();
+            if (op === '*')
+                left = left * right;
+            else if (op === '/') {
+                if (right === 0)
+                    throw new Error('SYNX :calc — division by zero');
+                left = left / right;
+            }
+            else {
+                if (right === 0)
+                    throw new Error('SYNX :calc — division by zero');
+                left = left % right;
+            }
+        }
+        return left;
+    }
+    factor() {
+        const tok = this.tokens[this.pos];
+        if (!tok) {
+            throw new Error('SYNX :calc — unexpected end of expression');
+        }
+        if (tok.type === 'number') {
+            this.pos++;
+            return tok.value;
+        }
+        if (tok.type === 'paren' && tok.value === '(') {
+            this.pos++; // skip '('
+            const val = this.expr();
+            if (!this.tokens[this.pos] || this.tokens[this.pos].type !== 'paren' || this.tokens[this.pos].value !== ')') {
+                throw new Error('SYNX :calc — missing closing parenthesis');
+            }
+            this.pos++; // skip ')'
+            return val;
+        }
+        throw new Error(`SYNX :calc — unexpected token: ${JSON.stringify(tok)}`);
+    }
+}
+/**
+ * Safely evaluate an arithmetic expression.
+ * All variable names must be substituted with numbers before calling this.
+ *
+ * @param expr - e.g. "100 * 5 + (20 / 4)"
+ * @returns The computed number
+ */
+function safeCalc(expr) {
+    const tokens = tokenize(expr.trim());
+    if (tokens.length === 0)
+        return 0;
+    return new ExprParser(tokens).parse();
+}
+//# sourceMappingURL=calc.js.map

package/dist/calc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calc.js","sourceRoot":"","sources":["../src/calc.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAqJH,4BAIC;AAlJD;;GAEG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IAEV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAEnB,kBAAkB;QAClB,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAC9B,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QAED,qEAAqE;QACrE,IACE,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,IAAI,GAAG,CAAC;YACxB,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;YAC/E,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAC3K,CAAC;YACD,IAAI,GAAG,GAAG,EAAE,CAAC;YACb,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACf,GAAG,IAAI,GAAG,CAAC;gBACX,CAAC,EAAE,CAAC;YACN,CAAC;YACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;gBAClF,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;gBACf,CAAC,EAAE,CAAC;YACN,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxD,SAAS;QACX,CAAC;QAED,YAAY;QACZ,IAAI,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;YACvC,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QAED,cAAc;QACd,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAC7B,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;YAC1C,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,uCAAuC,EAAE,oBAAoB,IAAI,GAAG,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU;IAId,YAAY,MAAe;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IACf,CAAC;IAED,KAAK;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,IAAI;QACV,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,EAAE,CAAC;YAC5J,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;YACvC,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1B,IAAI,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC;QAClD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,IAAI;QACV,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAe,CAAC,CAAC,EAAE,CAAC;YACvI,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;YACvC,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,EAAE,KAAK,GAAG;gBAAE,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;iBAC/B,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACpB,IAAI,KAAK,KAAK,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;gBAClE,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;YACtB,CAAC;iBACI,CAAC;gBACJ,IAAI,KAAK,KAAK,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;gBAClE,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QAED,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;YACX,OAAO,GAAG,CAAC,KAAK,CAAC;QACnB,CAAC;QAED,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,KAAK,KAAK,GAAG,EAAE,CAAC;YAC9C,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW;YACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,GAAG,EAAE,CAAC;gBAC5G,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;YAC9D,CAAC;YACD,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW;YACvB,OAAO,GAAG,CAAC;QACb,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;CACF;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CAAC,IAAY;IACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;AACxC,CAAC"}