soloforge 1.1.2 → 1.1.30

package/dist/engine/contracts/ood_solid_contract.js

@@ -0,0 +1,115 @@
+/**
+ * OOD 与 SOLID 实现契约。
+ *
+ * 复杂业务编码在执行前必须给出对象职责与依赖边界；审查和交付阶段
+ * 使用同一套 finding 口径阻断典型的 SOLID 违规。
+ */
+const COMPLEX_OOD_KEYWORDS = /领域|业务规则|状态流转|策略模式|计费策略|订单流转|支付编排|结算规则|工作流编排|重构架构|模块设计|服务设计|领域服务|应用服务设计|domain|aggregate|solid|面向对象|职责拆分|接口抽象|依赖倒置/i;
+const LOW_RISK_KEYWORDS = /错别字|拼写|文案|注释|样式|css|颜色|README|日志文案|配置值|测试数据|fixture/i;
+export function requiresOodSolidContract(intent, route, changedFiles = []) {
+    const text = `${intent} ${changedFiles.join(" ")}`;
+    if (LOW_RISK_KEYWORDS.test(text) && !COMPLEX_OOD_KEYWORDS.test(text))
+        return false;
+    const codeRoute = !route || ["code_change", "artifact_generation", "operation", "multi_stage_plan"].includes(route);
+    return codeRoute && COMPLEX_OOD_KEYWORDS.test(text);
+}
+export function createOodDesignSummary(taskId, intent) {
+    return {
+        task_id: taskId,
+        status: "required",
+        applicability_reason_zh: `该任务涉及复杂对象职责或依赖边界，编码前需补齐 OOD/SOLID 摘要: ${intent}`,
+        objects: [],
+        interfaces: [],
+        dependency_direction: [],
+        change_points: [],
+        solid_risks: [],
+    };
+}
+function hasCompleteDesignSummary(summary) {
+    return !!summary
+        && summary.objects.length > 0
+        && summary.objects.every((item) => item.name.trim().length > 0 && item.responsibility.trim().length > 0)
+        && summary.interfaces.length > 0
+        && summary.dependency_direction.length > 0
+        && summary.change_points.length > 0
+        && summary.solid_risks.length > 0;
+}
+export function evaluateOodDesignGate(input) {
+    if (!requiresOodSolidContract(input.intent, input.route, input.changed_files)) {
+        return {
+            applicable: false,
+            allowed: true,
+            status: "not_applicable",
+            reason_zh: "低风险或非对象设计任务，无需引入 OOD/SOLID 工作包",
+            findings: [],
+        };
+    }
+    if (!hasCompleteDesignSummary(input.summary)) {
+        return {
+            applicable: true,
+            allowed: false,
+            status: "blocked",
+            reason_zh: "复杂编码任务缺少完整 OOD/SOLID 设计摘要，不得开始实现",
+            required_summary: input.summary ?? createOodDesignSummary(input.task_id, input.intent),
+            findings: [],
+        };
+    }
+    return {
+        applicable: true,
+        allowed: true,
+        status: "satisfied",
+        reason_zh: "OOD/SOLID 设计摘要已具备，可进入实现并在审查阶段复验",
+        required_summary: { ...input.summary, status: "satisfied" },
+        findings: [],
+    };
+}
+function addFinding(findings, principle, severity, file, evidence, suggestion_zh) {
+    findings.push({ principle, severity, file, evidence, suggestion_zh });
+}
+export function reviewSolidCode(fileContents) {
+    const findings = [];
+    for (const [file, content] of Object.entries(fileContents)) {
+        const lowered = file.toLowerCase();
+        if (/controller/.test(lowered)
+            && /(?:repository\.|mapper\.|entitymanager|save\s*\(|@Transactional|calculate|compute)/i.test(content)) {
+            addFinding(findings, "SRP", "hard_fail", file, "Controller 同时出现持久化、事务或业务计算职责", "将业务规则与持久化移入应用服务，Controller 仅处理协议适配、校验和响应映射。");
+        }
+        if (/(?:service|usecase|application)/.test(lowered)
+            && /new\s+(?:RestTemplate|WebClient|HttpClient|Stripe|S3|OpenAI|Twilio|Axios|.*Repository)\s*\(/i.test(content)) {
+            addFinding(findings, "DIP", "hard_fail", file, "业务服务直接构造外部依赖或仓储实现", "通过端口接口与依赖注入隔离基础设施实现。");
+        }
+        if (/interface\s+\w+[\s\S]{0,800}(?:upload|export|notify|delete|approve)[\s\S]{0,800}(?:upload|export|notify|delete|approve)/i.test(content)
+            && /(?:UnsupportedOperationException|throw new Error\(['\"]not implemented)/i.test(content)) {
+            addFinding(findings, "ISP", "hard_fail", file, "实现被迫抛出未支持操作，接口职责过宽", "拆分为客户端真正需要的细粒度接口。");
+        }
+        if (/(?:extends|implements)\s+\w+[\s\S]{0,500}(?:UnsupportedOperationException|throw new Error\(['\"]unsupported)/i.test(content)) {
+            addFinding(findings, "LSP", "hard_fail", file, "子类型拒绝父契约操作", "重构抽象层级，确保替换后仍满足原契约。");
+        }
+        const branching = (content.match(/\b(?:if|else if|switch)\s*\([^)]*(?:type|status|kind|strategy)/gi) ?? []).length;
+        if (branching >= 3) {
+            addFinding(findings, "OCP", "warning", file, "同一变化维度出现多处分支扩展点", "用策略/处理器注册方式隔离新增类型，减少修改既有分支。");
+        }
+        if (/(?:component|page|\.tsx$|\.vue$)/.test(lowered)
+            && /(?:fetch\(|axios\.|apiClient|request\()/i.test(content)
+            && /(?:useState|useEffect|computed\(|ref\(|watch\()/i.test(content)
+            && /(?:if\s*\(|switch\s*\()/i.test(content)) {
+            addFinding(findings, "SRP", "hard_fail", file, "复杂 UI 组件混合远程调用、状态编排与业务判断", "拆分展示组件、状态 hook/composable 与 API client/业务服务。");
+        }
+    }
+    return findings;
+}
+export function hasBlockingSolidFindings(findings) {
+    return findings.some((finding) => finding.severity === "hard_fail");
+}
+export function evaluateOverdesignRisk(intent, summary) {
+    if (!LOW_RISK_KEYWORDS.test(intent) || !summary || summary.objects.length < 4)
+        return [];
+    return [{
+            principle: "OVERDESIGN",
+            severity: "warning",
+            file: "OOD设计摘要",
+            evidence: "低风险修改引入多个对象与抽象边界",
+            suggestion_zh: "保持最小实现，不为简单修改提前引入复杂对象结构。",
+        }];
+}
+//# sourceMappingURL=ood_solid_contract.js.map

package/dist/engine/contracts/ood_solid_contract.js.map

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

package/dist/engine/contracts/platform_context.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 问题四十: Platform Compatibility — 跨平台路径安全、规范化与兼容性。
+ *
+ * 强制执行:
+ * - symlink / case sensitivity / path separator / shell 差异不得绕过 scope
+ * - 跨平台兼容不得以降低安全边界为代价
+ * - 路径判定必须使用 path.resolve + path.relative，禁止 startsWith 字符串边界判断
+ */
+import type { PlatformContext, NormalizedPathRef, PlatformCompatibilityReport, PathSafetyCheck } from "./extension_platform_contracts.js";
+/**
+ * 路径解析器 — 可注入以支持测试环境和 CI。
+ * 默认使用 Node.js path.resolve + fs.realpathSync.native。
+ */
+export interface PathResolver {
+    resolve: (...pathSegments: string[]) => string;
+    realpath: (p: string) => string;
+}
+/**
+ * 检测当前平台上下文。
+ */
+export declare function detectPlatformContext(workspacePath: string): PlatformContext;
+/**
+ * 规范化路径引用。
+ *
+ * 安全策略:
+ * - 使用 path.resolve 解析 .. / ~ / 相对路径
+ * - 使用 path.relative + startsWith('..') 判断是否逃逸 scope
+ * - 禁止 startsWith 字符串边界判断作为 scope 判定方式
+ * - realpath 解析 symlink，文件不存在时回退到 resolved 路径
+ */
+export declare function normalizePathRef(rawPath: string, platform: PlatformContext, scopeBoundary: string, resolver?: PathResolver): NormalizedPathRef;
+/**
+ * 执行路径安全检查。
+ */
+export declare function checkPathSafety(pathRef: NormalizedPathRef, scopeBoundary: string): PathSafetyCheck;
+/**
+ * 生成平台兼容性报告。
+ */
+export declare function generatePlatformReport(platform: PlatformContext, pathsToCheck: string[], scopeBoundary: string): PlatformCompatibilityReport;
+/**
+ * 创建测试用的平台上下文。
+ */
+export declare function createTestPlatformContext(overrides?: Partial<PlatformContext>): PlatformContext;
+//# sourceMappingURL=platform_context.d.ts.map

package/dist/engine/contracts/platform_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform_context.d.ts","sourceRoot":"","sources":["../../../src/engine/contracts/platform_context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,2BAA2B,EAC3B,eAAe,EAGhB,MAAM,mCAAmC,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IAC/C,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CACjC;AAcD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,CAY5E;AAaD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,EACzB,aAAa,EAAE,MAAM,EACrB,QAAQ,GAAE,YAA+B,GACxC,iBAAiB,CA+CnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,EAAE,MAAM,GACpB,eAAe,CAoBjB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,EACzB,YAAY,EAAE,MAAM,EAAE,EACtB,aAAa,EAAE,MAAM,GACpB,2BAA2B,CAuB7B;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAY/F"}

package/dist/engine/contracts/platform_context.js

@@ -0,0 +1,169 @@
+/**
+ * 问题四十: Platform Compatibility — 跨平台路径安全、规范化与兼容性。
+ *
+ * 强制执行:
+ * - symlink / case sensitivity / path separator / shell 差异不得绕过 scope
+ * - 跨平台兼容不得以降低安全边界为代价
+ * - 路径判定必须使用 path.resolve + path.relative，禁止 startsWith 字符串边界判断
+ */
+import path from "node:path";
+import fs from "node:fs";
+/** 默认解析器 — 使用 Node.js 原生 path + fs */
+const DEFAULT_RESOLVER = {
+    resolve: (...segments) => path.resolve(...segments),
+    realpath: (p) => {
+        try {
+            return fs.realpathSync.native(p);
+        }
+        catch {
+            return p;
+        }
+    },
+};
+/**
+ * 检测当前平台上下文。
+ */
+export function detectPlatformContext(workspacePath) {
+    const platform = process.platform;
+    return {
+        os: platform === "win32" ? "win32" : platform === "darwin" ? "darwin" : "linux",
+        arch: process.arch,
+        shell: detectShell(),
+        path_case_sensitive: platform !== "win32" && platform !== "darwin",
+        path_separator: platform === "win32" ? "\\" : "/",
+        line_ending: platform === "win32" ? "crlf" : "lf",
+        supports_symlink: platform !== "win32",
+        workspace_realpath: workspacePath,
+    };
+}
+function detectShell() {
+    const shell = process.env.SHELL ?? "";
+    if (shell.includes("zsh"))
+        return "zsh";
+    if (shell.includes("bash"))
+        return "bash";
+    if (shell.includes("fish"))
+        return "fish";
+    if (process.platform === "win32") {
+        return process.env.COMSPEC?.includes("cmd") ? "cmd" : "powershell";
+    }
+    return "unknown";
+}
+/**
+ * 规范化路径引用。
+ *
+ * 安全策略:
+ * - 使用 path.resolve 解析 .. / ~ / 相对路径
+ * - 使用 path.relative + startsWith('..') 判断是否逃逸 scope
+ * - 禁止 startsWith 字符串边界判断作为 scope 判定方式
+ * - realpath 解析 symlink，文件不存在时回退到 resolved 路径
+ */
+export function normalizePathRef(rawPath, platform, scopeBoundary, resolver = DEFAULT_RESOLVER) {
+    // 跨平台分隔符归一化: Windows 反斜杠统一为正斜杠后再 resolve
+    const normalizedRaw = platform.os === "win32" ? rawPath.replace(/\\/g, "/") : rawPath;
+    const normalizedScope = platform.os === "win32" ? scopeBoundary.replace(/\\/g, "/") : scopeBoundary;
+    // path.resolve 解析所有 .. / . / 相对路径段
+    const resolved = resolver.resolve(normalizedRaw);
+    const resolvedScope = resolver.resolve(normalizedScope);
+    // realpath 解析 symlink — 文件不存在时回退到 resolved
+    const realPath = resolver.realpath(resolved);
+    const realScope = resolver.realpath(resolvedScope);
+    // 使用 path.relative 判断包含关系:
+    // relative 结果不以 .. 开头且不是绝对路径 → 在 scope 内
+    const relative = path.relative(realScope, realPath);
+    const isWithinWorkspace = relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+    let pathSafetyStatus = "safe";
+    // symlink / 逃逸检测
+    const hasSymlinkIndicator = rawPath.includes("..") || rawPath.includes("~");
+    // 大小写别名冲突: 仅当 resolved 与 realpath 大小写不一致时才标记
+    // 普通保留大小写路径（如 /tmp/Project/src/App.ts）在 macOS 上是安全的，
+    // 仅当请求路径与磁盘真实路径存在大小写别名歧义时才为冲突
+    const caseNormalized = !platform.path_case_sensitive
+        && resolved.toLowerCase() === realPath.toLowerCase()
+        && resolved !== realPath;
+    if (!isWithinWorkspace && hasSymlinkIndicator) {
+        pathSafetyStatus = "symlink_escape";
+    }
+    else if (!isWithinWorkspace) {
+        pathSafetyStatus = "outside_scope";
+    }
+    else if (caseNormalized) {
+        pathSafetyStatus = "case_conflict";
+    }
+    return {
+        original: rawPath,
+        normalized: resolved,
+        is_within_workspace: isWithinWorkspace,
+        case_normalized: caseNormalized,
+        symlink_resolved: realPath !== resolved,
+        platform: platform.os,
+        path_safety_status: pathSafetyStatus,
+    };
+}
+/**
+ * 执行路径安全检查。
+ */
+export function checkPathSafety(pathRef, scopeBoundary) {
+    const passes = pathRef.is_within_workspace && pathRef.path_safety_status === "safe";
+    let reason = "";
+    if (pathRef.path_safety_status === "symlink_escape") {
+        reason = "路径包含 .. 或 ~，可能逃逸工作区范围";
+    }
+    else if (pathRef.path_safety_status === "outside_scope") {
+        reason = "路径在工作区范围外";
+    }
+    else if (pathRef.path_safety_status === "case_conflict") {
+        reason = "不区分大小写的平台存在大小写冲突风险";
+    }
+    else if (passes) {
+        reason = "路径安全";
+    }
+    return {
+        path_ref: pathRef,
+        scope_boundary: scopeBoundary,
+        passes,
+        reason,
+    };
+}
+/**
+ * 生成平台兼容性报告。
+ */
+export function generatePlatformReport(platform, pathsToCheck, scopeBoundary) {
+    const issues = [];
+    let status = "compatible";
+    for (const rawPath of pathsToCheck) {
+        const ref = normalizePathRef(rawPath, platform, scopeBoundary);
+        if (ref.path_safety_status !== "safe") {
+            issues.push(`路径不安全: ${rawPath} (${ref.path_safety_status})`);
+        }
+    }
+    if (issues.some(i => i.includes("symlink_escape"))) {
+        status = "blocked";
+    }
+    else if (issues.length > 0) {
+        status = "needs_normalization";
+    }
+    return {
+        platform_context: platform,
+        path_refs_checked: pathsToCheck.length,
+        issues_found: issues,
+        platform_compatibility_status: status,
+    };
+}
+/**
+ * 创建测试用的平台上下文。
+ */
+export function createTestPlatformContext(overrides) {
+    return {
+        os: "darwin",
+        arch: "arm64",
+        shell: "zsh",
+        path_case_sensitive: false,
+        path_separator: "/",
+        line_ending: "lf",
+        supports_symlink: true,
+        workspace_realpath: "/tmp/test-workspace",
+        ...overrides,
+    };
+}
+//# sourceMappingURL=platform_context.js.map

package/dist/engine/contracts/platform_context.js.map

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

package/dist/engine/contracts/policy_drift_detector.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Policy ID 漂移检测 — 检查 policy_id 在代码、测试、知识、Prompt 间的交叉引用一致性。
+ * P1-5 范围: 检测 + 只读报告摘要，不做自动修复，不改能力状态。
+ */
+export type DriftType = "code_without_policy" | "policy_without_code" | "policy_without_tests" | "tests_without_policy" | "prompt_without_policy" | "enforced_without_lifecycle_tests" | "removed_but_documented";
+export { type PolicyRef } from "./capability_registry.js";
+import type { PolicyRef as PolicyRefType } from "./capability_registry.js";
+type PolicyRef = PolicyRefType;
+export interface DriftEntry {
+    type: DriftType;
+    policy_id?: string;
+    path?: string;
+    detail: string;
+}
+export interface DriftReport {
+    total_policies: number;
+    drift_count: number;
+    drifts: DriftEntry[];
+    by_type: Record<DriftType, number>;
+}
+export interface DriftScanInput {
+    policies: PolicyRef[];
+    existingFiles: Set<string>;
+    knownCodeFiles: string[];
+    knownTestFiles: string[];
+    knownPromptFiles: string[];
+}
+/**
+ * 检测特征
+ */
+export declare function detectPolicyDrift(input: DriftScanInput): DriftReport;
+export type PolicyStatus = "missing" | "stale" | "ok";
+export interface PolicyDriftSummary {
+    policy_id: string;
+    capability_id: string;
+    state: PolicyRefType["state"];
+    status: PolicyStatus;
+    drifts: DriftEntry[];
+}
+export interface DriftSummaryReport {
+    total: number;
+    missing: number;
+    stale: number;
+    ok: number;
+    unassigned_drifts: DriftEntry[];
+    policies: PolicyDriftSummary[];
+}
+/**
+ * 生成内容
+ */
+export declare function generateDriftSummary(policies: PolicyRefType[], report: DriftReport): DriftSummaryReport;
+import type { ContractRegistryEntry, ContractGovernanceFinding } from "./contract_registry.js";
+export interface ContractDriftEntry {
+    contract_id: string;
+    type: DriftType | "contract_not_registered" | "contract_no_test" | "contract_dependency_missing" | "contract_removed_referenced";
+    detail: string;
+}
+export interface ContractDriftReport {
+    total_contracts: number;
+    drift_count: number;
+    drifts: ContractDriftEntry[];
+    governance_findings: ContractGovernanceFinding[];
+}
+/**
+ * 契约漂移扫描 — 基于 Unified Contract Registry 检测契约与代码/测试/依赖的一致性。
+ * 扩展 policy drift，使 drift 能按 contract_id 归因。
+ */
+export declare function detectContractDrift(contracts: ContractRegistryEntry[], existingFiles: Set<string>, knownWorkflowRefs?: Array<{
+    workflow_id: string;
+    contract_refs: string[];
+}>): ContractDriftReport;
+//# sourceMappingURL=policy_drift_detector.d.ts.map

package/dist/engine/contracts/policy_drift_detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy_drift_detector.d.ts","sourceRoot":"","sources":["../../../src/engine/contracts/policy_drift_detector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,SAAS,GACjB,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,GACtB,sBAAsB,GACtB,uBAAuB,GACvB,kCAAkC,GAClC,wBAAwB,CAAC;AAE7B,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC3E,KAAK,SAAS,GAAG,aAAa,CAAC;AAE/B,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;CACpC;AAgBD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAyIpE;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,iBAAiB,EAAE,UAAU,EAAE,CAAC;IAChC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EAAE,EACzB,MAAM,EAAE,WAAW,GAClB,kBAAkB,CAyCpB;AAID,OAAO,KAAK,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAG/F,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,GAAG,yBAAyB,GAAG,kBAAkB,GAAG,6BAA6B,GAAG,6BAA6B,CAAC;IACjI,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,mBAAmB,EAAE,yBAAyB,EAAE,CAAC;CAClD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,qBAAqB,EAAE,EAClC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,iBAAiB,CAAC,EAAE,KAAK,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GAC1E,mBAAmB,CA+ErB"}