@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 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 neither may set `install: ""`.
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`; needs `@typescript-eslint/parser`).
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.0",
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",
@@ -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
- say(`LOWERED ${r.id}: ${describe(under)} (written to ${file}; commit it)`);
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.
@@ -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
- * When the installed `typescript` has no compiler API (7.0), the parser gets the classic one
8
- * (classic-typescript.ts, the `typescript-classic` alias).
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 { needsClassicTypeScript, useClassicTypeScript } from '../packs/ts-bun/classic-typescript.js';
12
+ import { loadTypeScriptEslint } from './config.js';
13
13
 
14
- if (needsClassicTypeScript()) useClassicTypeScript();
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;