@longzai-intelligence-issues/cli 0.0.1 → 0.0.2

package/src/commands/gate.commands.ts

@@ -18,11 +18,11 @@ import * as z from 'zod';
 import { fail, info, loadConfigOrExit, ok, repoRoot, violation } from './context.utils.js';
 
 /**
- * 门禁与观测命令组：lint / numbering / docs / health / triage
+ * 注册表 lint 门禁命令（12 核心规则 + 棘轮基线三态）
  *
- * 判据口径：exit 0 过 / exit 1 违规（报文逐条输出后退出）。
+ * @param program - CLI 程序实例
  */
-export function registerGateCommands(program: Command): void {
+function registerLintCommand(program: Command): void {
   defineCommand(program, {
     name: 'lint',
     description: '注册表 lint（12 核心规则 + 棘轮基线三态）',
@@ -31,33 +31,51 @@ export function registerGateCommands(program: Command): void {
       { flags: '--strict-legacy', description: '旧格式状态行一并计违规' },
       { flags: '--write-baseline', description: '再生棘轮基线（须配 --issue）' },
       { flags: '--issue <issue>', description: '收编指针（write-baseline 必填）' },
+      { flags: '--format <format>', description: 'text | json（json 为机器可读违规清单）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z
-      .object({
-        dir: z.union([z.string(), z.array(z.string())]).optional(),
-        strictLegacy: z.boolean().optional(),
-        writeBaseline: z.boolean().optional(),
-        issue: z.string().optional(),
-        config: z.string().optional(),
-      })
-      .passthrough(),
+    schema: z.looseObject({
+      dir: z.union([z.string(), z.array(z.string())]).optional(),
+      strictLegacy: z.boolean().optional(),
+      writeBaseline: z.boolean().optional(),
+      issue: z.string().optional(),
+      format: z.enum(['text', 'json']).optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置与命中路径
+       */
       const { config, configFilePath } = await loadConfigOrExit(opts.config);
 
       /**
        * 限定目录归一
        */
-      const dirRels = opts.dir === undefined ? undefined : Array.isArray(opts.dir) ? opts.dir : [opts.dir];
+      const dirRels =
+        opts.dir === undefined ? undefined : Array.isArray(opts.dir) ? opts.dir : [opts.dir];
 
       /**
        * strictLegacy 覆盖（命令级旗标优先）
        */
-      const effective = opts.strictLegacy === true ? { ...config, lint: { ...config.lint, strictLegacy: true } } : config;
+      const effective =
+        opts.strictLegacy === true
+          ? { ...config, lint: { ...config.lint, strictLegacy: true } }
+          : config;
 
       if (opts.writeBaseline === true) {
-        const regen = runWriteLintBaseline({ root, config: effective, issuePointer: opts.issue ?? '' });
+        /**
+         * 棘轮基线再生结果
+         */
+        const regen = runWriteLintBaseline({
+          root,
+          config: effective,
+          issuePointer: opts.issue ?? '',
+        });
 
         if (!regen.ok) {
           fail(regen.error);
@@ -68,36 +86,73 @@ export function registerGateCommands(program: Command): void {
         return;
       }
 
+      /**
+       * lint 判定结果（active + stale 违规与基线计数）
+       */
       const result = runLint({ root, config: effective, dirRels });
 
-      for (const v of result.violations) {
-        violation(`${v.file}:${v.line} [${v.rule}] ${v.message}`);
+      if (opts.format === 'json') {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              command: 'issues:lint',
+              ok: result.violations.length === 0,
+              violationCount: result.violations.length,
+              suppressed: result.suppressed,
+              baselineCount: result.baselineCount,
+              violations: result.violations,
+            },
+            null,
+            2,
+          )}\n`,
+        );
+      } else {
+        for (const v of result.violations) {
+          violation(`${v.file}:${v.line} [${v.rule}] ${v.message}`);
+        }
       }
 
       if (result.violations.length > 0) {
-        process.stderr.write(`错误: issues:lint ${result.violations.length} 项违规｜存量豁免 ${result.suppressed}｜基线 ${result.baselineCount} 条\n`);
+        if (opts.format !== 'json') {
+          process.stderr.write(
+            `错误: issues:lint ${result.violations.length} 项违规｜存量豁免 ${result.suppressed}｜基线 ${result.baselineCount} 条\n`,
+          );
+        }
+
         process.exit(1);
       }
 
-      ok(`issues:lint 通过（0 新增违规｜存量豁免 ${result.suppressed}｜基线 ${result.baselineCount} 条）`);
+      if (opts.format !== 'json') {
+        ok(
+          `issues:lint 通过（0 新增违规｜存量豁免 ${result.suppressed}｜基线 ${result.baselineCount} 条）`,
+        );
+      }
     },
   });
+}
 
+/**
+ * 编号门禁命令组（父命令 numbering + next / check / audit 三子命令）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerNumberingCommands(program: Command): void {
   /**
-   * numbering 三子命令
+   * numbering 三子命令共用 schema
    */
-  const numberingSchema = z
-    .object({
-      scope: z.string().optional(),
-      dir: z.string().optional(),
-      config: z.string().optional(),
-    })
-    .passthrough();
+  const numberingSchema = z.looseObject({
+    scope: z.string().optional(),
+    dir: z.string().optional(),
+    format: z.enum(['text', 'json']).optional(),
+    config: z.string().optional(),
+  });
 
   /**
    * numbering 父命令（子命令 next/check/audit）
    */
-  const numbering = program.command('numbering').description('编号门禁（next 取号 / check 判定 / audit 覆盖面审计）');
+  const numbering = program
+    .command('numbering')
+    .description('编号门禁（next 取号 / check 判定 / audit 覆盖面审计）');
 
   defineCommand(numbering, {
     name: 'next',
@@ -105,19 +160,37 @@ export function registerGateCommands(program: Command): void {
     options: [
       { flags: '--scope <scope>', description: '目标 scope key' },
       { flags: '--dir <dir>', description: '目标注册表目录' },
+      { flags: '--format <format>', description: 'text | json（json 为机器可读取号结果）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
     schema: numberingSchema,
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
+      /**
+       * 取号结果（下一可用编号）
+       */
       const result = runNumberingNext({ root, config, scopeKey: opts.scope, dirRel: opts.dir });
 
       if (!result.ok) {
         fail(result.error);
       }
 
+      if (opts.format === 'json') {
+        process.stdout.write(
+          `${JSON.stringify({ command: 'numbering:next', ok: true, target: result.target, number: result.number }, null, 2)}\n`,
+        );
+        return;
+      }
+
       info(`${result.target} 下一可用编号：${result.number}（已跳过保留号与已占用号）`);
     },
   });
@@ -127,55 +200,130 @@ export function registerGateCommands(program: Command): void {
     description: '编号门禁判定（缺省全量；--dir 目录增量）',
     options: [
       { flags: '--dir <dir>', description: '目录增量档' },
+      { flags: '--format <format>', description: 'text | json（json 为机器可读违例清单）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
     schema: numberingSchema,
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
+      /**
+       * 编号门禁判定结果
+       */
       const result = runNumberingCheck({ root, config, dirRel: opts.dir });
 
-      for (const f of result.findings) {
-        violation(`[${f.kind}] ${f.message}`);
+      if (opts.format === 'json') {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              command: 'numbering:check',
+              ok: result.findings.length === 0,
+              scopeCount: result.scopeCount,
+              scannedFiles: result.scannedFiles,
+              findings: result.findings,
+            },
+            null,
+            2,
+          )}\n`,
+        );
+      } else {
+        for (const f of result.findings) {
+          violation(`[${f.kind}] ${f.message}`);
+        }
       }
 
       if (result.findings.length > 0) {
-        process.stderr.write(`错误: numbering:check ${result.findings.length} 项违规（scope ${result.scopeCount} 个 / 扫描面 ${result.scannedFiles} 文件）\n`);
+        if (opts.format !== 'json') {
+          process.stderr.write(
+            `错误: numbering:check ${result.findings.length} 项违规（scope ${result.scopeCount} 个 / 扫描面 ${result.scannedFiles} 文件）\n`,
+          );
+        }
+
         process.exit(1);
       }
 
-      ok(`numbering:check 通过（scope ${result.scopeCount} 个 / 扫描面 ${result.scannedFiles} 文件 / 零违规）`);
+      if (opts.format !== 'json') {
+        ok(
+          `numbering:check 通过（scope ${result.scopeCount} 个 / 扫描面 ${result.scannedFiles} 文件 / 零违规）`,
+        );
+      }
     },
   });
 
   defineCommand(numbering, {
     name: 'audit',
     description: '覆盖面审计（未登记编号区 / pending 失效）',
-    options: [{ flags: '--config <path>', description: '显式配置路径' }],
+    options: [
+      { flags: '--format <format>', description: 'text | json（json 为机器可读发现清单）' },
+      { flags: '--config <path>', description: '显式配置路径' },
+    ],
     schema: numberingSchema,
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
+      /**
+       * 覆盖面审计结果（未登记编号区 / pending 失效）
+       */
       const result = runNumberingAudit({ root, config });
 
-      for (const f of result.findings) {
-        violation(`[${f.kind}] ${f.message}`);
+      if (opts.format === 'json') {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              command: 'numbering:audit',
+              ok: result.findings.length === 0,
+              scannedFiles: result.scannedFiles,
+              findings: result.findings,
+            },
+            null,
+            2,
+          )}\n`,
+        );
+      } else {
+        for (const f of result.findings) {
+          violation(`[${f.kind}] ${f.message}`);
+        }
       }
 
       if (result.findings.length > 0) {
-        process.stderr.write(`错误: numbering:audit ${result.findings.length} 项违规（扫描面 ${result.scannedFiles} 文件）\n`);
+        if (opts.format !== 'json') {
+          process.stderr.write(
+            `错误: numbering:audit ${result.findings.length} 项违规（扫描面 ${result.scannedFiles} 文件）\n`,
+          );
+        }
+
         process.exit(1);
       }
 
-      ok(`numbering:audit 通过（扫描面 ${result.scannedFiles} 文件 / 零未登记编号区）`);
+      if (opts.format !== 'json') {
+        ok(`numbering:audit 通过（扫描面 ${result.scannedFiles} 文件 / 零未登记编号区）`);
+      }
     },
   });
+}
 
-  /**
-   * docs 两子命令
-   */
+/**
+ * 文档 issue 引用检查命令（父命令 docs + 子命令 check）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerDocsCommand(program: Command): void {
   /**
    * docs 父命令（子命令 check / fix）
    */
@@ -189,13 +337,27 @@ export function registerGateCommands(program: Command): void {
       { flags: '--issue <issue>', description: '收编指针' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z.object({ writeBaseline: z.boolean().optional(), issue: z.string().optional(), config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({
+      writeBaseline: z.boolean().optional(),
+      issue: z.string().optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置与命中路径
+       */
       const { config, configFilePath } = await loadConfigOrExit(opts.config);
 
       if (opts.writeBaseline === true) {
         try {
+          /**
+           * docs 基线再生结果
+           */
           const regen = runWriteDocsBaseline({ root, config, issuePointer: opts.issue ?? '' });
 
           if (!regen.ok) {
@@ -211,6 +373,9 @@ export function registerGateCommands(program: Command): void {
       }
 
       try {
+        /**
+         * docs 引用检查结果
+         */
         const result = runDocsCheck({ root, config });
 
         for (const v of result.violations) {
@@ -218,7 +383,9 @@ export function registerGateCommands(program: Command): void {
         }
 
         if (result.violations.length > 0) {
-          process.stderr.write(`错误: docs:check ${result.violations.length} 项违规（扫描面 ${result.scannedFiles} 文件 / 豁免 ${result.suppressed}）\n`);
+          process.stderr.write(
+            `错误: docs:check ${result.violations.length} 项违规（扫描面 ${result.scannedFiles} 文件 / 豁免 ${result.suppressed}）\n`,
+          );
           process.exit(1);
         }
 
@@ -228,32 +395,78 @@ export function registerGateCommands(program: Command): void {
       }
     },
   });
+}
 
+/**
+ * 黄灯巡检命令（状态分布 / 最老账龄 / A-B-C 分类，JSON）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerHealthCommand(program: Command): void {
   defineCommand(program, {
     name: 'health',
     description: '黄灯巡检（状态分布 / 最老账龄 / A-B-C 分类，JSON）',
     options: [{ flags: '--config <path>', description: '显式配置路径' }],
-    schema: z.object({ config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({ config: z.string().optional() }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
       process.stdout.write(`${JSON.stringify(runHealth({ root, config }), null, 2)}\n`);
     },
   });
+}
 
+/**
+ * 黄灯分诊台账命令（append-only 落 .lzi/issues/runs/ledger/）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerTriageCommand(program: Command): void {
   defineCommand(program, {
     name: 'triage',
     description: '黄灯分诊台账（append-only 落 .lzi/issues/runs/ledger/）',
     options: [{ flags: '--config <path>', description: '显式配置路径' }],
-    schema: z.object({ config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({ config: z.string().optional() }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
+      /**
+       * 分诊台账落盘结果（台账文件路径与黄灯条目集）
+       */
       const { ledgerPath, ledger } = runTriage({ root, config });
 
       ok(`issues:triage 台账已落盘: ${ledgerPath}（黄灯 ${ledger.items.length} 项）`);
     },
   });
 }
+
+/**
+ * 门禁与观测命令组：lint / numbering / docs / health / triage
+ *
+ * 判据口径：exit 0 过 / exit 1 违规（报文逐条输出后退出）。
+ *
+ * @param program - CLI 程序实例
+ */
+export function registerGateCommands(program: Command): void {
+  registerLintCommand(program);
+  registerNumberingCommands(program);
+  registerDocsCommand(program);
+  registerHealthCommand(program);
+  registerTriageCommand(program);
+}

package/src/commands/index.ts

@@ -11,6 +11,7 @@ import type { Command } from '@longzai-intelligence-cli/core';
 import { registerCloseCommands } from './close.commands.js';
 import { registerGateCommands } from './gate.commands.js';
 import { registerIssueCommands } from './issue.commands.js';
+import { registerMigrateCommands } from './migrate.commands.js';
 import { registerScaffoldCommands } from './scaffold.commands.js';
 
 /**
@@ -26,4 +27,6 @@ export function registerCommands(program: Command): void {
   registerGateCommands(program);
 
   registerCloseCommands(program);
+
+  registerMigrateCommands(program);
 }