@longzai-intelligence-scripts/config 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+//#region src/types.d.ts
+/**
+ * 定义 lzi-scripts.config.ts 配置结构与真源注册数据契约
+ *
+ * 契约类型与真源仓 `registry/types.ts` 保持结构一致；真源仓发包后真源侧将改为
+ * `import type` 引用本包，消除双定义
+ */
+/**
+ * 注册条目严格级别
+ *
+ * - `required` 违例报错
+ * - `recommended` 违例仅警告
+ */
+type ScriptSeverity = 'required' | 'recommended';
+/**
+ * 标准档案键
+ *
+ * - `root` 产品群根仓基础档案
+ * - `root-engineering` 工程类根仓档案，追加 forbid 族与构建治理族
+ * - `package` 仓内子包档案
+ */
+type ScriptsProfileKey = 'root' | 'root-engineering' | 'package';
+/**
+ * 单条标准脚本注册条目
+ */
+type ScriptEntry = {
+  /**
+   * 脚本名，如 `version:sync`
+   */
+  name: string;
+  /**
+   * 标准命令行原文，如 `lzi-version sync`
+   */
+  definition: string;
+  /**
+   * 严格级别，见 `ScriptSeverity`
+   */
+  severity: ScriptSeverity;
+  /**
+   * 脚本族归属，如 `version`、`changelog`、`forbid`
+   */
+  family: string;
+  /**
+   * 允许的等价命令行列表，命中任一即视为合规
+   */
+  alternatives?: string[];
+};
+/**
+ * 兼伴配置文件注册条目
+ */
+type CompanionEntry = {
+  /**
+   * 相对仓根的文件路径，如 `lzi-version.config.ts`
+   */
+  path: string;
+  /**
+   * 严格级别，同脚本条目口径
+   */
+  severity: ScriptSeverity;
+  /**
+   * 登记依据，如 `ADR 0097 决策 9`
+   */
+  reason: string;
+};
+/**
+ * 遗留死链映射条目
+ */
+type LegacyMapping = {
+  /**
+   * 遗留命令前缀，如 `lzi-dev-cli version sync`
+   */
+  legacyPrefix: string;
+  /**
+   * 对应的标准脚本名，如 `version:sync`
+   */
+  targetScript: string;
+  /**
+   * 新命令行所属的 npm 包名，供改写后的依赖补装提示
+   */
+  targetPackage: string;
+  /**
+   * 迁出说明，供违例报告展示
+   */
+  note: string;
+};
+/**
+ * 真源仓注册数据整体形状（真源仓 `registry/index.ts` 的 default export 类型）
+ */
+type ScriptsRegistryData = {
+  /**
+   * 数据格式版本，当前为 1
+   */
+  formatVersion: 1;
+  /**
+   * 各档案的标准脚本条目集合
+   */
+  profiles: Partial<Record<ScriptsProfileKey, ScriptEntry[]>>;
+  /**
+   * 兼伴配置文件条目集合
+   */
+  companions: CompanionEntry[];
+  /**
+   * 遗留死链映射条目集合
+   */
+  legacyMappings: LegacyMapping[];
+};
+/**
+ * 就地配置的单条豁免声明
+ */
+type ExemptionDeclaration = {
+  /**
+   * 豁免的脚本名列表
+   */
+  scripts: string[];
+  /**
+   * 豁免理由（必填，审计报告原样展示）
+   */
+  reason: string;
+};
+/**
+ * 就地配置的单条等价形态追加
+ */
+type AlternativeDeclaration = {
+  /**
+   * 追加等价形态的脚本名
+   */
+  script: string;
+  /**
+   * 该仓合法的命令行形态
+   */
+  definition: string;
+};
+/**
+ * lzi-scripts.config.ts 配置根类型
+ */
+type LziScriptsConfig = {
+  /**
+   * 真源仓路径指针（相对或绝对），进入真源解析链第二优先级
+   */
+  registryRoot?: string;
+  /**
+   * 显式指定审计档案，缺省按 `workspaces` 有无自动判定
+   */
+  profile?: ScriptsProfileKey;
+  /**
+   * 豁免声明列表，豁免必须附理由
+   */
+  exempt?: ExemptionDeclaration[];
+  /**
+   * 等价形态追加列表
+   */
+  extraAlternatives?: AlternativeDeclaration[];
+};
+/**
+ * 配置加载结果
+ */
+type ScriptsConfigResult = {
+  /**
+   * 加载后的配置对象（无配置文件时为空对象走全缺省）
+   */
+  config: LziScriptsConfig;
+  /**
+   * 命中的配置文件绝对路径（同时用于推导目标仓根目录），无配置时为 null
+   */
+  configPath: string | null;
+};
+//#endregion
+//#region src/define.config.d.ts
+/**
+ * lzi-scripts 配置工厂（恒等返回，仅提供类型约束）
+ *
+ * @param config - 配置对象，缺省为空对象（全字段走默认值）
+ * @returns 原样返回的配置对象
+ */
+declare const defineConfig: (config?: LziScriptsConfig) => LziScriptsConfig;
+//#endregion
+//#region src/load.config.d.ts
+/**
+ * 自起点目录逐级上溯查找就地配置文件
+ *
+ * @param startDir - 发现起点目录（单仓检查为 cwd，跨仓普查为各项目目录）
+ * @returns 命中的配置文件绝对路径，未找到返回 null
+ */
+declare const findScriptsConfigFile: (startDir: string) => string | null;
+/**
+ * 加载就地配置
+ *
+ * @param startDir - 发现起点目录，缺省为进程 cwd
+ * @returns 配置加载结果；未找到配置文件时返回空配置且 `configPath` 为 null
+ * @throws {@link Error} 配置文件存在但动态加载失败或 default export 形态非法
+ */
+declare const loadScriptsConfig: (startDir?: string) => Promise<ScriptsConfigResult>;
+//#endregion
+//#region src/registry-resolution.utils.d.ts
+/**
+ * 真源命中来源（解析链层级）
+ */
+type RegistrySource = 'explicit' | 'config' | 'env' | 'sibling';
+/**
+ * 解析完成的真源（数据 + 根路径 + 来源）
+ */
+type ResolvedRegistry = {
+  /**
+   * 运行时守卫规整后的注册数据
+   */
+  data: ScriptsRegistryData;
+  /**
+   * 真源仓根绝对路径
+   */
+  root: string;
+  /**
+   * 命中的解析链层级
+   */
+  source: RegistrySource;
+};
+/**
+ * 将未知值规整为真源注册数据
+ *
+ * 只接受普通对象并逐层校验 profiles、companions、legacyMappings，不合法字段被忽略
+ * （等效空集），`formatVersion` 非 1 视为整体非法
+ *
+ * @param value - 真源 default export 的未知值
+ * @returns 规整后的注册数据，非法时返回 null
+ */
+declare const asRegistryData: (value: unknown) => ScriptsRegistryData | null;
+/**
+ * 真源解析选项
+ */
+type ResolveRegistryOptions = {
+  /**
+   * `--registry` 显式指定的真源根目录
+   */
+  explicit?: string;
+  /**
+   * 就地配置的 `registryRoot` 指针
+   */
+  configRoot?: string;
+  /**
+   * 目标仓根目录（兄弟目录约定以其父目录为基准）
+   */
+  repoDir: string;
+};
+/**
+ * 解析真源仓并加载注册数据
+ *
+ * @param options - 解析选项
+ * @returns 解析结果；全链未命中返回 null
+ */
+declare const resolveRegistry: (options: ResolveRegistryOptions) => Promise<ResolvedRegistry | null>;
+//#endregion
+export { type AlternativeDeclaration, type CompanionEntry, type ExemptionDeclaration, type LegacyMapping, type LziScriptsConfig, type RegistrySource, type ResolveRegistryOptions, type ResolvedRegistry, type ScriptEntry, type ScriptSeverity, type ScriptsConfigResult, type ScriptsProfileKey, type ScriptsRegistryData, asRegistryData, defineConfig, findScriptsConfigFile, loadScriptsConfig, resolveRegistry };

package/dist/index.js

@@ -0,0 +1 @@
+import{existsSync as e}from"node:fs";import{dirname as t,isAbsolute as n,join as r,resolve as i}from"node:path";const a=(e={})=>e,o=[`root`,`root-engineering`,`package`],s=a=>{let o=n(a)?a:i(process.cwd(),a);for(;o!==`/`;){let n=r(o,`lzi-scripts.config.ts`);if(e(n))return n;o=t(o)}return null},c=e=>typeof e==`object`&&!!e&&!Array.isArray(e),l=e=>typeof e==`string`&&o.includes(e),u=e=>Array.isArray(e)&&e.every(e=>typeof e==`string`),d=e=>{if(!c(e))return{};let t={};typeof e.registryRoot==`string`&&(t.registryRoot=e.registryRoot),l(e.profile)&&(t.profile=e.profile);let n=[];if(Array.isArray(e.exempt))for(let t of e.exempt)c(t)&&u(t.scripts)&&typeof t.reason==`string`&&t.reason.length>0&&n.push({scripts:t.scripts,reason:t.reason});n.length>0&&(t.exempt=n);let r=[];if(Array.isArray(e.extraAlternatives))for(let t of e.extraAlternatives)c(t)&&typeof t.script==`string`&&typeof t.definition==`string`&&r.push({script:t.script,definition:t.definition});return r.length>0&&(t.extraAlternatives=r),t},f=async(e=process.cwd())=>{let t=s(e);if(t===null)return{config:{},configPath:null};try{let e=await import(t),n=typeof e==`object`&&e&&`default`in e?e.default:e;if(typeof n!=`object`||!n||Array.isArray(n))throw Error(`配置 default export 须为对象: ${t}`);return{config:d(n),configPath:t}}catch(e){throw e instanceof Error&&e.message.startsWith(`配置 default export`)?e:Error(`加载配置文件失败: ${t} ${e instanceof Error?e.message:String(e)}`)}},p=r(`registry`,`index.ts`),m=e=>typeof e==`string`,h=e=>typeof e==`object`&&!!e&&!Array.isArray(e),g=e=>Array.isArray(e)&&e.every(e=>typeof e==`string`),_=e=>e===`required`||e===`recommended`,v=e=>{if(!h(e)||!m(e.name)||!m(e.definition)||!m(e.family)||!_(e.severity)||e.alternatives!==void 0&&!g(e.alternatives))return null;let t={name:e.name,definition:e.definition,severity:e.severity,family:e.family};return e.alternatives!==void 0&&(t.alternatives=e.alternatives),t},y=e=>{if(!h(e)||e.formatVersion!==1)return null;let t={};if(h(e.profiles))for(let[n,r]of Object.entries(e.profiles)){if(n!==`root`&&n!==`root-engineering`&&n!==`package`)continue;let e=[];if(Array.isArray(r))for(let t of r){let n=v(t);n!==null&&e.push(n)}t[n]=e}let n=[];if(Array.isArray(e.companions))for(let t of e.companions)h(t)&&m(t.path)&&m(t.reason)&&_(t.severity)&&n.push({path:t.path,severity:t.severity,reason:t.reason});let r=[];if(Array.isArray(e.legacyMappings))for(let t of e.legacyMappings)h(t)&&m(t.legacyPrefix)&&m(t.targetScript)&&m(t.targetPackage)&&m(t.note)&&r.push({legacyPrefix:t.legacyPrefix,targetScript:t.targetScript,targetPackage:t.targetPackage,note:t.note});return{formatVersion:1,profiles:t,companions:n,legacyMappings:r}},b=async t=>{let a=n(t)?t:i(process.cwd(),t),o=r(a,p);if(!e(o))return null;try{let e=await import(o),t=typeof e==`object`&&e&&`default`in e?e.default:e;return y(t)}catch{return null}},x=async e=>{if(e.explicit!==void 0&&e.explicit!==``){let t=await b(e.explicit);return t===null?null:{data:t,root:i(process.cwd(),e.explicit),source:`explicit`}}if(e.configRoot!==void 0&&e.configRoot!==``){let t=await b(i(e.repoDir,e.configRoot));if(t!==null)return{data:t,root:i(e.repoDir,e.configRoot),source:`config`}}let n=process.env.LZI_SCRIPTS_REGISTRY_ROOT;if(n!==void 0&&n!==``){let e=await b(n);if(e!==null)return{data:e,root:i(n),source:`env`}}let a=r(t(e.repoDir),`longzai-intelligence-scripts-registry`),o=await b(a);return o===null?null:{data:o,root:a,source:`sibling`}};export{y as asRegistryData,a as defineConfig,s as findScriptsConfigFile,f as loadScriptsConfig,x as resolveRegistry};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@longzai-intelligence-scripts/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Longzai Intelligence 标准脚本审计配置类型定义与加载器（lzi-scripts.config.ts）",
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "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 --pass-with-no-tests",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26.2.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.