autosnippet 3.3.4 → 3.3.6

package/dist/lib/types/evolution.d.ts

@@ -0,0 +1,135 @@
+/**
+ * evolution.ts — Evolution 系统类型定义
+ *
+ * 包含 ContentPatcher / RecipeLifecycleSupervisor / 结构化 suggestedChanges 的类型。
+ */
+/** suggestedChanges 中每项变更操作 */
+export interface PatchChange {
+    /** 目标字段路径（如 'content.markdown', 'coreCode', 'doClause'） */
+    field: string;
+    /** 操作类型 */
+    action: 'replace' | 'replace-section' | 'append';
+    /** 新值（replace / append 时必填） */
+    newValue?: string;
+    /** 目标 section 标题（replace-section 时必填） */
+    section?: string;
+    /** 新 section 内容（replace-section 时必填） */
+    newContent?: string;
+}
+/** 结构化 suggestedChanges 格式（Agent 输出） */
+export interface StructuredPatch {
+    patchVersion: number;
+    changes: PatchChange[];
+    reasoning: string;
+}
+/** Recipe 内容快照 */
+export interface RecipeContentSnapshot {
+    coreCode: string;
+    doClause: string;
+    dontClause: string;
+    whenClause: string;
+    content: {
+        markdown?: string;
+        rationale?: string;
+    };
+    sourceRefs: string[];
+    headers: string[];
+}
+/** ContentPatcher 应用结果 */
+export interface ContentPatchResult {
+    success: boolean;
+    recipeId: string;
+    fieldsPatched: string[];
+    beforeSnapshot: RecipeContentSnapshot;
+    afterSnapshot: RecipeContentSnapshot;
+    patchSource: 'agent-suggestion' | 'correction' | 'merge';
+    skipped: boolean;
+    skipReason?: string;
+}
+/** 状态转移触发类型 */
+export type TransitionTrigger = 'confidence-route' | 'grace-period-expire' | 'guard-conflict' | 'proposal-execution' | 'proposal-attach' | 'content-patch-complete' | 'decay-detection' | 'manual-deprecation' | 'timeout-recovery' | 'evidence-recovery' | 'resurrection';
+/** 状态转移证据 */
+export interface TransitionEvidence {
+    decayScore?: number;
+    fpRate?: number;
+    usageCount?: number;
+    suggestedChanges?: string;
+    patchResult?: ContentPatchResult;
+    reason: string;
+}
+/** 状态转移请求 */
+export interface TransitionRequest {
+    recipeId: string;
+    targetState: string;
+    trigger: TransitionTrigger;
+    evidence?: TransitionEvidence;
+    proposalId?: string;
+    operatorId?: string;
+}
+/** 状态转移事件（不可变记录） */
+export interface TransitionEvent {
+    id: string;
+    recipeId: string;
+    fromState: string;
+    toState: string;
+    trigger: TransitionTrigger;
+    evidence: TransitionEvidence | null;
+    proposalId: string | null;
+    operatorId: string;
+    createdAt: number;
+}
+/** 状态转移结果 */
+export interface TransitionResult {
+    success: boolean;
+    fromState: string;
+    toState: string;
+    event?: TransitionEvent;
+    error?: string;
+}
+/** 超时检查结果 */
+export interface TimeoutCheckResult {
+    timedOut: {
+        recipeId: string;
+        fromState: string;
+        toState: string;
+        age: number;
+    }[];
+    checked: number;
+}
+/** 生命周期健康摘要 */
+export interface LifecycleHealthSummary {
+    stateDistribution: Record<string, number>;
+    intermediateStates: {
+        stuckEvolving: {
+            count: number;
+            oldestAge: number;
+        };
+        stuckDecaying: {
+            count: number;
+            oldestAge: number;
+        };
+        stuckStaging: {
+            count: number;
+            oldestAge: number;
+        };
+        stuckPending: {
+            count: number;
+            oldestAge: number;
+        };
+    };
+    recentTransitions: {
+        last24h: number;
+        last7d: number;
+        topTriggers: {
+            trigger: string;
+            count: number;
+        }[];
+    };
+    proposalMetrics: {
+        pendingCount: number;
+        observingCount: number;
+        executionRate: number;
+        avgObservationDays: number;
+        contentPatchRate: number;
+    };
+}

package/dist/lib/types/evolution.js

@@ -0,0 +1,6 @@
+/**
+ * evolution.ts — Evolution 系统类型定义
+ *
+ * 包含 ContentPatcher / RecipeLifecycleSupervisor / 结构化 suggestedChanges 的类型。
+ */
+export {};

package/dist/lib/types/graph-shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * §10.6 Graph shared types — 图谱类型共享
+ *
+ * Bootstrap 管道和 KnowledgeGraphService 共享实体/边的概念。
+ * 统一枚举避免 string literal 不一致。
+ */
+/** 代码实体类型 */
+export type EntityType = 'class' | 'protocol' | 'category' | 'module' | 'pattern' | 'function' | 'file';
+/** 关系类型 */
+export type RelationType = 'inherits' | 'conforms' | 'extends' | 'depends_on' | 'uses_pattern' | 'is_part_of' | 'calls' | 'data_flow' | 'discovered_in';
+/** 图节点引用 */
+export interface GraphNodeRef {
+    id: string;
+    type: EntityType;
+    name: string;
+}
+/** 图边引用 */
+export interface GraphEdgeRef {
+    fromId: string;
+    fromType: EntityType;
+    toId: string;
+    toType: EntityType;
+    relation: RelationType;
+    weight?: number;
+}

package/dist/lib/types/graph-shared.js

@@ -0,0 +1,7 @@
+/**
+ * §10.6 Graph shared types — 图谱类型共享
+ *
+ * Bootstrap 管道和 KnowledgeGraphService 共享实体/边的概念。
+ * 统一枚举避免 string literal 不一致。
+ */
+export {};

package/dist/lib/types/knowledge-wire.d.ts

@@ -0,0 +1,131 @@
+/**
+ * §10.1 KnowledgeEntryWire — 统一的知识条目传输合约
+ *
+ * 这是后端 KnowledgeEntry.toJSON() 和前端 Dashboard 共享的唯一类型定义。
+ * 所有 API 层传输都使用此形状，消除后端 class 与前端 interface 的字段漂移。
+ */
+export type KnowledgeLifecycle = 'pending' | 'staging' | 'active' | 'evolving' | 'decaying' | 'deprecated';
+export type KnowledgeKind = 'rule' | 'pattern' | 'fact';
+export interface KnowledgeContentWire {
+    pattern: string;
+    markdown: string;
+    rationale: string;
+    steps: Array<{
+        title?: string;
+        description?: string;
+        code?: string;
+    }>;
+    codeChanges: Array<{
+        file: string;
+        before: string;
+        after: string;
+        explanation: string;
+    }>;
+    verification: {
+        method?: string;
+        expectedResult?: string;
+        testCode?: string;
+    } | null;
+}
+export interface KnowledgeReasoningWire {
+    whyStandard: string;
+    sources: string[];
+    confidence: number;
+    qualitySignals: Record<string, unknown>;
+    alternatives: string[];
+}
+export interface KnowledgeQualityWire {
+    completeness: number;
+    adaptation: number;
+    documentation: number;
+    overall: number;
+    grade: string;
+}
+export interface KnowledgeStatsWire {
+    views: number;
+    adoptions: number;
+    applications: number;
+    guardHits: number;
+    searchHits: number;
+    authority: number;
+    lastHitAt: number | null;
+    lastSearchedAt: number | null;
+    lastGuardHitAt: number | null;
+    hitsLast30d: number;
+    hitsLast90d: number;
+    searchHitsLast30d: number;
+    version: number;
+    ruleFalsePositiveRate: number | null;
+}
+export interface KnowledgeConstraintsWire {
+    guards: Array<{
+        id?: string | null;
+        type?: string;
+        pattern: string | null;
+        severity: string;
+        message?: string;
+        fixSuggestion?: string;
+    }>;
+    boundaries: string[];
+    preconditions: string[];
+    sideEffects: string[];
+}
+export interface KnowledgeRelationEntry {
+    target: string;
+    description?: string;
+}
+export interface KnowledgeRelationsWire {
+    [bucket: string]: KnowledgeRelationEntry[];
+}
+/** 后端 → 前端 / API 传输的唯一合约 */
+export interface KnowledgeEntryWire {
+    id: string;
+    title: string;
+    description: string;
+    lifecycle: string;
+    lifecycleHistory: Array<{
+        from: string;
+        to: string;
+        at: number;
+    }>;
+    autoApprovable: boolean;
+    language: string;
+    category: string;
+    kind: string;
+    knowledgeType: string;
+    complexity: string;
+    scope: string;
+    difficulty: string | null;
+    tags: string[];
+    trigger: string;
+    topicHint: string;
+    whenClause: string;
+    doClause: string;
+    dontClause: string;
+    coreCode: string;
+    usageGuide: string;
+    content: KnowledgeContentWire;
+    relations: KnowledgeRelationsWire;
+    constraints: KnowledgeConstraintsWire;
+    reasoning: KnowledgeReasoningWire;
+    quality: KnowledgeQualityWire;
+    stats: KnowledgeStatsWire;
+    headers: string[];
+    headerPaths: string[];
+    moduleName: string;
+    includeHeaders: boolean;
+    agentNotes: string | null;
+    aiInsight: string | null;
+    reviewedBy: string | null;
+    reviewedAt: number | null;
+    rejectionReason: string | null;
+    source: string;
+    sourceFile: string | null;
+    sourceCandidateId: string | null;
+    createdBy: string;
+    createdAt: number;
+    updatedAt: number;
+    publishedAt: number | null;
+    publishedBy: string | null;
+    [key: string]: unknown;
+}

package/dist/lib/types/knowledge-wire.js

@@ -0,0 +1,7 @@
+/**
+ * §10.1 KnowledgeEntryWire — 统一的知识条目传输合约
+ *
+ * 这是后端 KnowledgeEntry.toJSON() 和前端 Dashboard 共享的唯一类型定义。
+ * 所有 API 层传输都使用此形状，消除后端 class 与前端 interface 的字段漂移。
+ */
+export {};

package/dist/lib/types/project-snapshot-builder.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ProjectSnapshot Builder — 从 runAllPhases() 的松散返回值构建类型化快照
+ *
+ * 职责：
+ *   1. 类型归一化（unknown → typed interfaces）
+ *   2. 默认值填充
+ *   3. 不可变冻结（Object.freeze）
+ *
+ * @module types/project-snapshot-builder
+ * @see docs/copilot/unified-project-snapshot-design.md
+ */
+import type { ProjectSnapshot, ProjectSnapshotInput } from './project-snapshot.js';
+/**
+ * 从 runAllPhases() 的松散返回值构建类型化的 ProjectSnapshot。
+ *
+ * @param input runAllPhases() 返回值 + 额外的上下文信息
+ * @returns 不可变的 ProjectSnapshot 对象
+ */
+export declare function buildProjectSnapshot(input: ProjectSnapshotInput): ProjectSnapshot;

package/dist/lib/types/project-snapshot-builder.js

@@ -0,0 +1,189 @@
+/**
+ * ProjectSnapshot Builder — 从 runAllPhases() 的松散返回值构建类型化快照
+ *
+ * 职责：
+ *   1. 类型归一化（unknown → typed interfaces）
+ *   2. 默认值填充
+ *   3. 不可变冻结（Object.freeze）
+ *
+ * @module types/project-snapshot-builder
+ * @see docs/copilot/unified-project-snapshot-design.md
+ */
+const SNAPSHOT_VERSION = '1.0.0';
+/**
+ * 从 runAllPhases() 的松散返回值构建类型化的 ProjectSnapshot。
+ *
+ * @param input runAllPhases() 返回值 + 额外的上下文信息
+ * @returns 不可变的 ProjectSnapshot 对象
+ */
+export function buildProjectSnapshot(input) {
+    const primaryLang = typeof input.primaryLang === 'string' ? input.primaryLang : 'unknown';
+    const langStats = input.langStats && typeof input.langStats === 'object' ? input.langStats : {};
+    const language = {
+        primaryLang,
+        stats: langStats,
+        secondary: input.langProfile?.secondary,
+        isMultiLang: input.langProfile?.isMultiLang,
+    };
+    const snapshot = {
+        version: SNAPSHOT_VERSION,
+        timestamp: Date.now(),
+        projectRoot: input.projectRoot,
+        sourceTag: input.sourceTag,
+        // Phase 1
+        allFiles: normalizeFiles(input.allFiles),
+        allTargets: normalizeTargets(input.allTargets),
+        discoverer: normalizeDiscoverer(input.discoverer),
+        truncated: input.truncated ?? false,
+        // Phase 1.5
+        language,
+        ast: normalizeAst(input.astProjectSummary),
+        astContext: typeof input.astContext === 'string' ? input.astContext : null,
+        // Phase 1.6-1.7
+        codeEntityGraph: normalizeCodeEntity(input.codeEntityResult),
+        callGraph: normalizeCallGraph(input.callGraphResult),
+        // Phase 1.8
+        panorama: normalizePanorama(input.panoramaResult),
+        // Phase 2
+        dependencyGraph: normalizeDepGraph(input.depGraphData),
+        depEdgesWritten: typeof input.depEdgesWritten === 'number' ? input.depEdgesWritten : 0,
+        // Phase 3
+        guardAudit: normalizeGuardAudit(input.guardAudit),
+        // Phase 4
+        activeDimensions: normalizeDimensions(input.activeDimensions),
+        enhancementPackInfo: normalizeEnhancementPackInfo(input.enhancementPackInfo),
+        enhancementPatterns: Array.isArray(input.enhancementPatterns)
+            ? input.enhancementPatterns
+            : [],
+        enhancementGuardRules: Array.isArray(input.enhancementGuardRules)
+            ? input.enhancementGuardRules
+            : [],
+        detectedFrameworks: Array.isArray(input.detectedFrameworks) ? input.detectedFrameworks : [],
+        // Language profile & Targets summary
+        langProfile: language,
+        targetsSummary: normalizeTargets(input.targetsSummary || input.allTargets),
+        localPackageModules: normalizeLocalPackageModules(input.localPackageModules),
+        // Report
+        phaseReport: normalizePhaseReport(input.report),
+        warnings: Array.isArray(input.warnings) ? input.warnings : [],
+        // Incremental
+        incrementalPlan: normalizeIncrementalPlan(input.incrementalPlan),
+        // Empty
+        isEmpty: input.isEmpty ?? false,
+    };
+    return Object.freeze(snapshot);
+}
+// ── Normalize 函数 ──────────────────────────────────────────
+function normalizeFiles(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.map((f) => ({
+        name: String(f.name || ''),
+        path: String(f.path || ''),
+        relativePath: String(f.relativePath || ''),
+        content: String(f.content || ''),
+        targetName: String(f.targetName || ''),
+        language: f.language != null ? String(f.language) : undefined,
+        totalLines: typeof f.totalLines === 'number' ? f.totalLines : undefined,
+        priority: f.priority != null ? String(f.priority) : undefined,
+        truncated: typeof f.truncated === 'boolean' ? f.truncated : undefined,
+    }));
+}
+function normalizeTargets(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.map((t) => {
+        if (typeof t === 'string') {
+            return { name: t };
+        }
+        const obj = t;
+        return {
+            name: String(obj.name || ''),
+            type: obj.type != null ? String(obj.type) : undefined,
+            framework: obj.framework != null ? String(obj.framework) : undefined,
+            packageName: obj.packageName != null ? String(obj.packageName) : undefined,
+            inferredRole: obj.inferredRole != null ? String(obj.inferredRole) : undefined,
+            fileCount: typeof obj.fileCount === 'number' ? obj.fileCount : undefined,
+            isLocalPackage: typeof obj.isLocalPackage === 'boolean' ? obj.isLocalPackage : undefined,
+        };
+    });
+}
+function normalizeDiscoverer(raw) {
+    if (raw && typeof raw === 'object') {
+        const obj = raw;
+        return {
+            id: String(obj.id || 'unknown'),
+            displayName: String(obj.displayName || 'Unknown'),
+        };
+    }
+    return { id: 'unknown', displayName: 'Unknown' };
+}
+function normalizeAst(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    // Pass through — the shapes from analyzeProject() already match AstSummary
+    return raw;
+}
+function normalizeCodeEntity(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizeCallGraph(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizePanorama(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizeDepGraph(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizeGuardAudit(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizeDimensions(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw;
+}
+function normalizeEnhancementPackInfo(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw;
+}
+function normalizePhaseReport(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizeIncrementalPlan(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return raw;
+}
+function normalizeLocalPackageModules(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw;
+}