@h5l0/codelens 0.1.0 → 0.1.1

package/README.en.md

@@ -1,6 +1,6 @@
 # codelens
 
-A local dashboard for any git repository: commit history and lines of code.
+A local dashboard for a git repository: the change history and the lines of code.
 
 English | [简体中文](./README.md)
 
@@ -19,19 +19,19 @@ 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.
+No configuration is necessary. The tool collects the data at startup and serves it to the local browser only. It does not write to 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.
+A weekly heat map of the changes: each cell is one day and shows the lines added and removed. You can filter by group, or move the time window to see other weeks.
 
 ![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.
+A treemap: the area of a rectangle is the line count, the color is the category, and the shade is the directory depth. Click a rectangle to open that directory, or use the switches to set the counting mode and the depth.
 
 ![Lines of code](docs/screenshots/en/loc.png)
 
@@ -56,17 +56,17 @@ codelens [directory] [options]
 
 ## Profiles
 
-`--profile` decides how the repository is split. Two ways to use it:
+`--profile` sets how the tool splits the repository:
 
 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`.
+2. Or use a name under `profiles` in `codelens.config.json`. Use `--config` to move that file: `--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 |
+| `all` | Default; no groups, the tool counts the whole repository together |
+| `web` | `frontend/`, `web/`, `client/`, `ui/` and similar directories count as frontend, everything else as backend |
 
 ### Config file format
 
@@ -97,40 +97,40 @@ Two profiles are built in:
 
 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).
+- `groups[].match`, `categories[].match` and `ignore` use globs relative to the repository root: `**` crosses directories, `*` does not, `?` matches one character, and `{a,b}` matches either. A pattern without `/` matches items of that name at any depth. `/foo` is anchored to the root. `foo/` means the directory and everything inside it.
+- The config file accepts `//` and `/* */` comments and trailing commas.
+- `groups[].id` must not be `all`, and it must be unique in one profile.
+- `hue` and `sat` are HSL color components for the group and category colors. The defaults are 214 and 50.
+- `categories[].defaultOn: false` means the category starts 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.
+Without `categories`, the tool uses six built-in categories: application code, tests, scripts, docs, config and 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.
+A profile name that the config file does not define falls back to the built-in profile. A repository with a `codelens.config.json` that defines only custom profiles still supports `codelens --profile all` and `--profile web`. A name that is 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.
+- The tool honors `.gitignore` by default. If the directory is not a git repository, the tool applies equivalent ignore rules instead. `--no-gitignore` turns this off.
+- The tool always skips dependency and build directories, such as `node_modules`, `dist`, `build`, `coverage`, `.venv`, `__pycache__` and `target`.
+- `--exclude` and the config's `ignore` apply to both views. The tool does not count excluded directories, and the calendar does not show them.
+- The tool skips binary files, files larger than 3MB and empty files. If the tool cannot read a file, it skips that file and reports the count in the startup log. Line counts are physical lines; the newline at the end of a file does not count as one more line.
+- The calendar puts each commit in the day of its commit time (committer date). This matches the `--days` filter. "Changed lines" means insertions plus deletions.
+- Merge commits, empty commits and commits that only change file modes or binaries have no line counts. They still appear in the commit list and count as commits.
+- If you run the tool 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).
+- The change calendar needs git. A repository without commits, or without git, leaves the calendar empty. The lines view still works.
+- Line counts do not show the code complexity.
+- The treemap draws at most 6000 rectangles. The rest are not shown.
+- The calendar is padded to whole weeks. 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`.
+The page follows the 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 the language, for example `?lang=zh` or `?lang=ko`.
 
 ## Development
 
-See [DEV.md](./DEV.md) for the development setup, project layout and release process.
+See [DEV.md](./DEV.md) for the development setup, the project layout and the release process.
 
 ## License
 

package/README.md

@@ -12,26 +12,26 @@ 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)
 
@@ -40,12 +40,12 @@ codelens
 ```
 codelens [目录] [选项]
 
---profile <名称|文件>  配置档，见下一节，内置 all、web
+--profile <名称|文件>  配置档，见下节，内置 all、web
 --config <文件>        配置文件，默认 <目录>/codelens.config.json
---days <天数>          改动日历的时间跨度，0 表示全部历史（默认 120）
+--days <天数>          日历时间跨度，0 表示全部历史（默认 120）
 --exclude <glob>       额外忽略的路径，可重复
 --port <端口>          监听端口，默认 5178，被占用时向后尝试
---host <地址>          监听地址，默认 127.0.0.1；监听别的地址时页面对同网段可见
+--host <地址>          监听地址，默认 127.0.0.1；监听其他地址时页面对同网段可见
 --no-open              不自动打开浏览器
 --no-gitignore         不按 .gitignore 过滤，只跳过内置的重目录
 --dump <目录>          只写出 data.json 与 loc.json 后退出，不启动服务
@@ -56,17 +56,17 @@ codelens [目录] [选项]
 
 ## 配置档
 
-`--profile` 决定用什么维度切分这个仓库，两种用法：
+`--profile` 决定切分仓库的维度：
 
-1. 指向一个 json 文件：`--profile ./my-profile.json`；
-2. 取 `codelens.config.json`（可用 `--config` 换位置）里 `profiles` 下的名字：`--profile web`。
+1. 指向 json 文件：`--profile ./my-profile.json`；
+2. 取 `codelens.config.json` 里 `profiles` 下的档名，位置可用 `--config` 改：`--profile web`。
 
 内置两档：
 
 | 名称 | 作用 |
 | --- | --- |
-| `all` | 默认档，不做任何分组，整个仓库一起统计 |
-| `web` | 常见前后端目录：`frontend/`、`web/`、`client/`、`ui/` 等算前端，其余算后端 |
+| `all` | 默认档，不分组，整个仓库一起统计 |
+| `web` | `frontend/`、`web/`、`client/`、`ui/` 等算前端，其余算后端 |
 
 ### 配置文件格式
 
@@ -97,36 +97,36 @@ codelens [目录] [选项]
 
 字段说明：
 
-- `groups[].match`、`categories[].match`、`ignore` 都使用仓库相对路径的 glob：`**` 跨目录，`*` 不跨目录，`?` 匹配单个字符，`{a,b}` 择一；不含 `/` 的模式匹配任意层级的同名项，`/foo` 表示从仓库根起算，`foo/` 表示目录及其全部内容。
-- 配置文件允许写 `//`、`/* */` 注释与尾随逗号。
+- `groups[].match`、`categories[].match`、`ignore` 使用仓库相对路径的 glob：`**` 跨目录，`*` 不跨目录，`?` 匹配单个字符，`{a,b}` 择一；不含 `/` 的模式匹配任意层级的同名项，`/foo` 从仓库根起算，`foo/` 表示目录及其全部内容。
+- 配置文件允许 `//`、`/* */` 注释与尾随逗号。
 - `groups[].id` 不能是保留的 `all`，同一档里不能重复。
-- `hue`、`sat` 为 HSL 颜色分量，用于分组色与分类色，缺省分别为 214、50。
-- `categories[].defaultOn` 为 `false` 表示该分类在页面图例里默认关闭（内置分类中「生成代码」「文档」「配置」默认关闭）。
+- `hue`、`sat` 是 HSL 颜色分量，用于分组色与分类色，缺省为 214、50。
+- `categories[].defaultOn` 为 `false` 表示该分类在页面图例里默认关闭；内置分类中「生成代码」「文档」「配置」默认关闭。
 
-不写 `categories` 时使用内置的六类：应用代码、测试、脚本、文档、配置、生成代码。
+不写 `categories` 时使用内置六类：应用代码、测试、脚本、文档、配置、生成代码。
 
-配置文件里没有取到的档名会回退到内置档：仓库里放了一份只定义自定义档的 `codelens.config.json`，`codelens --profile all`、`--profile web` 依然可用；两个地方都没有的档名才会报错。
+配置里没有的档名回退到内置档：仓库里放一份只定义自定义档的 `codelens.config.json`，`--profile all`、`--profile web` 依然可用。两边都没有的档名才报错。
 
-## 统计口径
+## 统计规则
 
-- 默认完全遵守仓库的 `.gitignore`；目录不是 git 仓库时改用等价的忽略规则自行过滤。`--no-gitignore` 可关闭该过滤。
-- 任何情况下都跳过 `node_modules`、`dist`、`build`、`coverage`、`.venv`、`__pycache__`、`target` 等依赖与构建目录。
-- `--exclude`、配置里的 `ignore` 对两个视图同时生效：被排除的目录既不进行数统计，改动日历里也不计入。
-- 二进制文件、超过 3MB 的文件、空文件不计入；个别文件读不出来只跳过它，并在启动日志里给出数量。行数为物理行数（文件末尾换行不计一行）。
-- 改动日历按提交时间（committer date）归入所在天，与 `--days` 的过滤口径一致；「改动行数 = 新增 + 删除」。
-- 合并提交、空提交、只改文件权限或只动二进制的提交没有具体行数，但仍会出现在提交列表里并计入提交数。
-- 对仓库的某个子目录运行时，两个视图都只统计该子目录，路径也相对它计算。
+- 默认遵守仓库的 `.gitignore`；目录不是 git 仓库时改用等价的忽略规则。`--no-gitignore` 关闭该过滤。
+- 始终跳过 `node_modules`、`dist`、`build`、`coverage`、`.venv`、`__pycache__`、`target` 等依赖与构建目录。
+- `--exclude` 与配置里的 `ignore` 对两个视图同时生效：被排除的目录既不统计行数，也不计入改动日历。
+- 二进制文件、超过 3MB 的文件、空文件不统计；读不出的文件只跳过它，并在启动日志里给出数量。行数为物理行数，文件末尾换行不计一行。
+- 改动日历按提交时间（committer date）归入所在天，与 `--days` 的过滤规则一致；改动行数 = 新增 + 删除。
+- 合并提交、空提交、只改权限或只动二进制的提交没有行数，但仍出现在提交列表里并计入提交数。
+- 对仓库的子目录运行时，两个视图都只统计该子目录，路径也相对它计算。
 
-## 已知边界
+## 已知限制
 
-- 改动日历依赖 git，仓库没有提交或缺少 git 时日历为空，行数视图仍可用。
-- 行数视图按文本文件的行数统计，无法反映代码复杂度。
-- 树形图一次最多绘制 6000 个方块，超出的部分不显示。
+- 改动日历依赖 git：没有提交或没有 git 时日历为空，行数视图仍可用。
+- 行数只反映文本行数，不反映代码复杂度。
+- 树形图一次最多绘制 6000 个方块，超出部分不显示。
 - 日历按整周补齐，窗口首尾不足一周时会多画出几天没有数据的格子（底色更白）。
 
 ## 多语言
 
-页面语言跟随浏览器，目前内置简体中文、English、日本語、한국어，其余语言回落到英文。地址后加 `?lang={langCode}` 可临时覆盖，例如 `?lang=en`、`?lang=ja`。
+页面语言跟随浏览器，内置简体中文、English、日本語、한국어，其余回落到英文。地址后加 `?lang={langCode}` 可临时覆盖，例如 `?lang=en`。
 
 ## 开发
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h5l0/codelens",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "把任意 git 仓库的改动历史与代码行数可视化成本地看板 | Local dashboard for a git repository's commit history and lines of code",
   "keywords": [
     "git",