@longzai-intelligence-issues/config 0.0.1

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

@@ -0,0 +1,277 @@
+/**
+ * lzi-issues 配置 schema 与解析
+ *
+ * 单一真源 `lzi-issues.config.ts` 的形态定义：zod 守形态、跨条目语义由
+ * validate-cross-entries 纯函数承担（apex numbering.config.ts 同款分工），
+ * 非法配置在加载即失败。引擎零仓库知识——一切仓库特有信息（scope 注册、扫描
+ * 面、门禁正则）只存在于本配置。
+ */
+
+import * as z from 'zod';
+
+/**
+ * 存储策略全集（ADR-0048 多策略）：files 为 Local First 默认
+ */
+export const STORAGE_STRATEGIES = ['files', 'sqlite', 'postgres', 'mysql', 'memory'] as const;
+
+/**
+ * 存储策略类型
+ */
+export type StorageStrategy = (typeof STORAGE_STRATEGIES)[number];
+
+/**
+ * 关闭门禁挂起词默认集（状态行命中任一即拒绝收口——诚实黄灯维持）
+ */
+export const DEFAULT_PENDING_WORDS = [
+  '待补跑',
+  '待复跑',
+  '待低负载',
+  '环境不具备',
+  '挂起',
+  '后补跑',
+] as const;
+
+/**
+ * audit 覆盖面「形似编号」筛选默认模式
+ */
+export const DEFAULT_NUMBERISH_PATTERN = '^\\d{1,4}[-._]';
+
+/**
+ * audit 默认审计根（docs 树）
+ */
+export const DEFAULT_AUDIT_ROOTS = ['docs'] as const;
+
+/**
+ * init 缺省注册表目录
+ */
+export const DEFAULT_REGISTRY_DIR = 'docs/issues';
+
+/**
+ * sqlite 策略缺省库文件路径（统一收纳 .lzi/issues/ 命名空间）
+ */
+export const DEFAULT_SQLITE_PATH = '.lzi/issues/issues.sqlite';
+
+/**
+ * scope key 合法形态（kebab-case）
+ */
+export const SCOPE_KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * 编号形态（数字字符串，零填充原文）
+ */
+export const NUMBER_PATTERN = /^\d+$/;
+
+/**
+ * 扩展名形态（如 .md）
+ */
+export const EXTENSION_PATTERN = /^\.[A-Za-z0-9]+$/;
+
+/**
+ * 保留号条目 schema（不回收复用的历史空洞号）
+ */
+const reservedEntrySchema = z.object({
+  number: z.string().regex(NUMBER_PATTERN),
+  reason: z.string().min(1),
+});
+
+/**
+ * 棘轮基线条目 schema（豁免必须携带 issue 收编指针）
+ */
+export const baselineEntrySchema = z.object({
+  file: z.string().min(1),
+  rule: z.string().min(1),
+  issue: z.string().min(1),
+});
+
+/**
+ * glob + 理由条目 schema（豁免/排除逐条带理由登记）
+ */
+const globReasonEntrySchema = z.object({
+  glob: 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),
+  numbering: z.object({ reserved: z.array(reservedEntrySchema) }).default({ reserved: [] }),
+  slugDigitPolicy: z.literal('forbid').optional(),
+});
+
+/**
+ * scope 注册条目（书写形态）
+ */
+export type ScopeEntryInput = z.input<typeof scopeSchema>;
+
+/**
+ * scope 注册条目（解析后形态）
+ */
+export type ScopeEntry = z.output<typeof scopeSchema>;
+
+/**
+ * 存储节 schema（字段级默认，section 缺省整体回退 DEFAULT_STORAGE）
+ */
+const storageSchema = z.object({
+  strategy: z.enum(STORAGE_STRATEGIES).default('files'),
+  sqlitePath: z.string().min(1).default(DEFAULT_SQLITE_PATH),
+});
+
+/**
+ * lint 节 schema
+ */
+const lintSchema = z.object({
+  baseline: z.array(baselineEntrySchema).default([]),
+  strictLegacy: z.boolean().default(false),
+  rulePacks: z.array(z.string().min(1)).default([]),
+});
+
+/**
+ * 编号豁免条目 schema（存量撞号豁免：精确文件集 + 棘轮状态 + 理由）
+ */
+const allowlistEntrySchema = z.object({
+  scopeKey: z.string().min(1),
+  number: z.string().regex(NUMBER_PATTERN),
+  files: z.array(z.string().min(1)).min(2),
+  status: z.enum(['待清偿', '维持现状']),
+  reason: z.string().min(1),
+});
+
+/**
+ * numbering 节 schema
+ */
+const numberingSchema = z.object({
+  allowlist: z.array(allowlistEntrySchema).default([]),
+  globalExclusions: z.array(globReasonEntrySchema).default([]),
+  audit: z
+    .object({
+      roots: z
+        .array(z.string().min(1))
+        .min(1)
+        .default([...DEFAULT_AUDIT_ROOTS]),
+      numberishPattern: z.string().min(1).default(DEFAULT_NUMBERISH_PATTERN),
+      pending: z.array(globReasonEntrySchema).default([]),
+    })
+    .default({
+      roots: [...DEFAULT_AUDIT_ROOTS],
+      numberishPattern: DEFAULT_NUMBERISH_PATTERN,
+      pending: [],
+    }),
+});
+
+/**
+ * docs 节 schema（scanRoots 必填——引用检查扫描面不设隐式默认）
+ */
+const docsSchema = z.object({
+  scanRoots: z.array(z.string().min(1)).min(1),
+  includeExtensions: z.array(z.string().regex(EXTENSION_PATTERN)).default(['.md']),
+  exclusions: z.array(globReasonEntrySchema).default([]),
+  baseline: z.array(baselineEntrySchema).default([]),
+});
+
+/**
+ * close 节 schema
+ */
+const closeSchema = z.object({
+  pendingWords: z.array(z.string().min(1)).default([...DEFAULT_PENDING_WORDS]),
+  heavyPattern: z.string().min(1).optional(),
+  fullPattern: z.string().min(1).optional(),
+  blockingMustBeGreen: z.boolean().default(true),
+});
+
+/**
+ * prompts 节 schema
+ */
+const promptsSchema = z.object({
+  builtin: z.boolean().default(true),
+  extraDir: z.string().min(1).optional(),
+});
+
+/**
+ * lzi-issues 配置根 schema
+ *
+ * docs 节整体可选（未配置时 docs 引用检查命令显式拒绝，不设隐式扫描面）；
+ * 其余节缺省时整体回退该节全默认值。
+ */
+export const lziIssuesConfigSchema = z.object({
+  schemaVersion: z.literal(1),
+  storage: storageSchema.default({ strategy: 'files', sqlitePath: DEFAULT_SQLITE_PATH }),
+  scopes: z.array(scopeSchema).min(1),
+  lint: lintSchema.default({ baseline: [], strictLegacy: false, rulePacks: [] }),
+  numbering: numberingSchema.default({
+    allowlist: [],
+    globalExclusions: [],
+    audit: {
+      roots: [...DEFAULT_AUDIT_ROOTS],
+      numberishPattern: DEFAULT_NUMBERISH_PATTERN,
+      pending: [],
+    },
+  }),
+  slugDigitAllowlist: z.array(globReasonEntrySchema).default([]),
+  docs: docsSchema.optional(),
+  close: closeSchema.default({
+    pendingWords: [...DEFAULT_PENDING_WORDS],
+    blockingMustBeGreen: true,
+  }),
+  prompts: promptsSchema.default({ builtin: true }),
+});
+
+/**
+ * lzi-issues 配置（用户书写形态，可省略各默认值）
+ */
+export type LziIssuesConfigInput = z.input<typeof lziIssuesConfigSchema>;
+
+/**
+ * lzi-issues 配置（解析后形态，默认值全部落定）
+ */
+export type LziIssuesConfig = z.output<typeof lziIssuesConfigSchema>;
+
+/**
+ * 棘轮基线条目
+ */
+export type LintBaselineEntry = z.infer<typeof baselineEntrySchema>;
+
+/**
+ * 解析并校验配置（非法即抛，加载即失败）
+ *
+ * @param input - 配置原始对象（defineConfig 产物或统一配置字段值）
+ * @returns 默认值落定的配置
+ * @throws {@link Error} 形态违规（消息聚合全部违规项；跨条目语义校验由
+ * validateLziIssuesConfig 在加载链路上追加执行）
+ */
+export function parseLziIssuesConfig(input: unknown): LziIssuesConfig {
+  /**
+   * 形态解析结果
+   */
+  const parsed = lziIssuesConfigSchema.safeParse(input);
+
+  if (!parsed.success) {
+    /**
+     * 形态违规明细（路径 + 消息）
+     */
+    const details = parsed.error.issues
+      .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+      .join('；');
+
+    throw new Error(`lzi-issues 配置形态非法：${details}`);
+  }
+
+  return parsed.data;
+}
+
+/**
+ * 定义 lzi-issues 配置（identity 工厂）
+ *
+ * 类型透传，与 lzi-dev.config.ts / oxfmt.config.ts 等 workspace 配置惯例同构：
+ * 不在工厂层做任何合并——默认值由本模块 schema 解析层统一落定。
+ *
+ * @param config - 配置对象（可省略各默认值）
+ * @returns 原样返回传入的配置对象
+ */
+export function defineConfig(config: LziIssuesConfigInput): LziIssuesConfigInput {
+  return config;
+}

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

@@ -0,0 +1,260 @@
+/**
+ * lzi-issues 配置跨条目语义校验（纯函数）
+ *
+ * zod 只守形态；跨条目语义（查重、指向、路径形态）集中于此，非法即聚合抛错
+ * （apex numbering.config.ts 的 validateCrossEntries 同款分工）。
+ */
+
+import type { LziIssuesConfig } from '@/schema/lzi-issues-config.schema';
+
+/**
+ * 跨条目校验违规消息列表类型
+ */
+export type CrossEntryViolations = string[];
+
+/**
+ * 校验单条相对路径形态（禁绝对路径、禁 .. 上溯、禁反斜杠）
+ *
+ * @param label - 违规消息中的条目标签（如「scopes[0].registryDir」）
+ * @param value - 待校验路径
+ * @param violations - 违规消息收集器
+ */
+function checkRelativePath(label: string, value: string, violations: CrossEntryViolations): void {
+  if (value.startsWith('/') || value.startsWith('\\')) {
+    violations.push(`${label}「${value}」不得为绝对路径`);
+  }
+
+  if (value.includes('\\')) {
+    violations.push(`${label}「${value}」不得包含反斜杠（须为 posix 相对路径）`);
+  }
+
+  if (value.split('/').includes('..')) {
+    violations.push(`${label}「${value}」不得包含 .. 上溯段`);
+  }
+}
+
+/**
+ * 校验 glob 基本形态（禁反斜杠、禁绝对路径起首；完整可编译性由引擎 mini-glob
+ * 在加载链路上首编译时把关——本包保持零引擎依赖）
+ *
+ * @param label - 违规消息中的条目标签
+ * @param glob - 待校验 glob
+ * @param violations - 违规消息收集器
+ */
+function checkGlobShape(label: string, glob: string, violations: CrossEntryViolations): void {
+  if (glob.includes('\\')) {
+    violations.push(`${label}「${glob}」不得包含反斜杠`);
+  }
+
+  if (glob.startsWith('/')) {
+    violations.push(`${label}「${glob}」不得以 / 起首（须为仓库相对 glob）`);
+  }
+}
+
+/**
+ * 校验 glob 列表内部查重
+ *
+ * @param label - 列表标签
+ * @param globs - glob 值列表
+ * @param violations - 违规消息收集器
+ */
+function checkGlobUniqueness(
+  label: string,
+  globs: string[],
+  violations: CrossEntryViolations,
+): void {
+  /**
+   * 已见 glob 集合
+   */
+  const seen = new Set<string>();
+
+  for (const glob of globs) {
+    if (seen.has(glob)) {
+      violations.push(`${label} 存在重复 glob「${glob}」`);
+    }
+
+    seen.add(glob);
+  }
+}
+
+/**
+ * 跨条目语义校验
+ *
+ * 校验面：scope key 查重、保留号逐 scope 查重、基线 (file,rule) 查重（lint 与
+ * docs 各自为界）、allowlist 指向已登记 scope 且条目查重、全部 glob 形态与
+ * 查重、audit.roots 与 registryDir 相对路径形态。
+ *
+ * @param config - 解析后配置
+ * @returns 违规消息列表（空列表 = 合法）
+ */
+export function validateCrossEntries(config: LziIssuesConfig): CrossEntryViolations {
+  /**
+   * 违规消息收集器
+   */
+  const violations: CrossEntryViolations = [];
+
+  /**
+   * 已见 scope key 集合
+   */
+  const scopeKeys = new Set<string>();
+
+  config.scopes.forEach((scope, index) => {
+    /**
+     * scope 条目标签
+     */
+    const label = `scopes[${index}]（${scope.key}）`;
+
+    if (scopeKeys.has(scope.key)) {
+      violations.push(`scope key「${scope.key}」重复注册`);
+    }
+
+    scopeKeys.add(scope.key);
+
+    checkRelativePath(`${label}.registryDir`, scope.registryDir, violations);
+
+    /**
+     * 已见保留号集合（逐 scope 命名空间）
+     */
+    const reservedNumbers = new Set<string>();
+
+    for (const entry of scope.numbering.reserved) {
+      if (reservedNumbers.has(entry.number)) {
+        violations.push(`${label} 保留号「${entry.number}」重复登记`);
+      }
+
+      reservedNumbers.add(entry.number);
+    }
+  });
+
+  /**
+   * lint 基线 (file,rule) 查重
+   */
+  const lintBaselinePairs = new Set<string>();
+
+  for (const entry of config.lint.baseline) {
+    /**
+     * 基线条目配对键
+     */
+    const pair = `${entry.file}::${entry.rule}`;
+
+    if (lintBaselinePairs.has(pair)) {
+      violations.push(`lint.baseline 条目（${entry.file}, ${entry.rule}）重复`);
+    }
+
+    lintBaselinePairs.add(pair);
+  }
+
+  if (config.docs !== undefined) {
+    /**
+     * docs 基线 (file,rule) 查重
+     */
+    const docsBaselinePairs = new Set<string>();
+
+    for (const entry of config.docs.baseline) {
+      /**
+       * 基线条目配对键
+       */
+      const pair = `${entry.file}::${entry.rule}`;
+
+      if (docsBaselinePairs.has(pair)) {
+        violations.push(`docs.baseline 条目（${entry.file}, ${entry.rule}）重复`);
+      }
+
+      docsBaselinePairs.add(pair);
+    }
+
+    for (const exclusion of config.docs.exclusions) {
+      checkGlobShape(`docs.exclusions`, exclusion.glob, violations);
+    }
+
+    checkGlobUniqueness(
+      'docs.exclusions',
+      config.docs.exclusions.map((e) => e.glob),
+      violations,
+    );
+
+    for (const root of config.docs.scanRoots) {
+      checkRelativePath('docs.scanRoots', root, violations);
+    }
+  }
+
+  /**
+   * allowlist 指向与条目查重
+   */
+  const allowlistKeys = new Set<string>();
+
+  for (const entry of config.numbering.allowlist) {
+    if (!scopeKeys.has(entry.scopeKey)) {
+      violations.push(
+        `numbering.allowlist 条目指向未登记 scope「${entry.scopeKey}」（编号 ${entry.number}）`,
+      );
+    }
+
+    /**
+     * 豁免条目唯一键（scopeKey + number + 排序文件集）
+     */
+    const key = `${entry.scopeKey}::${entry.number}::${[...entry.files].sort().join(',')}`;
+
+    if (allowlistKeys.has(key)) {
+      violations.push(`numbering.allowlist 条目（${entry.scopeKey} ${entry.number}）重复`);
+    }
+
+    allowlistKeys.add(key);
+  }
+
+  for (const exclusion of config.numbering.globalExclusions) {
+    checkGlobShape('numbering.globalExclusions', exclusion.glob, violations);
+  }
+
+  checkGlobUniqueness(
+    'numbering.globalExclusions',
+    config.numbering.globalExclusions.map((e) => e.glob),
+    violations,
+  );
+
+  for (const pending of config.numbering.audit.pending) {
+    checkGlobShape('numbering.audit.pending', pending.glob, violations);
+  }
+
+  checkGlobUniqueness(
+    'numbering.audit.pending',
+    config.numbering.audit.pending.map((e) => e.glob),
+    violations,
+  );
+
+  for (const root of config.numbering.audit.roots) {
+    checkRelativePath('numbering.audit.roots', root, violations);
+  }
+
+  for (const entry of config.slugDigitAllowlist) {
+    checkGlobShape('slugDigitAllowlist', entry.glob, violations);
+  }
+
+  checkGlobUniqueness(
+    'slugDigitAllowlist',
+    config.slugDigitAllowlist.map((e) => e.glob),
+    violations,
+  );
+
+  return violations;
+}
+
+/**
+ * 校验配置并聚合抛错（加载链路统一入口）
+ *
+ * @param config - 解析后配置
+ * @returns 原样返回合法配置（链式便利）
+ * @throws {@link Error} 存在任何跨条目违规（消息聚合全部违规项）
+ */
+export function validateLziIssuesConfig(config: LziIssuesConfig): LziIssuesConfig {
+  /**
+   * 违规消息列表
+   */
+  const violations = validateCrossEntries(config);
+
+  if (violations.length > 0) {
+    throw new Error(`lzi-issues 配置跨条目校验失败：${violations.join('；')}`);
+  }
+
+  return config;
+}