@nac3/forge-cli 0.2.0-alpha.8 → 0.2.1-alpha.60

package/dist/semantic_graph/derive.js

@@ -0,0 +1,285 @@
+/**
+ * derive.ts -- GRAPH-1 (dogfood 2026-06-10).
+ *
+ * Derivacion del grafo semantico del proyecto: nodos de MODULO (por
+ * directorio) + nodos de LIBRERIA (package.json) + ARISTAS reales
+ * escaneando imports. Reemplaza el script descartable de z.199 (cuyo
+ * regex laxo parseaba basura) por un extractor robusto que:
+ *   - ignora comentarios antes de matchear,
+ *   - solo acepta imports/export-from/dynamic-import reales (la
+ *     comilla va inmediatamente despues de `from`/`import`),
+ *   - solo crea aristas cuyos DOS extremos existen como nodos
+ *     (cero colgantes).
+ *
+ * Es la funcionalidad detras del boton "Regenerar" del panel y del
+ * comando `yf graph ingest`. Idempotente.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ingestFromPackageJson } from '../chat/semantic_graph_ingest.js';
+import { upsertNodes, upsertEdges, pruneDanglingEdges } from './store.js';
+/** Directorios que cuentan como un modulo (un nodo cada uno). */
+async function discoverModuleDirs(projectRoot) {
+    const mods = [];
+    const add = (relDir) => {
+        const base = relDir.replace(/\\/g, '/').split('/').filter(Boolean).pop() || relDir;
+        mods.push({ id: 'module.' + sanitiseId(base), name: base, dir: relDir });
+    };
+    /* Subdirs inmediatos de src/ */
+    await collectChildDirs(projectRoot, 'src', add);
+    /* packages/* y apps/* (sus raices son modulos de nivel superior). */
+    await collectChildDirs(projectRoot, 'packages', add);
+    await collectChildDirs(projectRoot, 'apps', add);
+    return mods;
+}
+async function collectChildDirs(root, parent, add) {
+    const abs = path.join(root, parent);
+    let entries;
+    try {
+        entries = await fs.readdir(abs);
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (e.startsWith('.') || e === 'node_modules' || e === 'dist')
+            continue;
+        let st;
+        try {
+            st = await fs.stat(path.join(abs, e));
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            add(parent + '/' + e);
+    }
+}
+/** npm/dir name -> id token (lowercase, alfanumerico + dashes). */
+function sanitiseId(name) {
+    return name.replace(/^@/, '').replace(/[/]/g, '-').replace(/[^a-z0-9\-_]/gi, '-').toLowerCase();
+}
+/** Quita comentarios de linea y de bloque (sin tocar strings de
+ *  forma perfecta, pero suficiente para que el scanner de imports
+ *  no matchee texto en comentarios). */
+function stripComments(src) {
+    return src
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+/** Extrae los specifiers de import reales de un archivo TS/JS.
+ *  Solo statements de import/export-from/dynamic-import; la comilla
+ *  va inmediatamente tras `from`/`import`/`import(`. */
+export function extractImportSpecifiers(source) {
+    const src = stripComments(source);
+    const out = new Set();
+    const patterns = [
+        /\bfrom\s*['"]([^'"]+)['"]/g, /* import X from '...' / export ... from '...' */
+        /\bimport\s+['"]([^'"]+)['"]/g, /* import '...' (side-effect) */
+        /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g, /* await import('...') */
+        /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g, /* require('...') */
+    ];
+    for (const re of patterns) {
+        let m;
+        while ((m = re.exec(src)) !== null) {
+            if (m[1])
+                out.add(m[1]);
+        }
+    }
+    return [...out];
+}
+async function walkSourceFiles(absDir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await fs.readdir(absDir);
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.startsWith('.') || e === 'node_modules' || e === 'dist')
+            continue;
+        const full = path.join(absDir, e);
+        let st;
+        try {
+            st = await fs.stat(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            out.push(...await walkSourceFiles(full));
+        else if (/\.(ts|tsx|js|jsx|mjs)$/.test(e) && !e.endsWith('.d.ts'))
+            out.push(full);
+    }
+    return out;
+}
+/** PND-081 -- purpose real de un modulo: el doc-comment inicial
+ *  (/​** ... *​/) del archivo "principal" del dir (index, o el de
+ *  igual nombre, o el mas grande). Cae a un texto generico si no
+ *  hay header. */
+async function deriveModulePurpose(projectRoot, relDir, name) {
+    const absDir = path.join(projectRoot, relDir);
+    let files;
+    try {
+        files = (await fs.readdir(absDir)).filter((f) => /\.(ts|tsx|js|jsx|mjs)$/.test(f) && !f.endsWith('.d.ts'));
+    }
+    catch {
+        return 'Modulo ' + relDir + '.';
+    }
+    if (files.length === 0)
+        return 'Modulo ' + relDir + '.';
+    /* Candidato principal: index, <name>, server/store/panel comunes,
+     * o el archivo mas grande. */
+    const preferred = ['index.ts', 'index.tsx', name + '.ts', 'server.ts', 'store.ts', 'panel.ts', 'router.ts'];
+    let mainFile = files.find((f) => preferred.includes(f));
+    if (!mainFile) {
+        let biggest = files[0];
+        let max = -1;
+        for (const f of files) {
+            try {
+                const st = await fs.stat(path.join(absDir, f));
+                if (st.size > max) {
+                    max = st.size;
+                    biggest = f;
+                }
+            }
+            catch { /* */ }
+        }
+        mainFile = biggest;
+    }
+    let src;
+    try {
+        src = await fs.readFile(path.join(absDir, mainFile), 'utf-8');
+    }
+    catch {
+        return 'Modulo ' + relDir + '.';
+    }
+    const m = src.match(/\/\*\*?([\s\S]*?)\*\//);
+    if (!m || !m[1])
+        return 'Modulo ' + relDir + '.';
+    /* Limpiar el bloque: quitar los '*' de cada linea, colapsar
+     * espacios, tomar las primeras ~2 oraciones (<= 240 chars). */
+    const cleaned = m[1]
+        .split('\n').map((l) => l.replace(/^\s*\*?\s?/, '')).join(' ')
+        .replace(/\s+/g, ' ').trim();
+    if (!cleaned)
+        return 'Modulo ' + relDir + '.';
+    const text = cleaned.length > 240 ? cleaned.slice(0, 237) + '...' : cleaned;
+    return text + ' (' + relDir + ')';
+}
+/** Deriva nodos (modulo + libreria) + aristas validadas del
+ *  proyecto. No toca el store; el caller persiste. */
+export async function deriveProjectGraph(opts) {
+    const now = new Date().toISOString();
+    const mods = await discoverModuleDirs(opts.project_root);
+    /* Mapa de prefijo de dir -> module id, mas especifico primero. */
+    const dirMap = [...mods].sort((a, b) => b.dir.length - a.dir.length);
+    /* Nodos de libreria del package.json (reusa el ingest existente). */
+    const libIngest = await ingestFromPackageJson({
+        project_root: opts.project_root,
+        project_slug: opts.project_slug,
+        enrich: opts.enrich,
+        ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    const libIds = new Set(libIngest.map((l) => l.id));
+    /* Nodos de modulo. PND-081 -- purpose real extraido del
+     * doc-comment del archivo principal del modulo (no generico). */
+    const moduleNodes = [];
+    for (const m of mods) {
+        const purpose = await deriveModulePurpose(opts.project_root, m.dir, m.name);
+        moduleNodes.push({
+            id: m.id, kind: 'module', name: m.name,
+            source: 'ast', purpose,
+            solves: [], do_not_invent: [], api_surface: [],
+            confidence: 'auto', weight: 0.6, added_at: now, updated_at: now,
+        });
+    }
+    const allNodeIds = new Set([...mods.map((m) => m.id), ...libIds]);
+    function moduleForFile(absFile) {
+        const rel = path.relative(opts.project_root, absFile).replace(/\\/g, '/');
+        for (const m of dirMap) {
+            if (rel.startsWith(m.dir + '/'))
+                return m.id;
+        }
+        return null;
+    }
+    function libIdFor(spec) {
+        const pkg = spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : (spec.split('/')[0] || spec);
+        return 'lib.' + sanitiseId(pkg);
+    }
+    /* Aristas. */
+    const edgeMap = new Map();
+    let skipped = 0;
+    function addEdge(from, to, kind) {
+        if (from === to)
+            return;
+        if (!allNodeIds.has(from) || !allNodeIds.has(to)) {
+            skipped++;
+            return;
+        }
+        const id = kind + ':' + from + '->' + to;
+        if (!edgeMap.has(id))
+            edgeMap.set(id, { id, kind, from_id: from, to_id: to, weight: 0.6, source: 'ast', created_at: now });
+    }
+    for (const m of mods) {
+        const files = await walkSourceFiles(path.join(opts.project_root, m.dir));
+        for (const f of files) {
+            const owner = moduleForFile(f) || m.id;
+            let src;
+            try {
+                src = await fs.readFile(f, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            for (const spec of extractImportSpecifiers(src)) {
+                if (spec.startsWith('node:') || spec.startsWith('bun:'))
+                    continue;
+                if (spec.startsWith('.') || spec.startsWith('/')) {
+                    const target = moduleForFile(path.resolve(path.dirname(f), spec));
+                    if (target)
+                        addEdge(owner, target, 'uses');
+                }
+                else {
+                    addEdge(owner, libIdFor(spec), 'depends_on');
+                }
+            }
+        }
+    }
+    /* Los nodos de libreria del ingest no traen added_at/updated_at
+     * (su shape es IngestedNode); normalizarlos para el store. */
+    const libNodes = libIngest.map((l) => ({
+        ...l,
+        added_at: now,
+        updated_at: now,
+    }));
+    const edges = [...edgeMap.values()];
+    return {
+        nodes: [...moduleNodes, ...libNodes],
+        edges,
+        stats: {
+            module_nodes: moduleNodes.length,
+            lib_nodes: libIngest.length,
+            module_edges: edges.filter((e) => e.to_id.startsWith('module.')).length,
+            lib_edges: edges.filter((e) => e.to_id.startsWith('lib.')).length,
+            skipped_dangling: skipped,
+        },
+    };
+}
+/** GRAPH-1 -- deriva + PERSISTE el grafo (upsert nodos + aristas +
+ *  poda colgantes). Idempotente. Lo llaman el endpoint del boton
+ *  Refresh y el auto-regen del component-watcher. */
+export async function regenerateAndPersist(opts) {
+    const g = await deriveProjectGraph(opts);
+    if (g.nodes.length > 0)
+        await upsertNodes(opts.project_slug, g.nodes);
+    if (g.edges.length > 0)
+        await upsertEdges(opts.project_slug, g.edges);
+    const pruned = await pruneDanglingEdges(opts.project_slug);
+    return { ...g.stats, pruned: pruned.removed };
+}
+//# sourceMappingURL=derive.js.map

package/dist/semantic_graph/derive.js.map

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

package/dist/semantic_graph/llm_claim.d.ts

@@ -0,0 +1,21 @@
+export interface ClaimDetectionResult {
+    /** Unique bare-module specifiers found in the reply, after
+     *  filtering relative paths + dedup. */
+    candidates: string[];
+    /** Subset of candidates that were absent from the local graph
+     *  AND made it into the upsert. */
+    claimed_ids: string[];
+    /** Subset that the local graph already knew (no upsert). */
+    skipped_existing: string[];
+}
+export declare function claimsEnabled(): boolean;
+/** Extract every bare module specifier referenced via import or
+ *  require inside fenced code blocks of `text`. Returns unique
+ *  package names (rooted). */
+export declare function detectClaims(text: string): string[];
+/** Run detectClaims + upsert any newly-claimed packages into the
+ *  per-project local graph. Skips packages already known to the
+ *  graph (any confidence). Idempotent across multiple turns that
+ *  mention the same library. Returns a small report. */
+export declare function ingestClaimsFromReply(project_slug: string, reply_text: string): Promise<ClaimDetectionResult>;
+//# sourceMappingURL=llm_claim.d.ts.map

package/dist/semantic_graph/llm_claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_claim.d.ts","sourceRoot":"","sources":["../../src/semantic_graph/llm_claim.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,oBAAoB;IACnC;4CACwC;IACxC,UAAU,EAAG,MAAM,EAAE,CAAC;IACtB;uCACmC;IACnC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,aAAa,IAAI,OAAO,CAIvC;AA6BD;;8BAE8B;AAC9B,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBnD;AAED;;;wDAGwD;AACxD,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GACvC,OAAO,CAAC,oBAAoB,CAAC,CA0C/B"}

package/dist/semantic_graph/llm_claim.js

@@ -0,0 +1,164 @@
+/**
+ * PND-020 Phase 2b -- LLM-claim post-turn hook (conservative).
+ *
+ * After every chat turn, scan the assistant's reply for **explicit
+ * import statements inside fenced code blocks** that name a library
+ * the project hasn't acknowledged yet. Each unique library becomes
+ * a GraphNode with:
+ *   - source: 'llm-claim'
+ *   - confidence: 'claimed'  (lowest tier; user must promote)
+ *   - weight: 0.3            (under verified/auto baseline)
+ *
+ * The "claim" trigger is intentionally narrow to avoid false
+ * positives:
+ *   - Only fenced code blocks (``` ... ```).
+ *   - Only import / require statements (not prose like "use X").
+ *   - Only bare module specifiers (not relative paths).
+ *
+ * If the LLM mentions `react-query` in prose but never shows an
+ * import, we do NOT claim it. The cost of a false positive (noise
+ * in the system prompt next turn) is higher than missing a few
+ * implicit mentions.
+ *
+ * Failure mode: never throws. Silent skip when the local store is
+ * unreachable or the slug is empty.
+ *
+ * ASCII-only.
+ */
+import { listRelevant, upsertNodes } from './store.js';
+/** import X from 'pkg'  /  import { X } from 'pkg'  /  import 'pkg'
+ *  Multiline + multiple statements per block supported. */
+const IMPORT_RX = /\bimport\b[^'"]*?from\s+['"]([^'"\n]+)['"]/g;
+/** import 'pkg' (side-effect only). */
+const SIDE_EFFECT_IMPORT_RX = /\bimport\s+['"]([^'"\n]+)['"]/g;
+/** const X = require('pkg') / require('pkg') -- captures arg. */
+const REQUIRE_RX = /\brequire\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g;
+/** Match every fenced code block, capturing its body. Supports
+ *  ```ts, ```tsx, ```js, ```javascript, ``` (no lang). */
+const CODE_BLOCK_RX = /```(?:[a-zA-Z]*)\r?\n([\s\S]*?)```/g;
+const MAX_CLAIMS_PER_TURN = 10;
+export function claimsEnabled() {
+    const v = process.env['YF_LLM_CLAIMS_DISABLED'];
+    if (v === '1' || v === 'true' || v === 'yes')
+        return false;
+    return true;
+}
+/** Strip the leading scope prefix + version suffix so a bare
+ *  specifier like 'react-router/dom' becomes 'react-router'. */
+function rootPackageName(spec) {
+    if (!spec)
+        return null;
+    /* Relative paths: ./x, ../x, /abs. Skip them -- those are
+     * project-internal imports, not third-party libraries. */
+    if (spec.startsWith('.') || spec.startsWith('/'))
+        return null;
+    if (spec.startsWith('@')) {
+        /* @scope/pkg or @scope/pkg/sub  ->  @scope/pkg */
+        const parts = spec.split('/');
+        if (parts.length < 2)
+            return null;
+        return parts[0] + '/' + parts[1];
+    }
+    /* react/jsx-runtime -> react */
+    return spec.split('/')[0];
+}
+/** Sanitise an npm name to a graph node id (mirror of the
+ *  package.json ingester). */
+function nameToNodeId(pkg) {
+    return 'lib.' + pkg
+        .replace(/^@/, '')
+        .replace(/[/]/g, '-')
+        .replace(/[^a-z0-9\-_]/gi, '-')
+        .toLowerCase();
+}
+/** Extract every bare module specifier referenced via import or
+ *  require inside fenced code blocks of `text`. Returns unique
+ *  package names (rooted). */
+export function detectClaims(text) {
+    if (!text || typeof text !== 'string')
+        return [];
+    const blocks = [];
+    CODE_BLOCK_RX.lastIndex = 0;
+    let m;
+    while ((m = CODE_BLOCK_RX.exec(text)) !== null) {
+        if (m[1])
+            blocks.push(m[1]);
+    }
+    if (blocks.length === 0)
+        return [];
+    const seen = new Set();
+    for (const body of blocks) {
+        for (const rx of [IMPORT_RX, SIDE_EFFECT_IMPORT_RX, REQUIRE_RX]) {
+            rx.lastIndex = 0;
+            let im;
+            while ((im = rx.exec(body)) !== null) {
+                const spec = im[1];
+                if (!spec)
+                    continue;
+                const root = rootPackageName(spec);
+                if (root)
+                    seen.add(root);
+                if (seen.size >= MAX_CLAIMS_PER_TURN * 3)
+                    break;
+            }
+        }
+    }
+    return Array.from(seen).slice(0, MAX_CLAIMS_PER_TURN);
+}
+/** Run detectClaims + upsert any newly-claimed packages into the
+ *  per-project local graph. Skips packages already known to the
+ *  graph (any confidence). Idempotent across multiple turns that
+ *  mention the same library. Returns a small report. */
+export async function ingestClaimsFromReply(project_slug, reply_text) {
+    const empty = { candidates: [], claimed_ids: [], skipped_existing: [] };
+    if (!claimsEnabled())
+        return empty;
+    if (!project_slug || !reply_text)
+        return empty;
+    const candidates = detectClaims(reply_text);
+    if (candidates.length === 0)
+        return empty;
+    /* Look at the existing graph in one shot -- avoid N round-trips. */
+    let existing;
+    try {
+        const nodes = await listRelevant(project_slug, { limit: 1000, min_confidence: 'claimed' });
+        existing = new Set(nodes.map((n) => n.id));
+    }
+    catch {
+        return { ...empty, candidates };
+    }
+    const newNodes = [];
+    const claimed_ids = [];
+    const skipped_existing = [];
+    const now = new Date().toISOString();
+    for (const pkg of candidates) {
+        const id = nameToNodeId(pkg);
+        if (existing.has(id)) {
+            skipped_existing.push(id);
+            continue;
+        }
+        newNodes.push({
+            id,
+            kind: 'library',
+            name: pkg,
+            source: 'llm-claim',
+            purpose: pkg + ' (claimed by LLM via import statement in code block). Promote with `yf graph review` once you confirm it actually belongs.',
+            solves: [],
+            do_not_invent: [],
+            api_surface: ["import ... from '" + pkg + "'"],
+            confidence: 'claimed',
+            weight: 0.3,
+            added_at: now,
+            updated_at: now,
+        });
+        claimed_ids.push(id);
+    }
+    if (newNodes.length > 0) {
+        try {
+            await upsertNodes(project_slug, newNodes);
+        }
+        catch { /* graceful: claims are nice-to-have, not load-bearing */ }
+    }
+    return { candidates, claimed_ids, skipped_existing };
+}
+//# sourceMappingURL=llm_claim.js.map

package/dist/semantic_graph/llm_claim.js.map

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

package/dist/semantic_graph/npm_enrich.d.ts

@@ -0,0 +1,49 @@
+export interface NpmPackageMeta {
+    /** npm package name as the user typed it. */
+    name: string;
+    /** Resolved latest version (or '' if unknown). */
+    version: string;
+    /** <=200 chars, trimmed. '' when registry didn't have it. */
+    description: string;
+    homepage?: string;
+    repository?: string;
+    keywords: string[];
+    /** ISO 8601 timestamp of when we cached this. */
+    fetched_at: string;
+}
+export declare function enrichmentEnabled(): boolean;
+/** Read a single package's cached meta. Returns null on miss. */
+export declare function readCachedMeta(pkgName: string): Promise<NpmPackageMeta | null>;
+/** Fetch + parse the registry metadata for a single package. Returns
+ *  null on any failure (404, network, timeout, malformed JSON). */
+export declare function fetchPackageMeta(pkgName: string, opts?: {
+    fetchImpl?: typeof fetch;
+    timeout_ms?: number;
+}): Promise<NpmPackageMeta | null>;
+/** Get meta for one package: cache-first; only hits the network on
+ *  miss. Returns null on miss + fetch fail. */
+export declare function getPackageMeta(pkgName: string, opts?: {
+    fetchImpl?: typeof fetch;
+    timeout_ms?: number;
+    force?: boolean;
+}): Promise<NpmPackageMeta | null>;
+/** Batch enrichment with bounded concurrency. Mutates each input
+ *  node's `purpose` + `api_surface` in place when meta is available.
+ *  Returns the count enriched. Safe to call with empty array. */
+export interface EnrichableNode {
+    name: string;
+    purpose: string;
+    api_surface: string[];
+    solves: string[];
+    /** Allow null because IngestedNode.version is `string | null`. */
+    version?: string | null;
+}
+export declare function enrichNodes(nodes: EnrichableNode[], opts?: {
+    fetchImpl?: typeof fetch;
+    timeout_ms?: number;
+    concurrency?: number;
+}): Promise<{
+    enriched: number;
+    missed: number;
+}>;
+//# sourceMappingURL=npm_enrich.d.ts.map

package/dist/semantic_graph/npm_enrich.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"npm_enrich.d.ts","sourceRoot":"","sources":["../../src/semantic_graph/npm_enrich.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,IAAI,EAAS,MAAM,CAAC;IACpB,kDAAkD;IAClD,OAAO,EAAM,MAAM,CAAC;IACpB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAI,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAK,MAAM,EAAE,CAAC;IACtB,iDAAiD;IACjD,UAAU,EAAG,MAAM,CAAC;CACrB;AAgBD,wBAAgB,iBAAiB,IAAI,OAAO,CAI3C;AAED,iEAAiE;AACjE,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAiBpF;AAQD;mEACmE;AACnE,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3D,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkChC;AAED;+CAC+C;AAC/C,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5E,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAShC;AAED;;iEAEiE;AACjE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAS,MAAM,CAAC;IACpB,OAAO,EAAM,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAO,MAAM,EAAE,CAAC;IACtB,kEAAkE;IAClE,OAAO,CAAC,EAAK,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,cAAc,EAAE,EACvB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACjF,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B/C"}