@eserstack/codebase 0.0.0-stage → 5.0.0
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 +301 -2
- package/dist/changelog-gen.d.ts +105 -0
- package/dist/changelog-gen.js +498 -0
- package/dist/changelog-text.d.ts +39 -0
- package/dist/changelog-text.js +82 -0
- package/dist/cli-support.d.ts +140 -0
- package/dist/cli-support.js +244 -0
- package/dist/cli-system/app-opts.d.ts +15 -0
- package/dist/cli-system/app-opts.js +13 -0
- package/dist/cli-system/app.d.ts +29 -0
- package/dist/cli-system/app.js +12 -0
- package/dist/cli-system/handlers/completions-setup.d.ts +14 -0
- package/dist/cli-system/handlers/completions-setup.js +139 -0
- package/dist/cli-system/handlers/completions.d.ts +3 -0
- package/dist/cli-system/handlers/completions.js +79 -0
- package/dist/cli-system/handlers/doctor.d.ts +8 -0
- package/dist/cli-system/handlers/doctor.js +146 -0
- package/dist/cli-system/handlers/info.d.ts +3 -0
- package/dist/cli-system/handlers/info.js +69 -0
- package/dist/cli-system/handlers/install.d.ts +8 -0
- package/dist/cli-system/handlers/install.js +137 -0
- package/dist/cli-system/handlers/mod.d.ts +12 -0
- package/dist/cli-system/handlers/mod.js +13 -0
- package/dist/cli-system/handlers/uninstall.d.ts +3 -0
- package/dist/cli-system/handlers/uninstall.js +60 -0
- package/dist/cli-system/handlers/update.d.ts +76 -0
- package/dist/cli-system/handlers/update.js +310 -0
- package/dist/cli-system/handlers/version-check.d.ts +16 -0
- package/dist/cli-system/handlers/version-check.js +176 -0
- package/dist/cli-system/handlers/version.d.ts +3 -0
- package/dist/cli-system/handlers/version.js +45 -0
- package/dist/cli-system/mod.d.ts +19 -0
- package/dist/cli-system/mod.js +52 -0
- package/dist/commitmsg.d.ts +28 -0
- package/dist/commitmsg.js +232 -0
- package/dist/directive-analysis.d.ts +75 -0
- package/dist/directive-analysis.js +223 -0
- package/dist/ffi-client.d.ts +11 -0
- package/dist/ffi-client.js +12 -0
- package/dist/file-tool.d.ts +96 -0
- package/dist/file-tool.js +274 -0
- package/dist/file-tools-shared.d.ts +81 -0
- package/dist/file-tools-shared.js +276 -0
- package/dist/gh-contributors.d.ts +89 -0
- package/dist/gh-contributors.js +205 -0
- package/dist/gh.d.ts +3 -0
- package/dist/gh.js +64 -0
- package/dist/git-listing.d.ts +27 -0
- package/dist/git-listing.js +69 -0
- package/dist/git.d.ts +172 -0
- package/dist/git.js +277 -0
- package/dist/install.d.ts +34 -0
- package/dist/install.js +421 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +14 -0
- package/dist/mod.d.ts +25 -0
- package/dist/mod.js +8 -0
- package/dist/module.d.ts +10 -0
- package/dist/module.js +221 -0
- package/dist/native-functions.d.ts +1088 -0
- package/dist/native-functions.js +2 -0
- package/dist/npm-externals.d.ts +27 -0
- package/dist/npm-externals.js +34 -0
- package/dist/npm-workspace-specifiers.d.ts +6 -0
- package/dist/npm-workspace-specifiers.js +45 -0
- package/dist/package/loader.d.ts +34 -0
- package/dist/package/loader.js +203 -0
- package/dist/package/mod.d.ts +36 -0
- package/dist/package/mod.js +5 -0
- package/dist/package/types.d.ts +142 -0
- package/dist/package/types.js +32 -0
- package/dist/package/workspace.d.ts +33 -0
- package/dist/package/workspace.js +158 -0
- package/dist/package/writer.d.ts +52 -0
- package/dist/package/writer.js +278 -0
- package/dist/package.json +275 -0
- package/dist/release-notes.d.ts +90 -0
- package/dist/release-notes.js +236 -0
- package/dist/release-tag.d.ts +46 -0
- package/dist/release-tag.js +95 -0
- package/dist/release.d.ts +145 -0
- package/dist/release.js +584 -0
- package/dist/source-mask.d.ts +3 -0
- package/dist/source-mask.js +185 -0
- package/dist/validate-bom.d.ts +5 -0
- package/dist/validate-bom.js +43 -0
- package/dist/validate-case-conflict.d.ts +5 -0
- package/dist/validate-case-conflict.js +43 -0
- package/dist/validate-circular-deps.d.ts +11 -0
- package/dist/validate-circular-deps.js +53 -0
- package/dist/validate-code-conventions.d.ts +22 -0
- package/dist/validate-code-conventions.js +166 -0
- package/dist/validate-commit-msg.d.ts +50 -0
- package/dist/validate-commit-msg.js +182 -0
- package/dist/validate-docs.d.ts +20 -0
- package/dist/validate-docs.js +78 -0
- package/dist/validate-eof.d.ts +5 -0
- package/dist/validate-eof.js +61 -0
- package/dist/validate-error-coverage.d.ts +28 -0
- package/dist/validate-error-coverage.js +93 -0
- package/dist/validate-export-names.d.ts +17 -0
- package/dist/validate-export-names.js +56 -0
- package/dist/validate-filenames.d.ts +5 -0
- package/dist/validate-filenames.js +151 -0
- package/dist/validate-json.d.ts +5 -0
- package/dist/validate-json.js +71 -0
- package/dist/validate-large-files.d.ts +5 -0
- package/dist/validate-large-files.js +41 -0
- package/dist/validate-laroux-boundaries.d.ts +19 -0
- package/dist/validate-laroux-boundaries.js +59 -0
- package/dist/validate-licenses.d.ts +5 -0
- package/dist/validate-licenses.js +137 -0
- package/dist/validate-line-endings.d.ts +5 -0
- package/dist/validate-line-endings.js +47 -0
- package/dist/validate-merge-conflict.d.ts +5 -0
- package/dist/validate-merge-conflict.js +46 -0
- package/dist/validate-mod-exports.d.ts +16 -0
- package/dist/validate-mod-exports.js +56 -0
- package/dist/validate-naming-and-todos.d.ts +5 -0
- package/dist/validate-naming-and-todos.js +70 -0
- package/dist/validate-runtime-js-apis.d.ts +5 -0
- package/dist/validate-runtime-js-apis.js +78 -0
- package/dist/validate-secrets.d.ts +5 -0
- package/dist/validate-secrets.js +82 -0
- package/dist/validate-self-imports.d.ts +5 -0
- package/dist/validate-self-imports.js +78 -0
- package/dist/validate-server-loc.d.ts +32 -0
- package/dist/validate-server-loc.js +94 -0
- package/dist/validate-shebangs.d.ts +5 -0
- package/dist/validate-shebangs.js +33 -0
- package/dist/validate-stream.d.ts +25 -0
- package/dist/validate-stream.js +62 -0
- package/dist/validate-submodules.d.ts +5 -0
- package/dist/validate-submodules.js +43 -0
- package/dist/validate-symlinks.d.ts +5 -0
- package/dist/validate-symlinks.js +46 -0
- package/dist/validate-toml.d.ts +5 -0
- package/dist/validate-toml.js +40 -0
- package/dist/validate-trailing-whitespace.d.ts +5 -0
- package/dist/validate-trailing-whitespace.js +49 -0
- package/dist/validate-yaml.d.ts +5 -0
- package/dist/validate-yaml.js +40 -0
- package/dist/validation/config.d.ts +17 -0
- package/dist/validation/config.js +30 -0
- package/dist/validation/mod.d.ts +71 -0
- package/dist/validation/mod.js +479 -0
- package/dist/validation/registry.d.ts +57 -0
- package/dist/validation/registry.js +256 -0
- package/dist/validation/types.d.ts +101 -0
- package/dist/validation/types.js +2 -0
- package/dist/validation/validators/circular-deps.d.ts +7 -0
- package/dist/validation/validators/circular-deps.js +31 -0
- package/dist/validation/validators/docs.d.ts +7 -0
- package/dist/validation/validators/docs.js +38 -0
- package/dist/validation/validators/error-coverage.d.ts +2 -0
- package/dist/validation/validators/error-coverage.js +46 -0
- package/dist/validation/validators/export-names.d.ts +7 -0
- package/dist/validation/validators/export-names.js +31 -0
- package/dist/validation/validators/laroux-boundaries.d.ts +2 -0
- package/dist/validation/validators/laroux-boundaries.js +29 -0
- package/dist/validation/validators/mod-exports.d.ts +7 -0
- package/dist/validation/validators/mod-exports.js +32 -0
- package/dist/validation/validators/mod.d.ts +11 -0
- package/dist/validation/validators/mod.js +12 -0
- package/dist/validation/validators/server-loc.d.ts +2 -0
- package/dist/validation/validators/server-loc.js +48 -0
- package/dist/versions.d.ts +166 -0
- package/dist/versions.js +349 -0
- package/dist/violation-baseline.d.ts +58 -0
- package/dist/violation-baseline.js +144 -0
- package/dist/walk-stream.d.ts +24 -0
- package/dist/walk-stream.js +55 -0
- package/dist/workspace-discovery.d.ts +60 -0
- package/dist/workspace-discovery.js +130 -0
- package/package.json +222 -3
package/README.md
CHANGED
|
@@ -1,3 +1,302 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 🔧 [@eserstack/codebase](./)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/codebase` is
|
|
4
|
+
> published on npm under the same name (`pnpm add @eserstack/codebase`); the JSR
|
|
5
|
+
> versions stay available but get no updates.
|
|
6
|
+
|
|
7
|
+
> **eserstack Tool** — [eser/stack on GitHub](https://github.com/eser/stack)
|
|
8
|
+
> **Install:** `pnpm add @eserstack/codebase`
|
|
9
|
+
|
|
10
|
+
`@eserstack/codebase` provides validation tools and project management utilities
|
|
11
|
+
for maintaining code quality. It includes the validation tools listed under
|
|
12
|
+
Available Tools, git hook management, release tooling, and a workflow
|
|
13
|
+
integration layer.
|
|
14
|
+
|
|
15
|
+
## 🚀 Quick Start
|
|
16
|
+
|
|
17
|
+
### Install git hooks
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Install hooks from .eser/manifest.yml into .git/hooks/
|
|
21
|
+
npx eser codebase install
|
|
22
|
+
|
|
23
|
+
# Show installed hook status
|
|
24
|
+
npx eser codebase status
|
|
25
|
+
|
|
26
|
+
# Remove managed hooks
|
|
27
|
+
npx eser codebase uninstall
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Run individual tools
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Check JSON syntax
|
|
34
|
+
npx eser codebase validate-json
|
|
35
|
+
|
|
36
|
+
# Fix missing trailing newlines
|
|
37
|
+
npx eser codebase validate-eof --fix
|
|
38
|
+
|
|
39
|
+
# Skip paths that match a regular expression; repeat --exclude for more
|
|
40
|
+
npx eser codebase validate-trailing-whitespace --exclude docs/api/ --exclude etc/temp/
|
|
41
|
+
|
|
42
|
+
# Validate commit message format
|
|
43
|
+
npx eser codebase validate-commit-msg --message "feat(core): add feature"
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Cut a release
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
# Preview: prints old -> new version and whether a changelog entry is due
|
|
50
|
+
npx eser codebase release patch --dry-run
|
|
51
|
+
|
|
52
|
+
# Bump VERSION + every package.json, write the CHANGELOG section, commit
|
|
53
|
+
# "chore(codebase): release v<version>", push, then push the v<version> tag
|
|
54
|
+
npx eser codebase release patch
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The tag push is the trigger — CI reacts to `v*.*.*`, never to the commit, and
|
|
58
|
+
never creates tags itself (a tag pushed by a workflow's own `GITHUB_TOKEN`
|
|
59
|
+
dispatches nothing). `rerelease` re-fires the run by recreating the tag at HEAD;
|
|
60
|
+
`unrelease` removes the tag and the GitHub Release. Neither is safe once JSR or
|
|
61
|
+
npm has accepted the version — cut a new patch instead.
|
|
62
|
+
|
|
63
|
+
## 🛠 Available Tools
|
|
64
|
+
|
|
65
|
+
### Setup
|
|
66
|
+
|
|
67
|
+
| Command | Description |
|
|
68
|
+
| ----------- | ------------------------------------------- |
|
|
69
|
+
| `install` | Install git hooks from `.eser/manifest.yml` |
|
|
70
|
+
| `uninstall` | Remove managed git hooks |
|
|
71
|
+
| `status` | Show git hook installation status |
|
|
72
|
+
|
|
73
|
+
### Release
|
|
74
|
+
|
|
75
|
+
| Command | Description |
|
|
76
|
+
| --------------- | -------------------------------------------------------- |
|
|
77
|
+
| `release` | Bump, changelog, commit, push, then push the trigger tag |
|
|
78
|
+
| `rerelease` | Delete and recreate the current version tag at HEAD |
|
|
79
|
+
| `unrelease` | Delete the current version tag and its GitHub Release |
|
|
80
|
+
| `versions` | Bump version across all workspace packages |
|
|
81
|
+
| `changelog-gen` | Generate CHANGELOG entry from commits |
|
|
82
|
+
|
|
83
|
+
### AI
|
|
84
|
+
|
|
85
|
+
| Command | Description |
|
|
86
|
+
| ----------- | --------------------------------------- |
|
|
87
|
+
| `commitmsg` | Generate a commit message from the diff |
|
|
88
|
+
|
|
89
|
+
### GitHub
|
|
90
|
+
|
|
91
|
+
| Command | Description |
|
|
92
|
+
| ------------------ | ------------------------------------------------------- |
|
|
93
|
+
| `gh contributors` | Update contributor list in README.md |
|
|
94
|
+
| `gh release-notes` | Sync CHANGELOG to GitHub Releases, a new one as a draft |
|
|
95
|
+
| `gh release-tag` | Create and push the release tag (the release trigger) |
|
|
96
|
+
|
|
97
|
+
### Validation
|
|
98
|
+
|
|
99
|
+
| Command | Description |
|
|
100
|
+
| ------------------------------ | ---------------------------------------------- |
|
|
101
|
+
| `validate-eof` | Ensure files end with newline |
|
|
102
|
+
| `validate-trailing-whitespace` | Remove trailing whitespace |
|
|
103
|
+
| `validate-bom` | Remove UTF-8 byte order markers |
|
|
104
|
+
| `validate-line-endings` | Normalize line endings to LF |
|
|
105
|
+
| `validate-large-files` | Detect files exceeding size limit |
|
|
106
|
+
| `validate-case-conflict` | Detect case-conflicting filenames |
|
|
107
|
+
| `validate-merge-conflict` | Detect merge conflict markers |
|
|
108
|
+
| `validate-json` | Validate JSON syntax |
|
|
109
|
+
| `validate-toml` | Validate TOML syntax |
|
|
110
|
+
| `validate-yaml` | Validate YAML syntax |
|
|
111
|
+
| `validate-symlinks` | Detect broken symlinks |
|
|
112
|
+
| `validate-shebangs` | Validate shebang consistency |
|
|
113
|
+
| `validate-secrets` | Detect credentials and private keys |
|
|
114
|
+
| `validate-filenames` | Enforce filename conventions |
|
|
115
|
+
| `validate-submodules` | Detect git submodules |
|
|
116
|
+
| `validate-commit-msg` | Validate conventional commit format |
|
|
117
|
+
| `validate-docs` | Validate JSDoc documentation |
|
|
118
|
+
| `validate-circular-deps` | Detect circular dependencies |
|
|
119
|
+
| `validate-export-names` | Validate export naming conventions |
|
|
120
|
+
| `validate-licenses` | Validate license headers |
|
|
121
|
+
| `validate-mod-exports` | Detect modules no package entry point reaches |
|
|
122
|
+
| `validate-server-loc` | Fail when a non-test file exceeds a line cap |
|
|
123
|
+
| `validate-error-coverage` | Check error structs for required fields |
|
|
124
|
+
| `validate-self-imports` | Detect a package importing its own name |
|
|
125
|
+
| `validate-runtime-js-apis` | Detect runtime globals outside `runtime` |
|
|
126
|
+
| `validate-code-conventions` | Enforce namespace imports, `??`, no `export *` |
|
|
127
|
+
| `validate-laroux-boundaries` | Enforce the laroux package import rules |
|
|
128
|
+
|
|
129
|
+
Run any tool with `--help` for options:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
npx eser codebase validate-filenames --help
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## 📋 Configuration (.eser/manifest.yml)
|
|
136
|
+
|
|
137
|
+
Tools are configured through `.eser/manifest.yml` at the project root. Each tool
|
|
138
|
+
receives its options from the workflow step configuration:
|
|
139
|
+
|
|
140
|
+
```yaml
|
|
141
|
+
stack:
|
|
142
|
+
- javascript
|
|
143
|
+
- golang
|
|
144
|
+
|
|
145
|
+
workflows:
|
|
146
|
+
- id: default
|
|
147
|
+
on: [precommit, prepush]
|
|
148
|
+
steps:
|
|
149
|
+
# Validation tools with options
|
|
150
|
+
- validate-json:
|
|
151
|
+
exclude:
|
|
152
|
+
- "tsconfig.json"
|
|
153
|
+
- validate-filenames:
|
|
154
|
+
rules:
|
|
155
|
+
- directory: "apps/services/"
|
|
156
|
+
convention: "snake_case"
|
|
157
|
+
- directory: "*"
|
|
158
|
+
convention: "kebab-case"
|
|
159
|
+
exclude:
|
|
160
|
+
- "Makefile"
|
|
161
|
+
- "README.md"
|
|
162
|
+
- validate-secrets:
|
|
163
|
+
allowMissingCredentials: true
|
|
164
|
+
- validate-commit-msg:
|
|
165
|
+
forceScope: true
|
|
166
|
+
allowAsterisk: true
|
|
167
|
+
allowMultipleScopes: true
|
|
168
|
+
types: [ci, chore, docs, feat, fix, perf, refactor, revert, test]
|
|
169
|
+
|
|
170
|
+
# Shell commands for external tools
|
|
171
|
+
- shell:
|
|
172
|
+
name: formatter
|
|
173
|
+
command: oxfmt --check
|
|
174
|
+
fixCommand: oxfmt
|
|
175
|
+
- shell:
|
|
176
|
+
name: go-tests
|
|
177
|
+
command: "go test -race ./..."
|
|
178
|
+
workingDirectory: ./apps/services/
|
|
179
|
+
timeout: 300
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Baselines
|
|
183
|
+
|
|
184
|
+
`validate-code-conventions` applies its rules to new code while existing code
|
|
185
|
+
is migrated. It records the current violations per file in
|
|
186
|
+
`.eser/baselines/code-conventions.json` (the `baseline` step option points
|
|
187
|
+
elsewhere), and a file fails only when it has more violations than its baseline
|
|
188
|
+
allows. After fixing violations, shrink the baseline:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
npx eser codebase validate-code-conventions --write-baseline
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## 🔌 API Usage
|
|
195
|
+
|
|
196
|
+
The package root (`@eserstack/codebase`) is the CLI entry point. The library API
|
|
197
|
+
lives under `@eserstack/codebase/mod`:
|
|
198
|
+
|
|
199
|
+
```typescript
|
|
200
|
+
import * as codebase from "@eserstack/codebase/mod";
|
|
201
|
+
|
|
202
|
+
// Git operations
|
|
203
|
+
const commits = await codebase.getCommitsBetween("v1.0.0", "HEAD");
|
|
204
|
+
const branch = await codebase.getCurrentBranch();
|
|
205
|
+
|
|
206
|
+
// Workspace discovery
|
|
207
|
+
const packages = await codebase.discoverPackages(".");
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
```typescript
|
|
211
|
+
import * as validation from "@eserstack/codebase/validation";
|
|
212
|
+
|
|
213
|
+
// Run every validator that applies to the stack in .eser/manifest.yml
|
|
214
|
+
const report = await validation.validate({ root: "." });
|
|
215
|
+
|
|
216
|
+
// Get all registered tools as workflow-compatible objects
|
|
217
|
+
const tools = validation.getWorkflowTools();
|
|
218
|
+
|
|
219
|
+
// Run a specific validator programmatically
|
|
220
|
+
const validator = validation.getValidator("validate-json");
|
|
221
|
+
if (validator !== null) {
|
|
222
|
+
const result = await validator.validate({ root: "." });
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### The shared `system` command tree
|
|
227
|
+
|
|
228
|
+
`cli-system/` owns the operational commands every shipped binary carries —
|
|
229
|
+
`install`, `uninstall`, `update`, `completions`, `version`, `doctor`, `info` —
|
|
230
|
+
built once and parameterised by a `CliApp` so `eser`, `noskills` and `laroux`
|
|
231
|
+
each get a tree describing themselves.
|
|
232
|
+
|
|
233
|
+
```typescript
|
|
234
|
+
import * as cliSupport from "@eserstack/codebase/cli-support";
|
|
235
|
+
// The binary's own command module and package manifest.
|
|
236
|
+
import * as module from "./module.ts";
|
|
237
|
+
import config from "./package.json" with { type: "json" };
|
|
238
|
+
|
|
239
|
+
const app = cliSupport.attachStandardCommands(
|
|
240
|
+
module.moduleDef.toCommand("noskills", config.version),
|
|
241
|
+
);
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
It attaches to a binary's ROOT command, never to a Module. That is deliberate:
|
|
245
|
+
`eser` mounts the very same module object the standalone `noskills` binary
|
|
246
|
+
re-roots, so a layer living on the module would appear in both — and
|
|
247
|
+
`eser noskills version` would exist, implying a submodule has a version of its
|
|
248
|
+
own.
|
|
249
|
+
|
|
250
|
+
## Upgrading from 4.x
|
|
251
|
+
|
|
252
|
+
These changes since 4.5.2 need a change in code, commands or files that use this
|
|
253
|
+
package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
|
|
254
|
+
lists the changes in every package.
|
|
255
|
+
|
|
256
|
+
- `versions()` rejects with `VersionWriteError` (with `targetVersion` and
|
|
257
|
+
`failures`) when a `package.json` could not be written, and
|
|
258
|
+
does not write `VERSION`. It used to resolve and report those packages as
|
|
259
|
+
updated. Catch it, fix the listed files, then rerun with the explicit target:
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
# Before: a failed write still reported success
|
|
263
|
+
eser codebase versions minor
|
|
264
|
+
# After: fix the files in error.failures, then pass error.targetVersion
|
|
265
|
+
eser codebase versions target_version
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
- Validator help, `gh --help`, the `--write-baseline` result line of
|
|
269
|
+
`validate-code-conventions`, and the output of
|
|
270
|
+
`validate-docs`, `validate-mod-exports`, `validate-export-names`,
|
|
271
|
+
`validate-circular-deps`, `validate-commit-msg`
|
|
272
|
+
and the standalone `commitmsg` entry go through the shared CLI context. When
|
|
273
|
+
stdout is not a TTY, that output is plain text on stderr instead of stdout.
|
|
274
|
+
Capture both streams: `eser codebase validate-docs > report.txt` becomes
|
|
275
|
+
`eser codebase validate-docs > report.txt 2>&1`.
|
|
276
|
+
- For every file-tool validator, an empty `--exclude` value (a trailing
|
|
277
|
+
`--exclude` or `--exclude=`) fails with exit code 1; it used to match every
|
|
278
|
+
path, so nothing was checked. Repeated `--exclude` flags all apply, where only
|
|
279
|
+
the last one did. Pass real patterns and drop extra flags you relied on being
|
|
280
|
+
ignored.
|
|
281
|
+
- `validate-runtime-js-apis` reports every reference to a runtime global other
|
|
282
|
+
than Node's in code (through `globalThis`, an alias or a `typeof` check
|
|
283
|
+
included), and members of Node's global `process`, in test files too;
|
|
284
|
+
only `standards/cross-runtime/` is skipped on its own. Text in comments and
|
|
285
|
+
string literals does not count. The check runs in Go and needs the native
|
|
286
|
+
library. Its message is `direct <runtime> API usage: X; use Y from
|
|
287
|
+
@eserstack/standards/cross-runtime`. It has no baseline any more:
|
|
288
|
+
`--write-baseline`, the `baseline` option and
|
|
289
|
+
`.eser/baselines/runtime-js-apis.json` are gone. Switch to `runtime` from
|
|
290
|
+
`@eserstack/standards/cross-runtime`, or list scripts that run without it by
|
|
291
|
+
design in the step's `exclude`.
|
|
292
|
+
- `validate-package-configs` and the `./validate-package-configs` export are
|
|
293
|
+
removed: with package.json as the only package config there is nothing to
|
|
294
|
+
compare. Drop the step from `.eser/manifest.yml`.
|
|
295
|
+
- The `./lint-plugin` export and its rules (`copyright-header`,
|
|
296
|
+
`no-top-level-arrow-exports`, `prefer-private-fields`) are removed;
|
|
297
|
+
`validate-licenses` still checks license headers.
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
🔗 For further details, visit the
|
|
302
|
+
[eserstack repository](https://github.com/eser/stack).
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import * as functions from "@eserstack/functions";
|
|
2
|
+
import type * as shellArgs from "@eserstack/shell/args";
|
|
3
|
+
import type * as git from "./git.ts";
|
|
4
|
+
/**
|
|
5
|
+
* A parsed conventional commit.
|
|
6
|
+
*/
|
|
7
|
+
export type ConventionalCommit = {
|
|
8
|
+
/** Commit type (feat, fix, refactor, etc.) */
|
|
9
|
+
readonly type: string;
|
|
10
|
+
/** Commit scope (optional, e.g., "auth" in "feat(auth): message") */
|
|
11
|
+
readonly scope: string | undefined;
|
|
12
|
+
/** Commit message (after the colon) */
|
|
13
|
+
readonly message: string;
|
|
14
|
+
/** Original commit hash */
|
|
15
|
+
readonly hash: string;
|
|
16
|
+
};
|
|
17
|
+
/**
|
|
18
|
+
* CHANGELOG section name from Keep a Changelog format.
|
|
19
|
+
*/
|
|
20
|
+
export type ChangelogSection = "Added" | "Fixed" | "Changed" | "Removed";
|
|
21
|
+
/**
|
|
22
|
+
* Options for generating a changelog.
|
|
23
|
+
*/
|
|
24
|
+
export type GenerateChangelogOptions = {
|
|
25
|
+
/** Root directory containing VERSION and CHANGELOG.md (default: ".") */
|
|
26
|
+
readonly root?: string;
|
|
27
|
+
/** Release version for the heading. Default: next patch after the latest tag. */
|
|
28
|
+
readonly version?: string;
|
|
29
|
+
/** Preview without writing to CHANGELOG.md (default: false) */
|
|
30
|
+
readonly dryRun?: boolean;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Result of generating a changelog.
|
|
34
|
+
*/
|
|
35
|
+
export type GenerateChangelogResult = {
|
|
36
|
+
/** The version for this release */
|
|
37
|
+
readonly version: string;
|
|
38
|
+
/** Number of commits processed */
|
|
39
|
+
readonly commitCount: number;
|
|
40
|
+
/** Number of unique entries (after dedup) */
|
|
41
|
+
readonly entryCount: number;
|
|
42
|
+
/** The generated markdown content */
|
|
43
|
+
readonly content: string;
|
|
44
|
+
/** Whether this was a dry run */
|
|
45
|
+
readonly dryRun: boolean;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* Parse a single commit subject as a conventional commit.
|
|
49
|
+
* Returns undefined if the subject doesn't match the conventional format.
|
|
50
|
+
*/
|
|
51
|
+
export declare const parseConventionalCommit: (subject: string, hash: string) => ConventionalCommit | undefined;
|
|
52
|
+
/**
|
|
53
|
+
* Strip the "take" suffix from a message.
|
|
54
|
+
* "authentication system (take II)." → "authentication system."
|
|
55
|
+
* "authentication system (take 3)" → "authentication system"
|
|
56
|
+
*/
|
|
57
|
+
export declare const stripTakeSuffix: (message: string) => string;
|
|
58
|
+
/**
|
|
59
|
+
* Parse an array of git commits into conventional commits.
|
|
60
|
+
* Non-conventional commits are silently skipped.
|
|
61
|
+
*/
|
|
62
|
+
export declare const parseConventionalCommits: (commits: ReadonlyArray<git.Commit>) => ConventionalCommit[];
|
|
63
|
+
/**
|
|
64
|
+
* Deduplicate commits by stripping "take" suffixes and keeping only the first
|
|
65
|
+
* occurrence of each unique type+message pair.
|
|
66
|
+
*/
|
|
67
|
+
export declare const deduplicateCommits: (commits: ReadonlyArray<ConventionalCommit>) => ConventionalCommit[];
|
|
68
|
+
/**
|
|
69
|
+
* Group commits by CHANGELOG section.
|
|
70
|
+
* Skips commit types that are not user-facing (chore, ci, test).
|
|
71
|
+
*/
|
|
72
|
+
export declare const groupBySection: (commits: ReadonlyArray<ConventionalCommit>) => Map<ChangelogSection, ConventionalCommit[]>;
|
|
73
|
+
/**
|
|
74
|
+
* Generate a complete CHANGELOG section from grouped commits.
|
|
75
|
+
*/
|
|
76
|
+
export declare const generateChangelogSection: (version: string, commits: ReadonlyArray<ConventionalCommit>) => string;
|
|
77
|
+
/**
|
|
78
|
+
* Writes a version's section into CHANGELOG.md content and moves the notes under
|
|
79
|
+
* `## Unreleased` into it, leaving that heading empty above the section. This is
|
|
80
|
+
* the same layout as InsertIntoChangelog in pkg/ajan/codebasefx, which is what a
|
|
81
|
+
* release runs: {@link generateChangelog} calls the Go generator through the
|
|
82
|
+
* bridge, and a Go test compares the two on the same cases.
|
|
83
|
+
*
|
|
84
|
+
* The section goes below Unreleased, or first when there is no Unreleased. An
|
|
85
|
+
* existing section of the version is replaced in place, and the text in it a
|
|
86
|
+
* person wrote stays.
|
|
87
|
+
*
|
|
88
|
+
* @param version - The version string to check for duplicates (e.g., "4.1.2")
|
|
89
|
+
*/
|
|
90
|
+
export declare const insertIntoChangelog: (changelogContent: string, newSection: string, version?: string) => string;
|
|
91
|
+
/**
|
|
92
|
+
* Generate a changelog entry from conventional commits since the last tag and
|
|
93
|
+
* write it to CHANGELOG.md, moving the notes under `## Unreleased` into it. The
|
|
94
|
+
* Go generator does the work, so this needs the native library, and `content`
|
|
95
|
+
* holds the generated entries only. A dry run writes nothing.
|
|
96
|
+
*/
|
|
97
|
+
export declare const generateChangelog: (options?: GenerateChangelogOptions) => Promise<GenerateChangelogResult>;
|
|
98
|
+
/** Handler: wraps generateChangelog as a Task via fromPromise. */
|
|
99
|
+
export declare const generateChangelogHandler: functions.handler.Handler<GenerateChangelogOptions, GenerateChangelogResult, Error>;
|
|
100
|
+
/** Runnable CLI trigger for changelog-gen. */
|
|
101
|
+
export declare const handleCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
|
|
102
|
+
/** Parse the changelog-gen arguments: `--dry-run` (`-n`). */
|
|
103
|
+
export declare const parseCliArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
|
|
104
|
+
/** CLI entry point. */
|
|
105
|
+
export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;
|