@longzai-intelligence-specs/config 0.0.1

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

@@ -0,0 +1,122 @@
+/**
+ * lzi-specs 配置 schema 与解析
+ *
+ * 单一真源 `lzi-specs.config.ts` 的形态定义：zod 守形态、跨条目语义由
+ * validate-cross-entries 纯函数承担，非法配置在加载即失败。引擎零仓库知识——
+ * 一切仓库特有信息（scope 注册、豁免基线）只存在于本配置。
+ *
+ * specs 无编号取号（目录形态 `spec-YYYYMMDD-slug/`，日期即键），故配置面无
+ * numbering 维度；check 的豁免基线用于存量命名/缺件违例的棘轮收编。
+ */
+
+import * as z from 'zod';
+
+/**
+ * scope key 合法形态（kebab-case）
+ */
+export const SCOPE_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * init 缺省注册表目录
+ */
+export const DEFAULT_REGISTRY_DIR = 'docs/specs';
+
+/**
+ * 棘轮基线条目 schema（存量豁免逐条带理由登记——存量不追溯，豁免只许缩短）
+ */
+export const baselineEntrySchema = z.object({
+  file: z.string().min(1),
+  rule: z.string().min(1),
+  reason: z.string().min(1),
+});
+
+/**
+ * scope 注册条目 schema
+ */
+const scopeSchema = z.object({
+  key: z.string().regex(SCOPE_KEY_PATTERN),
+  title: z.string().min(1),
+  paths: z.array(z.string().min(1)).min(1),
+  registryDir: z.string().min(1),
+});
+
+/**
+ * scope 注册条目（书写形态）
+ */
+export type ScopeEntryInput = z.input<typeof scopeSchema>;
+
+/**
+ * scope 注册条目（解析后形态）
+ */
+export type ScopeEntry = z.output<typeof scopeSchema>;
+
+/**
+ * check 节 schema（baseline 为豁免基线：存量命名/缺件违例逐条登记，只许缩短）
+ */
+const checkSchema = z.object({
+  baseline: z.array(baselineEntrySchema).default([]),
+});
+
+/**
+ * lzi-specs 配置根 schema
+ */
+export const lziSpecsConfigSchema = z.object({
+  scopes: z.array(scopeSchema).min(1),
+  check: checkSchema.default({ baseline: [] }),
+});
+
+/**
+ * lzi-specs 配置（用户书写形态，可省略各默认值）
+ */
+export type LziSpecsConfigInput = z.input<typeof lziSpecsConfigSchema>;
+
+/**
+ * lzi-specs 配置（解析后形态，默认值全部落定）
+ */
+export type LziSpecsConfig = z.output<typeof lziSpecsConfigSchema>;
+
+/**
+ * 棘轮基线条目
+ */
+export type CheckBaselineEntry = z.infer<typeof baselineEntrySchema>;
+
+/**
+ * 解析并校验配置（非法即抛，加载即失败）
+ *
+ * @param input - 配置原始对象（defineConfig 产物）
+ * @returns 默认值落定的配置
+ * @throws {@link Error} 形态违规（消息聚合全部违规项；跨条目语义校验由
+ * validateLziSpecsConfig 在加载链路上追加执行）
+ */
+export function parseLziSpecsConfig(input: unknown): LziSpecsConfig {
+  /**
+   * 形态解析结果
+   */
+  const parsed = lziSpecsConfigSchema.safeParse(input);
+
+  if (!parsed.success) {
+    /**
+     * 形态违规明细（路径 + 消息）
+     */
+    const details = parsed.error.issues
+      .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+      .join('；');
+
+    throw new Error(`lzi-specs 配置形态非法：${details}`);
+  }
+
+  return parsed.data;
+}
+
+/**
+ * 定义 lzi-specs 配置（identity 工厂）
+ *
+ * 类型透传，与 lzi-dev.config.ts / oxfmt.config.ts 等 workspace 配置惯例同构：
+ * 不在工厂层做任何合并——默认值由本模块 schema 解析层统一落定。
+ *
+ * @param config - 配置对象（可省略各默认值）
+ * @returns 原样返回传入的配置对象
+ */
+export function defineConfig(config: LziSpecsConfigInput): LziSpecsConfigInput {
+  return config;
+}

package/src/validation/validate-cross-entries.ts

@@ -0,0 +1,85 @@
+/**
+ * lzi-specs 配置跨条目语义校验（纯函数，零 fs）
+ *
+ * 形态由 schema 承担；本模块承担条目间语义：scope key 唯一、注册表目录不共用
+ * （两 scope 共用同一 registryDir 会造成识别与 check 双重歧义）、基线豁免文件
+ * 须落在某 scope 注册表内。
+ */
+
+import type { LziSpecsConfig } from '@/schema/lzi-specs-config.schema';
+
+/**
+ * 校验并透传配置（语义非法即抛，消息聚合全部违规项）
+ *
+ * @param config - 形态解析后的配置
+ * @returns 原样透传（校验通过）
+ * @throws {@link Error} 跨条目语义违规
+ */
+export function validateLziSpecsConfig(config: LziSpecsConfig): LziSpecsConfig {
+  /**
+   * 违规消息列表
+   */
+  const violations: string[] = [];
+
+  /**
+   * scope key 重复检测（key → 出现次数）
+   */
+  const keyCounts = new Map<string, number>();
+
+  for (const scope of config.scopes) {
+    keyCounts.set(scope.key, (keyCounts.get(scope.key) ?? 0) + 1);
+  }
+
+  for (const [key, count] of keyCounts) {
+    if (count > 1) {
+      violations.push(`scopes: key「${key}」重复登记 ${count} 次（scope key 必须唯一）`);
+    }
+  }
+
+  /**
+   * 注册表目录重复检测（registryDir → 占用 scope key 列表）
+   */
+  const dirOwners = new Map<string, string[]>();
+
+  for (const scope of config.scopes) {
+    /**
+     * 现占用列表
+     */
+    const owners = dirOwners.get(scope.registryDir) ?? [];
+
+    owners.push(scope.key);
+    dirOwners.set(scope.registryDir, owners);
+  }
+
+  for (const [dir, owners] of dirOwners) {
+    if (owners.length > 1) {
+      violations.push(
+        `scopes: 注册表目录「${dir}」被 ${owners.join('、')} 共用（一目录一 scope，否则识别与 check 歧义）`,
+      );
+    }
+  }
+
+  /**
+   * 基线豁免文件落点检测（豁免文件须命中某 scope 的注册表目录内）
+   */
+  for (const entry of config.check.baseline) {
+    /**
+     * 命中标记（文件路径以某 registryDir 前缀开头）
+     */
+    const covered = config.scopes.some(
+      (scope) => entry.file === scope.registryDir || entry.file.startsWith(`${scope.registryDir}/`),
+    );
+
+    if (!covered) {
+      violations.push(
+        `check.baseline: 豁免条目「${entry.file}」（规则 ${entry.rule}）不在任何 scope 注册表目录内`,
+      );
+    }
+  }
+
+  if (violations.length > 0) {
+    throw new Error(`lzi-specs 配置跨条目语义非法：${violations.join('；')}`);
+  }
+
+  return config;
+}