wukong-gitlog-cli 0.0.1

package/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 100

package/.eslintignore

@@ -0,0 +1,8 @@
+/node_modules/**
+/build
+/dist
+/Doc
+/bin/
+/src/lib
+/backup
+#/src/**/*.zx.mjs

package/.eslintrc

@@ -0,0 +1,62 @@
+{
+  "env": {
+    "browser": true,
+    "es6": true,
+    "node": true
+  },
+  "extends": ["airbnb-base", "plugin:prettier/recommended"],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "globals": {
+    "GLOBAL": "writable",
+    "$": "readonly",
+    "cd": "readonly",
+    "fetch": "readonly",
+    "question": "readonly",
+    "chalk": "readonly",
+    "argv": "readonly"
+  },
+  "plugins": ["prettier"],
+  "rules": {
+    "array-callback-return": "off",
+    "consistent-return": "off",
+    "no-await-in-loop": "warn",
+    "no-unused-vars": "warn",
+    "no-console": "off",
+    "no-plusplus": "off",
+    "no-unresolved": "off",
+    "import/no-unresolved": "off",
+    "import/no-named-as-default": "off",
+    "no-restricted-syntax": "off",
+    "no-underscore-dangle": "off",
+    "no-unused-expressions": "off",
+    "no-useless-constructor": "warn",
+    "no-useless-escape": "off",
+    "prettier/prettier": "off",
+    "import/prefer-default-export": "off",
+    "import/no-named-as-default-member": "off",
+    "import/extensions": "off",
+    "import/no-extraneous-dependencies": [
+      "off",
+      {
+        "devDependencies": true,
+        "peerDependencies": true
+        // optionalDependencies: true,
+        // bundledDependencies: true
+      }
+    ]
+  },
+  "settings": {
+    "import/resolver": {
+      "alias": [["@", "./src"]]
+    }
+  },
+  "overrides": [
+    {
+      "files": ["*.js", "*.mjs"]
+      // ... 其他规则配置
+    }
+  ]
+}

package/.prettierignore

@@ -0,0 +1,13 @@
+# Dependencies
+node_modules
+
+
+build
+
+# Lock files
+package-lock.json
+
+# Misc
+dist
+public
+src/lib

package/.prettierrc

@@ -0,0 +1,21 @@
+{
+  "bracketSpacing": true,
+  "importOrder": [
+    "^./conf(.*)(?<!.css)$",
+    "^(#|#company|#command|#ui|components|#utils|#constants||#lib|utils|config|vendored-lib)(/(.*)(?<!.css)$)",
+    "^(src|@)/(.*)(?<!.css)$",
+    "^[./]",
+    "^api/(.*)(?<!.css)$",
+    "^.+\\.s?css$"
+  ],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true,
+  "jsxBracketSameLine": true,
+  "plugins": ["@trivago/prettier-plugin-sort-imports"],
+  "printWidth": 80,
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "useTabs": false
+}

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
+
+### 0.0.1 (2025-11-26)
+
+
+### Features
+
+* 🎸 文件结构优化 ([2bcedad](https://github.com/tomatobybike/wukong-gitlog-cli/commit/2bcedad8c8df7f41e0c8a03cb951c783343037b7))
+* 🎸 增加output目录 ([c5bdf9d](https://github.com/tomatobybike/wukong-gitlog-cli/commit/c5bdf9d4f52f39bd7d580318bafc8ba4b6c129bc))
+* 🎸 init ([ea82531](https://github.com/tomatobybike/wukong-gitlog-cli/commit/ea8253186a2fbf968c04b501ce180afc788e7b0f))
+* 🎸 package.json ([5b6e1d4](https://github.com/tomatobybike/wukong-gitlog-cli/commit/5b6e1d49cf61a4254584a4e1e737099db2e4adba))
+* 🎸 script ([94ea5e1](https://github.com/tomatobybike/wukong-gitlog-cli/commit/94ea5e1c5c6338f5da51d3e59aae059a98a333ac))
+
+
+### Bug Fixes
+
+* 🐛 eslint ([9edf3cb](https://github.com/tomatobybike/wukong-gitlog-cli/commit/9edf3cb94bafe65c2eb94a22bb68f9b3fb9a9b9b))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [杨琼]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# wukong-gitlog-cli
+
+Advanced Git commit log exporter with Excel/JSON/TXT output, grouping, stats and CLI.
+
+---
+
+## Features
+
+- Export commit logs to JSON / text or Excel (XLSX)
+- Group commits by date (day / month)
+- Include a daily stats sheet in Excel
+- Optional Gerrit links per commit (custom template or prefix)
+- Small, dependency-friendly CLI using ZX and ExcelJS
+
+---
+
+## What's new
+
+- `--gerrit` option to show Gerrit links in text/excel/json output
+- `--out-dir` / `--out-parent` to control where output files are written (useful to avoid committing generated files)
+- `npm` demo scripts for quickly running examples (`cli:text-demo`, `cli:excel-demo`, `cli:json-demo`, `cli:gerrit-demo` and parent variants)
+- `src/utils` restructured with `src/utils/index.mjs` barrel to simplify imports
+
+---
+
+## Installation
+
+Clone and install dependencies:
+
+```bash
+git clone https://github.com/tomatoboy/wukong-gitlog-cli.git
+cd wukong-gitlog-cli
+npm install
+```
+
+Run from the repo using Node:
+
+```bash
+node ./src/cli.mjs --help
+```
+
+(Optional) Install globally to run with a short command:
+
+```bash
+npm link
+# then you can run
+wukong-gitlog-cli --help
+```
+
+---
+
+## Usage
+
+```bash
+node ./src/cli.mjs [options]
+```
+
+Command-line options:
+
+- `--author <name>`        Filter commits by author name
+- `--email <email>`        Filter commits by author email
+- `--since <date>`         Start date (e.g., 2025-01-01)
+- `--until <date>`         End date
+- `--limit <n>`            Limit number of commits
+- `--no-merges`            Exclude merge commits
+- `--json`                 Output JSON
+- `--format <type>`        Output format: `text` | `excel` | `json` (default: `text`)
+- `--group-by <type>`      Group commits by date: `day` | `month`
+- `--stats`                Include a `Stats` sheet in the Excel export
+- `--gerrit <prefix>`      Show Gerrit URL for each commit (supports templates `{{hash}}` and `{{changeId}}`; `{{changeId}}` falls back to `hash` when absent)
+- `--out <file>`           Output file name (without path). Defaults: `commits.json` / `commits.txt` / `commits.xlsx`
+- `--out-dir <dir>`      Output directory path — supports relative or absolute path, e.g., `--out-dir ../output`
+- `--out-parent`         Place output in the parent directory's `output/` folder (same as `--out-dir ../output`)
+
+> Output files are written to an `output/` directory in the current working directory.
+>
+> Tip: Use `--out-parent` or `--out-dir ../output` to write outputs into the parent folder's `output/` to avoid accidentally committing generated files to your repository.
+
+---
+
+## Gerrit support
+
+Use the `--gerrit` option to include a Gerrit link for each commit. You can provide a template containing `{{hash}}` to place the full commit hash into the URL, for example:
+
+```bash
+node ./src/cli.mjs --gerrit "https://gerrit.example.com/c/project/+/{{hash}}" --limit 5 --format text
+```
+
+If `{{hash}}` is not present, the CLI will append the commit hash to the prefix with a `/` separator.
+
+You can also use `{{changeId}}` in the template to reference Gerrit change id. The tool will try to extract a `Change-Id: I...` value from the commit body and replace `{{changeId}}` with it. If it can't find a `Change-Id`, the CLI will fall back to using the commit `hash`.
+
+The Gerrit link will show up in:
+
+- The text output if `--format text` (as a new `Gerrit` column)
+- The Excel export as a `Gerrit` column if `--format excel`
+- JSON output will include a `gerrit` field for each record when `--gerrit` is used
+- JSON output will include a `gerrit` field for each record when `--gerrit` is used
+- When `--gerrit` uses `{{changeId}}`, the CLI will try to extract `Change-Id:` from the commit body and include `changeId` and `body` in the JSON record. If no `Change-Id` is present, the CLI falls back to `hash` when forming the Gerrit URL.
+
+Note: `--out <file>` is the filename only and the directory used to store that file depends on:
+
+- The default directory `./output/` in the current working directory
+- `--out-dir <dir>` to override the target folder (relative or absolute)
+- `--out-parent` to write to the parent repository folder `../output/` (same as `--out-dir ../output`)
+
+For example:
+
+```bash
+node ./src/cli.mjs --out parent.json --out-parent
+node ./src/cli.mjs --out demo.txt --out-dir ../temp
+```
+
+---
+
+## Examples
+
+Export as text, grouped by month, with Gerrit links:
+
+```bash
+node ./src/cli.mjs --format text --group-by month --gerrit "https://gerrit.example.com/c/project/+/{{hash}}"
+```
+
+Export to Excel with stats and Gerrit URLs:
+
+```bash
+node ./src/cli.mjs --format excel --stats --gerrit "https://gerrit.example.com/c/project/+/{{hash}}"
+```
+
+Export raw JSON:
+
+```bash
+node ./src/cli.mjs --json --out commits.json
+```
+
+Export text to a custom directory (parent output folder):
+
+```bash
+node ./src/cli.mjs --out-dir ../output --format text --limit 5 --out custom1.txt
+```
+
+---
+
+## Quick demo (npm scripts)
+
+We provided a few convenient npm scripts to quickly run common scenarios. Run them from the project root:
+
+```bash
+# show help
+npm run cli:help
+
+# simple text export (commits.txt in ./output)
+npm run cli:text-demo
+
+# Excel export with stats (commits.xlsx + commits.txt in ./output)
+npm run cli:excel-demo
+
+# JSON export (commits.json in ./output)
+npm run cli:json-demo
+
+# Gerrit text export demo
+npm run cli:gerrit-demo
+# Gerrit Change-Id demo (use commit Change-Id to build Gerrit URLs when present)
+npm run cli:gerrit-changeid-demo
+```
+
+If you prefer to write output outside the project (e.g., a parent `output/` folder), we also provide `npm` scripts that run with `--out-parent`:
+
+```bash
+# text export to parent `output/`
+npm run cli:text-demo-parent
+
+# excel export to parent `output/`
+npm run cli:excel-demo-parent
+```
+
+Example text output (from `npm run cli:text-demo`):
+
+```text
+Hash       | Author             | Date                 | Message
+---------------------------------------------------------------------------------------------------------------------
+c5bdf9d4   | tom                | 2025-11-25           | feat: 🎸 增加output目录
+
+ea82531   | tom                | 2025-11-25           | feat: 🎸 init
+
+741de50   | tom                | 2025-11-25           | first commit
+```
+
+Example JSON output (from `npm run cli:json-demo`):
+
+```json
+[
+  {
+    "hash": "c5bdf9d4f52f39bd7d580318bafc8ba4b6c129bc",
+    "author": "tom",
+    "email": "",
+    "date": "2025-11-25 17:24:32 +0800",
+    "message": "feat: 🎸 增加output目录"
+  }
+  /* truncated... */
+]
+```
+
+Example JSON output including `changeId`/`gerrit` when `--gerrit` uses `{{changeId}}` (if present in commit):
+
+```json
+[
+  {
+    "hash": "Iabc...",
+    "author": "tom",
+    "email": "",
+    "date": "2025-11-25 17:24:32 +0800",
+    "message": "feat: add feature",
+    "body": "feat: add feature\n\nChange-Id: Iabcd123456789",
+    "changeId": "Iabcd123456789",
+    "gerrit": "https://gerrit.example.com/c/project/+/Iabcd123456789"
+  }
+]
+```
+
+---
+
+## Notes & Developer Info
+
+- The CLI prints helpful messages after exporting files and writes outputs to the `output/` folder in the repo root.
+- Internally `src/utils/index.mjs` acts as a barrel that re-exports helper functions located in `src/utils/`.
+- If you plan to reuse the helpers in other modules, import from `./src/utils/index.mjs` explicitly.
+- The Excel export uses `exceljs` and adds an ``autoFilter`` to the sheet header.
+
+Suggested `.gitignore` snippet (to avoid accidentally committing generated files):
+
+```gitignore
+# ignore commit exports
+output/
+custom-output/
+```
+
+---
+
+## Contributing
+
+PRs are welcome — add tests and keep changes modular. If you add new CLI flags or new fields in commit records, please update this README accordingly.
+
+---
+
+## License
+
+MIT
+

package/bin/wukong-gitlog-cli

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/cli.mjs');

package/jsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "checkJs": false,
+    "allowJs": true,
+    "module": "esnext",
+    "target": "esnext",
+    "moduleResolution": "Node",
+
+    "allowSyntheticDefaultImports": true,
+    "paths": {
+      "#src/*": ["src/*"],
+      "#utils/*": ["src/utils/*"]
+    }
+  },
+
+  "include": ["src", "bin"],
+
+  "exclude": ["node_modules", "dist", "build", "**/*.test.js"]
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "wukong-gitlog-cli",
+  "version": "0.0.1",
+  "description": "Advanced Git commit log exporter with Excel/JSON/TXT output, grouping, stats and CLI.",
+  "keywords": [
+    "git",
+    "gitlog",
+    "commit-log",
+    "commits",
+    "gerrit",
+    "excel",
+    "json",
+    "text",
+    "cli",
+    "export",
+    "commit-logs",
+    "wukong-gitlog",
+    "提交",
+    "提交记录",
+    "提交日志",
+    "导出",
+    "命令行工具",
+    "Excel导出",
+    "JSON导出",
+    "文本导出",
+    "Gerrit链接"
+  ],
+  "homepage": "https://tomatobybike.github.io/wukong-gitlog-cli/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomatobybike/wukong-gitlog-cli"
+  },
+  "license": "MIT",
+  "author": "Tom <tomatobybike@gmail.com>",
+  "type": "module",
+  "bin": {
+    "wukong-gitlog-cli": "./bin/wukong-gitlog-cli"
+  },
+  "scripts": {
+    "cli:excel-demo": "node ./src/cli.mjs --format excel --stats --limit 5 --out commits.xlsx",
+    "cli:excel-demo-parent": "node ./src/cli.mjs --out-parent --format excel --stats --limit 5 --out commits-parent.xlsx",
+    "cli:gerrit-changeid-demo": "node ./src/cli.mjs --format text --gerrit \"https://gerrit.example.com/c/project/+/{{changeId}}\" --limit 5 --out commits-gerrit-changeid.txt",
+    "cli:gerrit-demo": "node ./src/cli.mjs --format text --gerrit \"https://gerrit.example.com/c/project/+/{{hash}}\" --limit 5 --out commits-gerrit.txt",
+    "cli:help": "node ./src/cli.mjs --help",
+    "cli:json-demo": "node ./src/cli.mjs --json --limit 5 --out commits.json",
+    "cli:text-demo": "node ./src/cli.mjs --format text --limit 5 --out commits.txt",
+    "cli:text-demo-parent": "node ./src/cli.mjs --out-parent --format text --limit 5 --out commits-parent.txt",
+    "format": "prettier --write \"src/**/*.{js,mjs}\"",
+    "lint": "eslint src --ext .js,.mjs src",
+    "lint:fix": "eslint src --ext .js,.mjs --fix",
+    "pack": "npm pack",
+    "build": "node scripts/esbuild.config.mjs",
+    "prepare": "husky install",
+    "prettierall": "npx prettier --write 'src/**/*.{js,jsx}'",
+    "prepublishOnly": "yarn lint && yarn build",
+    "release": "yarn release:patch && yarn push:tags && npm publish",
+    "push:tags": "git push origin main --follow-tags",
+    "release:major": "yarn lint && standard-version --release-as major",
+    "release:minor": "yarn lint && standard-version --release-as minor",
+    "release:patch": "yarn lint && standard-version --release-as patch",
+    "sort": "sort-package-json"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "package.json": [
+      "sort-package-json"
+    ],
+    "src/**/*.js": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "dayjs": "^1.11.10",
+    "exceljs": "^4.4.0",
+    "zx": "^7.2.3"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "5.2.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "eslint": "8.57.1",
+    "eslint-config-airbnb-base": "15.0.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-alias": "1.1.2",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-simple-import-sort": "12.1.1",
+    "prettier": "3.6.2",
+    "prettier-plugin-packagejson": "2.5.19",
+    "sort-package-json": "3.4.0",
+    "standard-version": "9.5.0"
+  }
+}

package/scripts/esbuild.config.mjs

@@ -0,0 +1 @@
+console.log('✅ Build finished')

package/src/cli.mjs

@@ -0,0 +1,112 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import path from 'path';
+import { getGitLogs } from './git.mjs';
+import { renderText } from './text.mjs';
+import { exportExcel } from './excel.mjs';
+import { groupRecords, writeJSON, writeTextFile, outputFilePath } from './utils/index.mjs';
+
+const program = new Command();
+
+program
+  .name('git-commits')
+  .description('Advanced Git commit log exporter.')
+  .option('--author <name>', '指定 author 名')
+  .option('--email <email>', '指定 email')
+  .option('--since <date>', '起始日期')
+  .option('--until <date>', '结束日期')
+  .option('--limit <n>', '限制数量', parseInt)
+  .option('--no-merges', '不包含 merge commit')
+  .option('--json', '输出 JSON')
+  .option('--format <type>', '输出格式: text | excel | json', 'text')
+  .option('--group-by <type>', '按日期分组: day | month')
+  .option('--stats', '输出每日统计数据')
+  .option('--gerrit <prefix>', '显示 Gerrit 地址，支持在 prefix 中使用 {{hash}} 占位符')
+  .option('--out <file>', '输出文件名（不含路径）')
+  .option('--out-dir <dir>', '自定义输出目录，支持相对路径或绝对路径，例如 `--out-dir ../output`')
+  .option('--out-parent', '将输出目录放到当前工程的父目录的 `output/`（等同于 `--out-dir ../output`）')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  let records = await getGitLogs(opts);
+
+  // compute output directory root if user provided one or wants parent
+  const outDir = opts.outParent
+    ? path.resolve(process.cwd(), '..', 'output')
+    : opts.outDir || undefined;
+
+  // --- Gerrit 地址处理（若提供） ---
+  if (opts.gerrit) {
+    const prefix = opts.gerrit;
+    // create new array to avoid mutating function parameters (eslint: no-param-reassign)
+    records = records.map(r => {
+      let gerritUrl;
+      if (prefix.includes('{{changeId}}')) {
+        const changeId = r.changeId || r.hash;
+        gerritUrl = prefix.replace('{{changeId}}', changeId);
+      } else if (prefix.includes('{{hash}}')) {
+        gerritUrl = prefix.replace('{{hash}}', r.hash);
+      } else {
+        // append hash to prefix, ensure slash handling
+        gerritUrl = prefix.endsWith('/') ? `${prefix}${r.hash}` : `${prefix}/${r.hash}`;
+      }
+
+      return { ...r, gerrit: gerritUrl };
+    });
+  }
+
+  // --- 分组 ---
+  const groups = opts.groupBy ? groupRecords(records, opts.groupBy) : null;
+
+  // --- JSON ---
+  if (opts.json || opts.format === 'json') {
+    const file = opts.out || 'commits.json';
+    const filepath = outputFilePath(file, outDir);
+
+    writeJSON(filepath, groups || records);
+    console.log(chalk.green(`JSON 已导出: ${filepath}`));
+    return;
+  }
+
+  // --- TEXT ---
+  if (opts.format === 'text') {
+    const file = opts.out || 'commits.txt';
+    const filepath = outputFilePath(file, outDir);
+
+    const text = renderText(records, groups, { showGerrit: !!opts.gerrit });
+    writeTextFile(filepath, text);
+
+    console.log(text);
+    console.log(chalk.green(`文本已导出: ${filepath}`));
+    return;
+  }
+
+  // --- EXCEL（强制同时输出 TXT） ---
+  if (opts.format === 'excel') {
+    // Excel
+    const excelFile = opts.out || 'commits.xlsx';
+    const excelPath = outputFilePath(excelFile, outDir);
+
+    // TXT（自动附带）
+    const txtFile = excelFile.replace(/\.xlsx$/, '.txt');
+    const txtPath = outputFilePath(txtFile, outDir);
+
+    // 导出 Excel 文件
+    await exportExcel(records, groups, {
+      file: excelPath,
+      stats: opts.stats,
+      gerrit: opts.gerrit
+    });
+
+    // 导出文本
+    const text = renderText(records, groups);
+    writeTextFile(txtPath, text);
+
+    console.log(chalk.green(`Excel 已导出: ${excelPath}`));
+    console.log(chalk.green(`文本已自动导出: ${txtPath}`));
+
+
+  }
+})();

package/src/excel.mjs

@@ -0,0 +1,52 @@
+import ExcelJS from 'exceljs';
+import dayjs from 'dayjs';
+
+export async function exportExcel(records, groups, options = {}) {
+  const { file, stats, gerrit } = options;
+
+  const wb = new ExcelJS.Workbook();
+  const ws = wb.addWorksheet('Commits');
+
+  const cols = [
+    { header: 'Hash', key: 'hash', width: 12 },
+    { header: 'Author', key: 'author', width: 20 },
+    { header: 'Email', key: 'email', width: 30 },
+    { header: 'Date', key: 'date', width: 20 },
+    { header: 'Message', key: 'message', width: 80 }
+  ];
+
+  if (gerrit) {
+    cols.push({ header: 'Gerrit', key: 'gerrit', width: 50 });
+  }
+
+  ws.columns = cols;
+
+  (groups ? Object.values(groups).flat() : records).forEach(r =>
+    ws.addRow(r)
+  );
+
+  ws.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: cols.length } };
+
+  // --- stats sheet ---
+  if (stats) {
+    const statWs = wb.addWorksheet('Stats');
+
+    const map = {};
+
+    records.forEach(r => {
+      const d = dayjs(r.date).format('YYYY-MM-DD');
+      map[d] = (map[d] || 0) + 1;
+    });
+
+    statWs.columns = [
+      { header: 'Date', key: 'date', width: 15 },
+      { header: 'Commits', key: 'count', width: 15 }
+    ];
+
+    Object.entries(map).forEach(([d, cnt]) =>
+      statWs.addRow({ date: d, count: cnt })
+    );
+  }
+
+  await wb.xlsx.writeFile(file);
+}

package/src/git.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env zx
+import 'zx/globals'
+
+export async function getGitLogs(opts) {
+  const { author, email, since, until, limit, merges } = opts
+
+  // include subject and full body so we can extract Change-Id from commit message
+  const pretty = '%H%x1f%an%x1f%ae%x1f%ad%x1f%s%x1f%B%x1e'
+
+  const args = ['log', `--pretty=format:${pretty}`, '--date=iso']
+
+  if (author) args.push(`--author=${author}`)
+  if (email) args.push(`--author=${email}`)
+  if (since) args.push(`--since=${since}`)
+  if (until) args.push(`--until=${until}`)
+  if (merges === false) args.push(`--no-merges`)
+  if (limit) args.push(`-n`, `${limit}`)
+
+  // 使用 spread 形式传参，ZX 才会正确处理
+  const { stdout } = await $`git ${args}`.quiet()
+
+  return stdout
+    .split('\x1e')
+    .filter(Boolean)
+    .map((r) => {
+      const f = r.split('\x1f').map((s) => (s || '').trim())
+
+      const hash = f[0]
+      const authorName = f[1]
+      const emailAddr = f[2]
+      const date = f[3]
+      const subject = f[4]
+      const body = f[5] || ''
+
+      // extract Change-Id from commit body (line like "Change-Id: Iabc123...")
+      const [, changeId] = body.match(/Change-Id:\s*(I[0-9a-fA-F]+)/) || []
+
+      return {
+        hash,
+        author: authorName,
+        email: emailAddr,
+        date,
+        message: subject,
+        body,
+        changeId
+      }
+    })
+}

package/src/text.mjs

@@ -0,0 +1,56 @@
+export function renderText(records, groups = null, opts = {}) {
+  const { showGerrit = false } = opts;
+  const pad = (s, n) =>
+    s.length >= n ? `${s.slice(0, n - 1)  }…` : s + ' '.repeat(n - s.length);
+
+  const baseHeader =
+    `${pad('Hash', 10) 
+    } | ${ 
+    pad('Author', 18) 
+    } | ${ 
+    pad('Date', 20) 
+    } | ${ 
+    pad('Message', 60)}`;
+
+  const gerritHeader = showGerrit ? ` | ${  pad('Gerrit', 50)}` : '';
+  const header = baseHeader + gerritHeader;
+
+  const line = '-'.repeat(header.length);
+
+  const rows = [];
+
+  if (groups) {
+    for (const [g, list] of Object.entries(groups)) {
+      rows.push(`\n=== ${g} ===\n`);
+      list.forEach(r => {
+        rows.push(
+          (
+            [
+              pad(r.hash.slice(0, 8), 10),
+              pad(r.author, 18),
+              pad(r.date.replace(/ .+/, ''), 20),
+              pad(r.message, 60)
+            ].join(' | ') +
+            (showGerrit ? ` | ${  pad(r.gerrit || '', 50)}` : '')
+          )
+        );
+      });
+    }
+  } else {
+    records.forEach(r => {
+      rows.push(
+        (
+          [
+            pad(r.hash.slice(0, 8), 10),
+            pad(r.author, 18),
+            pad(r.date.replace(/ .+/, ''), 20),
+            pad(r.message, 60)
+          ].join(' | ') +
+          (showGerrit ? ` | ${  pad(r.gerrit || '', 50)}` : '')
+        )
+      );
+    });
+  }
+
+  return [header, line, ...rows].join('\n');
+}

package/src/utils/file.mjs

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import dayjs from 'dayjs';
+
+export function writeJSON(file, data) {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2), 'utf8');
+}
+
+export function writeTextFile(file, text) {
+  fs.writeFileSync(file, text, 'utf8');
+}
+
+export function groupRecords(records, mode) {
+  const group = {};
+
+  records.forEach(r => {
+    const date = dayjs(r.date);
+
+    const key =
+      mode === 'day'
+        ? date.format('YYYY-MM-DD')
+        : date.format('YYYY-MM');
+
+    if (!group[key]) group[key] = [];
+    group[key].push(r);
+  });
+
+  return group;
+}

package/src/utils/index.mjs

@@ -0,0 +1,2 @@
+export { groupRecords, writeJSON, writeTextFile } from './file.mjs';
+export * from './output.mjs';

package/src/utils/output.mjs

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+
+export function ensureOutputDir(customDir) {
+  // If a custom absolute/relative path is provided, resolve relative to cwd as-is
+  // Otherwise default to `output` inside current working directory.
+  const dir = customDir
+    ? path.resolve(process.cwd(), customDir)
+    : path.resolve(process.cwd(), 'output');
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  return dir;
+}
+
+export function outputFilePath(filename, customDir) {
+  const dir = ensureOutputDir(customDir);
+  return path.join(dir, filename);
+}