@oscharko-dev/keiko-workspace 0.2.0

package/dist/importGraph.js

@@ -0,0 +1,131 @@
+// Import-graph adapter (Epic #177, Issue #180). Pure-JS regex extractor: scans discovered
+// files for ESM imports/re-exports and CJS requires, emits an EvidenceAtom for each file
+// whose specifier matches the query text. Fixed, anchored, non-nested-quantifier regexes
+// keep the scan ReDoS-safe; the binary probe and read cap come from the shared workspace
+// primitives. Stays within ADR-0019 rule 3b: imports only @oscharko-dev/keiko-contracts,
+// sibling workspace modules, and Node stdlib (node:crypto).
+import { createHash } from "node:crypto";
+import { looksBinary } from "./binaryDetect.js";
+import { readWorkspaceFile } from "./discovery.js";
+import { RepoSearchInvalidQueryError } from "./errors.js";
+import { resolveWithinWorkspace } from "./paths.js";
+import { assertContainedRealPath } from "./realpath.js";
+import { buildAtom, gatherCandidates } from "./repoSearchScan.js";
+function queryFingerprint(query) {
+    const canonical = JSON.stringify({ kind: query.kind, text: query.text });
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+// ESM static imports: import X from "y"; import * as X from "y"; import "y"; import { X } from "y".
+// [ \t]+\S+ tokens in the import clause avoid ReDoS: [ \t] and \S are complementary so the engine
+// never tries alternative splits. [ \t] (not \s) prevents the clause from crossing newlines.
+const ESM_IMPORT = /^\s*import(?:[ \t]+\S+(?:[ \t]+\S+)*[ \t]+from)?\s+["']([^"'\n]+)["']/gm;
+// ESM re-exports: export * from "y"; export { X } from "y".
+const ESM_REEXPORT = /^\s*export\s+(?:\*|\{[^}]*\})\s+from\s+["']([^"'\n]+)["']/gm;
+// CommonJS: require("y").
+const CJS_REQUIRE = /\brequire\s*\(\s*["']([^"'\n]+)["']\s*\)/g;
+const BINARY_PROBE_BYTES = 512;
+async function probeBinary(fs, abs, size) {
+    const cap = Math.min(BINARY_PROBE_BYTES, size);
+    if (cap === 0) {
+        return false;
+    }
+    if (fs.readFileBytes !== undefined) {
+        return looksBinary(await fs.readFileBytes(abs, cap));
+    }
+    const text = fs.readFileUtf8(abs);
+    return looksBinary(new TextEncoder().encode(text.slice(0, cap)));
+}
+function specifierMatches(specifier, query) {
+    if (query.kind === "exact-symbol") {
+        return specifier === query.text;
+    }
+    return specifier.toLowerCase().includes(query.text.toLowerCase());
+}
+function scoreFor(specifier, query) {
+    return specifier === query.text ? 1.0 : 0.7;
+}
+function lineNumberOf(text, charIndex) {
+    let line = 1;
+    for (let i = 0; i < charIndex && i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            line += 1;
+        }
+    }
+    return line;
+}
+function collectHits(text, query) {
+    const hits = [];
+    for (const regex of [ESM_IMPORT, ESM_REEXPORT, CJS_REQUIRE]) {
+        regex.lastIndex = 0;
+        let m = regex.exec(text);
+        while (m !== null) {
+            const specifier = m[1] ?? "";
+            if (specifierMatches(specifier, query)) {
+                hits.push({ specifier, line: lineNumberOf(text, m.index) });
+            }
+            m = regex.exec(text);
+        }
+    }
+    return hits;
+}
+function emitHitAtom(ctx, relativePath, hit) {
+    return buildAtom({
+        scopeId: ctx.scope.scopeId,
+        scopePath: relativePath,
+        lineRange: { startLine: hit.line, endLine: hit.line },
+        provenanceKind: "structural",
+        tool: "import-graph",
+        queryFingerprint: ctx.fingerprint,
+        score: scoreFor(hit.specifier, ctx.query),
+        emittedAtMs: ctx.nowMs(),
+    });
+}
+function elapsedOver(ctx) {
+    return ctx.nowMs() - ctx.startMs > ctx.limits.elapsedMsMax;
+}
+async function scanFileForImports(ctx, relativePath, atoms) {
+    const abs = resolveWithinWorkspace(ctx.scope.workspace.root, relativePath);
+    const containedAbs = assertContainedRealPath(ctx.fs, ctx.scope.workspace.root, abs, "scope");
+    const stat = ctx.fs.stat(containedAbs);
+    if (stat.hardLinkCount !== undefined && stat.hardLinkCount > 1) {
+        return;
+    }
+    if (await probeBinary(ctx.fs, containedAbs, stat.size)) {
+        return;
+    }
+    const content = readWorkspaceFile(ctx.scope.workspace, relativePath, { maxBytes: ctx.limits.maxBytesPerFileScanned }, ctx.fs);
+    const hits = collectHits(content.text, ctx.query);
+    for (const hit of hits) {
+        if (atoms.length >= ctx.limits.maxMatchesReturned) {
+            return;
+        }
+        atoms.push(emitHitAtom(ctx, relativePath, hit));
+    }
+}
+export const importGraphAdapter = {
+    name: "import-graph",
+    isAvailable: () => Promise.resolve(true),
+    lookup: async (scope, query, limits, fs, deps) => {
+        if (query.kind !== "natural-language" && query.kind !== "exact-symbol") {
+            throw new RepoSearchInvalidQueryError(`import-graph adapter does not accept query kind: ${query.kind}`);
+        }
+        const ctx = {
+            scope,
+            fs,
+            limits,
+            query,
+            fingerprint: queryFingerprint(query),
+            startMs: (deps?.nowMs ?? Date.now)(),
+            nowMs: deps?.nowMs ?? Date.now,
+        };
+        const candidateSet = gatherCandidates(scope, limits, fs);
+        const atoms = [];
+        for (const file of candidateSet.files) {
+            if (atoms.length >= limits.maxMatchesReturned || elapsedOver(ctx)) {
+                break;
+            }
+            await scanFileForImports(ctx, file.relativePath, atoms);
+        }
+        return atoms;
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export type { AuditEntry, AuditSummary, ContextEntry, ContextEntrySummary, ContextPack, ContextPackSummary, ContextRequest, DiscoveredFile, DiscoveryOptions, DiscoveryStats, FileContent, ReadOptions, SelectionReason, TestFramework, WorkspaceInfo, WorkspaceLanguage, WorkspaceSummary, } from "./types.js";
+export { DEFAULT_CONTEXT_REQUEST, DEFAULT_DISCOVERY_OPTIONS, DEFAULT_READ_OPTIONS, SELECTION_REASON_PRIORITY, } from "./types.js";
+export { FileTooLargeError, PathDeniedError, PathEscapeError, RepoSearchInvalidQueryError, RepoSearchInvalidRangeError, RepoSearchUnsupportedFileError, WORKSPACE_CODES, WorkspaceError, WorkspaceNotFoundError, WorkspaceReadError, type WorkspaceCode, } from "./errors.js";
+export { type WorkspaceDirEntry, type WorkspaceFs, type WorkspaceStat } from "./fs.js";
+export { isWithinWorkspace, resolveWithinWorkspace } from "./paths.js";
+export { assertContainedRealPath, containedRealPathInfo } from "./realpath.js";
+export { compileIgnore, DEFAULT_DENY_PATTERNS, isDenied, isIgnored, type IgnoreMatcher, } from "./ignore.js";
+export { detectWorkspace, detectWorkspaceAt } from "./detect.js";
+export { discoverFiles, discoverWithStats, readWorkspaceFile, type DiscoveryResult, } from "./discovery.js";
+export { lexicalRetrievalStrategy, type RankedFile, type RetrievalStrategy } from "./retrieval.js";
+export { buildContextPack, buildContextPackFromFiles, selectScoredTextByByteBudget, type ContextPackDeps, type ScoredTextBudgetResult, type ScoredTextBudgetSelection, } from "./contextPack.js";
+export { buildWorkspaceSummary, summarizeForAudit } from "./summary.js";
+export type { SearchScope, SearchLimits, SearchResult, ReadExcerptRequest, ReadExcerptResult, } from "./repoSearch.js";
+export { DEFAULT_SEARCH_LIMITS, searchText, findFiles, readExcerpt } from "./repoSearch.js";
+export type { CandidateBucket, SearchDiagnostics, SearchHints, SearchIntent, SearchPolicy, SearchPolicyMode, } from "./repoSearchPolicy.js";
+export { looksBinary, DEFAULT_BINARY_PROBE } from "./binaryDetect.js";
+export type { BinaryProbeOptions } from "./binaryDetect.js";
+export { evidenceAtomStableId, connectedContextPackStableId } from "./stableId.js";
+export type { AdapterError, RunAllResult, StructuralAdapter, StructuralAdapterDeps, StructuralAdapterRegistry, } from "./structuralAdapters.js";
+export { createDefaultStructuralRegistry, runStructuralAdapters } from "./structuralAdapters.js";
+export { testSourcePairingAdapter } from "./testSourcePairing.js";
+export { importGraphAdapter } from "./importGraph.js";
+export { gitHistoryAdapter } from "./gitHistory.js";
+export { KEIKO_WORKSPACE_VERSION } from "./version.js";
+export type { DocumentExtractionBudget, DocumentExtractionFailure, DocumentExtractionResult, ExtractedDocumentContext, } from "./document-extraction.js";
+export { MAX_EXTRACTED_BYTES, MAX_TOTAL_EXTRACTED_BYTES, SUPPORTED_MIME_LITERALS, SUPPORTED_MIME_PREFIXES, extractDocumentContext, } from "./document-extraction.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,25 @@
+// Public barrel for the repository-context & workspace-access layer (ADR-0005). The only
+// boundary-checked file-read seam is `readWorkspaceFile` (lexical containment + symlink
+// realpath gate + size cap + redaction). The Node-backed `nodeWorkspaceFs` adapter is kept on
+// the package's internal subpath so the public barrel exposes safe operations and injectable port
+// types, not a parallel raw read path.
+export { DEFAULT_CONTEXT_REQUEST, DEFAULT_DISCOVERY_OPTIONS, DEFAULT_READ_OPTIONS, SELECTION_REASON_PRIORITY, } from "./types.js";
+export { FileTooLargeError, PathDeniedError, PathEscapeError, RepoSearchInvalidQueryError, RepoSearchInvalidRangeError, RepoSearchUnsupportedFileError, WORKSPACE_CODES, WorkspaceError, WorkspaceNotFoundError, WorkspaceReadError, } from "./errors.js";
+export {} from "./fs.js";
+export { isWithinWorkspace, resolveWithinWorkspace } from "./paths.js";
+export { assertContainedRealPath, containedRealPathInfo } from "./realpath.js";
+export { compileIgnore, DEFAULT_DENY_PATTERNS, isDenied, isIgnored, } from "./ignore.js";
+export { detectWorkspace, detectWorkspaceAt } from "./detect.js";
+export { discoverFiles, discoverWithStats, readWorkspaceFile, } from "./discovery.js";
+export { lexicalRetrievalStrategy } from "./retrieval.js";
+export { buildContextPack, buildContextPackFromFiles, selectScoredTextByByteBudget, } from "./contextPack.js";
+export { buildWorkspaceSummary, summarizeForAudit } from "./summary.js";
+export { DEFAULT_SEARCH_LIMITS, searchText, findFiles, readExcerpt } from "./repoSearch.js";
+export { looksBinary, DEFAULT_BINARY_PROBE } from "./binaryDetect.js";
+export { evidenceAtomStableId, connectedContextPackStableId } from "./stableId.js";
+export { createDefaultStructuralRegistry, runStructuralAdapters } from "./structuralAdapters.js";
+export { testSourcePairingAdapter } from "./testSourcePairing.js";
+export { importGraphAdapter } from "./importGraph.js";
+export { gitHistoryAdapter } from "./gitHistory.js";
+export { KEIKO_WORKSPACE_VERSION } from "./version.js";
+export { MAX_EXTRACTED_BYTES, MAX_TOTAL_EXTRACTED_BYTES, SUPPORTED_MIME_LITERALS, SUPPORTED_MIME_PREFIXES, extractDocumentContext, } from "./document-extraction.js";

package/dist/paths.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveWithinWorkspace(root: string, candidate: string): string;
+export declare function isWithinWorkspace(root: string, candidate: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAeA,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAgB9E;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAO1E"}

package/dist/paths.js

@@ -0,0 +1,38 @@
+// PURE, security-critical lexical path containment. This module performs NO filesystem
+// access: it decides whether a candidate path lexically resolves inside a workspace root.
+// Symlink/realpath containment (which DOES touch the filesystem) is enforced separately at
+// the IO edge in discovery.ts — see ADR-0005 D2 for the split.
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { PathEscapeError } from "./errors.js";
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+// Returns the normalized absolute path of `candidate` inside `root`, or throws
+// PathEscapeError. The returned value is the ONLY path that downstream IO should read, so
+// a static analyser's path sanitizer sits on this boundary.
+export function resolveWithinWorkspace(root, candidate) {
+    if (hasNul(root) || hasNul(candidate)) {
+        throw new PathEscapeError("path contains a NUL byte", candidate);
+    }
+    const absoluteRoot = resolve(root);
+    const absoluteCandidate = isAbsolute(candidate)
+        ? resolve(candidate)
+        : resolve(absoluteRoot, candidate);
+    const rel = relative(absoluteRoot, absoluteCandidate);
+    if (rel === "") {
+        return absoluteRoot;
+    }
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PathEscapeError(`path escapes the workspace boundary: ${candidate}`, candidate);
+    }
+    return absoluteCandidate;
+}
+export function isWithinWorkspace(root, candidate) {
+    try {
+        resolveWithinWorkspace(root, candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/realpath.d.ts

@@ -0,0 +1,9 @@
+import type { WorkspaceFs } from "./fs.js";
+export interface ContainedRealPathInfo {
+    readonly path: string;
+    readonly realRelative: string;
+    readonly realBase: string;
+}
+export declare function containedRealPathInfo(fs: WorkspaceFs, root: string, absolutePath: string): ContainedRealPathInfo;
+export declare function assertContainedRealPath(fs: WorkspaceFs, root: string, absolutePath: string, _label: string): string;
+//# sourceMappingURL=realpath.d.ts.map

package/dist/realpath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realpath.d.ts","sourceRoot":"","sources":["../src/realpath.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAqC3C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAI9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAwBvB;AAQD,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,MAAM,CAGR"}

package/dist/realpath.js

@@ -0,0 +1,72 @@
+// PURE-at-the-port symlink containment. After lexical resolveWithinWorkspace has proven a path is
+// lexically inside the root, this gate defends against the symlink class of escape: a path whose
+// real (symlink-followed) location is outside the root, or a not-yet-existing create target whose
+// nearest existing parent escapes via a symlink. Every filesystem touch goes through the injected
+// WorkspaceFs port (realPath only) so the logic stays testable with an in-memory fake and all real
+// IO is auditable in one place (ADR-0005 D2, ADR-0006 D2). The read path (discovery.ts) and the
+// write/cwd paths (tools/patch.ts, tools/exec.ts) share this single primitive — no duplicated logic.
+import { dirname } from "node:path";
+import { isWithinWorkspace } from "./paths.js";
+import { PathEscapeError } from "./errors.js";
+// Resolves `root` through any platform symlinks (e.g. macOS /var -> /private/var) so the
+// containment comparison is symlink-consistent on both sides. Falls back to the lexical root.
+function realRoot(fs, root) {
+    try {
+        return fs.realPath(root);
+    }
+    catch {
+        return root;
+    }
+}
+// Walks up from `absolutePath` to the nearest ancestor that exists on disk and returns its real
+// path. A create target does not exist yet, so we must realpath the deepest existing parent to
+// catch a symlinked parent directory (e.g. `link/evil` where `link` -> /outside). Bounded by the
+// path depth; terminates at the filesystem root where dirname is a fixpoint.
+function realNearestExisting(fs, absolutePath) {
+    let current = absolutePath;
+    for (;;) {
+        try {
+            return fs.realPath(current);
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current) {
+                return absolutePath; // reached the root with nothing resolvable; lexical check stands
+            }
+            current = parent;
+        }
+    }
+}
+function toRelative(root, absolutePath) {
+    return absolutePath.slice(root.length).replace(/^[/\\]/, "");
+}
+export function containedRealPathInfo(fs, root, absolutePath) {
+    const realBase = realRoot(fs, root);
+    try {
+        const target = fs.realPath(absolutePath);
+        if (!isWithinWorkspace(realBase, target)) {
+            throw new PathEscapeError(`path escapes the workspace boundary via symlink: ${absolutePath}`, absolutePath);
+        }
+        return { path: target, realRelative: toRelative(realBase, target), realBase };
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            throw error;
+        }
+        const parentReal = realNearestExisting(fs, absolutePath);
+        if (!isWithinWorkspace(realBase, parentReal)) {
+            throw new PathEscapeError(`path escapes the workspace boundary via symlink: ${absolutePath}`, absolutePath);
+        }
+        return { path: absolutePath, realRelative: toRelative(realBase, parentReal), realBase };
+    }
+}
+// Asserts that `absolutePath` (already lexically contained) does not escape `root` via a symlink.
+// For an existing target, the target's own realpath must stay within the real root. For a
+// not-yet-existing target (create), the nearest existing ancestor's realpath must stay within it,
+// which blocks `create through a symlinked directory` (the S-H1 .git/hooks escalation).
+// Returns the canonical real path to hand to IO (existing case) or the lexically-resolved path
+// (pure-create case where the target itself has no realpath yet).
+export function assertContainedRealPath(fs, root, absolutePath, _label) {
+    const info = containedRealPathInfo(fs, root, absolutePath);
+    return info.path;
+}

package/dist/repoSearch.d.ts

@@ -0,0 +1,46 @@
+import type { CandidateFile, EvidenceAtom, RetrievalQuery } from "@oscharko-dev/keiko-contracts/connected-context";
+import { type WorkspaceFs } from "./fs.js";
+import { type SearchDiagnostics, type SearchHints } from "./repoSearchPolicy.js";
+import type { WorkspaceInfo } from "./types.js";
+export interface SearchScope {
+    readonly workspace: WorkspaceInfo;
+    readonly scopeId: string;
+    readonly relativePaths: readonly string[];
+}
+export interface SearchLimits {
+    readonly maxFilesScanned: number;
+    readonly maxMatchesReturned: number;
+    readonly maxBytesPerFileScanned: number;
+    readonly elapsedMsMax: number;
+}
+export declare const DEFAULT_SEARCH_LIMITS: SearchLimits;
+export interface SearchResult {
+    readonly atoms: readonly EvidenceAtom[];
+    readonly candidates: readonly CandidateFile[];
+    readonly filesScanned: number;
+    readonly elapsedMs: number;
+    readonly truncated: boolean;
+    readonly diagnostics: SearchDiagnostics | undefined;
+}
+export interface ReadExcerptRequest {
+    readonly scopePath: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly maxBytes: number;
+}
+export interface ReadExcerptResult {
+    readonly atom: EvidenceAtom;
+    readonly content: string;
+    readonly truncated: boolean;
+}
+interface FacadeDeps {
+    readonly fs?: WorkspaceFs;
+    readonly nowMs?: () => number;
+    readonly searchHints?: SearchHints | undefined;
+    readonly signal?: AbortSignal;
+}
+export declare function searchText(scope: SearchScope, query: RetrievalQuery, limits?: SearchLimits, deps?: FacadeDeps): Promise<SearchResult>;
+export declare function findFiles(scope: SearchScope, query: RetrievalQuery, limits?: SearchLimits, deps?: FacadeDeps): Promise<SearchResult>;
+export declare function readExcerpt(scope: SearchScope, request: ReadExcerptRequest, deps?: FacadeDeps): Promise<ReadExcerptResult>;
+export {};
+//# sourceMappingURL=repoSearch.d.ts.map

package/dist/repoSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoSearch.d.ts","sourceRoot":"","sources":["../src/repoSearch.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACf,MAAM,iDAAiD,CAAC;AAWzD,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAmB5D,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,qBAAqB,EAAE,YAK1B,CAAC;AAWX,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACrD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAqGD,wBAAsB,UAAU,CAC9B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,cAAc,EACrB,MAAM,GAAE,YAAoC,EAC5C,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,YAAY,CAAC,CAsCvB;AA+HD,wBAAsB,SAAS,CAC7B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,cAAc,EACrB,MAAM,GAAE,YAAoC,EAC5C,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,YAAY,CAAC,CAWvB;AAmHD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,kBAAkB,EAC3B,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CA+C5B"}