autosnippet 2.9.0 → 2.11.0

package/lib/domain/knowledge/Lifecycle.js

@@ -0,0 +1,99 @@
+/**
+ * Lifecycle — 知识实体生命周期状态机（3 状态简化版）
+ *
+ * pending    — 待审核（所有新条目初始状态）
+ * active     — 已发布（可被搜索/Guard/Export 消费）
+ * deprecated — 已废弃
+ */
+
+export const Lifecycle = {
+  /** 待审核 */
+  PENDING:       'pending',
+  /** 已发布（可被搜索/Guard/Export 消费） */
+  ACTIVE:        'active',
+  /** 已弃用 */
+  DEPRECATED:    '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 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);
+}
+
+/**
+ * 是否处于候选阶段（待审核）
+ * @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,128 @@
+/**
+ * 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.sideEffects ?? [];
+  }
+
+  /**
+   * 从任意输入构造 Constraints
+   * @param {Constraints|Object|null} input
+   * @returns {Constraints}
+   */
+  static from(input) {
+    if (input instanceof Constraints) return input;
+    if (!input) return new Constraints();
+    if (typeof input === 'string') {
+      try { input = JSON.parse(input); } catch { 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,
+      sideEffects:   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,69 @@
+/**
+ * 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.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();
+    if (typeof input === 'string') {
+      try { input = JSON.parse(input); } catch { return new Content(); }
+    }
+    return new Content(input);
+  }
+
+  /**
+   * 是否包含有效内容
+   * @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,
+      codeChanges:  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,81 @@
+/**
+ * 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;
+    if (typeof input === 'string') {
+      try { input = JSON.parse(input); } catch { return new Quality(); }
+    }
+    return new Quality(input || {});
+  }
+
+  /**
+   * 从 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,70 @@
+/**
+ * Reasoning — 推理值对象
+ */
+export class Reasoning {
+  constructor(props = {}) {
+    /** @type {string} 为什么遵循标准 */
+    this.whyStandard    = 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.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();
+    if (typeof input === 'string') {
+      try { input = JSON.parse(input); } catch { 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
+    );
+  }
+
+  /**
+   * 转换为 JSON
+   */
+  toJSON() {
+    return {
+      whyStandard:    this.whyStandard,
+      sources:         this.sources,
+      confidence:      this.confidence,
+      qualitySignals:  this.qualitySignals,
+      alternatives:    this.alternatives,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Reasoning}
+   */
+  static fromJSON(data) {
+    return new Reasoning(data);
+  }
+}
+
+export default Reasoning;

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

@@ -0,0 +1,142 @@
+/**
+ * Relations — 关系图值对象
+ *
+ * 统一为分桶结构（非扁平数组）。
+ * 每个桶存储 [{ target, description }] 格式的关系列表。
+ */
+
+/** 所有合法的关系桶名 (snake_case) */
+export const RELATION_BUCKETS = [
+  'inherits',       // 继承
+  'implements',     // 实现接口/协议
+  'calls',          // 调用
+  'depends_on',     // 依赖
+  'data_flow',      // 数据流向
+  'conflicts',      // 冲突
+  'extends',        // 扩展
+  'related',        // 弱关联
+  'alternative',    // 替代方案
+  'prerequisite',   // 前置条件
+  'deprecated_by',  // 被取代
+  'solves',         // 解决问题
+  'enforces',       // 强制约束
+  'references',     // 引用
+];
+
+export class Relations {
+  constructor(buckets = {}) {
+    /** @type {Object.<string, Array<{target:string, description:string}>>} */
+    this._b = {};
+    for (const k of RELATION_BUCKETS) {
+      const vals = buckets[k] || [];
+      this._b[k] = vals.map(r => ({
+        target:      r.target || '',
+        description: r.description || '',
+      }));
+    }
+  }
+
+  /**
+   * 从任意输入构造 Relations
+   * @param {Relations|Array|Object|null} input
+   * @returns {Relations}
+   */
+  static from(input) {
+    if (input instanceof Relations) return input;
+    if (!input) return new Relations();
+    if (typeof input === 'string') {
+      try { input = JSON.parse(input); } catch { return new Relations(); }
+    }
+    if (Array.isArray(input)) {
+      // 扁平数组 → 自动分桶
+      const buckets = {};
+      for (const rel of input) {
+        const bucket = rel.type || 'related';
+        if (!buckets[bucket]) buckets[bucket] = [];
+        buckets[bucket].push({
+          target:      rel.target || '',
+          description: rel.description || '',
+        });
+      }
+      return new Relations(buckets);
+    }
+    return new Relations(input);
+  }
+
+  /**
+   * 扁平视图（仅 Dashboard 渲染用）
+   * @returns {Array<{type:string, target:string, description:string}>}
+   */
+  toFlatArray() {
+    const result = [];
+    for (const [type, list] of Object.entries(this._b)) {
+      for (const r of list) {
+        result.push({ type, ...r });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 获取指定桶
+   * @param {string} type
+   * @returns {Array<{target:string, description:string}>}
+   */
+  getByType(type) {
+    return this._b[type] || [];
+  }
+
+  /**
+   * 是否为空
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return Object.values(this._b).every(l => l.length === 0);
+  }
+
+  /**
+   * 添加关系
+   * @param {string} type 桶名
+   * @param {string} target 目标
+   * @param {string} description
+   * @returns {Relations}
+   */
+  add(type, target, description = '') {
+    if (!this._b[type]) this._b[type] = [];
+    if (!this._b[type].some(r => r.target === target)) {
+      this._b[type].push({ target, description });
+    }
+    return this;
+  }
+
+  /**
+   * 移除关系
+   * @param {string} type 桶名
+   * @param {string} target 目标
+   * @returns {Relations}
+   */
+  remove(type, target) {
+    if (this._b[type]) {
+      this._b[type] = this._b[type].filter(r => r.target !== target);
+    }
+    return this;
+  }
+
+  /**
+   * 转换为 wire format JSON (分桶)
+   */
+  toJSON() {
+    return { ...this._b };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object|Array} data
+   * @returns {Relations}
+   */
+  static fromJSON(data) {
+    return Relations.from(data);
+  }
+}
+
+export default Relations;

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

@@ -0,0 +1,72 @@
+/**
+ * Stats — 统计值对象
+ *
+ * 记录知识条目的使用统计：浏览、采用、应用、Guard 命中、搜索命中、权威分。
+ */
+export class Stats {
+  constructor(props = {}) {
+    /** @type {number} 浏览次数 */
+    this.views        = props.views        ?? 0;
+    /** @type {number} 采用次数 */
+    this.adoptions    = props.adoptions    ?? 0;
+    /** @type {number} 应用次数 */
+    this.applications = props.applications ?? 0;
+    /** @type {number} Guard 命中次数 */
+    this.guardHits    = props.guardHits ?? 0;
+    /** @type {number} 搜索命中次数 */
+    this.searchHits   = props.searchHits ?? 0;
+    /** @type {number} 权威分 0-5 */
+    this.authority    = props.authority    ?? 0;
+  }
+
+  /**
+   * 从任意输入构造 Stats
+   * @param {Stats|Object|null} input
+   * @returns {Stats}
+   */
+  static from(input) {
+    if (input instanceof Stats) return input;
+    if (typeof input === 'string') {
+      try { input = JSON.parse(input); } catch { return new Stats(); }
+    }
+    return new Stats(input || {});
+  }
+
+  /**
+   * 增加计数
+   * @param {'views'|'adoptions'|'applications'|'guardHits'|'searchHits'} counter
+   * @param {number} delta
+   * @returns {Stats}
+   */
+  increment(counter, delta = 1) {
+    if (counter in this && typeof this[counter] === 'number') {
+      this[counter] += delta;
+    }
+    return this;
+  }
+
+  /**
+   * 转换为 JSON
+   */
+  toJSON() {
+    return {
+      views:        this.views,
+      adoptions:    this.adoptions,
+      applications: this.applications,
+      guardHits:    this.guardHits,
+      searchHits:   this.searchHits,
+      authority:    this.authority,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Stats}
+   */
+  static fromJSON(data) {
+    return Stats.from(data);
+  }
+}
+
+export default Stats;

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

@@ -0,0 +1,9 @@
+/**
+ * 值对象统一导出
+ */
+export { Content } from './Content.js';
+export { Relations, RELATION_BUCKETS } from './Relations.js';
+export { Constraints } from './Constraints.js';
+export { Reasoning } from './Reasoning.js';
+export { Quality } from './Quality.js';
+export { Stats } from './Stats.js';