@longzai-intelligence-specs/config 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 更新日志
+
+本项目的所有重要更改都将记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.0.1] - 2026-09-27
+
+### 新增
+
+- 新增 @longzai-intelligence-specs/config 包提供配置 schema 与加载器

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import "./rolldown-runtime-BqT_7tdF.js";
+import * as z from "zod";
+//#region src/schema/lzi-specs-config.schema.d.ts
+/**
+ * scope key 合法形态（kebab-case）
+ */
+declare const SCOPE_KEY_PATTERN: RegExp;
+/**
+ * init 缺省注册表目录
+ */
+declare const DEFAULT_REGISTRY_DIR = "docs/specs";
+/**
+ * 棘轮基线条目 schema（存量豁免逐条带理由登记——存量不追溯，豁免只许缩短）
+ */
+declare const baselineEntrySchema: z.ZodObject<{
+  file: z.ZodString;
+  rule: z.ZodString;
+  reason: z.ZodString;
+}, z.core.$strip>;
+/**
+ * scope 注册条目 schema
+ */
+declare const scopeSchema: z.ZodObject<{
+  key: z.ZodString;
+  title: z.ZodString;
+  paths: z.ZodArray<z.ZodString>;
+  registryDir: z.ZodString;
+}, z.core.$strip>;
+/**
+ * scope 注册条目（书写形态）
+ */
+type ScopeEntryInput = z.input<typeof scopeSchema>;
+/**
+ * scope 注册条目（解析后形态）
+ */
+type ScopeEntry = z.output<typeof scopeSchema>;
+/**
+ * lzi-specs 配置根 schema
+ */
+declare const lziSpecsConfigSchema: z.ZodObject<{
+  scopes: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    title: z.ZodString;
+    paths: z.ZodArray<z.ZodString>;
+    registryDir: z.ZodString;
+  }, z.core.$strip>>;
+  check: z.ZodDefault<z.ZodObject<{
+    baseline: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      file: z.ZodString;
+      rule: z.ZodString;
+      reason: z.ZodString;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * lzi-specs 配置（用户书写形态，可省略各默认值）
+ */
+type LziSpecsConfigInput = z.input<typeof lziSpecsConfigSchema>;
+/**
+ * lzi-specs 配置（解析后形态，默认值全部落定）
+ */
+type LziSpecsConfig = z.output<typeof lziSpecsConfigSchema>;
+/**
+ * 棘轮基线条目
+ */
+type CheckBaselineEntry = z.infer<typeof baselineEntrySchema>;
+/**
+ * 解析并校验配置（非法即抛，加载即失败）
+ *
+ * @param input - 配置原始对象（defineConfig 产物）
+ * @returns 默认值落定的配置
+ * @throws {@link Error} 形态违规（消息聚合全部违规项；跨条目语义校验由
+ * validateLziSpecsConfig 在加载链路上追加执行）
+ */
+declare function parseLziSpecsConfig(input: unknown): LziSpecsConfig;
+/**
+ * 定义 lzi-specs 配置（identity 工厂）
+ *
+ * 类型透传，与 lzi-dev.config.ts / oxfmt.config.ts 等 workspace 配置惯例同构：
+ * 不在工厂层做任何合并——默认值由本模块 schema 解析层统一落定。
+ *
+ * @param config - 配置对象（可省略各默认值）
+ * @returns 原样返回传入的配置对象
+ */
+declare function defineConfig(config: LziSpecsConfigInput): LziSpecsConfigInput;
+//#endregion
+//#region src/loader/load-specs-config.utils.d.ts
+/**
+ * 配置来源类型
+ */
+type LziSpecsConfigSource = 'standalone' | 'unified' | 'explicit';
+/**
+ * 加载成功结果
+ */
+type LoadLziSpecsConfigSuccess = {
+  /**
+   * 加载成功标记
+   */
+  ok: true;
+  /**
+   * 解析并校验后的配置（默认值全部落定）
+   */
+  config: LziSpecsConfig;
+  /**
+   * 命中的配置文件绝对路径
+   */
+  configFilePath: string;
+  /**
+   * 配置来源
+   */
+  source: LziSpecsConfigSource;
+};
+/**
+ * 加载失败结果（未找到配置）
+ */
+type LoadLziSpecsConfigFailure = {
+  /**
+   * 加载成功标记
+   */
+  ok: false;
+  /**
+   * 失败原因
+   */
+  reason: string;
+};
+/**
+ * 加载结果
+ */
+type LoadLziSpecsConfigResult = LoadLziSpecsConfigSuccess | LoadLziSpecsConfigFailure;
+/**
+ * 加载选项
+ */
+type LoadLziSpecsConfigOptions = {
+  /**
+   * 查找起点目录（缺省 process.cwd()）
+   */
+  cwd?: string;
+  /**
+   * 显式配置文件路径（优先级最高，绕过向上查找）
+   */
+  configPath?: string;
+};
+/**
+ * 加载 lzi-specs 配置
+ *
+ * @param options - 加载选项
+ * @returns 加载结果：命中返回解析后配置；未找到返回失败（显式路径不存在也按失败处理）
+ * @throws {@link Error} 命中配置但形态/跨条目非法（加载即失败语义）
+ */
+declare function loadLziSpecsConfig(options?: LoadLziSpecsConfigOptions): Promise<LoadLziSpecsConfigResult>;
+/**
+ * 按显式文件 URL 动态导入配置模块（测试与工具内部使用）
+ *
+ * @param configPath - 配置文件绝对路径
+ * @returns 配置模块 default 导出
+ * @throws {@link Error} 导入失败或无 default 导出
+ */
+declare function importConfigModule(configPath: string): Promise<unknown>;
+//#endregion
+//#region src/scaffold/render-scaffold.renderer.d.ts
+/**
+ * lzi-specs 配置脚手架渲染（init 命令落盘）
+ *
+ * 渲染 lzi-specs.config.ts 全文（单 scope 起步形态）；幂等不覆盖由命令层守卫。
+ */
+/**
+ * 脚手架渲染入参
+ */
+type ConfigScaffoldInput = {
+  /**
+   * scope key（kebab-case）
+   */
+  scopeKey: string;
+  /**
+   * scope 人类可读名
+   */
+  scopeTitle: string;
+  /**
+   * 注册表目录（posix 相对仓库根）
+   */
+  registryDir: string;
+};
+/**
+ * 渲染 lzi-specs.config.ts 脚手架全文
+ *
+ * @param input - 脚手架入参
+ * @returns 可直接落盘的配置文件全文
+ */
+declare function renderConfigScaffold(input: ConfigScaffoldInput): string;
+//#endregion
+//#region src/validation/validate-cross-entries.d.ts
+/**
+ * 校验并透传配置（语义非法即抛，消息聚合全部违规项）
+ *
+ * @param config - 形态解析后的配置
+ * @returns 原样透传（校验通过）
+ * @throws {@link Error} 跨条目语义违规
+ */
+declare function validateLziSpecsConfig(config: LziSpecsConfig): LziSpecsConfig;
+//#endregion
+export { CheckBaselineEntry, ConfigScaffoldInput, DEFAULT_REGISTRY_DIR, LoadLziSpecsConfigFailure, LoadLziSpecsConfigOptions, LoadLziSpecsConfigResult, LoadLziSpecsConfigSuccess, LziSpecsConfig, LziSpecsConfigInput, LziSpecsConfigSource, SCOPE_KEY_PATTERN, ScopeEntry, ScopeEntryInput, baselineEntrySchema, defineConfig, importConfigModule, loadLziSpecsConfig, lziSpecsConfigSchema, parseLziSpecsConfig, renderConfigScaffold, validateLziSpecsConfig };

package/dist/index.js

@@ -0,0 +1,2 @@
+import"./rolldown-runtime-BqT_7tdF.js";import{loadUnifiedConfig as e}from"@longzai-intelligence-shared-config/core";import{existsSync as t}from"node:fs";import{resolve as n}from"node:path";import{pathToFileURL as r}from"node:url";import*as i from"zod";const a=/^[a-z][a-z0-9-]*$/,o=`docs/specs`,s=i.object({file:i.string().min(1),rule:i.string().min(1),reason:i.string().min(1)}),c=i.object({key:i.string().regex(a),title:i.string().min(1),paths:i.array(i.string().min(1)).min(1),registryDir:i.string().min(1)}),l=i.object({baseline:i.array(s).default([])}),u=i.object({scopes:i.array(c).min(1),check:l.default({baseline:[]})});function d(e){let t=u.safeParse(e);if(!t.success){let e=t.error.issues.map(e=>`${e.path.join(`.`)}: ${e.message}`).join(`；`);throw Error(`lzi-specs 配置形态非法：${e}`)}return t.data}function f(e){return e}function p(e){let t=[],n=/* @__PURE__ */ new Map;for(let t of e.scopes)n.set(t.key,(n.get(t.key)??0)+1);for(let[e,r]of n)r>1&&t.push(`scopes: key「${e}」重复登记 ${r} 次（scope key 必须唯一）`);let r=/* @__PURE__ */ new Map;for(let t of e.scopes){let e=r.get(t.registryDir)??[];e.push(t.key),r.set(t.registryDir,e)}for(let[e,n]of r)n.length>1&&t.push(`scopes: 注册表目录「${e}」被 ${n.join(`、`)} 共用（一目录一 scope，否则识别与 check 歧义）`);for(let n of e.check.baseline)e.scopes.some(e=>n.file===e.registryDir||n.file.startsWith(`${e.registryDir}/`))||t.push(`check.baseline: 豁免条目「${n.file}」（规则 ${n.rule}）不在任何 scope 注册表目录内`);if(t.length>0)throw Error(`lzi-specs 配置跨条目语义非法：${t.join(`；`)}`);return e}function m(e,t){try{return p(d(e))}catch(e){let n=e instanceof Error?e.message:String(e);throw Error(`${n}（配置文件：${t}）`)}}async function h(r={}){if(r.configPath!==void 0){let e=n(r.cwd??process.cwd(),r.configPath);return t(e)?{ok:!0,config:m(await g(e),e),configFilePath:e,source:`explicit`}:{ok:!1,reason:`未找到配置文件：${e}`}}let i=await e({standaloneFile:`lzi-specs.config.ts`,unifiedField:`specs`,cwd:r.cwd});return i.success?{ok:!0,config:m(i.config,i.configFilePath),configFilePath:i.configFilePath,source:i.source}:{ok:!1,reason:`未找到 lzi-specs.config.ts（且 lzi.config.ts 无 specs 字段）——可先执行 lzi-specs init`}}async function g(e){let t=await import(r(e).href);if(t.default===void 0)throw Error(`配置文件缺少 default 导出：${e}`);return t.default}function _(e){return[`import { defineConfig } from '@longzai-intelligence-specs/config';`,``,`/**`,` * lzi-specs 配置`,` */`,`export default defineConfig({`,`  scopes: [`,`    { key: '${e.scopeKey}', title: '${e.scopeTitle}', paths: ['.'], registryDir: '${e.registryDir}' },`,`  ],`,`});`,``].join(`
+`)}export{o as DEFAULT_REGISTRY_DIR,a as SCOPE_KEY_PATTERN,s as baselineEntrySchema,f as defineConfig,g as importConfigModule,h as loadLziSpecsConfig,u as lziSpecsConfigSchema,d as parseLziSpecsConfig,_ as renderConfigScaffold,p as validateLziSpecsConfig};

package/dist/rolldown-runtime-BqT_7tdF.js

@@ -0,0 +1 @@
+import"node:module";export{};

package/lzi-builder.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from '@longzai-intelligence-builder/esm';
+
+/**
+ * 配置包构建配置
+ */
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+  },
+  platform: 'node',
+});

package/oxlint.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@longzai-intelligence-oxlint/presets/library';
+
+/**
+ * Oxlint 配置
+ */
+export default defineConfig();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@longzai-intelligence-specs/config",
+  "version": "0.0.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "@longzai-intelligence-shared-config/core": "^0.0.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/__tests__/schema/lzi-specs-config.schema.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+
+import { defineConfig, parseLziSpecsConfig } from '@/schema/lzi-specs-config.schema';
+import { validateLziSpecsConfig } from '@/validation/validate-cross-entries';
+
+/**
+ * lzi-specs 配置 schema 解析与跨条目校验测试
+ */
+describe('lzi-specs-config schema', () => {
+  test('最小合法配置解析且默认值落定', () => {
+    /**
+     * 最小配置
+     */
+    const config = parseLziSpecsConfig(
+      defineConfig({
+        scopes: [{ key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/specs' }],
+      }),
+    );
+
+    expect(config.scopes).toHaveLength(1);
+    expect(config.check.baseline).toEqual([]);
+  });
+
+  test('scope key 形态非法即抛', () => {
+    expect(() =>
+      parseLziSpecsConfig({
+        scopes: [{ key: 'Root', title: '全局', paths: ['.'], registryDir: 'docs/specs' }],
+      }),
+    ).toThrow('lzi-specs 配置形态非法');
+  });
+
+  test('scopes 空数组即抛（至少一个注册面）', () => {
+    expect(() => parseLziSpecsConfig({ scopes: [] })).toThrow();
+  });
+
+  test('跨条目：注册表目录被两 scope 共用即抛', () => {
+    /**
+     * 共用目录配置
+     */
+    const config = parseLziSpecsConfig({
+      scopes: [
+        { key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/specs' },
+        { key: 'sub', title: '子面', paths: ['packages'], registryDir: 'docs/specs' },
+      ],
+    });
+
+    expect(() => validateLziSpecsConfig(config)).toThrow(
+      '注册表目录「docs/specs」被 root、sub 共用',
+    );
+  });
+
+  test('跨条目：基线豁免文件不在注册面内即抛', () => {
+    /**
+     * 带越界基线的配置
+     */
+    const config = parseLziSpecsConfig({
+      scopes: [{ key: 'root', title: '全局', paths: ['.'], registryDir: 'docs/specs' }],
+      check: { baseline: [{ file: 'docs/other/0001-x.md', rule: 'R-FILENAME', reason: '存量' }] },
+    });
+
+    expect(() => validateLziSpecsConfig(config)).toThrow('不在任何 scope 注册表目录内');
+  });
+});

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 配置包入口
+ *
+ * 汇出：defineConfig、schema 与解析、跨条目校验、加载器、init 脚手架渲染。
+ */
+
+export * from '@/loader/load-specs-config.utils';
+
+export * from '@/scaffold/render-scaffold.renderer';
+
+export * from '@/schema/lzi-specs-config.schema';
+
+export * from '@/validation/validate-cross-entries';

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

@@ -0,0 +1,180 @@
+/**
+ * lzi-specs 配置加载器
+ *
+ * 复用 shared-config 的 loadUnifiedConfig 统一加载：优先工具专属
+ * lzi-specs.config.ts（cwd 向上查找），回退统一配置 lzi.config.ts 的 specs
+ * 字段；命中后 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 LziSpecsConfig, parseLziSpecsConfig } from '@/schema/lzi-specs-config.schema';
+import { validateLziSpecsConfig } from '@/validation/validate-cross-entries';
+
+/**
+ * 配置来源类型
+ */
+export type LziSpecsConfigSource = 'standalone' | 'unified' | 'explicit';
+
+/**
+ * 加载成功结果
+ */
+export type LoadLziSpecsConfigSuccess = {
+  /**
+   * 加载成功标记
+   */
+  ok: true;
+
+  /**
+   * 解析并校验后的配置（默认值全部落定）
+   */
+  config: LziSpecsConfig;
+
+  /**
+   * 命中的配置文件绝对路径
+   */
+  configFilePath: string;
+
+  /**
+   * 配置来源
+   */
+  source: LziSpecsConfigSource;
+};
+
+/**
+ * 加载失败结果（未找到配置）
+ */
+export type LoadLziSpecsConfigFailure = {
+  /**
+   * 加载成功标记
+   */
+  ok: false;
+
+  /**
+   * 失败原因
+   */
+  reason: string;
+};
+
+/**
+ * 加载结果
+ */
+export type LoadLziSpecsConfigResult = LoadLziSpecsConfigSuccess | LoadLziSpecsConfigFailure;
+
+/**
+ * 加载选项
+ */
+export type LoadLziSpecsConfigOptions = {
+  /**
+   * 查找起点目录（缺省 process.cwd()）
+   */
+  cwd?: string;
+
+  /**
+   * 显式配置文件路径（优先级最高，绕过向上查找）
+   */
+  configPath?: string;
+};
+
+/**
+ * 解析 + 校验配置对象（形态 + 跨条目，非法即抛带路径上下文）
+ *
+ * @param input - 配置原始对象
+ * @param configFilePath - 配置文件路径（错误消息附注）
+ * @returns 解析并校验后的配置
+ * @throws {@link Error} 形态或跨条目违规
+ */
+function parseAndValidate(input: unknown, configFilePath: string): LziSpecsConfig {
+  try {
+    /**
+     * 形态解析 + 跨条目校验后的配置
+     */
+    return validateLziSpecsConfig(parseLziSpecsConfig(input));
+  } catch (error) {
+    /**
+     * 原始错误消息
+     */
+    const message = error instanceof Error ? error.message : String(error);
+
+    throw new Error(`${message}（配置文件：${configFilePath}）`);
+  }
+}
+
+/**
+ * 加载 lzi-specs 配置
+ *
+ * @param options - 加载选项
+ * @returns 加载结果：命中返回解析后配置；未找到返回失败（显式路径不存在也按失败处理）
+ * @throws {@link Error} 命中配置但形态/跨条目非法（加载即失败语义）
+ */
+export async function loadLziSpecsConfig(
+  options: LoadLziSpecsConfigOptions = {},
+): Promise<LoadLziSpecsConfigResult> {
+  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 specs 字段）
+   */
+  const unified = await loadUnifiedConfig({
+    standaloneFile: 'lzi-specs.config.ts',
+    unifiedField: 'specs',
+    cwd: options.cwd,
+  });
+
+  if (!unified.success) {
+    return {
+      ok: false,
+      reason:
+        '未找到 lzi-specs.config.ts（且 lzi.config.ts 无 specs 字段）——可先执行 lzi-specs 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,47 @@
+/**
+ * lzi-specs 配置脚手架渲染（init 命令落盘）
+ *
+ * 渲染 lzi-specs.config.ts 全文（单 scope 起步形态）；幂等不覆盖由命令层守卫。
+ */
+
+/**
+ * 脚手架渲染入参
+ */
+export type ConfigScaffoldInput = {
+  /**
+   * scope key（kebab-case）
+   */
+  scopeKey: string;
+
+  /**
+   * scope 人类可读名
+   */
+  scopeTitle: string;
+
+  /**
+   * 注册表目录（posix 相对仓库根）
+   */
+  registryDir: string;
+};
+
+/**
+ * 渲染 lzi-specs.config.ts 脚手架全文
+ *
+ * @param input - 脚手架入参
+ * @returns 可直接落盘的配置文件全文
+ */
+export function renderConfigScaffold(input: ConfigScaffoldInput): string {
+  return [
+    "import { defineConfig } from '@longzai-intelligence-specs/config';",
+    '',
+    '/**',
+    ' * lzi-specs 配置',
+    ' */',
+    'export default defineConfig({',
+    '  scopes: [',
+    `    { key: '${input.scopeKey}', title: '${input.scopeTitle}', paths: ['.'], registryDir: '${input.registryDir}' },`,
+    '  ],',
+    '});',
+    '',
+  ].join('\n');
+}