@gong-ym/ai-spec-auto 0.2.3

package/src/asset/asset-fork.js

@@ -0,0 +1,300 @@
+/**
+ * AssetFork — 资产 Fork/Override/继承管理
+ *
+ * 支持企业级资产的 Fork（团队/项目级别）、项目级 Override、
+ * 继承树构建、冲突检测和上游合并。
+ * 支持 NDJSON 持久化 Fork 记录。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createAssetRegistry, AssetRegistry } = require('./asset-registry');
+
+// ============================================================
+// AssetFork 类
+// ============================================================
+
+class AssetFork {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.storageDir] - NDJSON 持久化目录
+   */
+  constructor(options = {}) {
+    const storageDir = options.storageDir || null;
+
+    /** @type {AssetRegistry} */
+    this.registry = createAssetRegistry({
+      storagePath: storageDir ? path.join(storageDir, 'fork-registry.ndjson') : undefined,
+    });
+
+    /** @type {Map<string, object>} forkKey(assetId:projectId) → ForkRecord */
+    this._forks = new Map();
+
+    /** @type {Array<{line: number, raw: string, error: string}>} */
+    this.loadErrors = [];
+
+    /** @type {string|null} */
+    this._storagePath = storageDir ? path.join(storageDir, 'forks.ndjson') : null;
+
+    if (this._storagePath) {
+      this._loadFromFile();
+    }
+  }
+
+  // ============================================================
+  // NDJSON 持久化
+  // ============================================================
+
+  _loadFromFile() {
+    if (!this._storagePath) return;
+
+    try {
+      if (!fs.existsSync(this._storagePath)) return;
+    } catch {
+      return;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(this._storagePath, 'utf-8');
+    } catch {
+      return;
+    }
+
+    if (!content || !content.trim()) return;
+
+    const lines = content.split('\n');
+    this._forks.clear();
+
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim();
+      if (!trimmed) continue;
+      try {
+        const entry = JSON.parse(trimmed);
+        if (entry.assetId && entry.projectId) {
+          const key = this._key(entry.assetId, entry.projectId);
+          this._forks.set(key, entry);
+        }
+      } catch (err) {
+        this.loadErrors.push({ line: i + 1, raw: trimmed, error: err.message });
+      }
+    }
+  }
+
+  _appendToFile(entry) {
+    if (!this._storagePath) return;
+
+    const dir = path.dirname(this._storagePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.appendFileSync(this._storagePath, JSON.stringify(entry) + '\n', 'utf-8');
+  }
+
+  _key(assetId, projectId) {
+    return `${assetId}:${projectId}`;
+  }
+
+  /**
+   * 获取加载坏行错误列表
+   * @returns {Array<{line: number, raw: string, error: string}>}
+   */
+  getLoadErrors() {
+    return [...this.loadErrors];
+  }
+
+  // ============================================================
+  // forkAsset — Fork 资产
+  // ============================================================
+
+  /**
+   * Fork 资产到目标项目/团队
+   * @param {string} assetId
+   * @param {string} projectId
+   * @param {object} [options]
+   * @param {string} [options.forkType] - fork 类型：enterprise/team/project
+   * @param {string} [options.parentId] - 父 Fork ID
+   * @param {string} [options.upstreamVersion] - Fork 时的上游版本
+   * @returns {object} Fork 记录
+   */
+  forkAsset(assetId, projectId, options = {}) {
+    const asset = this.registry.get(assetId);
+    if (!asset) {
+      throw new Error(`资产不存在: ${assetId}`);
+    }
+
+    const key = this._key(assetId, projectId);
+    if (this._forks.has(key)) {
+      throw new Error(`已 Fork: ${assetId} → ${projectId}`);
+    }
+
+    const now = new Date().toISOString();
+    const record = {
+      forkId: `fork-${assetId}-${projectId}-${Date.now()}`,
+      assetId,
+      projectId,
+      parentId: options.parentId || null,
+      forkType: options.forkType || 'project',
+      overrides: {},
+      forkedAt: now,
+      upstreamVersion: options.upstreamVersion || asset.currentVersion,
+    };
+
+    this._forks.set(key, record);
+    this._appendToFile(record);
+
+    return { ...record, overrides: { ...record.overrides } };
+  }
+
+  // ============================================================
+  // override — 项目级 Override
+  // ============================================================
+
+  /**
+   * 设置项目级 Override
+   * @param {string} assetId
+   * @param {string} projectId
+   * @param {object} overrides
+   * @returns {object} 更新后的 Fork 记录
+   */
+  override(assetId, projectId, overrides) {
+    const key = this._key(assetId, projectId);
+    const existing = this._forks.get(key);
+    if (!existing) {
+      throw new Error(`未找到 Fork 记录: ${assetId} → ${projectId}`);
+    }
+
+    const updated = {
+      ...existing,
+      overrides: { ...existing.overrides, ...overrides },
+    };
+
+    this._forks.set(key, updated);
+    this._appendToFile(updated);
+
+    return { ...updated, overrides: { ...updated.overrides } };
+  }
+
+  // ============================================================
+  // getInheritanceTree — 继承树
+  // ============================================================
+
+  /**
+   * 获取资产的继承树
+   * @param {string} assetId
+   * @returns {object[]}
+   */
+  getInheritanceTree(assetId) {
+    const result = [];
+    for (const record of this._forks.values()) {
+      if (record.assetId === assetId) {
+        result.push({ ...record, overrides: { ...record.overrides } });
+      }
+    }
+    return result;
+  }
+
+  // ============================================================
+  // getForkRecord — 获取 Fork 记录
+  // ============================================================
+
+  /**
+   * 获取 Fork 记录
+   * @param {string} assetId
+   * @param {string} projectId
+   * @returns {object|null}
+   */
+  getForkRecord(assetId, projectId) {
+    const key = this._key(assetId, projectId);
+    const record = this._forks.get(key);
+    if (!record) return null;
+    return { ...record, overrides: { ...record.overrides } };
+  }
+
+  // ============================================================
+  // detectConflicts — 冲突检测
+  // ============================================================
+
+  /**
+   * 检测继承冲突
+   * @param {string} assetId
+   * @param {string} projectId
+   * @returns {{ hasConflict: boolean, conflicts: object[] }}
+   */
+  detectConflicts(assetId, projectId) {
+    const key = this._key(assetId, projectId);
+    const record = this._forks.get(key);
+    if (!record) {
+      return { hasConflict: false, conflicts: [] };
+    }
+
+    const asset = this.registry.get(assetId);
+    const conflicts = [];
+
+    // 版本漂移检测
+    if (asset && record.upstreamVersion !== asset.currentVersion) {
+      conflicts.push({
+        type: 'version_drift',
+        message: `上游版本已从 ${record.upstreamVersion} 更新到 ${asset.currentVersion}`,
+        forkVersion: record.upstreamVersion,
+        currentVersion: asset.currentVersion,
+      });
+    }
+
+    return {
+      hasConflict: conflicts.length > 0,
+      conflicts,
+    };
+  }
+
+  // ============================================================
+  // mergeUpstream — 合并上游
+  // ============================================================
+
+  /**
+   * 合并上游更新
+   * @param {string} assetId
+   * @param {string} projectId
+   * @returns {object} 更新后的 Fork 记录
+   */
+  mergeUpstream(assetId, projectId) {
+    const key = this._key(assetId, projectId);
+    const existing = this._forks.get(key);
+    if (!existing) {
+      throw new Error(`未找到 Fork 记录: ${assetId} → ${projectId}`);
+    }
+
+    const asset = this.registry.get(assetId);
+    if (!asset) {
+      throw new Error(`资产不存在: ${assetId}`);
+    }
+
+    const updated = {
+      ...existing,
+      upstreamVersion: asset.currentVersion,
+    };
+
+    this._forks.set(key, updated);
+    this._appendToFile(updated);
+
+    return { ...updated, overrides: { ...updated.overrides } };
+  }
+}
+
+// ============================================================
+// 工厂函数
+// ============================================================
+
+/**
+ * 创建资产 Fork 管理器
+ * @param {object} [options]
+ * @returns {AssetFork}
+ */
+function createAssetFork(options) {
+  return new AssetFork(options);
+}
+
+module.exports = {
+  createAssetFork,
+  AssetFork,
+};

package/src/asset/asset-install.js

@@ -0,0 +1,278 @@
+/**
+ * AssetInstall — 资产安装记录模型
+ *
+ * 管理资产安装记录的创建、查询和状态更新，
+ * 支持 NDJSON 文件持久化。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { redactObject } = require('../governance/audit-log');
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** 安装状态枚举 */
+const INSTALL_STATUSES = Object.freeze({
+  INSTALLED: 'installed',
+  FAILED: 'failed',
+  ROLLED_BACK: 'rolled_back',
+  UPGRADED: 'upgraded',
+});
+
+/** 合法状态值 */
+const VALID_INSTALL_STATUSES = new Set(Object.values(INSTALL_STATUSES));
+
+// ============================================================
+// 校验
+// ============================================================
+
+const REQUIRED_FIELDS = ['assetId', 'version', 'projectId'];
+
+function validateInstallSpec(spec) {
+  const errors = [];
+  for (const field of REQUIRED_FIELDS) {
+    if (!spec[field] || typeof spec[field] !== 'string') {
+      errors.push(`${field} 必须为非空字符串`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// ============================================================
+// AssetInstall 类
+// ============================================================
+
+class AssetInstall {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.storagePath] - NDJSON 持久化路径
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, object>} installId -> record */
+    this._records = new Map();
+    /** @type {number} */
+    this._nextId = 1;
+    /** @type {string|null} */
+    this.storagePath = options.storagePath || null;
+    /** @type {object[]} */
+    this.loadErrors = [];
+
+    if (this.storagePath) {
+      this._loadFromFile();
+    }
+  }
+
+  // ============================================================
+  // NDJSON 持久化
+  // ============================================================
+
+  _loadFromFile() {
+    if (!this.storagePath) return;
+
+    try {
+      if (!fs.existsSync(this.storagePath)) return;
+    } catch {
+      return;
+    }
+
+    let content;
+    try {
+      content = fs.readFileSync(this.storagePath, 'utf-8');
+    } catch {
+      return;
+    }
+
+    if (!content || !content.trim()) return;
+
+    const lines = content.split('\n');
+    this._records.clear();
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      try {
+        const entry = JSON.parse(line);
+        if (entry.installId) {
+          this._records.set(entry.installId, entry);
+
+          // 恢复 ID 编号
+          const match = String(entry.installId).match(/^inst-(\d+)$/);
+          if (match) {
+            const num = parseInt(match[1], 10);
+            if (num >= this._nextId) {
+              this._nextId = num + 1;
+            }
+          }
+        }
+      } catch (err) {
+        this.loadErrors.push({
+          lineNumber: i + 1,
+          line: line.substring(0, 200),
+          message: err.message || 'JSON 解析失败',
+        });
+      }
+    }
+  }
+
+  _appendToFile(entry) {
+    if (!this.storagePath) return;
+
+    const dir = path.dirname(this.storagePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    const line = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(this.storagePath, line, 'utf-8');
+  }
+
+  // ============================================================
+  // record — 记录安装
+  // ============================================================
+
+  /**
+   * 记录一次安装
+   * @param {object} spec
+   * @returns {object} 安装记录
+   */
+  record(spec) {
+    const validation = validateInstallSpec(spec);
+    if (!validation.ok) {
+      throw new Error(`安装记录校验失败: ${validation.errors.join('; ')}`);
+    }
+
+    const record = {
+      installId: `inst-${this._nextId++}`,
+      assetId: spec.assetId,
+      version: spec.version,
+      projectId: spec.projectId,
+      status: spec.status || 'installed',
+      installedAt: new Date().toISOString(),
+      installedFiles: Array.isArray(spec.installedFiles) ? [...spec.installedFiles] : [],
+      checksum: spec.checksum || '',
+      metadata: redactObject(spec.metadata || {}),
+    };
+
+    this._records.set(record.installId, record);
+    this._appendToFile(record);
+
+    return { ...record, installedFiles: [...record.installedFiles], metadata: { ...record.metadata } };
+  }
+
+  // ============================================================
+  // get — 获取安装记录
+  // ============================================================
+
+  /**
+   * 获取安装记录
+   * @param {string} installId
+   * @returns {object|null}
+   */
+  get(installId) {
+    const record = this._records.get(installId);
+    if (!record) return null;
+    return { ...record, installedFiles: [...record.installedFiles], metadata: { ...record.metadata } };
+  }
+
+  // ============================================================
+  // list — 查询
+  // ============================================================
+
+  /**
+   * 查询安装记录
+   * @param {object} [filters]
+   * @param {string} [filters.assetId]
+   * @param {string} [filters.projectId]
+   * @param {string} [filters.status]
+   * @returns {object[]}
+   */
+  list(filters = {}) {
+    let results = [...this._records.values()];
+
+    if (filters.assetId) {
+      results = results.filter(r => r.assetId === filters.assetId);
+    }
+    if (filters.projectId) {
+      results = results.filter(r => r.projectId === filters.projectId);
+    }
+    if (filters.status) {
+      results = results.filter(r => r.status === filters.status);
+    }
+
+    return results.map(r => ({ ...r, installedFiles: [...r.installedFiles], metadata: { ...r.metadata } }));
+  }
+
+  // ============================================================
+  // updateStatus — 更新安装状态
+  // ============================================================
+
+  /**
+   * 更新安装状态
+   * @param {string} installId
+   * @param {string} status
+   * @returns {object} 更新后的记录
+   */
+  updateStatus(installId, status) {
+    if (!VALID_INSTALL_STATUSES.has(status)) {
+      throw new Error(`无效的安装状态: ${status}，必须是 ${[...VALID_INSTALL_STATUSES].join('/')} 之一`);
+    }
+
+    const existing = this._records.get(installId);
+    if (!existing) {
+      throw new Error(`安装记录不存在: ${installId}`);
+    }
+
+    const updated = { ...existing, status };
+    this._records.set(installId, updated);
+    this._appendToFile(updated);
+
+    return { ...updated, installedFiles: [...updated.installedFiles], metadata: { ...updated.metadata } };
+  }
+
+  // ============================================================
+  // getInstalledAssets — 获取项目已安装资产
+  // ============================================================
+
+  /**
+   * 获取项目已安装的资产列表
+   * @param {string} projectId
+   * @returns {object[]}
+   */
+  getInstalledAssets(projectId) {
+    return [...this._records.values()]
+      .filter(r => r.projectId === projectId && r.status === 'installed')
+      .map(r => ({ ...r, installedFiles: [...r.installedFiles], metadata: { ...r.metadata } }));
+  }
+
+  // ============================================================
+  // getLoadErrors
+  // ============================================================
+
+  /** @returns {object[]} */
+  getLoadErrors() {
+    return this.loadErrors.map(e => ({ ...e }));
+  }
+}
+
+// ============================================================
+// 工厂函数
+// ============================================================
+
+/**
+ * 创建资产安装记录管理器
+ * @param {object} [options]
+ * @returns {AssetInstall}
+ */
+function createAssetInstall(options) {
+  return new AssetInstall(options);
+}
+
+module.exports = {
+  INSTALL_STATUSES,
+  VALID_INSTALL_STATUSES,
+  createAssetInstall,
+  AssetInstall,
+};