@kainappsinc/factory 0.1.0 → 0.1.1
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/CHANGELOG.md +25 -0
- package/LICENSE +21 -0
- package/README.md +27 -2
- package/package.json +4 -5
- package/src/cli/ratchet.ts +17 -1
- package/src/eslint/tester.ts +4 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- `ratchet --against`: when the target's counter command fails, the message says to check whether
|
|
6
|
+
it runs a path this branch removed, and to keep a thin shim there for one merge request.
|
|
7
|
+
- `ratchet --update` names the keys it drops from a baseline (and the zero keys it adds), instead
|
|
8
|
+
of printing an empty description (`LOWERED boundaries: (written to …)`).
|
|
9
|
+
- `ratchet` notes baseline keys the count no longer produces and says `--update` drops them.
|
|
10
|
+
Pass/fail is unchanged: a missing key still counts as 0, so an orphan at 0 passes and one above
|
|
11
|
+
0 fails as stale.
|
|
12
|
+
- `@kainappsinc/factory/eslint/tester` takes its parser from `typescript-eslint`; the
|
|
13
|
+
`@typescript-eslint/parser` peer dependency is gone.
|
|
14
|
+
- `LICENSE` (MIT) ships in the package. README: migrating from a vendored copy, and why the CI
|
|
15
|
+
jobs need a real `install`.
|
|
16
|
+
|
|
17
|
+
## 0.1.0
|
|
18
|
+
|
|
19
|
+
First release: the `factory` CLI (`check`, `ratchet`, `risk`, `validate`), the ts-bun counters
|
|
20
|
+
(`factory-eslint-counts`, `factory-depcruise-counts`) and TypeScript 7 shim, the shared ESLint
|
|
21
|
+
rules and config, the dependency-cruiser rule shapes and the manifest schema.
|
|
22
|
+
|
|
23
|
+
`import-suffix` reports with the message ids `missing` (a relative import without the
|
|
24
|
+
convention's suffix) and `wrong` (with the other one); a repository overriding its messages passes
|
|
25
|
+
`messages: { missing, wrong }`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kain Apps Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -40,6 +40,9 @@ It ships TypeScript source and runs on **Bun** (1.3 or later); there is no build
|
|
|
40
40
|
`"typescript-classic": "npm:typescript@~6.0.3"` (see "TypeScript 7" below). With TypeScript 6
|
|
41
41
|
or earlier it is not needed.
|
|
42
42
|
|
|
43
|
+
The CLI and the counters live in `node_modules`: without installed dependencies
|
|
44
|
+
`bun run factory` fails with "command not found" (exit 127).
|
|
45
|
+
|
|
43
46
|
2. Write `factory.yaml` at the root (format: `schema.json`; for editor completion add
|
|
44
47
|
`# yaml-language-server: $schema=node_modules/@kainappsinc/factory/src/cli/factory.schema.json`):
|
|
45
48
|
|
|
@@ -118,7 +121,29 @@ It ships TypeScript source and runs on **Bun** (1.3 or later); there is no build
|
|
|
118
121
|
`factory:ratchet` runs `ratchet --against origin/<target branch>` on a branch and plain
|
|
119
122
|
`ratchet` on the default branch; `factory:risk` runs `risk --base origin/<target branch>` and
|
|
120
123
|
writes `factory-risk.json` and `FACTORY_RISK_ZONES`. Both need the installed package (the CLI
|
|
121
|
-
lives in `node_modules`), so
|
|
124
|
+
lives in `node_modules`), so each needs a real `install` (as above); with `install: ""` the job
|
|
125
|
+
fails with "command not found" (exit 127).
|
|
126
|
+
|
|
127
|
+
## Migrating from a vendored copy
|
|
128
|
+
|
|
129
|
+
A repository that copied the factory scripts in (for example `factory/packs/ts-bun/*.ts`) moves to
|
|
130
|
+
the package in two merge requests, because a merge request is judged by the **target** branch's
|
|
131
|
+
`factory.yaml` (`ratchet --against`): while the target's `eslint` or `boundaries` definition still
|
|
132
|
+
runs the vendored path, a branch without that file cannot be counted by it.
|
|
133
|
+
|
|
134
|
+
1. The merge request that adopts the package points `factory.yaml` at the package bins
|
|
135
|
+
(`bun run factory-eslint-counts`, `bun run factory-depcruise-counts`) and deletes the vendored
|
|
136
|
+
code, but leaves a thin shim at each old counter path, calling the package's `main()`:
|
|
137
|
+
|
|
138
|
+
```ts
|
|
139
|
+
// factory/packs/ts-bun/eslint-counts.ts: remove once the target's factory.yaml runs the package bin.
|
|
140
|
+
import { main } from '@kainappsinc/factory/ts-bun/eslint-counts';
|
|
141
|
+
process.exit(await main(process.argv.slice(2)));
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
(`depcruise-counts.ts` the same, from `@kainappsinc/factory/ts-bun/depcruise-counts`.) The
|
|
145
|
+
changed definition is reported as `CHANGED`; the shims let the target's definition still count.
|
|
146
|
+
2. Once that has merged, a follow-up merge request deletes the shims.
|
|
122
147
|
|
|
123
148
|
## Commands
|
|
124
149
|
|
|
@@ -239,7 +264,7 @@ Not type-aware: typed linting costs gigabytes of memory under Bun.
|
|
|
239
264
|
|
|
240
265
|
For rule authors: `@kainappsinc/factory/eslint/ast` (defensive AST accessors that see the
|
|
241
266
|
TypeScript nodes too) and `@kainappsinc/factory/eslint/tester` (a TypeScript-parsing `RuleTester`
|
|
242
|
-
wired to `bun:test`;
|
|
267
|
+
wired to `bun:test`; its parser comes from `typescript-eslint`).
|
|
243
268
|
|
|
244
269
|
## dependency-cruiser rule shapes
|
|
245
270
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kainappsinc/factory",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Software factory kit: a gate runner, debt ratchets that only go down, risk zones, shared ESLint rules and the ts-bun stack pack. Runs on Bun.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -39,7 +39,9 @@
|
|
|
39
39
|
"files": [
|
|
40
40
|
"src/",
|
|
41
41
|
"!src/**/__tests__/",
|
|
42
|
-
"README.md"
|
|
42
|
+
"README.md",
|
|
43
|
+
"CHANGELOG.md",
|
|
44
|
+
"LICENSE"
|
|
43
45
|
],
|
|
44
46
|
"scripts": {
|
|
45
47
|
"factory": "bun src/cli/index.ts",
|
|
@@ -50,7 +52,6 @@
|
|
|
50
52
|
"peerDependencies": {
|
|
51
53
|
"@eslint-community/eslint-plugin-eslint-comments": "^4.8.1",
|
|
52
54
|
"@eslint/js": "^9.39.5",
|
|
53
|
-
"@typescript-eslint/parser": "^8.73.0",
|
|
54
55
|
"dependency-cruiser": "^18.8.0",
|
|
55
56
|
"eslint": "^9.39.5",
|
|
56
57
|
"typescript": ">=5.0.0",
|
|
@@ -59,7 +60,6 @@
|
|
|
59
60
|
"peerDependenciesMeta": {
|
|
60
61
|
"@eslint-community/eslint-plugin-eslint-comments": { "optional": true },
|
|
61
62
|
"@eslint/js": { "optional": true },
|
|
62
|
-
"@typescript-eslint/parser": { "optional": true },
|
|
63
63
|
"dependency-cruiser": { "optional": true },
|
|
64
64
|
"eslint": { "optional": true },
|
|
65
65
|
"typescript": { "optional": true },
|
|
@@ -69,7 +69,6 @@
|
|
|
69
69
|
"@eslint-community/eslint-plugin-eslint-comments": "^4.8.1",
|
|
70
70
|
"@eslint/js": "^9.39.5",
|
|
71
71
|
"@types/bun": "^1.3.11",
|
|
72
|
-
"@typescript-eslint/parser": "^8.73.0",
|
|
73
72
|
"dependency-cruiser": "^18.8.0",
|
|
74
73
|
"eslint": "^9.39.5",
|
|
75
74
|
"typescript": "7.0.2",
|
package/src/cli/ratchet.ts
CHANGED
|
@@ -108,6 +108,8 @@ function describe(ds: readonly Delta[]): string {
|
|
|
108
108
|
return ds.map((d) => `${d.key === 'total' ? '' : `${d.key} `}${d.base} -> ${d.now} (${signed(d.now - d.base)})`).join(', ');
|
|
109
109
|
}
|
|
110
110
|
const sum = (c: Counts) => Object.values(c).reduce((a, b) => a + b, 0);
|
|
111
|
+
/** Keys `a` has and `b` does not. */
|
|
112
|
+
const keysMissingFrom = (a: Counts, b: Counts) => Object.keys(a).filter((k) => !(k in b)).sort();
|
|
111
113
|
|
|
112
114
|
/** Whether two ratchets count the same thing: kind, counter and file selection; `why` and `show` are ignored. */
|
|
113
115
|
export function sameDefinition(a: Ratchet, b: Ratchet): boolean {
|
|
@@ -292,7 +294,14 @@ function updateBaseline(ctx: Ctx, r: Ratchet, m: Measured, base: Counts | undefi
|
|
|
292
294
|
// Lowered, or the same counts with a zero key added or dropped: the file is rewritten either way.
|
|
293
295
|
if (under.length || formatBaseline(r.id, now) !== formatBaseline(r.id, base)) {
|
|
294
296
|
writeBaseline(root, manifest.baselines_dir, r.id, now);
|
|
295
|
-
|
|
297
|
+
const dropped = keysMissingFrom(base, now);
|
|
298
|
+
const added = keysMissingFrom(now, base);
|
|
299
|
+
const what = [
|
|
300
|
+
describe(under),
|
|
301
|
+
dropped.length ? `dropped ${dropped.join(', ')}` : '',
|
|
302
|
+
added.length ? `added ${added.join(', ')} at 0` : '',
|
|
303
|
+
].filter(Boolean).join('; ');
|
|
304
|
+
say(`LOWERED ${r.id}: ${what} (written to ${file}; commit it)`);
|
|
296
305
|
return { row: row('lowered'), failed: false };
|
|
297
306
|
}
|
|
298
307
|
return { row: row('ok'), failed: false };
|
|
@@ -311,6 +320,12 @@ function checkBaseline(ctx: Ctx, r: Ratchet, m: Measured, base: Counts | undefin
|
|
|
311
320
|
printLocations(m, ctx.changed, say);
|
|
312
321
|
return { row: row('no baseline'), failed: true };
|
|
313
322
|
}
|
|
323
|
+
// Output only: a missing key counts as 0, so an orphan key fails only if its baseline is above 0 (stale).
|
|
324
|
+
const orphans = keysMissingFrom(base, now);
|
|
325
|
+
if (orphans.length) {
|
|
326
|
+
const pronoun = orphans.length === 1 ? 'it' : 'them';
|
|
327
|
+
say(`NOTE ${r.id}: the count no longer has ${orphans.join(', ')}; \`${manifest.cli} ratchet --update\` drops ${pronoun} from ${file}.`);
|
|
328
|
+
}
|
|
314
329
|
const { over, under } = deltas(base, now);
|
|
315
330
|
if (over.length) {
|
|
316
331
|
say(`FAIL ${r.id}: ${describe(over)}`);
|
|
@@ -415,6 +430,7 @@ function judgeByRefDefinition(ctx: Ctx, r: Ratchet, refDef: Ratchet, ref: RefSta
|
|
|
415
430
|
const m = measure(ctx.root, refDef, ctx.files, ctx.cache);
|
|
416
431
|
if (m.error) {
|
|
417
432
|
say(`FAIL ${r.id}: could not count with ${label}'s definition: ${m.error}`);
|
|
433
|
+
say(` Do: check whether ${label}'s command runs a path this branch removed. If so, keep a thin shim there for this merge request and remove it in a follow-up.`);
|
|
418
434
|
return true;
|
|
419
435
|
}
|
|
420
436
|
// Keys the ref never had cannot be judged by it; the working-tree rule still covers them.
|
package/src/eslint/tester.ts
CHANGED
|
@@ -4,15 +4,14 @@
|
|
|
4
4
|
* import { ruleTester } from '@kainappsinc/factory/eslint/tester';
|
|
5
5
|
* ruleTester.run('my-rule', rule, { valid: [...], invalid: [...] });
|
|
6
6
|
*
|
|
7
|
-
*
|
|
8
|
-
* (
|
|
7
|
+
* The parser is the one typescript-eslint exposes (a peer dependency); when the installed
|
|
8
|
+
* `typescript` has no compiler API (7.0), it gets the classic one (loadTypeScriptEslint).
|
|
9
9
|
*/
|
|
10
10
|
import { describe, it } from 'bun:test';
|
|
11
11
|
import { RuleTester } from 'eslint';
|
|
12
|
-
import {
|
|
12
|
+
import { loadTypeScriptEslint } from './config.js';
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
const { default: parser } = await import('@typescript-eslint/parser');
|
|
14
|
+
const { parser } = await loadTypeScriptEslint();
|
|
16
15
|
|
|
17
16
|
RuleTester.describe = describe;
|
|
18
17
|
RuleTester.it = it;
|