@h5l0/codelens 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +80 -76
- package/README.zh.md +141 -0
- package/docs/screenshots/en/calendar.png +0 -0
- package/docs/screenshots/en/loc.png +0 -0
- package/docs/screenshots/zh/calendar.png +0 -0
- package/docs/screenshots/zh/loc.png +0 -0
- package/package.json +2 -2
- package/README.en.md +0 -137
package/README.md
CHANGED
|
@@ -1,137 +1,141 @@
|
|
|
1
1
|
# codelens
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@h5l0/codelens)
|
|
4
|
+
[](https://github.com/H5L0/codelens/actions/workflows/ci.yml)
|
|
5
|
+
[](https://github.com/H5L0/codelens/actions/workflows/publish.yml)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
A local dashboard for a git repository: the change history and the lines of code.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
English | [简体中文](./README.zh.md)
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
8
12
|
|
|
9
13
|
```bash
|
|
10
|
-
npx @h5l0/codelens #
|
|
11
|
-
npx @h5l0/codelens ../my-repo #
|
|
12
|
-
npx @h5l0/codelens --profile web #
|
|
14
|
+
npx @h5l0/codelens # analyze the current directory and open the browser
|
|
15
|
+
npx @h5l0/codelens ../my-repo # analyze another repository
|
|
16
|
+
npx @h5l0/codelens --profile web # split the calendar into frontend / backend
|
|
13
17
|
```
|
|
14
18
|
|
|
15
|
-
|
|
19
|
+
Or install it globally:
|
|
16
20
|
|
|
17
21
|
```bash
|
|
18
22
|
npm install -g @h5l0/codelens
|
|
19
23
|
codelens
|
|
20
24
|
```
|
|
21
25
|
|
|
22
|
-
|
|
26
|
+
No configuration is needed. The tool collects the data at startup and serves it to the local browser only. It does not write to the analyzed repository.
|
|
23
27
|
|
|
24
|
-
##
|
|
28
|
+
## The two views
|
|
25
29
|
|
|
26
|
-
###
|
|
30
|
+
### Change calendar
|
|
27
31
|
|
|
28
|
-
|
|
32
|
+
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.
|
|
29
33
|
|
|
30
|
-
|
|
31
35
|
|
|
32
|
-
###
|
|
36
|
+
### Lines of code
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
A treemap: each rectangle's area is its line count, its color is the category, and its shade is the directory depth. Click a rectangle to open that directory, or use the switches to set the counting mode and the depth.
|
|
35
39
|
|
|
36
|
-
|
|
37
41
|
|
|
38
|
-
##
|
|
42
|
+
## Command line
|
|
39
43
|
|
|
40
44
|
```
|
|
41
|
-
codelens [
|
|
42
|
-
|
|
43
|
-
--profile
|
|
44
|
-
--config
|
|
45
|
-
--days
|
|
46
|
-
--exclude <glob>
|
|
47
|
-
--port
|
|
48
|
-
--host
|
|
49
|
-
--no-open
|
|
50
|
-
--no-gitignore
|
|
51
|
-
--dump
|
|
52
|
-
--dev
|
|
53
|
-
-h, --help
|
|
54
|
-
-v, --version
|
|
45
|
+
codelens [directory] [options]
|
|
46
|
+
|
|
47
|
+
--profile <name|file> Profile, see below; built in: all, web
|
|
48
|
+
--config <file> Config file, defaults to <directory>/codelens.config.json
|
|
49
|
+
--days <days> Calendar time span, 0 means full history (default 120)
|
|
50
|
+
--exclude <glob> Extra paths to ignore, repeatable
|
|
51
|
+
--port <port> Listen port, default 5178, tries the next ports when busy
|
|
52
|
+
--host <address> Listen address, default 127.0.0.1; other addresses expose the page to your network
|
|
53
|
+
--no-open Do not open the browser automatically
|
|
54
|
+
--no-gitignore Ignore .gitignore; only built-in heavy directories are skipped
|
|
55
|
+
--dump <dir> Write data.json and loc.json, then exit without starting a server
|
|
56
|
+
--dev Dev mode with Vite hot reload
|
|
57
|
+
-h, --help Show help
|
|
58
|
+
-v, --version Show version
|
|
55
59
|
```
|
|
56
60
|
|
|
57
|
-
##
|
|
61
|
+
## Profiles
|
|
58
62
|
|
|
59
|
-
`--profile`
|
|
63
|
+
`--profile` sets how the tool splits the repository:
|
|
60
64
|
|
|
61
|
-
1.
|
|
62
|
-
2.
|
|
65
|
+
1. Point it at a JSON file: `--profile ./my-profile.json`;
|
|
66
|
+
2. Or use a name under `profiles` in `codelens.config.json`. Use `--config` to move that file: `--profile web`.
|
|
63
67
|
|
|
64
|
-
|
|
68
|
+
Two profiles are built in:
|
|
65
69
|
|
|
66
|
-
|
|
|
70
|
+
| Name | What it does |
|
|
67
71
|
| --- | --- |
|
|
68
|
-
| `all` |
|
|
69
|
-
| `web` | `frontend
|
|
72
|
+
| `all` | Default; no groups, the tool counts the whole repository together |
|
|
73
|
+
| `web` | `frontend/`, `web/`, `client/`, `ui/` and similar directories count as frontend, everything else as backend |
|
|
70
74
|
|
|
71
|
-
###
|
|
75
|
+
### Config file format
|
|
72
76
|
|
|
73
77
|
```jsonc
|
|
74
78
|
{
|
|
75
79
|
"profiles": {
|
|
76
80
|
"modules": {
|
|
77
|
-
"label": "
|
|
78
|
-
//
|
|
79
|
-
//
|
|
81
|
+
"label": "By module",
|
|
82
|
+
// Calendar groups: a file goes to the first group whose patterns match.
|
|
83
|
+
// End the list with ["**"] to get an "A / everything else" split.
|
|
80
84
|
"groups": [
|
|
81
|
-
{ "id": "core", "label": "
|
|
82
|
-
{ "id": "web", "label": "
|
|
83
|
-
{ "id": "other", "label": "
|
|
85
|
+
{ "id": "core", "label": "Core", "hue": 214, "sat": 58, "match": ["src/core/**"] },
|
|
86
|
+
{ "id": "web", "label": "UI", "hue": 152, "sat": 46, "match": ["src/web/**"] },
|
|
87
|
+
{ "id": "other", "label": "Other", "hue": 32, "sat": 62, "match": ["**"] }
|
|
84
88
|
],
|
|
85
|
-
//
|
|
89
|
+
// Line-count categories: drive the legend and colors; the entry without a match is the fallback.
|
|
86
90
|
"categories": [
|
|
87
|
-
{ "id": "core", "label": "
|
|
88
|
-
{ "id": "test", "label": "
|
|
89
|
-
{ "id": "app", "label": "
|
|
91
|
+
{ "id": "core", "label": "Core code", "hue": 214, "sat": 58, "match": ["src/core/**"] },
|
|
92
|
+
{ "id": "test", "label": "Tests", "hue": 152, "sat": 46, "defaultOn": false, "match": ["**/*.test.ts"] },
|
|
93
|
+
{ "id": "app", "label": "Other code", "hue": 220, "sat": 20 }
|
|
90
94
|
],
|
|
91
|
-
//
|
|
95
|
+
// Extra paths to ignore on top of .gitignore
|
|
92
96
|
"ignore": ["data/**", "**/*.snap"]
|
|
93
97
|
}
|
|
94
98
|
}
|
|
95
99
|
}
|
|
96
100
|
```
|
|
97
101
|
|
|
98
|
-
|
|
102
|
+
Field notes:
|
|
99
103
|
|
|
100
|
-
- `groups[].match
|
|
101
|
-
-
|
|
102
|
-
- `groups[].id`
|
|
103
|
-
- `hue
|
|
104
|
-
- `categories[].defaultOn
|
|
104
|
+
- `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.
|
|
105
|
+
- The config file accepts `//` and `/* */` comments and trailing commas.
|
|
106
|
+
- `groups[].id` must not be `all`, and it must be unique in one profile.
|
|
107
|
+
- `hue` and `sat` are HSL color components for the group and category colors. The defaults are 214 and 50.
|
|
108
|
+
- `categories[].defaultOn: false` means the category is off in the legend by default. Of the built-in categories, "generated code", "docs" and "config" are off by default.
|
|
105
109
|
|
|
106
|
-
|
|
110
|
+
Without `categories`, the tool uses six built-in categories: application code, tests, scripts, docs, config and generated code.
|
|
107
111
|
|
|
108
|
-
|
|
112
|
+
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.
|
|
109
113
|
|
|
110
|
-
##
|
|
114
|
+
## Counting rules
|
|
111
115
|
|
|
112
|
-
-
|
|
113
|
-
-
|
|
114
|
-
- `--exclude`
|
|
115
|
-
-
|
|
116
|
-
-
|
|
117
|
-
-
|
|
118
|
-
-
|
|
116
|
+
- 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.
|
|
117
|
+
- The tool always skips dependency and build directories, such as `node_modules`, `dist`, `build`, `coverage`, `.venv`, `__pycache__` and `target`.
|
|
118
|
+
- `--exclude` and the config's `ignore` apply to both views. The tool does not count excluded directories, and the calendar does not show them.
|
|
119
|
+
- 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.
|
|
120
|
+
- 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.
|
|
121
|
+
- 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.
|
|
122
|
+
- If you run the tool on a subdirectory of a repository, both views count that subdirectory only and resolve paths relative to it.
|
|
119
123
|
|
|
120
|
-
##
|
|
124
|
+
## Known limits
|
|
121
125
|
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
-
|
|
125
|
-
-
|
|
126
|
+
- The change calendar needs git. A repository without commits, or without git, leaves the calendar empty. The lines view still works.
|
|
127
|
+
- Line counts say nothing about code complexity.
|
|
128
|
+
- The treemap draws at most 6000 rectangles. The rest are not shown.
|
|
129
|
+
- 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.
|
|
126
130
|
|
|
127
|
-
##
|
|
131
|
+
## Languages
|
|
128
132
|
|
|
129
|
-
|
|
133
|
+
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`.
|
|
130
134
|
|
|
131
|
-
##
|
|
135
|
+
## Development
|
|
132
136
|
|
|
133
|
-
|
|
137
|
+
See [DEV.md](./DEV.md) for the development setup, the project layout and the release process.
|
|
134
138
|
|
|
135
|
-
##
|
|
139
|
+
## License
|
|
136
140
|
|
|
137
141
|
[MIT](./LICENSE)
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# codelens
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@h5l0/codelens)
|
|
4
|
+
[](https://github.com/H5L0/codelens/actions/workflows/ci.yml)
|
|
5
|
+
[](https://github.com/H5L0/codelens/actions/workflows/publish.yml)
|
|
6
|
+
|
|
7
|
+
把任意 git 仓库的改动历史与代码行数，做成一个本地看板。
|
|
8
|
+
|
|
9
|
+
[English](./README.md) | 简体中文
|
|
10
|
+
|
|
11
|
+
## 快速开始
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx @h5l0/codelens # 统计当前目录并在浏览器打开
|
|
15
|
+
npx @h5l0/codelens ../my-repo # 统计指定仓库
|
|
16
|
+
npx @h5l0/codelens --profile web # 按前后端拆分改动日历
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
也可以全局安装：
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g @h5l0/codelens
|
|
23
|
+
codelens
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
无需配置。数据在启动时生成，只提供给本机浏览器，不写入被统计的仓库。
|
|
27
|
+
|
|
28
|
+
## 两个视图
|
|
29
|
+
|
|
30
|
+
### 改动日历
|
|
31
|
+
|
|
32
|
+
按周排布的改动热力图：每格是一天，显示当天新增与删除的行数。可以按分组过滤，也可以平移时间窗口看其他周。
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### 代码行数
|
|
37
|
+
|
|
38
|
+
树形图：方块面积表示行数，颜色表示分类，深浅表示目录层级。点方块进入该目录，右侧开关控制统计规则与展开层级。
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
## 命令行参数
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
codelens [目录] [选项]
|
|
46
|
+
|
|
47
|
+
--profile <名称|文件> 配置档，见下节，内置 all、web
|
|
48
|
+
--config <文件> 配置文件，默认 <目录>/codelens.config.json
|
|
49
|
+
--days <天数> 日历时间跨度，0 表示全部历史（默认 120）
|
|
50
|
+
--exclude <glob> 额外忽略的路径，可重复
|
|
51
|
+
--port <端口> 监听端口，默认 5178，被占用时向后尝试
|
|
52
|
+
--host <地址> 监听地址，默认 127.0.0.1；监听其他地址时页面对同网段可见
|
|
53
|
+
--no-open 不自动打开浏览器
|
|
54
|
+
--no-gitignore 不按 .gitignore 过滤，只跳过内置的重目录
|
|
55
|
+
--dump <目录> 只写出 data.json 与 loc.json 后退出，不启动服务
|
|
56
|
+
--dev 开发模式，用 Vite 托管前端源码并热更新
|
|
57
|
+
-h, --help 显示帮助
|
|
58
|
+
-v, --version 显示版本
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## 配置档
|
|
62
|
+
|
|
63
|
+
`--profile` 决定切分仓库的维度：
|
|
64
|
+
|
|
65
|
+
1. 指向 json 文件：`--profile ./my-profile.json`；
|
|
66
|
+
2. 取 `codelens.config.json` 里 `profiles` 下的档名，位置可用 `--config` 改：`--profile web`。
|
|
67
|
+
|
|
68
|
+
内置两档：
|
|
69
|
+
|
|
70
|
+
| 名称 | 作用 |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `all` | 默认档，不分组，整个仓库一起统计 |
|
|
73
|
+
| `web` | `frontend/`、`web/`、`client/`、`ui/` 等算前端，其余算后端 |
|
|
74
|
+
|
|
75
|
+
### 配置文件格式
|
|
76
|
+
|
|
77
|
+
```jsonc
|
|
78
|
+
{
|
|
79
|
+
"profiles": {
|
|
80
|
+
"modules": {
|
|
81
|
+
"label": "按模块",
|
|
82
|
+
// 改动日历的分组：命中的文件算进该组，按数组顺序取第一个命中的。
|
|
83
|
+
// 最后一个用 ["**"] 兜底，就能得到「A / 其余」这种两分效果。
|
|
84
|
+
"groups": [
|
|
85
|
+
{ "id": "core", "label": "核心", "hue": 214, "sat": 58, "match": ["src/core/**"] },
|
|
86
|
+
{ "id": "web", "label": "界面", "hue": 152, "sat": 46, "match": ["src/web/**"] },
|
|
87
|
+
{ "id": "other", "label": "其他", "hue": 32, "sat": 62, "match": ["**"] }
|
|
88
|
+
],
|
|
89
|
+
// 行数视图的分类：决定图例与配色，省略 match 的那一项是兜底类。
|
|
90
|
+
"categories": [
|
|
91
|
+
{ "id": "core", "label": "核心代码", "hue": 214, "sat": 58, "match": ["src/core/**"] },
|
|
92
|
+
{ "id": "test", "label": "测试", "hue": 152, "sat": 46, "defaultOn": false, "match": ["**/*.test.ts"] },
|
|
93
|
+
{ "id": "app", "label": "其他代码", "hue": 220, "sat": 20 }
|
|
94
|
+
],
|
|
95
|
+
// 在 .gitignore 之外额外忽略的路径
|
|
96
|
+
"ignore": ["data/**", "**/*.snap"]
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
字段说明：
|
|
103
|
+
|
|
104
|
+
- `groups[].match`、`categories[].match`、`ignore` 使用仓库相对路径的 glob：`**` 跨目录，`*` 不跨目录，`?` 匹配单个字符，`{a,b}` 择一；不含 `/` 的模式匹配任意层级的同名项，`/foo` 从仓库根起算，`foo/` 表示目录及其全部内容。
|
|
105
|
+
- 配置文件允许 `//`、`/* */` 注释与尾随逗号。
|
|
106
|
+
- `groups[].id` 不能是保留的 `all`，同一档里不能重复。
|
|
107
|
+
- `hue`、`sat` 是 HSL 颜色分量，用于分组色与分类色，缺省为 214、50。
|
|
108
|
+
- `categories[].defaultOn` 为 `false` 表示该分类在页面图例里默认关闭；内置分类中「生成代码」「文档」「配置」默认关闭。
|
|
109
|
+
|
|
110
|
+
不写 `categories` 时使用内置六类：应用代码、测试、脚本、文档、配置、生成代码。
|
|
111
|
+
|
|
112
|
+
配置里没有的档名回退到内置档：仓库里放一份只定义自定义档的 `codelens.config.json`，`--profile all`、`--profile web` 依然可用。两边都没有的档名才报错。
|
|
113
|
+
|
|
114
|
+
## 统计规则
|
|
115
|
+
|
|
116
|
+
- 默认遵守仓库的 `.gitignore`；目录不是 git 仓库时改用等价的忽略规则。`--no-gitignore` 关闭该过滤。
|
|
117
|
+
- 始终跳过 `node_modules`、`dist`、`build`、`coverage`、`.venv`、`__pycache__`、`target` 等依赖与构建目录。
|
|
118
|
+
- `--exclude` 与配置里的 `ignore` 对两个视图同时生效：被排除的目录既不统计行数，也不计入改动日历。
|
|
119
|
+
- 二进制文件、超过 3MB 的文件、空文件不统计；读不出的文件只跳过它，并在启动日志里给出数量。行数为物理行数，文件末尾换行不计一行。
|
|
120
|
+
- 改动日历按提交时间（committer date）归入所在天，与 `--days` 的过滤规则一致；改动行数 = 新增 + 删除。
|
|
121
|
+
- 合并提交、空提交、只改权限或只动二进制的提交没有行数，但仍出现在提交列表里并计入提交数。
|
|
122
|
+
- 对仓库的子目录运行时，两个视图都只统计该子目录，路径也相对它计算。
|
|
123
|
+
|
|
124
|
+
## 已知限制
|
|
125
|
+
|
|
126
|
+
- 改动日历依赖 git：没有提交或没有 git 时日历为空，行数视图仍可用。
|
|
127
|
+
- 行数不代表代码复杂度。
|
|
128
|
+
- 树形图一次最多绘制 6000 个方块，超出部分不显示。
|
|
129
|
+
- 日历按整周补齐，窗口首尾不足一周时会多画出几天没有数据的格子（底色更白）。
|
|
130
|
+
|
|
131
|
+
## 多语言
|
|
132
|
+
|
|
133
|
+
页面语言跟随浏览器，内置简体中文、English、日本語、한국어，其余回落到英文。地址后加 `?lang={langCode}` 可临时覆盖，例如 `?lang=en`。
|
|
134
|
+
|
|
135
|
+
## 开发
|
|
136
|
+
|
|
137
|
+
开发环境、项目结构与发布流程见 [DEV.md](./DEV.md)。
|
|
138
|
+
|
|
139
|
+
## 许可
|
|
140
|
+
|
|
141
|
+
[MIT](./LICENSE)
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@h5l0/codelens",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "把任意 git 仓库的改动历史与代码行数可视化成本地看板 | Local dashboard for a git repository's commit history and lines of code",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"git",
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"dist",
|
|
32
32
|
"docs/screenshots",
|
|
33
33
|
"README.md",
|
|
34
|
-
"README.
|
|
34
|
+
"README.zh.md",
|
|
35
35
|
"LICENSE"
|
|
36
36
|
],
|
|
37
37
|
"engines": {
|
package/README.en.md
DELETED
|
@@ -1,137 +0,0 @@
|
|
|
1
|
-
# codelens
|
|
2
|
-
|
|
3
|
-
A local dashboard for a git repository: the change history and the lines of code.
|
|
4
|
-
|
|
5
|
-
English | [简体中文](./README.md)
|
|
6
|
-
|
|
7
|
-
## Quick start
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npx @h5l0/codelens # analyze the current directory and open the browser
|
|
11
|
-
npx @h5l0/codelens ../my-repo # analyze another repository
|
|
12
|
-
npx @h5l0/codelens --profile web # split the calendar into frontend / backend
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Or install it globally:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
npm install -g @h5l0/codelens
|
|
19
|
-
codelens
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
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.
|
|
23
|
-
|
|
24
|
-
## The two views
|
|
25
|
-
|
|
26
|
-
### Change calendar
|
|
27
|
-
|
|
28
|
-
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.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
### Lines of code
|
|
33
|
-
|
|
34
|
-
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.
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
## Command line
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
codelens [directory] [options]
|
|
42
|
-
|
|
43
|
-
--profile <name|file> Profile, see below; built in: all, web
|
|
44
|
-
--config <file> Config file, defaults to <directory>/codelens.config.json
|
|
45
|
-
--days <days> Calendar time span, 0 means full history (default 120)
|
|
46
|
-
--exclude <glob> Extra paths to ignore, repeatable
|
|
47
|
-
--port <port> Listen port, default 5178, tries the next ports when busy
|
|
48
|
-
--host <address> Listen address, default 127.0.0.1; other addresses expose the page to your network
|
|
49
|
-
--no-open Do not open the browser automatically
|
|
50
|
-
--no-gitignore Ignore .gitignore; only built-in heavy directories are skipped
|
|
51
|
-
--dump <dir> Write data.json and loc.json, then exit without starting a server
|
|
52
|
-
--dev Dev mode with Vite hot reload
|
|
53
|
-
-h, --help Show help
|
|
54
|
-
-v, --version Show version
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
## Profiles
|
|
58
|
-
|
|
59
|
-
`--profile` sets how the tool splits the repository:
|
|
60
|
-
|
|
61
|
-
1. Point it at a JSON file: `--profile ./my-profile.json`;
|
|
62
|
-
2. Or use a name under `profiles` in `codelens.config.json`. Use `--config` to move that file: `--profile web`.
|
|
63
|
-
|
|
64
|
-
Two profiles are built in:
|
|
65
|
-
|
|
66
|
-
| Name | What it does |
|
|
67
|
-
| --- | --- |
|
|
68
|
-
| `all` | Default; no groups, the tool counts the whole repository together |
|
|
69
|
-
| `web` | `frontend/`, `web/`, `client/`, `ui/` and similar directories count as frontend, everything else as backend |
|
|
70
|
-
|
|
71
|
-
### Config file format
|
|
72
|
-
|
|
73
|
-
```jsonc
|
|
74
|
-
{
|
|
75
|
-
"profiles": {
|
|
76
|
-
"modules": {
|
|
77
|
-
"label": "By module",
|
|
78
|
-
// Calendar groups: a file goes to the first group whose patterns match.
|
|
79
|
-
// End the list with ["**"] to get an "A / everything else" split.
|
|
80
|
-
"groups": [
|
|
81
|
-
{ "id": "core", "label": "Core", "hue": 214, "sat": 58, "match": ["src/core/**"] },
|
|
82
|
-
{ "id": "web", "label": "UI", "hue": 152, "sat": 46, "match": ["src/web/**"] },
|
|
83
|
-
{ "id": "other", "label": "Other", "hue": 32, "sat": 62, "match": ["**"] }
|
|
84
|
-
],
|
|
85
|
-
// Line-count categories: drive the legend and colors; the entry without a match is the fallback.
|
|
86
|
-
"categories": [
|
|
87
|
-
{ "id": "core", "label": "Core code", "hue": 214, "sat": 58, "match": ["src/core/**"] },
|
|
88
|
-
{ "id": "test", "label": "Tests", "hue": 152, "sat": 46, "defaultOn": false, "match": ["**/*.test.ts"] },
|
|
89
|
-
{ "id": "app", "label": "Other code", "hue": 220, "sat": 20 }
|
|
90
|
-
],
|
|
91
|
-
// Extra paths to ignore on top of .gitignore
|
|
92
|
-
"ignore": ["data/**", "**/*.snap"]
|
|
93
|
-
}
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
Field notes:
|
|
99
|
-
|
|
100
|
-
- `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.
|
|
101
|
-
- The config file accepts `//` and `/* */` comments and trailing commas.
|
|
102
|
-
- `groups[].id` must not be `all`, and it must be unique in one profile.
|
|
103
|
-
- `hue` and `sat` are HSL color components for the group and category colors. The defaults are 214 and 50.
|
|
104
|
-
- `categories[].defaultOn: false` means the category starts off in the legend. Of the built-in categories, "generated code", "docs" and "config" start off.
|
|
105
|
-
|
|
106
|
-
Without `categories`, the tool uses six built-in categories: application code, tests, scripts, docs, config and generated code.
|
|
107
|
-
|
|
108
|
-
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.
|
|
109
|
-
|
|
110
|
-
## Counting rules
|
|
111
|
-
|
|
112
|
-
- 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.
|
|
113
|
-
- The tool always skips dependency and build directories, such as `node_modules`, `dist`, `build`, `coverage`, `.venv`, `__pycache__` and `target`.
|
|
114
|
-
- `--exclude` and the config's `ignore` apply to both views. The tool does not count excluded directories, and the calendar does not show them.
|
|
115
|
-
- 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.
|
|
116
|
-
- 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.
|
|
117
|
-
- 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.
|
|
118
|
-
- If you run the tool on a subdirectory of a repository, both views count that subdirectory only and resolve paths relative to it.
|
|
119
|
-
|
|
120
|
-
## Known limits
|
|
121
|
-
|
|
122
|
-
- The change calendar needs git. A repository without commits, or without git, leaves the calendar empty. The lines view still works.
|
|
123
|
-
- Line counts do not show the code complexity.
|
|
124
|
-
- The treemap draws at most 6000 rectangles. The rest are not shown.
|
|
125
|
-
- 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.
|
|
126
|
-
|
|
127
|
-
## Languages
|
|
128
|
-
|
|
129
|
-
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`.
|
|
130
|
-
|
|
131
|
-
## Development
|
|
132
|
-
|
|
133
|
-
See [DEV.md](./DEV.md) for the development setup, the project layout and the release process.
|
|
134
|
-
|
|
135
|
-
## License
|
|
136
|
-
|
|
137
|
-
[MIT](./LICENSE)
|