@longzai-intelligence-issues/config 0.0.1

package/src/loader/load-issues-config.utils.ts

@@ -0,0 +1,180 @@
+/**
+ * lzi-issues 配置加载器
+ *
+ * 复用 shared-config 的 loadUnifiedConfig 统一加载：优先工具专属
+ * lzi-issues.config.ts（cwd 向上查找），回退统一配置 lzi.config.ts 的 issues
+ * 字段；命中后 zod 形态解析 + 跨条目语义校验，非法即抛（加载即失败）。
+ */
+
+import { loadUnifiedConfig } from '@longzai-intelligence-shared-config/core';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { type LziIssuesConfig, parseLziIssuesConfig } from '@/schema/lzi-issues-config.schema';
+import { validateLziIssuesConfig } from '@/validation/validate-cross-entries';
+
+/**
+ * 配置来源类型
+ */
+export type LziIssuesConfigSource = 'standalone' | 'unified' | 'explicit';
+
+/**
+ * 加载成功结果
+ */
+export type LoadLziIssuesConfigSuccess = {
+  /**
+   * 加载成功标记
+   */
+  ok: true;
+
+  /**
+   * 解析并校验后的配置（默认值全部落定）
+   */
+  config: LziIssuesConfig;
+
+  /**
+   * 命中的配置文件绝对路径
+   */
+  configFilePath: string;
+
+  /**
+   * 配置来源
+   */
+  source: LziIssuesConfigSource;
+};
+
+/**
+ * 加载失败结果（未找到配置）
+ */
+export type LoadLziIssuesConfigFailure = {
+  /**
+   * 加载成功标记
+   */
+  ok: false;
+
+  /**
+   * 失败原因
+   */
+  reason: string;
+};
+
+/**
+ * 加载结果
+ */
+export type LoadLziIssuesConfigResult = LoadLziIssuesConfigSuccess | LoadLziIssuesConfigFailure;
+
+/**
+ * 加载选项
+ */
+export type LoadLziIssuesConfigOptions = {
+  /**
+   * 查找起点目录（缺省 process.cwd()）
+   */
+  cwd?: string;
+
+  /**
+   * 显式配置文件路径（优先级最高，绕过向上查找）
+   */
+  configPath?: string;
+};
+
+/**
+ * 解析 + 校验配置对象（形态 + 跨条目，非法即抛带路径上下文）
+ *
+ * @param input - 配置原始对象
+ * @param configFilePath - 配置文件路径（错误消息附注）
+ * @returns 解析并校验后的配置
+ * @throws {@link Error} 形态或跨条目违规
+ */
+function parseAndValidate(input: unknown, configFilePath: string): LziIssuesConfig {
+  try {
+    /**
+     * 形态解析 + 跨条目校验后的配置
+     */
+    return validateLziIssuesConfig(parseLziIssuesConfig(input));
+  } catch (error) {
+    /**
+     * 原始错误消息
+     */
+    const message = error instanceof Error ? error.message : String(error);
+
+    throw new Error(`${message}（配置文件：${configFilePath}）`);
+  }
+}
+
+/**
+ * 加载 lzi-issues 配置
+ *
+ * @param options - 加载选项
+ * @returns 加载结果：命中返回解析后配置；未找到返回失败（显式路径不存在也按失败处理）
+ * @throws {@link Error} 命中配置但形态/跨条目非法（加载即失败语义）
+ */
+export async function loadLziIssuesConfig(
+  options: LoadLziIssuesConfigOptions = {},
+): Promise<LoadLziIssuesConfigResult> {
+  if (options.configPath !== undefined) {
+    /**
+     * 显式路径解析结果（相对 cwd 锚定）
+     */
+    const resolved = resolve(options.cwd ?? process.cwd(), options.configPath);
+
+    if (!existsSync(resolved)) {
+      return {
+        ok: false,
+        reason: `未找到配置文件：${resolved}`,
+      };
+    }
+
+    return {
+      ok: true,
+      config: parseAndValidate(await importConfigModule(resolved), resolved),
+      configFilePath: resolved,
+      source: 'explicit',
+    };
+  }
+
+  /**
+   * 统一加载结果（standalone 优先 > unified issues 字段）
+   */
+  const unified = await loadUnifiedConfig({
+    standaloneFile: 'lzi-issues.config.ts',
+    unifiedField: 'issues',
+    cwd: options.cwd,
+  });
+
+  if (!unified.success) {
+    return {
+      ok: false,
+      reason:
+        '未找到 lzi-issues.config.ts（且 lzi.config.ts 无 issues 字段）——可先执行 lzi-issues init',
+    };
+  }
+
+  return {
+    ok: true,
+    config: parseAndValidate(unified.config, unified.configFilePath),
+    configFilePath: unified.configFilePath,
+    source: unified.source,
+  };
+}
+
+/**
+ * 按显式文件 URL 动态导入配置模块（测试与工具内部使用）
+ *
+ * @param configPath - 配置文件绝对路径
+ * @returns 配置模块 default 导出
+ * @throws {@link Error} 导入失败或无 default 导出
+ */
+export async function importConfigModule(configPath: string): Promise<unknown> {
+  /**
+   * 动态导入的配置模块
+   */
+  const module = await import(pathToFileURL(configPath).href);
+
+  if (module.default === undefined) {
+    throw new Error(`配置文件缺少 default 导出：${configPath}`);
+  }
+
+  return module.default;
+}

package/src/scaffold/render-scaffold.renderer.ts

@@ -0,0 +1,420 @@
+/**
+ * lzi-issues 配置脚手架渲染（init 命令载体）
+ *
+ * 结构化渲染而非手拼字符串：create 模式生成完整 config 文件（defineConfig
+ * 范式 + 契约注释头）；append 模式在既有 scopes 数组内做括号配平插入，不动
+ * 其他节。序列化器与基线再生渲染共用（同构 TS 字面量输出）。
+ */
+
+import { DEFAULT_REGISTRY_DIR } from '@/schema/lzi-issues-config.schema';
+
+/**
+ * scope 脚手架入参（init 命令旗标映射）
+ */
+export type ScopeScaffoldInput = {
+  /**
+   * scope key（kebab-case）
+   */
+  key: string;
+
+  /**
+   * scope 人类可读名
+   */
+  title: string;
+
+  /**
+   * 覆盖路径 glob（缺省 ['.']——本目录树全部）
+   */
+  paths?: string[];
+
+  /**
+   * 注册表目录（缺省 docs/issues）
+   */
+  registryDir?: string;
+};
+
+/**
+ * 配置文件契约注释头（create 模式）
+ */
+export const CONFIG_SCAFFOLD_HEADER = [
+  '/**',
+  ' * lzi-issues 配置（单一真源）——由 `lzi-issues init` 生成。',
+  ' *',
+  ' * 引擎零仓库知识：一切仓库特有信息（scope 注册 / 扫描面 / 门禁参数）只在本文件登记。',
+  ' * 存储默认 files（Local First）：issue 为注册表 markdown，派生数据统一 .lzi/issues/。',
+  ' */',
+].join('\n');
+
+/**
+ * 字符串字面量序列化（单引号，转义反斜杠 / 单引号 / 换行）
+ *
+ * @param value - 待序列化字符串
+ * @returns TS 字面量文本
+ */
+function serializeString(value: string): string {
+  /**
+   * 转义后内容
+   */
+  const escaped = value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n');
+
+  return `'${escaped}'`;
+}
+
+/**
+ * 数组序列化（对象元素多行、原始元素单行；空数组渲染 []）
+ *
+ * @param values - 待序列化数组
+ * @param indentLevel - 当前缩进层级（2 空格每级）
+ * @returns TS 字面量文本
+ */
+function serializeArray(values: readonly unknown[], indentLevel: number): string {
+  if (values.length === 0) {
+    return '[]';
+  }
+
+  /**
+   * 单元缩进（元素行）
+   */
+  const itemIndent = '  '.repeat(indentLevel + 1);
+
+  /**
+   * 收口缩进（闭括号行）
+   */
+  const closeIndent = '  '.repeat(indentLevel);
+
+  /**
+   * 是否对象元素数组（多行形态）
+   */
+  const objectItems = values.every((value) => typeof value === 'object' && value !== null);
+
+  if (objectItems) {
+    /**
+     * 逐元素序列化结果
+     */
+    const items = values.map((value) => `${itemIndent}${serializeValue(value, indentLevel + 1)},`);
+
+    return `[\n${items.join('\n')}\n${closeIndent}]`;
+  }
+
+  /**
+   * 原始元素单行形态
+   */
+  const items = values.map((value) => serializeValue(value, indentLevel + 1));
+
+  return `[${items.join(', ')}]`;
+}
+
+/**
+ * 对象序列化（多行；undefined 值字段跳过；空对象渲染 {}）
+ *
+ * @param record - 待序列化对象
+ * @param indentLevel - 当前缩进层级（2 空格每级）
+ * @returns TS 字面量文本
+ */
+function serializeObject(record: Record<string, unknown>, indentLevel: number): string {
+  /**
+   * 有效字段名列表（值为 undefined 的字段跳过）
+   */
+  const keys = Object.keys(record).filter((key) => record[key] !== undefined);
+
+  if (keys.length === 0) {
+    return '{}';
+  }
+
+  /**
+   * 字段缩进
+   */
+  const fieldIndent = '  '.repeat(indentLevel + 1);
+
+  /**
+   * 收口缩进
+   */
+  const closeIndent = '  '.repeat(indentLevel);
+
+  /**
+   * 逐字段序列化结果
+   */
+  const fields = keys.map(
+    (key) => `${fieldIndent}${key}: ${serializeValue(record[key], indentLevel + 1)},`,
+  );
+
+  return `{\n${fields.join('\n')}\n${closeIndent}}`;
+}
+
+/**
+ * 普通对象判定（数组除外）
+ *
+ * @param value - 待判定值
+ * @returns 是否普通对象
+ */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 任意配置值序列化（TS 字面量，与 oxfmt 风格对齐）
+ *
+ * @param value - 待序列化值
+ * @param indentLevel - 当前缩进层级
+ * @returns TS 字面量文本
+ */
+function serializeValue(value: unknown, indentLevel: number): string {
+  if (typeof value === 'string') {
+    return serializeString(value);
+  }
+
+  if (Array.isArray(value)) {
+    return serializeArray(value, indentLevel);
+  }
+
+  if (isPlainRecord(value)) {
+    return serializeObject(value, indentLevel);
+  }
+
+  return String(value);
+}
+
+/**
+ * 序列化完整配置对象为 defineConfig 包裹的配置体文本（不含文件头注释）
+ *
+ * @param config - 配置对象（解析后或字面量输入形态）
+ * @returns 配置体文本（export default defineConfig({...});）
+ */
+export function serializeConfigBody(config: Record<string, unknown>): string {
+  return `export default defineConfig(${serializeValue(config, 0)});\n`;
+}
+
+/**
+ * 渲染完整配置文件文本（create 模式）
+ *
+ * @param config - 配置对象
+ * @param header - 文件头注释（缺省 init 契约头）
+ * @returns 完整文件文本
+ */
+export function renderConfigFile(
+  config: Record<string, unknown>,
+  header: string = CONFIG_SCAFFOLD_HEADER,
+): string {
+  return `import { defineConfig } from '@longzai-intelligence-issues/config';\n\n${header}\n${serializeConfigBody(config)}`;
+}
+
+/**
+ * 渲染 scope 条目字面量（4 空格基准缩进，append 模式插入单元）
+ *
+ * @param scope - scope 脚手架入参
+ * @returns scope 条目字面量文本
+ */
+export function renderScopeEntry(scope: ScopeScaffoldInput): string {
+  /**
+   * 序列化用条目对象（缺省值落定）
+   */
+  const entry = {
+    key: scope.key,
+    title: scope.title,
+    paths: scope.paths ?? ['.'],
+    registryDir: scope.registryDir ?? DEFAULT_REGISTRY_DIR,
+  };
+
+  return serializeValue(entry, 2).trimStart();
+}
+
+/**
+ * 渲染 init 生成的完整配置文件（单 scope 起步）
+ *
+ * @param scope - 首个 scope 入参
+ * @returns 完整配置文件文本
+ */
+export function renderConfigScaffoldFile(scope: ScopeScaffoldInput): string {
+  /**
+   * 脚手架配置对象（其余节省略——解析层统一落默认值）
+   */
+  const config = {
+    schemaVersion: 1,
+    scopes: [
+      {
+        key: scope.key,
+        title: scope.title,
+        paths: scope.paths ?? ['.'],
+        registryDir: scope.registryDir ?? DEFAULT_REGISTRY_DIR,
+      },
+    ],
+  };
+
+  return renderConfigFile(config);
+}
+
+/**
+ * 括号配平扫描：定位与 openIndex 处开括号匹配的闭括号下标
+ *
+ * 跳过字符串（' " `，含转义）与注释（// 行注释、块注释）。
+ *
+ * @param text - 待扫描文本
+ * @param openIndex - 开括号下标（[ { ( 之一）
+ *   @returns 匹配闭括号下标
+ *   @throws {@link Error} 括号不配平或 openIndex 非开括号
+ */
+function scanToMatchingBracket(text: string, openIndex: number): number {
+  /**
+   * 开括号字符
+   */
+  const openChar = text[openIndex] ?? '';
+
+  /**
+   * 括号配对表
+   */
+  const pairs: Record<string, string> = { '[': ']', '{': '}', '(': ')' };
+
+  /**
+   * 期望的闭括号字符
+   */
+  const closeChar = pairs[openChar];
+
+  if (closeChar === undefined) {
+    throw new Error(`扫描起点不是开括号：位置 ${openIndex}`);
+  }
+
+  /**
+   * 深度计数器
+   */
+  let depth = 0;
+
+  for (let index = openIndex; index < text.length; index += 1) {
+    /**
+     * 当前字符
+     */
+    const char = text[index] ?? '';
+
+    /**
+     * 下一字符
+     */
+    const next = text[index + 1] ?? '';
+
+    if (char === '/' && next === '/') {
+      /**
+       * 行注释：跳至行尾
+       */
+      index = text.indexOf('\n', index);
+
+      if (index === -1) {
+        break;
+      }
+
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      /**
+       * 块注释：跳至注释闭包
+       */
+      index = text.indexOf('*/', index + 2);
+
+      if (index === -1) {
+        throw new Error('括号扫描遇未闭合块注释');
+      }
+
+      index += 1;
+
+      continue;
+    }
+
+    if (char === "'" || char === '"' || char === '`') {
+      /**
+       * 字符串：跳至闭引号（含转义）
+       */
+      index += 1;
+
+      while (index < text.length) {
+        /**
+         * 字符串内当前字符
+         */
+        const strChar = text[index] ?? '';
+
+        if (strChar === '\\') {
+          index += 2;
+
+          continue;
+        }
+
+        if (strChar === char) {
+          break;
+        }
+
+        index += 1;
+      }
+
+      continue;
+    }
+
+    if (char === openChar) {
+      depth += 1;
+    } else if (char === closeChar) {
+      depth -= 1;
+
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+
+  throw new Error('括号不配平：scopes 数组未闭合');
+}
+
+/**
+ * 在既有配置文本的 scopes 数组内追加 scope（append 模式，不动其他节）
+ *
+ * 仅依赖括号配平定位数组收口，在收口前插入条目；scope key 已存在时显式抛错。
+ * 插入缩进按本包渲染器规范（4 空格）——非规范缩进的文件插入后由 oxfmt 归一。
+ *
+ * @param configText - 既有配置文件全文
+ * @param scope - 待追加 scope 入参
+ * @returns 追加后的配置文件全文
+ * @throws {@link Error} key 已注册 / 无 scopes 数组 / 括号不配平
+ */
+export function appendScopeToConfigText(configText: string, scope: ScopeScaffoldInput): string {
+  /**
+   * key 重复检测模式（key: '<key>' 字面量形态）
+   */
+  const duplicatePattern = new RegExp(`key\\s*:\\s*'${scope.key}'`);
+
+  if (duplicatePattern.test(configText)) {
+    throw new Error(`scope key「${scope.key}」已注册，拒绝重复追加`);
+  }
+
+  /**
+   * scopes 数组开括号定位
+   */
+  const scopesMatch = /scopes\s*:\s*\[/.exec(configText);
+
+  if (scopesMatch === null) {
+    throw new Error('配置文件缺少 scopes 数组，无法追加 scope');
+  }
+
+  /**
+   * scopes 数组开括号下标
+   */
+  const openIndex = (scopesMatch.index ?? 0) + scopesMatch[0].length - 1;
+
+  /**
+   * 匹配闭括号下标
+   */
+  const closeIndex = scanToMatchingBracket(configText, openIndex);
+
+  /**
+   * 闭括号前最后一个非空白字符下标
+   */
+  let lastNonWs = closeIndex - 1;
+
+  while (lastNonWs >= 0 && /\s/.test(configText[lastNonWs] ?? '')) {
+    lastNonWs -= 1;
+  }
+
+  /**
+   * 插入文本（前一字符已是逗号则免逗号；否则补逗号）
+   */
+  const insertion =
+    configText[lastNonWs] === ','
+      ? `\n    ${renderScopeEntry(scope)}`
+      : `,\n    ${renderScopeEntry(scope)}`;
+
+  return `${configText.slice(0, closeIndex)}${insertion}${configText.slice(closeIndex)}`;
+}