autosnippet 3.3.5 → 3.3.6

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;
+}