@tinkered/cli 0.28.0 → 0.29.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 CHANGED
@@ -32,7 +32,7 @@ bun --bun tinker check
32
32
 
33
33
  ## The check loop
34
34
 
35
- `tinker check` runs two stages in order.
35
+ `tinker check` runs these stages in order.
36
36
 
37
37
  1. **types:** the app's `tsc`, the kind gate and
38
38
  the cast gate.
@@ -86,6 +86,77 @@ A tool with no config is skipped, and the
86
86
  `tinker check: not done`, with exit 2: only a
87
87
  run of every stage can say OK.
88
88
 
89
+ ## The tests and the exits
90
+
91
+ An exit is one way out of an operation: each
92
+ `kind` of its answer, a refusal, or a plain
93
+ return (ADR 0159). A test must reach each one.
94
+
95
+ Name the test command in `tinker.json`:
96
+
97
+ ```json
98
+ { "tests": "bun run test" }
99
+ ```
100
+
101
+ Then the check runs two more stages:
102
+
103
+ 3. **tests:** the command. Red tests print the
104
+ end of their output.
105
+ 4. **exits:** each exit that the types declare
106
+ and no test reached is a finding.
107
+
108
+ ```text
109
+ src/todos.server.ts:41 tinker/exit `todo.remove.do`
110
+ answers `gone`, and no test reaches it
111
+ Right: a test for each exit the check names.
112
+ ```
113
+
114
+ A test scope lists the capsule that writes the
115
+ exits. A scope with no `exits` reaches none.
116
+
117
+ ```ts
118
+ import { exits } from "@tinkered/cli/test";
119
+
120
+ const scope = createScope({
121
+ capsules: [
122
+ exits({ file: process.env.TINKER_EXITS }),
123
+ ],
124
+ });
125
+ ```
126
+
127
+ A page has no file. Its scope passes a store:
128
+
129
+ ```ts
130
+ exits({ store: localStorage });
131
+ ```
132
+
133
+ - The exits go to the key `tinker.exits`, as
134
+ counts by `label<tab>exit`. One write for
135
+ each burst; a run does not wait for it.
136
+ - A setup file of the browser tests leaves the
137
+ store's text in `.tinker/exits/`:
138
+
139
+ ```ts
140
+ afterAll(async () => {
141
+ const exits = localStorage.getItem("tinker.exits");
142
+ if (!exits) return;
143
+ const name = crypto.randomUUID();
144
+ await commands.writeFile(
145
+ `.tinker/exits/${name}.json`,
146
+ exits,
147
+ );
148
+ });
149
+ ```
150
+
151
+ - The check empties `.tinker/exits/` before the
152
+ tests. Put `.tinker/` in `.gitignore`.
153
+ - The check sets `TINKER_EXITS` for the command.
154
+ In a plain test run it is not set, and the
155
+ capsule writes nothing.
156
+ - The check reads the label of an operation as
157
+ a literal, and the return type of its `run`.
158
+ - A thrown error is not an exit.
159
+
89
160
  ## Where the fix comes from
90
161
 
91
162
  A skill has a section per mistake. Its heading
package/dist/cli.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { t as main } from "./main-DQK2xJ_R.mjs";
2
+ import { t as main } from "./main-BO5BHvEC.mjs";
3
3
  //#region src/cli.ts
4
4
  if (import.meta.main) {
5
5
  const { code, out, err } = main(process.argv.slice(2), process.cwd());
package/dist/index.d.mts CHANGED
@@ -41,6 +41,11 @@ declare namespace Check {
41
41
  * above is allowed while row `G<n>` of that doc is open and within its count.
42
42
  */
43
43
  gaps?: string;
44
+ /**
45
+ * The command that runs the app's tests, as a shell line. With it, the tests are a stage of
46
+ * the check, and each exit an operation declares must be reached by a test (ADR 0159).
47
+ */
48
+ tests?: string;
44
49
  };
45
50
  /** One row of the gaps doc: its id, whether it is open, its count, and its marked lines. */
46
51
  type Gap = {
@@ -96,8 +101,17 @@ export declare function isError<N extends Errors.Name>(value: unknown, kind: N):
96
101
  //#endregion
97
102
  //#region src/tools.d.ts
98
103
  declare namespace Tools {
99
- /** A stage of `tinker check`: `types` runs first, and `rules` only once it is clean. */
100
- type Stage = "types" | "rules";
104
+ /**
105
+ * A stage of `tinker check`: `types` runs first, `rules` only once it is clean, and `exits`
106
+ * only once the app's tests pass.
107
+ */
108
+ type Stage = "types" | "rules" | "exits";
109
+ /** A run of the app's tests: its exit status, all it said, and the exits no test reached. */
110
+ type Tested = {
111
+ status: number | null;
112
+ output: string;
113
+ unreached: Found[];
114
+ };
101
115
  /**
102
116
  * One error from the app's own tools. `rule` is a Tinker rule id, a `TS` code, or a lint
103
117
  * rule as `<plugin>/<rule>`. `help` is the tool's own hint, when it gives one.
@@ -134,7 +148,8 @@ declare namespace Main {
134
148
  /**
135
149
  * The answer of `tinker check`. `ok` is the only answer that means done: every stage ran
136
150
  * and is clean. `failed` names the first stage that failed, its first findings, and how many
137
- * it has in all. `incomplete` is clean, but a tool did not run for want of its config.
151
+ * it has in all. `incomplete` is clean, but a tool did not run for want of its config. `red`
152
+ * is the app's tests failing: `output` is the end of what they said.
138
153
  */
139
154
  type Report = {
140
155
  kind: "ok";
@@ -145,6 +160,10 @@ declare namespace Main {
145
160
  ran: string[];
146
161
  skipped: string[];
147
162
  gaps: Check.Gap[];
163
+ } | {
164
+ kind: "red";
165
+ output: string;
166
+ gaps: Check.Gap[];
148
167
  } | {
149
168
  kind: "failed";
150
169
  stage: Tools.Stage;
package/dist/index.mjs CHANGED
@@ -1,2 +1,2 @@
1
- import { n as check, r as isError, t as main } from "./main-DQK2xJ_R.mjs";
1
+ import { n as check, r as isError, t as main } from "./main-BO5BHvEC.mjs";
2
2
  export { check, isError, main };
@@ -1,8 +1,9 @@
1
- import { existsSync, globSync, readFileSync } from "node:fs";
2
- import { dirname, join, matchesGlob, resolve } from "node:path";
1
+ import { existsSync, globSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
2
+ import { dirname, join, matchesGlob, relative, resolve } from "node:path";
3
3
  import ts from "typescript-api";
4
4
  import { IntentCoreError, listIntentSkills, loadIntentSkill } from "@tanstack/intent/core";
5
5
  import { spawnSync } from "node:child_process";
6
+ import { tmpdir } from "node:os";
6
7
  //#region src/errors.ts
7
8
  /** The only place the command throws a registry error. */
8
9
  function raise(kind, payload) {
@@ -1057,6 +1058,11 @@ const parts = [
1057
1058
  ["gaps"],
1058
1059
  (value) => typeof value === "string",
1059
1060
  "`gaps` is the path of the gaps doc"
1061
+ ],
1062
+ [
1063
+ ["tests"],
1064
+ (value) => typeof value === "string",
1065
+ "`tests` is the command that runs the tests"
1060
1066
  ]
1061
1067
  ];
1062
1068
  function parse(text) {
@@ -1131,7 +1137,8 @@ function readApp(root) {
1131
1137
  return {
1132
1138
  sources: [...new Map([...app, ...page].map((source) => [source.path, source])).values()],
1133
1139
  found,
1134
- ...config.gaps ? { doc: gapsDoc(root, config.gaps) } : {}
1140
+ ...config.gaps ? { doc: gapsDoc(root, config.gaps) } : {},
1141
+ ...config.tests ? { tests: config.tests } : {}
1135
1142
  };
1136
1143
  }
1137
1144
  /**
@@ -1182,7 +1189,8 @@ const taught = {
1182
1189
  const rules = [.../* @__PURE__ */ new Set([
1183
1190
  ...own,
1184
1191
  ...Object.values(gates),
1185
- ...Object.values(taught)
1192
+ ...Object.values(taught),
1193
+ "tinker/exit"
1186
1194
  ])];
1187
1195
  //#endregion
1188
1196
  //#region src/skills.ts
@@ -1261,6 +1269,148 @@ function loadSkill(root, use) {
1261
1269
  }).content;
1262
1270
  }
1263
1271
  //#endregion
1272
+ //#region src/exits.ts
1273
+ /** The exit of a return with no `kind` of its own. */
1274
+ const plain = "value";
1275
+ /** A hook's `refuse(payload)`, by the name Core gives its type. */
1276
+ const refusal = "Refused";
1277
+ /**
1278
+ * The app's own code. The base under `tinker/` is Tinker's, and moves into a package that has
1279
+ * its own tests (ADR 0159).
1280
+ */
1281
+ const appCode = /^(?:src|cmds)\//;
1282
+ /** A test file declares no exit: its operations are fixtures. */
1283
+ const testFile = /\.test\.[mc]?tsx?$/;
1284
+ function kindsOf(checker, type) {
1285
+ const kind = type.getProperty("kind");
1286
+ if (!kind) return [];
1287
+ const of = checker.getTypeOfSymbol(kind);
1288
+ const parts = of.isUnion() ? of.types : [of];
1289
+ return parts.every((part) => part.isStringLiteral()) ? parts.map((part) => part.value) : [];
1290
+ }
1291
+ /** Each exit a return type holds: a union gives one per member, and a promise gives its value's. */
1292
+ function exitsOf(checker, returned) {
1293
+ const type = checker.getAwaitedType(returned) ?? returned;
1294
+ if (type.flags & ts.TypeFlags.Never) return [];
1295
+ const exits = /* @__PURE__ */ new Set();
1296
+ for (const part of type.isUnion() ? type.types : [type]) {
1297
+ if (checker.typeToString(part) === refusal) {
1298
+ exits.add("refused");
1299
+ continue;
1300
+ }
1301
+ const kinds = kindsOf(checker, part);
1302
+ for (const kind of kinds.length ? kinds : [plain]) exits.add(kind);
1303
+ }
1304
+ return [...exits].sort();
1305
+ }
1306
+ /** The names a file imports from Core. */
1307
+ function coreImports(source) {
1308
+ return source.statements.flatMap((statement) => {
1309
+ if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) return [];
1310
+ const names = statement.importClause?.namedBindings;
1311
+ return statement.moduleSpecifier.text === "@tinkered/core" && names && ts.isNamedImports(names) ? [...names.elements] : [];
1312
+ });
1313
+ }
1314
+ /** The name `operation` has in this file, when it comes from Core. */
1315
+ function coreOperation(source) {
1316
+ return coreImports(source).find((element) => (element.propertyName ?? element.name).text === "operation")?.name.text;
1317
+ }
1318
+ function member(options, name) {
1319
+ return options.properties.find((property) => property.name && ts.isIdentifier(property.name) && property.name.text === name);
1320
+ }
1321
+ /** The return type of an operation's `run`, written as a property or as a method. */
1322
+ function returnOf(checker, run) {
1323
+ if (ts.isMethodDeclaration(run)) return checker.getSignatureFromDeclaration(run)?.getReturnType();
1324
+ if (!ts.isPropertyAssignment(run)) return void 0;
1325
+ return checker.getTypeAtLocation(run.initializer).getCallSignatures()[0]?.getReturnType();
1326
+ }
1327
+ /** The options of a call of `operation`, when the call has them as a literal. */
1328
+ function optionsOf(node, operation) {
1329
+ if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return void 0;
1330
+ const [options] = node.arguments;
1331
+ if (node.expression.text !== operation || !options) return void 0;
1332
+ return ts.isObjectLiteralExpression(options) ? options : void 0;
1333
+ }
1334
+ /** An operation's label, when it is a literal: a tool cannot name a label made at run time. */
1335
+ function labelOf(options) {
1336
+ const label = member(options, "label");
1337
+ if (!label || !ts.isPropertyAssignment(label)) return void 0;
1338
+ return ts.isStringLiteralLike(label.initializer) ? label.initializer.text : void 0;
1339
+ }
1340
+ function exitsIn(checker, source, path) {
1341
+ const operation = coreOperation(source);
1342
+ const found = [];
1343
+ if (!operation) return found;
1344
+ const visit = (node) => {
1345
+ ts.forEachChild(node, visit);
1346
+ const options = optionsOf(node, operation);
1347
+ const label = options && labelOf(options);
1348
+ const run = options && member(options, "run");
1349
+ if (!label || !run) return;
1350
+ const returned = returnOf(checker, run);
1351
+ const line = source.getLineAndCharacterOfPosition(node.getStart()).line + 1;
1352
+ for (const exit of returned ? exitsOf(checker, returned) : []) found.push({
1353
+ path,
1354
+ line,
1355
+ label,
1356
+ exit
1357
+ });
1358
+ };
1359
+ visit(source);
1360
+ return found;
1361
+ }
1362
+ /**
1363
+ * Each exit the app's operations declare, read from the types of the app's own `tsconfig.json`.
1364
+ * An app with no `tsconfig.json` declares none.
1365
+ */
1366
+ function declaredExits(root) {
1367
+ const config = join(root, "tsconfig.json");
1368
+ if (!existsSync(config)) return [];
1369
+ const parsed = ts.getParsedCommandLineOfConfigFile(config, {}, {
1370
+ ...ts.sys,
1371
+ onUnRecoverableConfigFileDiagnostic: () => void 0
1372
+ });
1373
+ if (!parsed) return [];
1374
+ const program = ts.createProgram(parsed.fileNames, parsed.options);
1375
+ const checker = program.getTypeChecker();
1376
+ return program.getSourceFiles().flatMap((source) => {
1377
+ const path = relative(root, source.fileName).replaceAll("\\", "/");
1378
+ if (source.isDeclarationFile || !appCode.test(path) || testFile.test(path)) return [];
1379
+ return exitsIn(checker, source, path);
1380
+ });
1381
+ }
1382
+ /** Where a page test leaves its store's text: one `.json` file a test file, under the app. */
1383
+ const pageExits = ".tinker/exits";
1384
+ /** The exits of one page file: the keys of the store's JSON object. */
1385
+ function keysIn(path) {
1386
+ const counts = JSON.parse(readFileSync(path, "utf8"));
1387
+ return typeof counts === "object" && counts !== null ? Object.keys(counts) : [];
1388
+ }
1389
+ /**
1390
+ * The exits a test run reached. The `exits` capsule wrote `file`: one `label<tab>exit` a line.
1391
+ * A page test wrote its store's JSON to a file in `pageExits`.
1392
+ */
1393
+ function reachedIn(root, file) {
1394
+ const folder = join(root, pageExits);
1395
+ const pages = existsSync(folder) ? readdirSync(folder) : [];
1396
+ const lines = existsSync(file) ? readFileSync(file, "utf8").split("\n") : [];
1397
+ return /* @__PURE__ */ new Set([...lines, ...pages.flatMap((name) => keysIn(join(folder, name)))]);
1398
+ }
1399
+ const said = {
1400
+ refused: "refuses",
1401
+ [plain]: "returns"
1402
+ };
1403
+ /** A finding for each declared exit that no test reached. */
1404
+ function unreached(root, file) {
1405
+ const reached = reachedIn(root, file);
1406
+ return declaredExits(root).filter(({ label, exit }) => !reached.has(`${label}\t${exit}`)).map(({ path, line, label, exit }) => ({
1407
+ path,
1408
+ line,
1409
+ rule: "tinker/exit",
1410
+ what: `\`${label}\` ${said[exit] ?? `answers \`${exit}\``}, and no test reaches it`
1411
+ }));
1412
+ }
1413
+ //#endregion
1264
1414
  //#region src/tools.ts
1265
1415
  const tscLine = /^(?:(.+)\((\d+),\d+\): )?error (TS\d+): (.*)$/;
1266
1416
  const viteConfig = "vite.config.{ts,mts,js,mjs}";
@@ -1569,17 +1719,57 @@ function runTools(root, sources) {
1569
1719
  skipped
1570
1720
  };
1571
1721
  }
1722
+ /**
1723
+ * Run the app's tests by its own command, in its folder. `TINKER_EXITS` names a new file: the
1724
+ * `exits` capsule of a test scope writes each exit it sees there, and the file goes after the
1725
+ * read. A page test leaves its exits in `pageExits`, which is emptied first, so an old run says
1726
+ * nothing. A red run names no exit: its tests are the finding.
1727
+ */
1728
+ function runTests(root, command) {
1729
+ const folder = mkdtempSync(join(tmpdir(), "tinker-exits-"));
1730
+ const file = join(folder, "exits.tsv");
1731
+ const env = {
1732
+ ...process.env,
1733
+ TINKER_EXITS: file
1734
+ };
1735
+ rmSync(join(root, pageExits), {
1736
+ recursive: true,
1737
+ force: true
1738
+ });
1739
+ const done = spawnSync(command, {
1740
+ cwd: root,
1741
+ env,
1742
+ shell: true,
1743
+ encoding: "utf8",
1744
+ maxBuffer: 1 << 28
1745
+ });
1746
+ const output = `${done.error ? `${done.error.message}\n` : ""}${done.stdout ?? ""}${done.stderr ?? ""}`;
1747
+ const missed = done.status === 0 ? unreached(root, file) : [];
1748
+ rmSync(folder, {
1749
+ recursive: true,
1750
+ force: true
1751
+ });
1752
+ return {
1753
+ status: done.status,
1754
+ output,
1755
+ unreached: missed
1756
+ };
1757
+ }
1572
1758
  //#endregion
1573
1759
  //#region src/main.ts
1574
1760
  /** A writer fixes a few findings at a time: more than this is noise. */
1575
1761
  const shown = 5;
1762
+ function tail(output) {
1763
+ return output.trimEnd().split("\n").slice(-40).join("\n");
1764
+ }
1576
1765
  const usage = `usage:
1577
1766
  tinker check [root] [--json]
1578
1767
  tinker skill list
1579
1768
  tinker skill load <skill>
1580
1769
 
1581
1770
  check runs the app's types (tsc, the kind gate, the cast gate), then its rules (Tinker's
1582
- rules and the app's other lint). Only the first stage that fails prints. Each finding
1771
+ rules and the app's other lint), then its tests when tinker.json names their command: each
1772
+ exit an operation declares must be reached by a test. Only the first stage that fails prints. Each finding
1583
1773
  prints its fix. "tinker check: OK" and exit 0 is the only sign that the work is done.
1584
1774
  `;
1585
1775
  /** One line per gaps row: marked lines over the row's count, as `G3 5/5`. */
@@ -1622,7 +1812,7 @@ function failed(root, stage, found, gaps) {
1622
1812
  * error; its own findings are rules.
1623
1813
  */
1624
1814
  function stages(root) {
1625
- const { sources, found, doc } = readApp(root);
1815
+ const { sources, found, doc, tests } = readApp(root);
1626
1816
  const tools = runTools(root, sources);
1627
1817
  const all = [
1628
1818
  ...tools.types,
@@ -1648,11 +1838,27 @@ function stages(root) {
1648
1838
  skipped: tools.skipped,
1649
1839
  gaps
1650
1840
  };
1651
- return {
1841
+ if (!tests) return {
1652
1842
  kind: "ok",
1653
1843
  ran,
1654
1844
  gaps
1655
1845
  };
1846
+ const tested = runTests(root, tests);
1847
+ if (tested.status !== 0) return {
1848
+ kind: "red",
1849
+ output: tail(tested.output),
1850
+ gaps
1851
+ };
1852
+ if (tested.unreached.length) return failed(root, "exits", tested.unreached, gaps);
1853
+ return {
1854
+ kind: "ok",
1855
+ ran: [
1856
+ ...ran,
1857
+ "tests",
1858
+ "exits"
1859
+ ],
1860
+ gaps
1861
+ };
1656
1862
  }
1657
1863
  /** A finding's lines: the finding, then its fix once per rule, then the skill to load. */
1658
1864
  function block({ path, line, rule, what, fix, skill }, first) {
@@ -1663,6 +1869,19 @@ function block({ path, line, rule, what, fix, skill }, first) {
1663
1869
  }
1664
1870
  /** Two findings print one fix once: the second points at the first. */
1665
1871
  const sameFix = (a, b) => a.join("\n") === b.join("\n");
1872
+ function failedText({ stage, total, findings, gaps }) {
1873
+ const blocks = findings.map((finding, index) => block(finding, findings.findIndex(({ fix }) => sameFix(fix, finding.fix)) === index));
1874
+ const count = total > findings.length ? `${total} findings, ${findings.length} shown` : "";
1875
+ const after = stage === "types" ? " The rules stage runs once types pass." : "";
1876
+ const next = stage === "exits" ? "add a test for each finding" : "fix each finding";
1877
+ return [
1878
+ gapLine(gaps) + blocks.map((lines) => lines.join("\n")).join("\n\n"),
1879
+ "",
1880
+ `tinker check: ${stage} failed${count ? `, ${count}` : ""}.`,
1881
+ `Next: ${next}, then run \`tinker check\` again.${after}`,
1882
+ ""
1883
+ ].join("\n");
1884
+ }
1666
1885
  function text(report) {
1667
1886
  const gaps = gapLine(report.gaps);
1668
1887
  switch (report.kind) {
@@ -1674,25 +1893,21 @@ function text(report) {
1674
1893
  "Next: add the config the skipped line names, then run `tinker check` again.",
1675
1894
  ""
1676
1895
  ].join("\n");
1677
- case "failed": {
1678
- const { stage, total, findings } = report;
1679
- const blocks = findings.map((finding, index) => block(finding, findings.findIndex(({ fix }) => sameFix(fix, finding.fix)) === index));
1680
- const count = total > findings.length ? `${total} findings, ${findings.length} shown` : "";
1681
- const after = stage === "types" ? " The rules stage runs once types pass." : "";
1682
- return [
1683
- gaps + blocks.map((lines) => lines.join("\n")).join("\n\n"),
1684
- "",
1685
- `tinker check: ${stage} failed${count ? `, ${count}` : ""}.`,
1686
- `Next: fix each finding, then run \`tinker check\` again.${after}`,
1687
- ""
1688
- ].join("\n");
1689
- }
1896
+ case "red": return [
1897
+ report.output,
1898
+ "",
1899
+ "tinker check: tests failed.",
1900
+ "Next: make the tests pass, then run `tinker check` again.",
1901
+ ""
1902
+ ].join("\n");
1903
+ case "failed": return failedText(report);
1690
1904
  }
1691
1905
  }
1692
1906
  /** Exit 0 only for `ok`; a stage that did not run is a config the command cannot use. */
1693
1907
  const codes = {
1694
1908
  ok: 0,
1695
1909
  failed: 1,
1910
+ red: 1,
1696
1911
  incomplete: 2
1697
1912
  };
1698
1913
  function checkCommand(root, json) {
@@ -0,0 +1,16 @@
1
+ //#region src/test.d.ts
2
+ export declare namespace Exits {
3
+ /** Where a page keeps its exits: `localStorage`, or a thing with the same two methods. */
4
+ type Store = Pick<Storage, "getItem" | "setItem">;
5
+ }
6
+ /**
7
+ * Put this first in a test scope's `capsules`. A server test passes
8
+ * `{ file: process.env.TINKER_EXITS }`; a page passes `{ store: localStorage }`. It keeps the exit
9
+ * of each operation run, and `tinker check` then names each declared exit that no test reached.
10
+ * A run that throws reaches no exit.
11
+ */
12
+ export declare const exits: import("@tinkered/core").Capsule.Handle<{
13
+ readonly file: import("@tinkered/core").Edge<"optional", import("@tinkered/core").Tag.Handle<string>>;
14
+ readonly store: import("@tinkered/core").Edge<"optional", import("@tinkered/core").Tag.Handle<Exits.Store>>;
15
+ }, {}, void>;
16
+ //#endregion
package/dist/test.mjs ADDED
@@ -0,0 +1,74 @@
1
+ import { capsule, tag } from "@tinkered/core";
2
+ //#region src/test.ts
3
+ /**
4
+ * The file the reached exits go to. `tinker check` names it in `TINKER_EXITS` for the tests it
5
+ * runs; outside a check there is none, and the capsule writes nothing.
6
+ */
7
+ const file = tag({ label: "tinker.exits.file" });
8
+ /**
9
+ * A page has no file: its exits go to this store, under the key `tinker.exits`, as a JSON object
10
+ * of `label<tab>exit` to how many times it was reached. Devtools reads the same key.
11
+ */
12
+ const store = tag({ label: "tinker.exits.store" });
13
+ /** The one key of a store. Each browser key of Tinker starts with `tinker.`. */
14
+ const key = "tinker.exits";
15
+ /** The exits a store has not got yet. The first one of a task asks for the write. */
16
+ const waiting = /* @__PURE__ */ new WeakMap();
17
+ /** One write for every exit that waited: a run never waits for the store. */
18
+ function flush(to) {
19
+ const counts = JSON.parse(to.getItem(key) ?? "{}");
20
+ for (const line of waiting.get(to) ?? []) counts[line] = (counts[line] ?? 0) + 1;
21
+ waiting.delete(to);
22
+ to.setItem(key, JSON.stringify(counts));
23
+ }
24
+ function keep(to, line) {
25
+ const lines = waiting.get(to);
26
+ if (lines) return void lines.push(line);
27
+ waiting.set(to, [line]);
28
+ queueMicrotask(() => flush(to));
29
+ }
30
+ /** `node:fs` by name at the first write, so a page that passes no `file` never loads it. */
31
+ function append(to, line) {
32
+ process.getBuiltinModule("node:fs").appendFileSync(to, `${line}\n`);
33
+ }
34
+ /**
35
+ * Core marks a refusal with a symbol it does not export, so its description is the one sign a
36
+ * capsule has. This look goes when Core says a run's exit itself.
37
+ */
38
+ function isRefusal(value) {
39
+ return Object.getOwnPropertySymbols(value).some(({ description }) => description === "refused");
40
+ }
41
+ /** A run's exit, in the words `tinker check` reads from the types: a `kind`, `refused`, `value`. */
42
+ function exitOf(value) {
43
+ if (typeof value !== "object" || value === null) return "value";
44
+ if (isRefusal(value)) return "refused";
45
+ return "kind" in value && typeof value.kind === "string" ? value.kind : "value";
46
+ }
47
+ /**
48
+ * Put this first in a test scope's `capsules`. A server test passes
49
+ * `{ file: process.env.TINKER_EXITS }`; a page passes `{ store: localStorage }`. It keeps the exit
50
+ * of each operation run, and `tinker check` then names each declared exit that no test reached.
51
+ * A run that throws reaches no exit.
52
+ */
53
+ const exits = capsule({
54
+ label: "tinker.exits",
55
+ config: {
56
+ file: file.optional,
57
+ store: store.optional
58
+ },
59
+ hooks: { run(event) {
60
+ const { file: to, store: page } = event.config;
61
+ const label = "label" in event.op ? event.op.label : void 0;
62
+ if (!label || !to.present && !page.present) return event.next();
63
+ const say = (value) => {
64
+ const line = `${label}\t${exitOf(value)}`;
65
+ if (to.present) append(to.value, line);
66
+ if (page.present) keep(page.value, line);
67
+ return value;
68
+ };
69
+ const out = event.next();
70
+ return out instanceof Promise ? out.then(say) : say(out);
71
+ } }
72
+ });
73
+ //#endregion
74
+ export { exits };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinkered/cli",
3
- "version": "0.28.0",
3
+ "version": "0.29.0",
4
4
  "description": "The tinker command: one check that corrects the writer (types, then rules, each finding with its fix from the skill), and the skills.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -21,6 +21,7 @@
21
21
  "exports": {
22
22
  ".": "./dist/index.mjs",
23
23
  "./config": "./dist/config.mjs",
24
+ "./test": "./dist/test.mjs",
24
25
  "./lint": "./lint/index.mjs",
25
26
  "./tsconfig.json": "./base/tsconfig.json",
26
27
  "./package.json": "./package.json"
@@ -35,9 +36,19 @@
35
36
  "devDependencies": {
36
37
  "@stryker-mutator/core": "^10.0.0",
37
38
  "@stryker-mutator/vitest-runner": "^10.0.0",
39
+ "@tinkered/core": "^0.29.0",
38
40
  "@types/node": "^26.1.1",
39
41
  "vite-plus": "1.0.0",
40
- "vitest": "5.0.1"
42
+ "vitest": "5.0.1",
43
+ "zod": "^4.0.0"
44
+ },
45
+ "peerDependencies": {
46
+ "@tinkered/core": "^0.29.0"
47
+ },
48
+ "peerDependenciesMeta": {
49
+ "@tinkered/core": {
50
+ "optional": true
51
+ }
41
52
  },
42
53
  "engines": {
43
54
  "node": ">=22.5"