autosnippet 2.8.3 → 2.10.0

package/lib/domain/knowledge/KnowledgeRepository.js

@@ -0,0 +1,123 @@
+/**
+ * KnowledgeRepository — 统一知识实体仓储接口
+ *
+ * 替代 CandidateRepository + RecipeRepository。
+ * 实现类见 lib/repository/knowledge/KnowledgeRepository.impl.js
+ */
+export class KnowledgeRepository {
+
+  /**
+   * 创建 KnowledgeEntry
+   * @param {import('./KnowledgeEntry.js').KnowledgeEntry} entry
+   * @returns {Promise<import('./KnowledgeEntry.js').KnowledgeEntry>}
+   */
+  async create(entry) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 根据 ID 获取
+   * @param {string} id
+   * @returns {Promise<import('./KnowledgeEntry.js').KnowledgeEntry|null>}
+   */
+  async findById(id) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 分页查询
+   * @param {Object} filters - { lifecycle, kind, language, category, knowledge_type, source }
+   * @param {Object} options - { page, pageSize, orderBy, order }
+   * @returns {Promise<{ data: KnowledgeEntry[], pagination: Object }>}
+   */
+  async findWithPagination(filters = {}, options = {}) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 根据生命周期状态查询
+   * @param {string} lifecycle
+   * @param {Object} pagination
+   * @returns {Promise<{ data: KnowledgeEntry[], pagination: Object }>}
+   */
+  async findByLifecycle(lifecycle, pagination = {}) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 根据 kind 查询
+   * @param {string} kind - 'rule' | 'pattern' | 'fact'
+   * @param {Object} options - { page, pageSize, lifecycle }
+   * @returns {Promise<{ data: KnowledgeEntry[], pagination: Object }>}
+   */
+  async findByKind(kind, options = {}) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 查询所有 active 的 rule 类型（Guard 消费热路径）
+   * @returns {Promise<KnowledgeEntry[]>}
+   */
+  async findActiveRules() {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 根据语言查询
+   * @param {string} language
+   * @param {Object} pagination
+   * @returns {Promise<{ data: KnowledgeEntry[], pagination: Object }>}
+   */
+  async findByLanguage(language, pagination = {}) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 根据分类查询
+   * @param {string} category
+   * @param {Object} pagination
+   * @returns {Promise<{ data: KnowledgeEntry[], pagination: Object }>}
+   */
+  async findByCategory(category, pagination = {}) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 搜索 (标题/内容/触发词/标签)
+   * @param {string} keyword
+   * @param {Object} pagination
+   * @returns {Promise<{ data: KnowledgeEntry[], pagination: Object }>}
+   */
+  async search(keyword, pagination = {}) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 更新
+   * @param {string} id
+   * @param {Object} updates - wire format 的部分字段
+   * @returns {Promise<import('./KnowledgeEntry.js').KnowledgeEntry>}
+   */
+  async update(id, updates) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 删除
+   * @param {string} id
+   * @returns {Promise<boolean>}
+   */
+  async delete(id) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * 获取统计信息
+   * @returns {Promise<Object>}
+   */
+  async getStats() {
+    throw new Error('Not implemented');
+  }
+}
+
+export default KnowledgeRepository;

package/lib/domain/knowledge/Lifecycle.js

@@ -0,0 +1,109 @@
+/**
+ * Lifecycle — 知识实体生命周期状态机（3 状态简化版）
+ *
+ * pending    — 待审核（所有新条目初始状态）
+ * active     — 已发布（可被搜索/Guard/Export 消费）
+ * deprecated — 已废弃
+ *
+ * 仅开发者可执行 pending → active（发布）。
+ */
+
+export const Lifecycle = {
+  /** 待审核 */
+  PENDING:       'pending',
+  /** 已发布（可被搜索/Guard/Export 消费） */
+  ACTIVE:        'active',
+  /** 已弃用 */
+  DEPRECATED:    'deprecated',
+};
+
+// ── 向后兼容别名（旧数据中仍存在这些值） ──
+export const LEGACY_LIFECYCLE_MAP = {
+  draft:         Lifecycle.PENDING,
+  approved:      Lifecycle.PENDING,
+  auto_approved: Lifecycle.PENDING,
+  rejected:      Lifecycle.DEPRECATED,
+};
+
+/** 候选阶段的所有状态 */
+export const CANDIDATE_STATES = [
+  Lifecycle.PENDING,
+];
+
+/** 合法状态转移表 */
+const VALID_TRANSITIONS = {
+  [Lifecycle.PENDING]:    [Lifecycle.ACTIVE, Lifecycle.DEPRECATED],
+  [Lifecycle.ACTIVE]:     [Lifecycle.DEPRECATED],
+  [Lifecycle.DEPRECATED]: [Lifecycle.PENDING],
+};
+
+/**
+ * 规范化生命周期值（兼容旧数据）
+ * @param {string} lifecycle
+ * @returns {string}
+ */
+export function normalizeLifecycle(lifecycle) {
+  if (Object.values(Lifecycle).includes(lifecycle)) return lifecycle;
+  return LEGACY_LIFECYCLE_MAP[lifecycle] || Lifecycle.PENDING;
+}
+
+/**
+ * 检查状态转移是否合法
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isValidTransition(from, to) {
+  const normalFrom = normalizeLifecycle(from);
+  const normalTo = normalizeLifecycle(to);
+  const allowed = VALID_TRANSITIONS[normalFrom];
+  return Array.isArray(allowed) && allowed.includes(normalTo);
+}
+
+/**
+ * 是否为合法的生命周期值（含旧值兼容）
+ * @param {string} lifecycle
+ * @returns {boolean}
+ */
+export function isValidLifecycle(lifecycle) {
+  return Object.values(Lifecycle).includes(lifecycle) || lifecycle in LEGACY_LIFECYCLE_MAP;
+}
+
+/**
+ * 是否处于候选阶段（待审核）
+ * @param {string} lifecycle
+ * @returns {boolean}
+ */
+export function isCandidate(lifecycle) {
+  const normalized = normalizeLifecycle(lifecycle);
+  return normalized === Lifecycle.PENDING;
+}
+
+/* ── knowledgeType → kind 映射 ── */
+
+const KIND_MAP = {
+  'code-standard':       'rule',
+  'code-style':          'rule',
+  'best-practice':       'rule',
+  'boundary-constraint': 'rule',
+  'code-pattern':        'pattern',
+  'architecture':        'pattern',
+  'solution':            'pattern',
+  'anti-pattern':        'pattern',
+  'code-relation':       'fact',
+  'inheritance':         'fact',
+  'call-chain':          'fact',
+  'data-flow':           'fact',
+  'module-dependency':   'fact',
+};
+
+/**
+ * 从 knowledgeType 推导 kind
+ * @param {string} knowledgeType
+ * @returns {'rule'|'pattern'|'fact'}
+ */
+export function inferKind(knowledgeType) {
+  return KIND_MAP[knowledgeType] || 'pattern';
+}
+
+export default Lifecycle;

package/lib/domain/knowledge/index.js

@@ -0,0 +1,27 @@
+/**
+ * KnowledgeEntry 领域层统一导出
+ */
+
+// 实体
+export { KnowledgeEntry } from './KnowledgeEntry.js';
+
+// 生命周期
+export {
+  Lifecycle,
+  isValidTransition,
+  isValidLifecycle,
+  isCandidate,
+  CANDIDATE_STATES,
+  inferKind,
+} from './Lifecycle.js';
+
+// 值对象
+export { Content } from './values/Content.js';
+export { Relations, RELATION_BUCKETS } from './values/Relations.js';
+export { Constraints } from './values/Constraints.js';
+export { Reasoning } from './values/Reasoning.js';
+export { Quality } from './values/Quality.js';
+export { Stats } from './values/Stats.js';
+
+// Repository 接口
+export { KnowledgeRepository } from './KnowledgeRepository.js';

package/lib/domain/knowledge/values/Constraints.js

@@ -0,0 +1,125 @@
+/**
+ * Constraints — 约束值对象
+ *
+ * 包含 Guard 规则 (regex + ast)、边界约束、前置条件、副作用。
+ * Guard 规则预留 AST 类型，为语义规则做前瞻设计。
+ */
+export class Constraints {
+  constructor(props = {}) {
+    /** @type {Array<Guard>} Guard 规则列表 */
+    this.guards        = (props.guards || []).map(Constraints._normalizeGuard);
+    /** @type {string[]} 边界约束 */
+    this.boundaries    = props.boundaries    || [];
+    /** @type {string[]} 前置条件 */
+    this.preconditions = props.preconditions || [];
+    /** @type {string[]} 副作用 */
+    this.sideEffects   = props.side_effects  ?? props.sideEffects ?? [];
+  }
+
+  /**
+   * 从任意输入构造 Constraints
+   * @param {Constraints|Object|null} input
+   * @returns {Constraints}
+   */
+  static from(input) {
+    if (input instanceof Constraints) return input;
+    if (!input) return new Constraints();
+    return new Constraints(input);
+  }
+
+  /**
+   * 标准化 Guard 对象
+   * @param {Object} g
+   * @returns {Guard}
+   */
+  static _normalizeGuard(g) {
+    return {
+      id:             g.id             || null,
+      type:           g.type           || (g.ast_query ? 'ast' : 'regex'),
+      pattern:        g.pattern        || null,
+      ast_query:      g.ast_query      || null,
+      message:        g.message        || '',
+      severity:       g.severity       || 'warning',
+      fix_suggestion: g.fix_suggestion || null,
+    };
+  }
+
+  /**
+   * 获取 regex 类型的 Guard 规则
+   * @returns {Array<Guard>}
+   */
+  getRegexGuards() {
+    return this.guards.filter(g => g.type === 'regex' && g.pattern);
+  }
+
+  /**
+   * 获取 ast 类型的 Guard 规则
+   * @returns {Array<Guard>}
+   */
+  getAstGuards() {
+    return this.guards.filter(g => g.type === 'ast' && g.ast_query);
+  }
+
+  /**
+   * 添加 Guard 规则
+   * @param {Object} guard
+   * @returns {Constraints}
+   */
+  addGuard(guard) {
+    this.guards.push(Constraints._normalizeGuard(guard));
+    return this;
+  }
+
+  /**
+   * 是否有 Guard 规则
+   * @returns {boolean}
+   */
+  hasGuards() {
+    return this.guards.length > 0;
+  }
+
+  /**
+   * 是否为空
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.guards.length === 0 &&
+           this.boundaries.length === 0 &&
+           this.preconditions.length === 0 &&
+           this.sideEffects.length === 0;
+  }
+
+  /**
+   * 转换为 wire format JSON
+   */
+  toJSON() {
+    return {
+      guards:        this.guards,
+      boundaries:    this.boundaries,
+      preconditions: this.preconditions,
+      side_effects:  this.sideEffects,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Constraints}
+   */
+  static fromJSON(data) {
+    return Constraints.from(data);
+  }
+}
+
+/**
+ * @typedef {Object} Guard
+ * @property {?string} id          - Guard 唯一标识
+ * @property {'regex'|'ast'} type  - 类型
+ * @property {?string} pattern     - regex pattern (type=regex 时)
+ * @property {?Object} ast_query   - AST 查询 (type=ast 时)
+ * @property {string}  message     - 错误/警告消息
+ * @property {'error'|'warning'|'info'} severity - 严重级别
+ * @property {?string} fix_suggestion - 关联修复 Recipe 的 trigger
+ */
+
+export default Constraints;

package/lib/domain/knowledge/values/Content.js

@@ -0,0 +1,86 @@
+/**
+ * Content — 内容值对象
+ *
+ * 统一承载代码片段 (pattern) 或 Markdown 全文 (markdown)，
+ * 以及设计原理、实施步骤、代码变更、验证方式。
+ */
+export class Content {
+  constructor(props = {}) {
+    /** @type {string} 代码片段 */
+    this.pattern      = props.pattern      ?? '';
+    /** @type {string} Markdown 全文（与 pattern 二选一） */
+    this.markdown     = props.markdown     ?? '';
+    /** @type {string} 设计原理 */
+    this.rationale    = props.rationale    ?? '';
+    /** @type {Array<{title?:string, description?:string, code?:string}>} 实施步骤 */
+    this.steps        = props.steps        ?? [];
+    /** @type {Array<{file:string, before:string, after:string, explanation:string}>} 代码变更 */
+    this.codeChanges  = props.code_changes ?? props.codeChanges ?? [];
+    /** @type {?{method?:string, expected_result?:string, test_code?:string}} 验证方式 */
+    this.verification = props.verification ?? null;
+  }
+
+  /**
+   * 从任意输入构造 Content
+   * @param {Content|Object|null} input
+   * @returns {Content}
+   */
+  static from(input) {
+    if (input instanceof Content) return input;
+    if (!input) return new Content();
+    return new Content(input);
+  }
+
+  /**
+   * 从旧 Candidate 的 code + metadata 构建
+   * @param {string} code
+   * @param {Object} meta
+   * @returns {Content}
+   */
+  static fromLegacyCandidate(code, meta = {}) {
+    const isMarkdown = code && (
+      code.includes('— 项目特写') || /^#{1,3}\s/.test(code.trimStart())
+    );
+    return new Content({
+      pattern:      isMarkdown ? '' : (code || ''),
+      markdown:     isMarkdown ? code : '',
+      rationale:    meta.rationale || '',
+      steps:        meta.steps || [],
+      code_changes: meta.codeChanges || meta.code_changes || [],
+      verification: meta.verification || null,
+    });
+  }
+
+  /**
+   * 是否包含有效内容
+   * @returns {boolean}
+   */
+  hasContent() {
+    return !!(this.pattern || this.markdown || this.rationale || this.steps.length > 0);
+  }
+
+  /**
+   * 转换为 wire format JSON
+   */
+  toJSON() {
+    return {
+      pattern:      this.pattern,
+      markdown:     this.markdown,
+      rationale:    this.rationale,
+      steps:        this.steps,
+      code_changes: this.codeChanges,
+      verification: this.verification,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Content}
+   */
+  static fromJSON(data) {
+    return new Content(data);
+  }
+}
+
+export default Content;

package/lib/domain/knowledge/values/Quality.js

@@ -0,0 +1,93 @@
+/**
+ * Quality — 质量值对象
+ *
+ * 4 维度评分 + 综合分 + 等级。
+ */
+export class Quality {
+  constructor(props = {}) {
+    /** @type {number} 内容完整度 (0-1) */
+    this.completeness   = props.completeness   ?? 0;
+    /** @type {number} 项目适配度 (0-1) */
+    this.adaptation     = props.adaptation     ?? 0;
+    /** @type {number} 文档清晰度 (0-1) */
+    this.documentation  = props.documentation  ?? 0;
+    /** @type {number} 综合分 (0-1) */
+    this.overall        = props.overall        ?? 0;
+    /** @type {string} 等级 A-F */
+    this.grade          = props.grade          || Quality.calcGrade(this.overall);
+  }
+
+  /**
+   * 从任意输入构造 Quality
+   * @param {Quality|Object|null} input
+   * @returns {Quality}
+   */
+  static from(input) {
+    if (input instanceof Quality) return input;
+    return new Quality(input || {});
+  }
+
+  /**
+   * 从旧 Recipe quality 字段映射
+   * @param {Object} old { codeCompleteness, projectAdaptation, documentationClarity, overall }
+   * @returns {Quality}
+   */
+  static fromLegacyRecipe(old) {
+    if (!old) return new Quality();
+    return new Quality({
+      completeness:  old.codeCompleteness      ?? old.completeness  ?? 0,
+      adaptation:    old.projectAdaptation      ?? old.adaptation    ?? 0,
+      documentation: old.documentationClarity   ?? old.documentation ?? 0,
+      overall:       old.overall                ?? 0,
+    });
+  }
+
+  /**
+   * 从 3 维度计算综合分
+   * @returns {Quality}
+   */
+  recalculate() {
+    this.overall = Math.round(
+      ((this.completeness + this.adaptation + this.documentation) / 3) * 100
+    ) / 100;
+    this.grade = Quality.calcGrade(this.overall);
+    return this;
+  }
+
+  /**
+   * 根据分数计算等级
+   * @param {number} score 0-1
+   * @returns {string}
+   */
+  static calcGrade(score) {
+    if (score >= 0.9) return 'A';
+    if (score >= 0.75) return 'B';
+    if (score >= 0.6) return 'C';
+    if (score >= 0.4) return 'D';
+    return 'F';
+  }
+
+  /**
+   * 转换为 wire format JSON
+   */
+  toJSON() {
+    return {
+      completeness:  this.completeness,
+      adaptation:    this.adaptation,
+      documentation: this.documentation,
+      overall:       this.overall,
+      grade:         this.grade,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Quality}
+   */
+  static fromJSON(data) {
+    return Quality.from(data);
+  }
+}
+
+export default Quality;

package/lib/domain/knowledge/values/Reasoning.js

@@ -0,0 +1,69 @@
+/**
+ * Reasoning — 推理值对象（V3 统一版）
+ *
+ * 与旧 Candidate.Reasoning 逻辑一致，但 wire format 统一为 snake_case。
+ */
+export class Reasoning {
+  constructor(props = {}) {
+    /** @type {string} 为什么遵循标准 */
+    this.whyStandard    = props.why_standard    ?? props.whyStandard ?? '';
+    /** @type {string[]} 来源列表 */
+    this.sources        = props.sources         || [];
+    /** @type {number} 置信度 0-1 */
+    this.confidence     = props.confidence      ?? 0.7;
+    /** @type {Object.<string, number>} 质量信号 */
+    this.qualitySignals = props.quality_signals  ?? props.qualitySignals ?? {};
+    /** @type {string[]} 备选方案 */
+    this.alternatives   = props.alternatives    || [];
+  }
+
+  /**
+   * 从任意输入构造 Reasoning
+   * @param {Reasoning|Object|null} input
+   * @returns {Reasoning}
+   */
+  static from(input) {
+    if (input instanceof Reasoning) return input;
+    if (!input) return new Reasoning();
+    return new Reasoning(input);
+  }
+
+  /**
+   * 验证推理信息的完整性
+   * @returns {boolean}
+   */
+  isValid() {
+    return !!(
+      this.whyStandard?.trim() &&
+      Array.isArray(this.sources) &&
+      this.sources.length > 0 &&
+      typeof this.confidence === 'number' &&
+      this.confidence >= 0 &&
+      this.confidence <= 1
+    );
+  }
+
+  /**
+   * 转换为 wire format JSON (snake_case)
+   */
+  toJSON() {
+    return {
+      why_standard:    this.whyStandard,
+      sources:         this.sources,
+      confidence:      this.confidence,
+      quality_signals: this.qualitySignals,
+      alternatives:    this.alternatives,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Reasoning}
+   */
+  static fromJSON(data) {
+    return new Reasoning(data);
+  }
+}
+
+export default Reasoning;