@h5l0/codelens 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codelens contributors
+
+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.en.md

@@ -0,0 +1,137 @@
+# codelens
+
+A local dashboard for any git repository: commit history and lines of code.
+
+English | [简体中文](./README.md)
+
+## Quick start
+
+```bash
+npx @h5l0/codelens                 # analyze the current directory and open the browser
+npx @h5l0/codelens ../my-repo      # analyze another repository
+npx @h5l0/codelens --profile web   # split the calendar into frontend / backend
+```
+
+Or install it globally:
+
+```bash
+npm install -g @h5l0/codelens
+codelens
+```
+
+No configuration is required. Data is generated on the fly at startup, served to your local browser only, and never written into the analyzed repository.
+
+## The two views
+
+### Change calendar
+
+A week-based heatmap: the top bar of each cell is inserted lines, the bottom bar is deleted lines, and bar width uses a square-root scale. Hover a day to see that day's summary and commits, and click it to pin the day (click again to unpin); you can also Tab into the calendar and move between days with the arrow keys. The header switch filters by group, and both the stats cards and the commit list then follow that group. The calendar shows as many weeks as the window fits and never scrolls sideways, sitting flush right with today at the far right; when a repository has been quiet for more than 28 days the right edge stops at the last commit instead. Days before the first commit and after the last one stay in the grid with a paler background. The top row shows the visible date range on the left and the inserted/deleted line legend on the right; the strip along the bottom (it appears only once the history is longer than one screen) has one cell per week, coloured grey to green by that week's inserted lines — the frame sits in the middle and you drag the strip itself to pan (drag right for older weeks), with a fixed opacity gradient at both ends. Stat cards read "Total" on the range and show both the daily average and the peak in their note.
+
+![Change calendar](docs/screenshots/en/calendar.png)
+
+### Lines of code
+
+A treemap where rectangle area is proportional to line count, color is the category, and shade is the directory depth. Click a rectangle to zoom into that directory and use the breadcrumb or Esc to go back; directories you can zoom into in the current view are reachable with Tab and Enter. The switches control the counting mode and expansion depth, and the legend toggles categories.
+
+![Lines of code](docs/screenshots/en/loc.png)
+
+## Command line
+
+```
+codelens [directory] [options]
+
+--profile <name|file>  Profile, see below; built in: all, web
+--config <file>        Config file, defaults to <directory>/codelens.config.json
+--days <days>          Calendar time span, 0 means full history (default 120)
+--exclude <glob>       Extra paths to ignore, repeatable
+--port <port>          Listen port, default 5178, tries the next ports when busy
+--host <address>       Listen address, default 127.0.0.1; other addresses expose the page to your network
+--no-open              Do not open the browser automatically
+--no-gitignore         Ignore .gitignore; only built-in heavy directories are skipped
+--dump <dir>           Write data.json and loc.json, then exit without starting a server
+--dev                  Dev mode with Vite hot reload
+-h, --help             Show help
+-v, --version          Show version
+```
+
+## Profiles
+
+`--profile` decides how the repository is split. Two ways to use it:
+
+1. Point it at a JSON file: `--profile ./my-profile.json`;
+2. Or use a name under `profiles` in `codelens.config.json` (relocate it with `--config`): `--profile web`.
+
+Two profiles are built in:
+
+| Name | What it does |
+| --- | --- |
+| `all` | Default; no grouping, the whole repository is counted together |
+| `web` | Common frontend/backend layout: `frontend/`, `web/`, `client/`, `ui/` and friends count as frontend, everything else as backend |
+
+### Config file format
+
+```jsonc
+{
+  "profiles": {
+    "modules": {
+      "label": "By module",
+      // Calendar groups: a file goes to the first group whose patterns match.
+      // End the list with ["**"] to get an "A / everything else" split.
+      "groups": [
+        { "id": "core", "label": "Core", "hue": 214, "sat": 58, "match": ["src/core/**"] },
+        { "id": "web", "label": "UI", "hue": 152, "sat": 46, "match": ["src/web/**"] },
+        { "id": "other", "label": "Other", "hue": 32, "sat": 62, "match": ["**"] }
+      ],
+      // Line-count categories: drive the legend and colors; the entry without a match is the fallback.
+      "categories": [
+        { "id": "core", "label": "Core code", "hue": 214, "sat": 58, "match": ["src/core/**"] },
+        { "id": "test", "label": "Tests", "hue": 152, "sat": 46, "defaultOn": false, "match": ["**/*.test.ts"] },
+        { "id": "app", "label": "Other code", "hue": 220, "sat": 20 }
+      ],
+      // Extra paths to ignore on top of .gitignore
+      "ignore": ["data/**", "**/*.snap"]
+    }
+  }
+}
+```
+
+Field notes:
+
+- `groups[].match`, `categories[].match` and `ignore` use globs relative to the repository root: `**` crosses directories, `*` does not, `?` matches one character, `{a,b}` matches either; a pattern without `/` matches items of that name at any depth, `/foo` is anchored to the root, and `foo/` means the directory and everything inside it.
+- The config file may contain `//` and `/* */` comments and trailing commas.
+- `groups[].id` must not be the reserved `all` and must be unique within a profile.
+- `hue` and `sat` are HSL color components for group and category colors; they default to 214 and 50.
+- `categories[].defaultOn: false` means the category starts switched off in the legend (of the built-in categories, "generated code", "docs" and "config" start off).
+
+Without `categories`, six built-in ones are used: application code, tests, scripts, docs, config, generated code.
+
+A profile name the config file does not define falls back to the built-in profile: a repository shipping a `codelens.config.json` with only custom profiles still supports `codelens --profile all` and `--profile web`. Only a name missing from both places is an error.
+
+## Counting rules
+
+- `.gitignore` is honored by default; when the directory is not a git repository, equivalent ignore rules are applied instead. `--no-gitignore` turns this off.
+- Dependency and build directories such as `node_modules`, `dist`, `build`, `coverage`, `.venv`, `__pycache__` and `target` are always skipped.
+- `--exclude` and the config's `ignore` apply to both views: excluded directories are neither counted nor attributed in the change calendar.
+- Binary files, files larger than 3MB and empty files are excluded; a file that cannot be read is skipped and reported as a count in the startup log. Line counts are physical lines (a trailing newline does not count as an extra line).
+- Calendar entries are grouped by the day of the commit time (committer date), matching how `--days` filters. "Changed lines = insertions + deletions".
+- Merge commits, empty commits and commits that only change file modes or binaries have no line counts, but they still appear in the commit list and count as commits.
+- When you run it on a subdirectory of a repository, both views count that subdirectory only and resolve paths relative to it.
+
+## Known limits
+
+- The change calendar needs git: a repository without commits, or without git at all, leaves the calendar empty while the lines view still works.
+- Line counts say nothing about code complexity.
+- The treemap draws at most 6000 rectangles; the rest are not shown.
+- The calendar is padded to whole weeks, so a window that does not start or end on a week boundary shows a few extra days without data (with a paler background).
+
+## Languages
+
+The page follows your browser language. Simplified Chinese, English, Japanese and Korean are built in; other languages fall back to English. Append `?lang={langCode}` to the URL to override it for this session, for example `?lang=zh` or `?lang=ko`.
+
+## Development
+
+See [DEV.md](./DEV.md) for the development setup, project layout and release process.
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -0,0 +1,137 @@
+# codelens
+
+把任意 git 仓库的改动历史与代码行数，做成一个本地看板。
+
+[English](./README.en.md) | 简体中文
+
+## 快速开始
+
+```bash
+npx @h5l0/codelens                 # 统计当前目录并在浏览器打开
+npx @h5l0/codelens ../my-repo      # 统计指定仓库
+npx @h5l0/codelens --profile web   # 按前后端拆分改动日历
+```
+
+也可以全局安装后随时使用：
+
+```bash
+npm install -g @h5l0/codelens
+codelens
+```
+
+无需任何配置即可运行。统计数据在启动时现场生成，只提供给本机浏览器，不写入被统计的仓库。
+
+## 两个视图
+
+### 改动日历
+
+按周排布的热力格，每格上条为新增行、下条为删除行，条宽是行数的平方根刻度。鼠标移到某天即可查看当天的统计与提交列表，点一下可以钉住这天（再点取消）；也可以用 Tab 进入日历、用方向键切换日期。顶部开关可按分组过滤，此时统计卡与提交列表都只算该分组。日历一屏铺得下几周就排几周、不横向滚动，整体靠右，最右边是今天；仓库超过 28 天没有提交时，最右边停在最后一次提交那天。第一次提交之前与最后一次提交之后的日子也留在网格里，底色比普通格子更白。顶部一行左边是当前显示的时间范围，右边是新增行与删除行的图例；底部是一条自绘的拖动条（提交多到一屏放不下时才出现），一格一周、颜色从灰到绿表示那一周的新增行数，包裹框固定在条中间，直接拖格子条即可平移窗口（往右拖看更早的周），条的两端固定是一段透明度渐变。统计卡在区间口径下显示「累计」，备注里给出日均与峰值。
+
+![改动日历](docs/screenshots/zh/calendar.png)
+
+### 代码行数
+
+面积树形图，方块面积正比于行数，颜色代表分类，颜色深浅代表目录层级。点击方块放大到该目录，面包屑或 Esc 返回；当前视图里可以直接放大的目录能用 Tab 聚焦、回车放大。右侧开关可切换统计口径与展开层级，图例可切换类别是否计入。
+
+![代码行数](docs/screenshots/zh/loc.png)
+
+## 命令行参数
+
+```
+codelens [目录] [选项]
+
+--profile <名称|文件>  配置档，见下一节，内置 all、web
+--config <文件>        配置文件，默认 <目录>/codelens.config.json
+--days <天数>          改动日历的时间跨度，0 表示全部历史（默认 120）
+--exclude <glob>       额外忽略的路径，可重复
+--port <端口>          监听端口，默认 5178，被占用时向后尝试
+--host <地址>          监听地址，默认 127.0.0.1；监听别的地址时页面对同网段可见
+--no-open              不自动打开浏览器
+--no-gitignore         不按 .gitignore 过滤，只跳过内置的重目录
+--dump <目录>          只写出 data.json 与 loc.json 后退出，不启动服务
+--dev                  开发模式，用 Vite 托管前端源码并热更新
+-h, --help             显示帮助
+-v, --version          显示版本
+```
+
+## 配置档
+
+`--profile` 决定用什么维度切分这个仓库，两种用法：
+
+1. 指向一个 json 文件：`--profile ./my-profile.json`；
+2. 取 `codelens.config.json`（可用 `--config` 换位置）里 `profiles` 下的名字：`--profile web`。
+
+内置两档：
+
+| 名称 | 作用 |
+| --- | --- |
+| `all` | 默认档，不做任何分组，整个仓库一起统计 |
+| `web` | 常见前后端目录：`frontend/`、`web/`、`client/`、`ui/` 等算前端，其余算后端 |
+
+### 配置文件格式
+
+```jsonc
+{
+  "profiles": {
+    "modules": {
+      "label": "按模块",
+      // 改动日历的分组：命中的文件算进该组，按数组顺序取第一个命中的。
+      // 最后一个用 ["**"] 兜底，就能得到「A / 其余」这种两分效果。
+      "groups": [
+        { "id": "core", "label": "核心", "hue": 214, "sat": 58, "match": ["src/core/**"] },
+        { "id": "web", "label": "界面", "hue": 152, "sat": 46, "match": ["src/web/**"] },
+        { "id": "other", "label": "其他", "hue": 32, "sat": 62, "match": ["**"] }
+      ],
+      // 行数视图的分类：决定图例与配色，省略 match 的那一项是兜底类。
+      "categories": [
+        { "id": "core", "label": "核心代码", "hue": 214, "sat": 58, "match": ["src/core/**"] },
+        { "id": "test", "label": "测试", "hue": 152, "sat": 46, "defaultOn": false, "match": ["**/*.test.ts"] },
+        { "id": "app", "label": "其他代码", "hue": 220, "sat": 20 }
+      ],
+      // 在 .gitignore 之外额外忽略的路径
+      "ignore": ["data/**", "**/*.snap"]
+    }
+  }
+}
+```
+
+字段说明：
+
+- `groups[].match`、`categories[].match`、`ignore` 都使用仓库相对路径的 glob：`**` 跨目录，`*` 不跨目录，`?` 匹配单个字符，`{a,b}` 择一；不含 `/` 的模式匹配任意层级的同名项，`/foo` 表示从仓库根起算，`foo/` 表示目录及其全部内容。
+- 配置文件允许写 `//`、`/* */` 注释与尾随逗号。
+- `groups[].id` 不能是保留的 `all`，同一档里不能重复。
+- `hue`、`sat` 为 HSL 颜色分量，用于分组色与分类色，缺省分别为 214、50。
+- `categories[].defaultOn` 为 `false` 表示该分类在页面图例里默认关闭（内置分类中「生成代码」「文档」「配置」默认关闭）。
+
+不写 `categories` 时使用内置的六类：应用代码、测试、脚本、文档、配置、生成代码。
+
+配置文件里没有取到的档名会回退到内置档：仓库里放了一份只定义自定义档的 `codelens.config.json`，`codelens --profile all`、`--profile web` 依然可用；两个地方都没有的档名才会报错。
+
+## 统计口径
+
+- 默认完全遵守仓库的 `.gitignore`；目录不是 git 仓库时改用等价的忽略规则自行过滤。`--no-gitignore` 可关闭该过滤。
+- 任何情况下都跳过 `node_modules`、`dist`、`build`、`coverage`、`.venv`、`__pycache__`、`target` 等依赖与构建目录。
+- `--exclude`、配置里的 `ignore` 对两个视图同时生效：被排除的目录既不进行数统计，改动日历里也不计入。
+- 二进制文件、超过 3MB 的文件、空文件不计入；个别文件读不出来只跳过它，并在启动日志里给出数量。行数为物理行数（文件末尾换行不计一行）。
+- 改动日历按提交时间（committer date）归入所在天，与 `--days` 的过滤口径一致；「改动行数 = 新增 + 删除」。
+- 合并提交、空提交、只改文件权限或只动二进制的提交没有具体行数，但仍会出现在提交列表里并计入提交数。
+- 对仓库的某个子目录运行时，两个视图都只统计该子目录，路径也相对它计算。
+
+## 已知边界
+
+- 改动日历依赖 git，仓库没有提交或缺少 git 时日历为空，行数视图仍可用。
+- 行数视图按文本文件的行数统计，无法反映代码复杂度。
+- 树形图一次最多绘制 6000 个方块，超出的部分不显示。
+- 日历按整周补齐，窗口首尾不足一周时会多画出几天没有数据的格子（底色更白）。
+
+## 多语言
+
+页面语言跟随浏览器，目前内置简体中文、English、日本語、한국어，其余语言回落到英文。地址后加 `?lang={langCode}` 可临时覆盖，例如 `?lang=en`、`?lang=ja`。
+
+## 开发
+
+开发环境、项目结构与发布流程见 [DEV.md](./DEV.md)。
+
+## 许可
+
+[MIT](./LICENSE)

package/dist/cli/args.js

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// 命令行参数
+// ---------------------------------------------------------------------------
+import { builtinProfileNames } from '../core/profile.js';
+const STRING_FLAGS = {
+    '--profile': 'profile',
+    '--config': 'config',
+    '--dump': 'dump',
+    '--host': 'host',
+};
+const NUMBER_FLAGS = {
+    '--days': 'days',
+    '--port': 'port',
+};
+const BOOL_FLAGS = {
+    '--dev': ['dev', true],
+    '--open': ['open', true],
+    '--no-open': ['open', false],
+    '--gitignore': ['useGitignore', true],
+    '--no-gitignore': ['useGitignore', false],
+    '-h': ['help', true],
+    '--help': ['help', true],
+    '-v': ['version', true],
+    '--version': ['version', true],
+};
+/** 主机名、IPv4、IPv6（含方括号与 `%` 作用域）都用得到的字符。 */
+const HOST_RE = /^[A-Za-z0-9._:[\]%-]+$/;
+export function parseArgs(argv) {
+    const args = {
+        dir: '',
+        profile: 'all',
+        config: undefined,
+        days: 120,
+        exclude: [],
+        port: Number(process.env.PORT ?? 5178),
+        host: '127.0.0.1',
+        open: true,
+        useGitignore: true,
+        dump: undefined,
+        dev: false,
+        help: false,
+        version: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const raw = argv[i];
+        const eq = raw.indexOf('=');
+        const flag = eq > 0 ? raw.slice(0, eq) : raw;
+        const inline = eq > 0 ? raw.slice(eq + 1) : undefined;
+        if (BOOL_FLAGS[flag]) {
+            const [key, value] = BOOL_FLAGS[flag];
+            args[key] = inline === undefined ? value : inline !== 'false';
+            continue;
+        }
+        if (flag === '--exclude') {
+            const value = inline ?? argv[++i];
+            if (value === undefined || value === '') {
+                throw new Error('--exclude requires a value');
+            }
+            args.exclude.push(value);
+            continue;
+        }
+        if (STRING_FLAGS[flag]) {
+            const value = inline ?? argv[++i];
+            if (value === undefined || value === '') {
+                throw new Error(`${flag} requires a value`);
+            }
+            args[STRING_FLAGS[flag]] = value;
+            continue;
+        }
+        if (NUMBER_FLAGS[flag]) {
+            const value = inline ?? argv[++i];
+            const num = Number(value);
+            if (value === undefined || value === '' || !Number.isInteger(num) || num < 0) {
+                throw new Error(`${flag} requires a whole number >= 0, got: ${value ?? '(empty)'}`);
+            }
+            args[NUMBER_FLAGS[flag]] = num;
+            continue;
+        }
+        if (raw.startsWith('-') && raw !== '-') {
+            throw new Error(`unknown option: ${raw} (see --help)`);
+        }
+        if (args.dir !== '') {
+            throw new Error(`only one directory argument is accepted, extra: ${raw}`);
+        }
+        args.dir = raw;
+    }
+    if (args.port > 65535) {
+        throw new Error(`--port must be between 0 and 65535, got: ${args.port}`);
+    }
+    // 地址只允许主机名与 IP 里常见的字符，避免把奇怪的值一路带进 URL 与启动命令
+    if (!HOST_RE.test(args.host)) {
+        throw new Error(`--host must be an address or hostname, got: ${args.host}`);
+    }
+    return args;
+}
+/** 选项与说明分两列对齐，说明统一从这里开始的列。 */
+const FLAG_COL = 23;
+/** 示例比选项长，用更宽的一列。 */
+const EXAMPLE_COL = 35;
+const row = (left, text, width = FLAG_COL) => `  ${left.padEnd(width)}${text}`;
+export function helpText() {
+    return `codelens: visualize a git repository's change history and lines of code in a local dashboard
+
+Usage
+  codelens [directory] [options]
+
+Options
+${row('--profile <name|file>', `Profile: built in ${builtinProfileNames().join(', ')}, or a custom json file`)}
+${row('--config <file>', 'Config file, defaults to <directory>/codelens.config.json')}
+${row('--days <days>', 'Calendar span, 0 for full history (default 120)')}
+${row('--exclude <glob>', 'Extra ignored paths, repeatable')}
+${row('--port <port>', 'Listen port, default 5178, tries the next ports when busy')}
+${row('--host <address>', 'Listen address, default 127.0.0.1')}
+${row('--no-open', 'Do not open the browser automatically')}
+${row('--no-gitignore', 'Ignore .gitignore; only built-in heavy directories are skipped')}
+${row('--dump <dir>', 'Write data.json and loc.json to <dir>, then exit')}
+${row('--dev', 'Dev mode with Vite hot reload')}
+${row('-h, --help', 'Show help')}
+${row('-v, --version', 'Show version')}
+
+Examples
+${row('npx @h5l0/codelens', 'analyze the current directory', EXAMPLE_COL)}
+${row('npx @h5l0/codelens ../my-repo', 'analyze another repository', EXAMPLE_COL)}
+${row('npx @h5l0/codelens --profile web', 'split the calendar into frontend / backend', EXAMPLE_COL)}
+${row('npx @h5l0/codelens --profile ./p.json', 'use a custom profile file', EXAMPLE_COL)}`;
+}

package/dist/cli/dev.js

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// 开发服务器
+// 用 Vite 托管前端源码并复用同一套数据接口，改动前端代码即时生效。
+// ---------------------------------------------------------------------------
+import { resolve } from 'node:path';
+import { packageRoot } from './paths.js';
+import { createApiMiddleware } from './server.js';
+export async function startDevServer(payloads, opts) {
+    let vite;
+    try {
+        vite = await import('vite');
+    }
+    catch {
+        throw new Error('dev mode requires vite; run npm install inside the package directory and retry');
+    }
+    const server = await vite.createServer({
+        configFile: resolve(packageRoot, 'vite.config.ts'),
+        server: { host: opts.host, port: opts.port, strictPort: false, open: false },
+        plugins: [
+            {
+                name: 'codelens-api',
+                configureServer(viteServer) {
+                    viteServer.middlewares.use(createApiMiddleware(payloads));
+                },
+            },
+        ],
+    });
+    await server.listen();
+    return {
+        url: server.resolvedUrls?.local?.[0] ?? `http://${opts.host}:${opts.port}/`,
+        close: () => server.close(),
+    };
+}

package/dist/cli/index.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// codelens 命令行入口
+// 解析参数 -> 按 .gitignore 列出仓库文件并统计行数 -> 读取 git 历史 -> 启动本地服务。
+// ---------------------------------------------------------------------------
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { buildCalendar, emptyCalendar, isGitRepo } from '../core/calendar.js';
+import { buildLoc, emptyLoc } from '../core/loc.js';
+import { loadProfile } from '../core/profile.js';
+import { helpText, parseArgs } from './args.js';
+import { startDevServer } from './dev.js';
+import { packageRoot, webDir } from './paths.js';
+import { compose, createApiMiddleware, createStaticMiddleware, isLoopbackHost, startServer } from './server.js';
+const f = (n) => n.toLocaleString();
+const message = (err) => (err instanceof Error ? err.message : String(err));
+function version() {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+    return pkg.version ?? '0.0.0';
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function exists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 左侧标签统一宽度，让多行输出对齐。 */
+const LABEL_COL = 10;
+const tag = (name) => name.padEnd(LABEL_COL);
+function log(label, text) {
+    console.log(`${tag(label)}${text}`);
+}
+/** git 不可用或目录不是仓库时保留空日历，让行数视图仍能打开。 */
+async function readCalendar(root, profile, days) {
+    if (!isGitRepo(root)) {
+        console.warn(`${tag('warn')}directory is not inside a git repository, the calendar will be empty`);
+        return emptyCalendar(root, profile);
+    }
+    try {
+        return await buildCalendar(root, profile, { days });
+    }
+    catch (err) {
+        console.warn(`${tag('warn')}failed to read git history, the calendar will be empty: ${message(err)}`);
+        return emptyCalendar(root, profile);
+    }
+}
+/** 行数统计失败时保留空清单，日历视图仍能打开。 */
+async function readLoc(root, profile, useGitignore) {
+    try {
+        return await buildLoc(root, profile, { useGitignore });
+    }
+    catch (err) {
+        console.warn(`${tag('warn')}failed to count lines, the line view will be empty: ${message(err)}`);
+        return { data: emptyLoc(root, profile), scan: { entries: [], mode: 'walk' } };
+    }
+}
+function launchBrowser(url) {
+    const cmd = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] :
+        process.platform === 'darwin' ? ['open', [url]] :
+            ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true });
+        // 没有可用的打开方式（例如 linux 上缺 xdg-open）时不该抛未捕获异常
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // 打不开浏览器不影响服务本身
+    }
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        console.log(helpText());
+        return;
+    }
+    if (args.version) {
+        console.log(version());
+        return;
+    }
+    const root = resolve(args.dir === '' ? process.cwd() : args.dir);
+    if (!isDirectory(root)) {
+        throw new Error(`directory does not exist: ${root}`);
+    }
+    const profile = loadProfile({
+        root,
+        name: args.profile,
+        configPath: args.config,
+        exclude: args.exclude,
+    });
+    console.log(`codelens ${version()}`);
+    log('repo', root);
+    log('profile', `${profile.name} (${profile.label})${profile.configPath ? ` · ${profile.configPath}` : ''}`);
+    const loc = await readLoc(root, profile, args.useGitignore);
+    const scanLabel = loc.scan.mode === 'git' ? 'git index, filtered by .gitignore' : 'directory walk';
+    log('files', `${f(loc.data.totals.files)} files · ${f(loc.data.totals.lines)} lines (${scanLabel})`);
+    if (loc.data.skipped.unreadable > 0) {
+        log('warn', `${f(loc.data.skipped.unreadable)} files could not be read and were skipped`);
+    }
+    if (profile.groups.length > 0) {
+        log('groups', profile.groups.map((group) => `${group.label}=${group.match.join(' ')}`).join('  '));
+    }
+    const calendar = await readCalendar(root, profile, args.days);
+    log('calendar', calendar.range.min
+        ? `${calendar.range.min} ~ ${calendar.range.max} · ${calendar.totals.days} days with commits`
+        : 'no commits in this range');
+    if (args.dump) {
+        const outDir = resolve(args.dump);
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(join(outDir, 'data.json'), JSON.stringify(calendar));
+        writeFileSync(join(outDir, 'loc.json'), JSON.stringify(loc.data));
+        log('export', join(outDir, 'data.json'));
+        log('', join(outDir, 'loc.json'));
+        return;
+    }
+    const payloads = { data: JSON.stringify(calendar), loc: JSON.stringify(loc.data) };
+    if (!isLoopbackHost(args.host)) {
+        console.warn(`${tag('warn')}listening on ${args.host}, the dashboard is reachable from other machines`);
+    }
+    if (args.dev) {
+        const dev = await startDevServer(payloads, { host: args.host, port: args.port });
+        log('server', `${dev.url} (Vite dev mode, front-end changes apply instantly)`);
+        if (args.open) {
+            launchBrowser(dev.url);
+        }
+        process.on('SIGINT', () => {
+            void dev.close().then(() => process.exit(0));
+        });
+        return;
+    }
+    const dir = webDir();
+    if (!exists(join(dir, 'index.html'))) {
+        throw new Error(`front-end build not found at ${dir}; run npm run build or use --dev`);
+    }
+    const server = await startServer(compose([createApiMiddleware(payloads), createStaticMiddleware(dir)]), {
+        host: args.host,
+        port: args.port,
+    });
+    log('server', server.url);
+    if (args.open) {
+        launchBrowser(server.url);
+    }
+    process.on('SIGINT', () => {
+        server.close();
+        process.exit(0);
+    });
+}
+main().catch((err) => {
+    console.error(`${tag('error')}${message(err)}`);
+    process.exit(1);
+});

package/dist/cli/paths.js

@@ -0,0 +1,11 @@
+// ---------------------------------------------------------------------------
+// 包内路径
+// 源码运行时是 src/cli/*.ts，构建后是 dist/cli/*.js，上两级都是包根目录。
+// ---------------------------------------------------------------------------
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+/** 前端资源目录：构建产物所在位置。 */
+export function webDir() {
+    return resolve(packageRoot, 'dist', 'web');
+}