@tinkered/cli 0.30.0 → 0.31.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 +140 -2
- package/dist/cli.mjs +1 -1
- package/dist/index.d.mts +5 -4
- package/dist/index.mjs +1 -1
- package/dist/{main-BO5BHvEC.mjs → main-BAo7SB-T.mjs} +746 -162
- package/dist/vite.d.mts +10 -0
- package/dist/vite.mjs +37 -0
- package/package.json +8 -3
package/README.md
CHANGED
|
@@ -20,6 +20,7 @@ GitHub release; the
|
|
|
20
20
|
|
|
21
21
|
```text
|
|
22
22
|
tinker check [root] [--json]
|
|
23
|
+
tinker graph [root] [--write]
|
|
23
24
|
tinker skill list
|
|
24
25
|
tinker skill load <skill>
|
|
25
26
|
```
|
|
@@ -38,6 +39,8 @@ bun --bun tinker check
|
|
|
38
39
|
the cast gate.
|
|
39
40
|
2. **rules:** Tinker's rules, then the app's
|
|
40
41
|
other lint.
|
|
42
|
+
3. **graph:** the graph of the code must match
|
|
43
|
+
`tinker.graph`.
|
|
41
44
|
|
|
42
45
|
- Only the first stage that fails prints.
|
|
43
46
|
- At most 5 findings print.
|
|
@@ -86,6 +89,94 @@ A tool with no config is skipped, and the
|
|
|
86
89
|
`tinker check: not done`, with exit 2: only a
|
|
87
90
|
run of every stage can say OK.
|
|
88
91
|
|
|
92
|
+
## The graph
|
|
93
|
+
|
|
94
|
+
`tinker graph` prints the app's graph. It has one
|
|
95
|
+
line per operation (ADR 0161). The line holds
|
|
96
|
+
facts:
|
|
97
|
+
|
|
98
|
+
- `exits`: each way out, as the exit stage names
|
|
99
|
+
them;
|
|
100
|
+
- `reads`: each cell read, and how;
|
|
101
|
+
- `writes`: each cell write, and how;
|
|
102
|
+
- `calls`: each operation it runs.
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
issue.move.do exits{gone,moved,stale}
|
|
106
|
+
reads{issues.list.of} writes{issues.list.set}
|
|
107
|
+
calls{issues.inTeam}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- A name is the label, never a local name.
|
|
111
|
+
- The sets hold all the code of `run`, callbacks
|
|
112
|
+
too. They do not say which exit a write is on.
|
|
113
|
+
- A dep written in place, in a `const`, or spread
|
|
114
|
+
from one reads the same.
|
|
115
|
+
- A dep taken apart in the body,
|
|
116
|
+
`const { list } = deps`, reads the same as one
|
|
117
|
+
taken apart in the parameters.
|
|
118
|
+
- A bare cell dep, `all: issues`, gives `run` its
|
|
119
|
+
value: that reads `issues.list.get` each run.
|
|
120
|
+
- The graph reads `src` and `cmds` only.
|
|
121
|
+
|
|
122
|
+
The graph is facts only. It never judges them.
|
|
123
|
+
The reader judges: a person or an LLM reads the
|
|
124
|
+
line and its diff, and asks if the change is
|
|
125
|
+
meant.
|
|
126
|
+
|
|
127
|
+
An empty set means "none". A `?` in a set means
|
|
128
|
+
"the graph could not see here": it never guesses.
|
|
129
|
+
A set gets `?` when the code can touch a dep in a
|
|
130
|
+
way the graph cannot follow:
|
|
131
|
+
|
|
132
|
+
- a dep handed on: passed to a function, put in
|
|
133
|
+
an array or an object, or given another name;
|
|
134
|
+
- the deps handed on whole, a rest
|
|
135
|
+
`{ a, ...others }` taken from them, or a key
|
|
136
|
+
the graph cannot read, such as `{ [key]: x }`;
|
|
137
|
+
- a call on a dep the graph does not know, such
|
|
138
|
+
as `list.watch(…)`;
|
|
139
|
+
- a dep the graph cannot name: a member of a
|
|
140
|
+
capsule or a contract (`seaApi["clock.now"]`),
|
|
141
|
+
a cell whose label is not written as a string,
|
|
142
|
+
an `atScope` or `atNamespace` controller;
|
|
143
|
+
- a tag dep that holds a unit (ADR 0151), through
|
|
144
|
+
any edge: an operation gives `calls{?}`; a
|
|
145
|
+
cell, a view or a read gives `reads{?}`, and a
|
|
146
|
+
cell `writes{?}` too;
|
|
147
|
+
- a `run` passed by name, not written in place.
|
|
148
|
+
With a dep the graph cannot name, every set
|
|
149
|
+
gets `?`.
|
|
150
|
+
|
|
151
|
+
The `?` goes in each set that dep can touch: a
|
|
152
|
+
cell in `reads` and `writes`, a read in `reads`,
|
|
153
|
+
an operation in `calls`. For a dep the graph
|
|
154
|
+
cannot name, its type in `run` says which.
|
|
155
|
+
|
|
156
|
+
A tag that holds a union of unit kinds, or a held
|
|
157
|
+
cell that `run` never uses, may show no `?`.
|
|
158
|
+
|
|
159
|
+
The graph reads each op's own body. A resource's
|
|
160
|
+
own code is not read: a write inside a
|
|
161
|
+
resource's value does not show.
|
|
162
|
+
|
|
163
|
+
`tinker graph --write` writes the graph to
|
|
164
|
+
`tinker.graph`. Commit that file. Then the check
|
|
165
|
+
builds the graph again and compares. Each line
|
|
166
|
+
that differs is a finding at the operation:
|
|
167
|
+
|
|
168
|
+
```text
|
|
169
|
+
src/issues/ops.server.ts:80 tinker/graph
|
|
170
|
+
issue.move.do: writes{issues.list.set},
|
|
171
|
+
tinker.graph says writes{}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- Meant the change? Run `--write` again. The
|
|
175
|
+
reviewer reads the diff of the file.
|
|
176
|
+
- Did not mean it? Fix the code.
|
|
177
|
+
- No `tinker.graph` is one finding, when the app
|
|
178
|
+
has an operation.
|
|
179
|
+
|
|
89
180
|
## The tests and the exits
|
|
90
181
|
|
|
91
182
|
An exit is one way out of an operation: each
|
|
@@ -100,9 +191,9 @@ Name the test command in `tinker.json`:
|
|
|
100
191
|
|
|
101
192
|
Then the check runs two more stages:
|
|
102
193
|
|
|
103
|
-
|
|
194
|
+
4. **tests:** the command. Red tests print the
|
|
104
195
|
end of their output.
|
|
105
|
-
|
|
196
|
+
5. **exits:** each exit that the types declare
|
|
106
197
|
and no test reached is a finding.
|
|
107
198
|
|
|
108
199
|
```text
|
|
@@ -228,6 +319,19 @@ Intent finds them (ADR 0143).
|
|
|
228
319
|
State lives in a Core cell.
|
|
229
320
|
- `tinker/gap` — a gap marker sits on an open
|
|
230
321
|
row: see below.
|
|
322
|
+
- `tinker/barrel` — a file in `src/` or `cmds/`
|
|
323
|
+
exports only what it declares. A re-export is
|
|
324
|
+
a finding: `export … from "…"`, of values or
|
|
325
|
+
types, or `export { name }` of an imported
|
|
326
|
+
name (ADR 0160).
|
|
327
|
+
- `tinker/link` — a page has no plain `<a>` to
|
|
328
|
+
a path in the app: `/issues`, `./next`. A
|
|
329
|
+
click loads the whole page, so the app state
|
|
330
|
+
is lost. Use the router's `Link`.
|
|
331
|
+
A server path, such as `/auth/login`: add `rel="external"`.
|
|
332
|
+
A link to another site or to a file, `#top`,
|
|
333
|
+
a download, a new tab, or what the rule
|
|
334
|
+
cannot read passes.
|
|
231
335
|
|
|
232
336
|
A page file is a file in `src/` with no `.server`
|
|
233
337
|
in its name.
|
|
@@ -369,6 +473,40 @@ const answer = await fetch("/api/auth");
|
|
|
369
473
|
Each run prints the counts:
|
|
370
474
|
`gaps: G1 3/3, G3 5/5`.
|
|
371
475
|
|
|
476
|
+
## The page guard
|
|
477
|
+
|
|
478
|
+
A page build can take server code by accident,
|
|
479
|
+
through an import or a re-export. `pageGuard()`
|
|
480
|
+
stops it (ADR 0160).
|
|
481
|
+
|
|
482
|
+
```ts
|
|
483
|
+
import { pageGuard } from "@tinkered/cli/vite";
|
|
484
|
+
|
|
485
|
+
export default defineConfig({
|
|
486
|
+
plugins: [pageGuard()],
|
|
487
|
+
});
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
It runs only where the page is built: in dev, in
|
|
491
|
+
the build, and in browser tests. It refuses an
|
|
492
|
+
import of:
|
|
493
|
+
|
|
494
|
+
- a file with a `.server.` part in its name;
|
|
495
|
+
- a `node:` or `bun:` name;
|
|
496
|
+
- `@tinkered/entry`, or one of its entries;
|
|
497
|
+
- `@tinkered/bun`, but not `@tinkered/bun/client`.
|
|
498
|
+
|
|
499
|
+
The build error names the import and its file:
|
|
500
|
+
|
|
501
|
+
```text
|
|
502
|
+
page imports server code "./db.server"
|
|
503
|
+
from src/todo/barrel.ts
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
An `import type` is gone before the build reads
|
|
507
|
+
imports. So a page may take types from a server
|
|
508
|
+
file.
|
|
509
|
+
|
|
372
510
|
## Lint rules
|
|
373
511
|
|
|
374
512
|
`@tinkered/cli/lint` is an Oxlint plugin.
|
package/dist/cli.mjs
CHANGED
package/dist/index.d.mts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
+
import ts from "typescript-api";
|
|
1
2
|
//#region src/rules.d.ts
|
|
2
3
|
/** Tinker's own rules: `check` finds them in the app's files. */
|
|
3
|
-
declare const own: readonly ["tinker/plain", "tinker/one-wire", "tinker/react-state", "tinker/gap"];
|
|
4
|
+
declare const own: readonly ["tinker/plain", "tinker/one-wire", "tinker/react-state", "tinker/gap", "tinker/barrel", "tinker/link"];
|
|
4
5
|
//#endregion
|
|
5
6
|
//#region src/check.d.ts
|
|
6
7
|
declare namespace Check {
|
|
@@ -102,10 +103,10 @@ export declare function isError<N extends Errors.Name>(value: unknown, kind: N):
|
|
|
102
103
|
//#region src/tools.d.ts
|
|
103
104
|
declare namespace Tools {
|
|
104
105
|
/**
|
|
105
|
-
* A stage of `tinker check`: `types` runs first, `rules` only once it is clean,
|
|
106
|
-
* only once the app's tests pass.
|
|
106
|
+
* A stage of `tinker check`: `types` runs first, `rules` only once it is clean, `graph` only
|
|
107
|
+
* once the rules are, and `exits` only once the app's tests pass.
|
|
107
108
|
*/
|
|
108
|
-
type Stage = "types" | "rules" | "exits";
|
|
109
|
+
type Stage = "types" | "rules" | "graph" | "exits";
|
|
109
110
|
/** A run of the app's tests: its exit status, all it said, and the exits no test reached. */
|
|
110
111
|
type Tested = {
|
|
111
112
|
status: number | null;
|
package/dist/index.mjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { n as check, r as isError, t as main } from "./main-
|
|
1
|
+
import { n as check, r as isError, t as main } from "./main-BAo7SB-T.mjs";
|
|
2
2
|
export { check, isError, main };
|
|
@@ -1,9 +1,48 @@
|
|
|
1
|
-
import { existsSync, globSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
|
|
1
|
+
import { existsSync, globSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
2
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
6
|
import { tmpdir } from "node:os";
|
|
7
|
+
//#region src/barrel.ts
|
|
8
|
+
/** The names one import binds: its default, its namespace, and each named one. */
|
|
9
|
+
function boundBy({ name, namedBindings }) {
|
|
10
|
+
const names = name ? [name.text] : [];
|
|
11
|
+
if (!namedBindings) return names;
|
|
12
|
+
if (ts.isNamespaceImport(namedBindings)) return [...names, namedBindings.name.text];
|
|
13
|
+
return [...names, ...namedBindings.elements.map((element) => element.name.text)];
|
|
14
|
+
}
|
|
15
|
+
function importedNames(source) {
|
|
16
|
+
return new Set(source.statements.flatMap((statement) => ts.isImportDeclaration(statement) && statement.importClause ? boundBy(statement.importClause) : []));
|
|
17
|
+
}
|
|
18
|
+
/** `export { a, b as c }` with no `from`: it passes on an import when one local name is one. */
|
|
19
|
+
function passesOn(imported, statement) {
|
|
20
|
+
const list = statement.exportClause;
|
|
21
|
+
if (!list || !ts.isNamedExports(list)) return false;
|
|
22
|
+
return list.elements.some(({ propertyName, name }) => imported.has((propertyName ?? name).text));
|
|
23
|
+
}
|
|
24
|
+
/** A statement that exports what another module declares. */
|
|
25
|
+
function isBarrel(imported, statement) {
|
|
26
|
+
if (!ts.isExportDeclaration(statement)) return false;
|
|
27
|
+
return Boolean(statement.moduleSpecifier) || passesOn(imported, statement);
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* `tinker/barrel` (ADR 0160): app code has no barrel. A barrel hides which file an import
|
|
31
|
+
* reaches, so a page can take server code by accident. A finding is `export … from "…"` of
|
|
32
|
+
* values or of types, and `export { name }` of an imported name. A file that exports what it
|
|
33
|
+
* declares passes, as `export const plus = add` does. Only top-level statements can export.
|
|
34
|
+
*/
|
|
35
|
+
function findBarrel({ path, text }) {
|
|
36
|
+
const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
|
|
37
|
+
const imported = importedNames(source);
|
|
38
|
+
return source.statements.filter((statement) => isBarrel(imported, statement)).map((statement) => ({
|
|
39
|
+
path,
|
|
40
|
+
line: source.getLineAndCharacterOfPosition(statement.getStart()).line + 1,
|
|
41
|
+
rule: "tinker/barrel",
|
|
42
|
+
what: `\`${statement.getText(source).replace(/\s+/g, " ").replace(/;$/, "")}\`: a re-export`
|
|
43
|
+
}));
|
|
44
|
+
}
|
|
45
|
+
//#endregion
|
|
7
46
|
//#region src/errors.ts
|
|
8
47
|
/** The only place the command throws a registry error. */
|
|
9
48
|
function raise(kind, payload) {
|
|
@@ -17,6 +56,154 @@ function isError(value, kind) {
|
|
|
17
56
|
return value instanceof Error && value.kind === kind;
|
|
18
57
|
}
|
|
19
58
|
//#endregion
|
|
59
|
+
//#region src/exits.ts
|
|
60
|
+
/** The exit of a return with no `kind` of its own. */
|
|
61
|
+
const plain = "value";
|
|
62
|
+
/** A hook's `refuse(payload)`, by the name Core gives its type. */
|
|
63
|
+
const refusal = "Refused";
|
|
64
|
+
/**
|
|
65
|
+
* The app's own code. The base under `tinker/` is Tinker's, and moves into a package that has
|
|
66
|
+
* its own tests (ADR 0159).
|
|
67
|
+
*/
|
|
68
|
+
const appCode = /^(?:src|cmds)\//;
|
|
69
|
+
/** A test file declares no exit: its operations are fixtures. */
|
|
70
|
+
const testFile = /\.test\.[mc]?tsx?$/;
|
|
71
|
+
function kindsOf(checker, type) {
|
|
72
|
+
const kind = type.getProperty("kind");
|
|
73
|
+
if (!kind) return [];
|
|
74
|
+
const of = checker.getTypeOfSymbol(kind);
|
|
75
|
+
const parts = of.isUnion() ? of.types : [of];
|
|
76
|
+
return parts.every((part) => part.isStringLiteral()) ? parts.map((part) => part.value) : [];
|
|
77
|
+
}
|
|
78
|
+
/** Each exit a return type holds: a union gives one per member, and a promise gives its value's. */
|
|
79
|
+
function exitsOf(checker, returned) {
|
|
80
|
+
const type = checker.getAwaitedType(returned) ?? returned;
|
|
81
|
+
if (type.flags & ts.TypeFlags.Never) return [];
|
|
82
|
+
const exits = /* @__PURE__ */ new Set();
|
|
83
|
+
for (const part of type.isUnion() ? type.types : [type]) {
|
|
84
|
+
if (checker.typeToString(part) === refusal) {
|
|
85
|
+
exits.add("refused");
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
88
|
+
const kinds = kindsOf(checker, part);
|
|
89
|
+
for (const kind of kinds.length ? kinds : [plain]) exits.add(kind);
|
|
90
|
+
}
|
|
91
|
+
return [...exits].sort();
|
|
92
|
+
}
|
|
93
|
+
/** The names a file imports from Core. */
|
|
94
|
+
function coreImports(source) {
|
|
95
|
+
return source.statements.flatMap((statement) => {
|
|
96
|
+
if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) return [];
|
|
97
|
+
const names = statement.importClause?.namedBindings;
|
|
98
|
+
return statement.moduleSpecifier.text === "@tinkered/core" && names && ts.isNamedImports(names) ? [...names.elements] : [];
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
/** The name `operation` has in this file, when it comes from Core. */
|
|
102
|
+
function coreOperation(source) {
|
|
103
|
+
return coreImports(source).find((element) => (element.propertyName ?? element.name).text === "operation")?.name.text;
|
|
104
|
+
}
|
|
105
|
+
function member(options, name) {
|
|
106
|
+
return options.properties.find((property) => property.name && ts.isIdentifier(property.name) && property.name.text === name);
|
|
107
|
+
}
|
|
108
|
+
/** The return type of an operation's `run`, written as a property or as a method. */
|
|
109
|
+
function returnOf(checker, run) {
|
|
110
|
+
if (ts.isMethodDeclaration(run)) return checker.getSignatureFromDeclaration(run)?.getReturnType();
|
|
111
|
+
if (!ts.isPropertyAssignment(run)) return void 0;
|
|
112
|
+
return checker.getTypeAtLocation(run.initializer).getCallSignatures()[0]?.getReturnType();
|
|
113
|
+
}
|
|
114
|
+
/** The options of a call of `operation`, when the call has them as a literal. */
|
|
115
|
+
function optionsOf(node, operation) {
|
|
116
|
+
if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return void 0;
|
|
117
|
+
const [options] = node.arguments;
|
|
118
|
+
if (node.expression.text !== operation || !options) return void 0;
|
|
119
|
+
return ts.isObjectLiteralExpression(options) ? options : void 0;
|
|
120
|
+
}
|
|
121
|
+
/** An operation's label, when it is a literal: a tool cannot name a label made at run time. */
|
|
122
|
+
function labelOf(options) {
|
|
123
|
+
const label = member(options, "label");
|
|
124
|
+
if (!label || !ts.isPropertyAssignment(label)) return void 0;
|
|
125
|
+
return ts.isStringLiteralLike(label.initializer) ? label.initializer.text : void 0;
|
|
126
|
+
}
|
|
127
|
+
function operationsIn(checker, source, path) {
|
|
128
|
+
const operation = coreOperation(source);
|
|
129
|
+
const found = [];
|
|
130
|
+
if (!operation) return found;
|
|
131
|
+
const visit = (node) => {
|
|
132
|
+
ts.forEachChild(node, visit);
|
|
133
|
+
const options = optionsOf(node, operation);
|
|
134
|
+
const label = options && labelOf(options);
|
|
135
|
+
const run = options && member(options, "run");
|
|
136
|
+
if (!label || !run) return;
|
|
137
|
+
const returned = returnOf(checker, run);
|
|
138
|
+
const line = source.getLineAndCharacterOfPosition(node.getStart()).line + 1;
|
|
139
|
+
const exits = returned ? exitsOf(checker, returned) : [];
|
|
140
|
+
found.push({
|
|
141
|
+
path,
|
|
142
|
+
line,
|
|
143
|
+
label,
|
|
144
|
+
options,
|
|
145
|
+
run,
|
|
146
|
+
exits
|
|
147
|
+
});
|
|
148
|
+
};
|
|
149
|
+
visit(source);
|
|
150
|
+
return found;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* The app's operations, read with the types of the app's own `tsconfig.json`. An app with no
|
|
154
|
+
* `tsconfig.json` has none.
|
|
155
|
+
*/
|
|
156
|
+
function readOperations(root) {
|
|
157
|
+
const config = join(root, "tsconfig.json");
|
|
158
|
+
if (!existsSync(config)) return void 0;
|
|
159
|
+
const parsed = ts.getParsedCommandLineOfConfigFile(config, {}, {
|
|
160
|
+
...ts.sys,
|
|
161
|
+
onUnRecoverableConfigFileDiagnostic: () => void 0
|
|
162
|
+
});
|
|
163
|
+
if (!parsed) return void 0;
|
|
164
|
+
const program = ts.createProgram(parsed.fileNames, parsed.options);
|
|
165
|
+
const checker = program.getTypeChecker();
|
|
166
|
+
return {
|
|
167
|
+
checker,
|
|
168
|
+
operations: program.getSourceFiles().flatMap((source) => {
|
|
169
|
+
const path = relative(root, source.fileName).replaceAll("\\", "/");
|
|
170
|
+
if (source.isDeclarationFile || !appCode.test(path) || testFile.test(path)) return [];
|
|
171
|
+
return operationsIn(checker, source, path);
|
|
172
|
+
})
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
/** Where a page test leaves its store's text: one `.json` file a test file, under the app. */
|
|
176
|
+
const pageExits = ".tinker/exits";
|
|
177
|
+
/** The exits of one page file: the keys of the store's JSON object. */
|
|
178
|
+
function keysIn(path) {
|
|
179
|
+
const counts = JSON.parse(readFileSync(path, "utf8"));
|
|
180
|
+
return typeof counts === "object" && counts !== null ? Object.keys(counts) : [];
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* The exits a test run reached. The `exits` capsule wrote `file`: one `label<tab>exit` a line.
|
|
184
|
+
* A page test wrote its store's JSON to a file in `pageExits`.
|
|
185
|
+
*/
|
|
186
|
+
function reachedIn(root, file) {
|
|
187
|
+
const folder = join(root, pageExits);
|
|
188
|
+
const pages = existsSync(folder) ? readdirSync(folder) : [];
|
|
189
|
+
const lines = existsSync(file) ? readFileSync(file, "utf8").split("\n") : [];
|
|
190
|
+
return /* @__PURE__ */ new Set([...lines, ...pages.flatMap((name) => keysIn(join(folder, name)))]);
|
|
191
|
+
}
|
|
192
|
+
const said = {
|
|
193
|
+
refused: "refuses",
|
|
194
|
+
[plain]: "returns"
|
|
195
|
+
};
|
|
196
|
+
/** A finding for each exit in `declared` that no test reached. */
|
|
197
|
+
function unreached(root, file, declared) {
|
|
198
|
+
const reached = reachedIn(root, file);
|
|
199
|
+
return declared.filter(({ label, exit }) => !reached.has(`${label}\t${exit}`)).map(({ path, line, label, exit }) => ({
|
|
200
|
+
path,
|
|
201
|
+
line,
|
|
202
|
+
rule: "tinker/exit",
|
|
203
|
+
what: `\`${label}\` ${said[exit] ?? `answers \`${exit}\``}, and no test reaches it`
|
|
204
|
+
}));
|
|
205
|
+
}
|
|
206
|
+
//#endregion
|
|
20
207
|
//#region src/gaps.ts
|
|
21
208
|
/** A marker allows the finding on the next line: `// tinker-gap: G3`, alone on its line. */
|
|
22
209
|
const markerLine = /^\s*\/\/ tinker-gap: (G\d+)\s*$/;
|
|
@@ -113,6 +300,94 @@ function applyGaps(findings, sources, doc) {
|
|
|
113
300
|
};
|
|
114
301
|
}
|
|
115
302
|
//#endregion
|
|
303
|
+
//#region src/link.ts
|
|
304
|
+
/** A scheme, as in `https:`, `mailto:` or `tel:`: the link leaves the app. */
|
|
305
|
+
const scheme = /^[a-z][\w+.-]*:/i;
|
|
306
|
+
/**
|
|
307
|
+
* A path that ends in a file name, as `/llms.txt` or `/sea.html?room=1`: the server sends a file,
|
|
308
|
+
* and no route of the router answers it. A route with a dot, as `/v1.2`, passes too: the price of
|
|
309
|
+
* a rule that reads no route list.
|
|
310
|
+
*/
|
|
311
|
+
const file = /^[^?#]*\.\w+(?:[?#]|$)/;
|
|
312
|
+
/**
|
|
313
|
+
* The text of a value written out: a string, in braces or not, or a template literal with `…` for
|
|
314
|
+
* each substitution. A template that starts with a substitution cannot be read: no text.
|
|
315
|
+
*/
|
|
316
|
+
function textOf$1(value) {
|
|
317
|
+
const written = value && ts.isJsxExpression(value) ? value.expression : value;
|
|
318
|
+
if (!written) return;
|
|
319
|
+
if (ts.isStringLiteral(written) || ts.isNoSubstitutionTemplateLiteral(written)) return written.text;
|
|
320
|
+
if (!ts.isTemplateExpression(written) || !written.head.text) return;
|
|
321
|
+
return written.head.text + written.templateSpans.map(({ literal }) => `…${literal.text}`).join("");
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* A page inside the app: `/issues`, `./next`, `?page=2`. Not `//host`, `#top`, a scheme, or a
|
|
325
|
+
* file. An empty `href` cannot be read, so it is no finding.
|
|
326
|
+
*/
|
|
327
|
+
function isPage(href) {
|
|
328
|
+
if (href === "" || href.startsWith("//") || href.startsWith("#")) return false;
|
|
329
|
+
return !scheme.test(href) && !file.test(href);
|
|
330
|
+
}
|
|
331
|
+
/**
|
|
332
|
+
* An attribute the `<a>` has whose text passes `says`, or whose text the rule cannot read. A
|
|
333
|
+
* target or rel that is partly read (a template with a gap) counts as read.
|
|
334
|
+
*/
|
|
335
|
+
function saysOrUnread(attributes, name, says) {
|
|
336
|
+
if (!attributes.has(name)) return false;
|
|
337
|
+
const text = textOf$1(attributes.get(name));
|
|
338
|
+
return text === void 0 || says(text);
|
|
339
|
+
}
|
|
340
|
+
/**
|
|
341
|
+
* `download`, `target="_blank"` or `rel="external"`: the link means to leave the page. A
|
|
342
|
+
* `target` or `rel` the rule cannot read passes, as an `href` it cannot read does.
|
|
343
|
+
*/
|
|
344
|
+
function leaves(attributes) {
|
|
345
|
+
return attributes.has("download") || saysOrUnread(attributes, "target", (target) => target === "_blank") || saysOrUnread(attributes, "rel", (rel) => rel.split(/\s+/).includes("external"));
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* The attributes of one `<a>`, or none when it has a spread: the spread may hold a `target` or
|
|
349
|
+
* `rel` the rule cannot read.
|
|
350
|
+
*/
|
|
351
|
+
function attributesOf(link) {
|
|
352
|
+
const attributes = /* @__PURE__ */ new Map();
|
|
353
|
+
for (const attribute of link.attributes.properties) {
|
|
354
|
+
if (!ts.isJsxAttribute(attribute)) return;
|
|
355
|
+
attributes.set(attribute.name.getText(), attribute.initializer);
|
|
356
|
+
}
|
|
357
|
+
return attributes;
|
|
358
|
+
}
|
|
359
|
+
/** The `href` of an `<a>` that is a finding: written out, a page inside the app, and it stays. */
|
|
360
|
+
function inAppHref(node) {
|
|
361
|
+
if (!ts.isJsxOpeningElement(node) && !ts.isJsxSelfClosingElement(node)) return;
|
|
362
|
+
if (node.tagName.getText() !== "a") return;
|
|
363
|
+
const attributes = attributesOf(node);
|
|
364
|
+
if (!attributes) return;
|
|
365
|
+
const href = textOf$1(attributes.get("href"));
|
|
366
|
+
return href !== void 0 && isPage(href) && !leaves(attributes) ? href : void 0;
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* `tinker/link`: a plain `<a href>` to a path inside the app does a full page load, so app state
|
|
370
|
+
* is lost (CUJ eval run 5: 3 of 10 writers). The router's `Link` moves without one. It borrows
|
|
371
|
+
* the scope of Next.js `no-html-link-for-pages`: only a link to a page of the app, so a link to a
|
|
372
|
+
* file passes. What the rule cannot read is no finding: the rule does not guess.
|
|
373
|
+
*/
|
|
374
|
+
function findLink({ path, text }) {
|
|
375
|
+
const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
|
|
376
|
+
const findings = [];
|
|
377
|
+
const visit = (node) => {
|
|
378
|
+
const href = inAppHref(node);
|
|
379
|
+
if (href !== void 0) findings.push({
|
|
380
|
+
path,
|
|
381
|
+
line: source.getLineAndCharacterOfPosition(node.getStart()).line + 1,
|
|
382
|
+
rule: "tinker/link",
|
|
383
|
+
what: `\`${href}\`: a plain <a href> to an in-app path reloads the page`
|
|
384
|
+
});
|
|
385
|
+
ts.forEachChild(node, visit);
|
|
386
|
+
};
|
|
387
|
+
visit(source);
|
|
388
|
+
return findings;
|
|
389
|
+
}
|
|
390
|
+
//#endregion
|
|
116
391
|
//#region src/page.ts
|
|
117
392
|
/** The banned hooks, by the name of the hook React exports. */
|
|
118
393
|
const hooks = /* @__PURE__ */ new Set([
|
|
@@ -1133,7 +1408,12 @@ function readApp(root) {
|
|
|
1133
1408
|
const config = configOf(root);
|
|
1134
1409
|
const app = sourcesOf(root, appFiles, appFile);
|
|
1135
1410
|
const page = pageSources(root, config.page ?? {});
|
|
1136
|
-
const found = [
|
|
1411
|
+
const found = [
|
|
1412
|
+
...findPlain(app, config.plain?.entries ?? {}),
|
|
1413
|
+
...page.flatMap(findPage),
|
|
1414
|
+
...page.filter(({ path }) => path.endsWith("x")).flatMap(findLink),
|
|
1415
|
+
...app.filter(({ path }) => appCode.test(path)).flatMap(findBarrel)
|
|
1416
|
+
];
|
|
1137
1417
|
return {
|
|
1138
1418
|
sources: [...new Map([...app, ...page].map((source) => [source.path, source])).values()],
|
|
1139
1419
|
found,
|
|
@@ -1161,13 +1441,403 @@ function check(root) {
|
|
|
1161
1441
|
};
|
|
1162
1442
|
}
|
|
1163
1443
|
//#endregion
|
|
1444
|
+
//#region src/graph.ts
|
|
1445
|
+
/** The app's committed graph, at its root (ADR 0161). */
|
|
1446
|
+
const graphFile = "tinker.graph";
|
|
1447
|
+
const writeKinds = [
|
|
1448
|
+
"set",
|
|
1449
|
+
"update",
|
|
1450
|
+
"delete"
|
|
1451
|
+
];
|
|
1452
|
+
const readKinds = [
|
|
1453
|
+
"get",
|
|
1454
|
+
"of",
|
|
1455
|
+
"where"
|
|
1456
|
+
];
|
|
1457
|
+
/** A dep that reads one part of a keyed cell: `issues.where({ teamId })`. */
|
|
1458
|
+
const partKinds = ["of", "where"];
|
|
1459
|
+
/** The call kinds that run an operation a dep names. */
|
|
1460
|
+
const runKinds = ["run", "settle"];
|
|
1461
|
+
/** The `const` a name stands for, through an import. */
|
|
1462
|
+
function declarationOf(checker, symbol) {
|
|
1463
|
+
if (!symbol) return void 0;
|
|
1464
|
+
const declaration = (symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol).valueDeclaration;
|
|
1465
|
+
return declaration && ts.isVariableDeclaration(declaration) ? declaration : void 0;
|
|
1466
|
+
}
|
|
1467
|
+
/** The Core function a call names, by Core's own name for it: `data`, `operation`. */
|
|
1468
|
+
function coreName({ expression }) {
|
|
1469
|
+
const local = expression.getText();
|
|
1470
|
+
const item = coreImports(expression.getSourceFile()).find(({ name }) => name.text === local);
|
|
1471
|
+
return item && (item.propertyName ?? item.name).text;
|
|
1472
|
+
}
|
|
1473
|
+
/** The unit a name holds, when it is a `const` made by a Core call with a literal label. */
|
|
1474
|
+
function unitAt(checker, symbol) {
|
|
1475
|
+
const call = declarationOf(checker, symbol)?.initializer;
|
|
1476
|
+
if (!call || !ts.isCallExpression(call)) return void 0;
|
|
1477
|
+
const [options] = call.arguments;
|
|
1478
|
+
const label = options && ts.isObjectLiteralExpression(options) ? labelOf(options) : void 0;
|
|
1479
|
+
const made = coreName(call);
|
|
1480
|
+
return label && made ? {
|
|
1481
|
+
made,
|
|
1482
|
+
label,
|
|
1483
|
+
call
|
|
1484
|
+
} : void 0;
|
|
1485
|
+
}
|
|
1486
|
+
/** What a tag holds: the `T` of the `Tag.Handle<T>` its call makes, which `def` carries. */
|
|
1487
|
+
function heldOf(checker, call) {
|
|
1488
|
+
const def = checker.getTypeAtLocation(call).getProperty("def");
|
|
1489
|
+
return def && checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(def, call));
|
|
1490
|
+
}
|
|
1491
|
+
/** The unit a dep reads a part of: `issues.where({ teamId })`. */
|
|
1492
|
+
function partOf(checker, value) {
|
|
1493
|
+
if (!ts.isPropertyAccessExpression(value.expression)) return void 0;
|
|
1494
|
+
const read = value.expression.name.text;
|
|
1495
|
+
const unit = unitAt(checker, checker.getSymbolAtLocation(value.expression.expression));
|
|
1496
|
+
return unit && partKinds.includes(read) ? {
|
|
1497
|
+
...unit,
|
|
1498
|
+
read
|
|
1499
|
+
} : void 0;
|
|
1500
|
+
}
|
|
1501
|
+
const bareOf = (unit) => unit && {
|
|
1502
|
+
...unit,
|
|
1503
|
+
bare: true
|
|
1504
|
+
};
|
|
1505
|
+
/**
|
|
1506
|
+
* The unit a dep's value names: an operation, an edge of a unit (a cell's `controller`, a tag's
|
|
1507
|
+
* `required`), or a part of a cell. `record` keeps only the calls each kind of unit has.
|
|
1508
|
+
*/
|
|
1509
|
+
function unitOf(checker, value) {
|
|
1510
|
+
if (ts.isIdentifier(value)) return bareOf(unitAt(checker, checker.getSymbolAtLocation(value)));
|
|
1511
|
+
if (ts.isCallExpression(value)) return partOf(checker, value);
|
|
1512
|
+
if (!ts.isPropertyAccessExpression(value)) return void 0;
|
|
1513
|
+
return unitAt(checker, checker.getSymbolAtLocation(value.expression));
|
|
1514
|
+
}
|
|
1515
|
+
/** The unit a dep's declaration names: `list: issues.controller`, or `{ inTeam }`. */
|
|
1516
|
+
function depUnit(checker, declaration) {
|
|
1517
|
+
if (declaration && ts.isShorthandPropertyAssignment(declaration)) return bareOf(unitAt(checker, checker.getShorthandAssignmentValueSymbol(declaration)));
|
|
1518
|
+
return declaration && ts.isPropertyAssignment(declaration) ? unitOf(checker, declaration.initializer) : void 0;
|
|
1519
|
+
}
|
|
1520
|
+
const allSets = [
|
|
1521
|
+
"reads",
|
|
1522
|
+
"writes",
|
|
1523
|
+
"calls"
|
|
1524
|
+
];
|
|
1525
|
+
/** The mark of a fact the graph could not see: never a guess at the fact. */
|
|
1526
|
+
const unseen = "?";
|
|
1527
|
+
/** What each call the graph knows on an operation or a cell adds. */
|
|
1528
|
+
function touchesOf({ made, label, read }) {
|
|
1529
|
+
const touches = /* @__PURE__ */ new Map();
|
|
1530
|
+
const add = (kinds, set, fact) => {
|
|
1531
|
+
for (const kind of kinds) touches.set(kind, {
|
|
1532
|
+
set,
|
|
1533
|
+
fact: fact(kind)
|
|
1534
|
+
});
|
|
1535
|
+
};
|
|
1536
|
+
if (made === "operation") add(runKinds, "calls", () => label);
|
|
1537
|
+
else if (read) add(["get"], "reads", () => `${label}.${read}`);
|
|
1538
|
+
else {
|
|
1539
|
+
add(readKinds, "reads", (kind) => `${label}.${kind}`);
|
|
1540
|
+
add(writeKinds, "writes", (kind) => `${label}.${kind}`);
|
|
1541
|
+
}
|
|
1542
|
+
return touches;
|
|
1543
|
+
}
|
|
1544
|
+
/**
|
|
1545
|
+
* The sets a dep the graph cannot name may hide facts in, by its type in `run`: `settle` runs an
|
|
1546
|
+
* operation, `set` writes a cell, `get` reads one.
|
|
1547
|
+
*/
|
|
1548
|
+
function hidesOf(type) {
|
|
1549
|
+
if (type?.getProperty("settle")) return ["calls"];
|
|
1550
|
+
if (type?.getProperty("set")) return ["reads", "writes"];
|
|
1551
|
+
return type?.getProperty("get") ? ["reads"] : [];
|
|
1552
|
+
}
|
|
1553
|
+
/** The type a dep has in `run`: a controller, a reader, or a value. */
|
|
1554
|
+
function slotOf(checker, param, key) {
|
|
1555
|
+
const slot = param && checker.getTypeAtLocation(param).getProperty(key);
|
|
1556
|
+
return slot && checker.getTypeOfSymbolAtLocation(slot, slot.valueDeclaration ?? param);
|
|
1557
|
+
}
|
|
1558
|
+
/**
|
|
1559
|
+
* The sets a tag may hide facts in, by what it holds (ADR 0151), through any edge: a cell may be
|
|
1560
|
+
* read and written, an operation run, a view or a read read. A plain value or a resource holds
|
|
1561
|
+
* no fact the graph reads: a resource's own code is not read.
|
|
1562
|
+
*/
|
|
1563
|
+
function heldHides(held) {
|
|
1564
|
+
if (held?.getProperty("mode")) return ["reads", "writes"];
|
|
1565
|
+
if (held?.getProperty("run")) return ["calls"];
|
|
1566
|
+
return held?.getProperty("kind") ? ["reads"] : [];
|
|
1567
|
+
}
|
|
1568
|
+
/** A dep whose unit the graph cannot name: it hides in `hides`. */
|
|
1569
|
+
const unnamed = (hides) => ({
|
|
1570
|
+
touches: /* @__PURE__ */ new Map(),
|
|
1571
|
+
hides,
|
|
1572
|
+
named: false
|
|
1573
|
+
});
|
|
1574
|
+
/** A dep on an operation or a cell: a bare cell gives `run` its value, read on each run. */
|
|
1575
|
+
function namedDep(unit) {
|
|
1576
|
+
if (unit.bare && unit.made === "data") return {
|
|
1577
|
+
touches: /* @__PURE__ */ new Map(),
|
|
1578
|
+
hides: [],
|
|
1579
|
+
named: true,
|
|
1580
|
+
value: `${unit.label}.get`
|
|
1581
|
+
};
|
|
1582
|
+
const touches = touchesOf(unit);
|
|
1583
|
+
const sets = [...touches.values()].map(({ set }) => set);
|
|
1584
|
+
return {
|
|
1585
|
+
touches,
|
|
1586
|
+
hides: allSets.filter((set) => sets.includes(set)),
|
|
1587
|
+
named: true
|
|
1588
|
+
};
|
|
1589
|
+
}
|
|
1590
|
+
/**
|
|
1591
|
+
* A dep, from the declaration that names its unit. A tag hides by what it holds, through any
|
|
1592
|
+
* edge. Any other dep but an operation or a cell is read by its type in `run`: a dep the graph
|
|
1593
|
+
* cannot name may be anything.
|
|
1594
|
+
*/
|
|
1595
|
+
function depOf(checker, key, param) {
|
|
1596
|
+
const unit = depUnit(checker, key.valueDeclaration);
|
|
1597
|
+
if (unit?.made === "tag") return unnamed(heldHides(heldOf(checker, unit.call)));
|
|
1598
|
+
return unit?.made === "operation" || unit?.made === "data" ? namedDep(unit) : unnamed(hidesOf(slotOf(checker, param, key.name)));
|
|
1599
|
+
}
|
|
1600
|
+
/**
|
|
1601
|
+
* Each dep of an operation by its key, from the type of its `depends`. A dep written in place,
|
|
1602
|
+
* in a `const`, or spread from one is a property of that type, and its declaration names its
|
|
1603
|
+
* unit. `param` is `run`'s first parameter: its type says what each dep is.
|
|
1604
|
+
*/
|
|
1605
|
+
function depsOf(checker, options, param) {
|
|
1606
|
+
const depends = checker.getTypeAtLocation(options).getProperty("depends");
|
|
1607
|
+
const keys = depends ? checker.getTypeOfSymbolAtLocation(depends, options).getProperties() : [];
|
|
1608
|
+
const deps = /* @__PURE__ */ new Map();
|
|
1609
|
+
for (const key of keys) deps.set(key.name, depOf(checker, key, param));
|
|
1610
|
+
return deps;
|
|
1611
|
+
}
|
|
1612
|
+
/** A binding's key as text: a name or a string. Any other key the graph cannot read. */
|
|
1613
|
+
function keyText(key) {
|
|
1614
|
+
return ts.isIdentifier(key) || ts.isStringLiteral(key) ? key.text : void 0;
|
|
1615
|
+
}
|
|
1616
|
+
/** `name` is the value a `const { … } = name` takes apart. */
|
|
1617
|
+
function destructured(name) {
|
|
1618
|
+
const { parent } = name;
|
|
1619
|
+
return ts.isVariableDeclaration(parent) && parent.initializer === name;
|
|
1620
|
+
}
|
|
1621
|
+
/** Call `see` on every name in the node's code, a callback's body too. */
|
|
1622
|
+
function eachName(node, see) {
|
|
1623
|
+
const visit = (child) => {
|
|
1624
|
+
if (ts.isIdentifier(child)) see(child);
|
|
1625
|
+
ts.forEachChild(child, visit);
|
|
1626
|
+
};
|
|
1627
|
+
visit(node);
|
|
1628
|
+
}
|
|
1629
|
+
/** The method a call names on `node`: `list.set(…)` gives `set`. */
|
|
1630
|
+
function calledOn(node) {
|
|
1631
|
+
const { parent } = node;
|
|
1632
|
+
if (!ts.isPropertyAccessExpression(parent) || parent.expression !== node) return void 0;
|
|
1633
|
+
return ts.isCallExpression(parent.parent) && parent.parent.expression === parent ? parent.name.text : void 0;
|
|
1634
|
+
}
|
|
1635
|
+
/**
|
|
1636
|
+
* Reads the code of one `run`: every use of its deps, through the checker's symbols. A dep is
|
|
1637
|
+
* bound by the first parameter, or by `const { a, b: c } = deps` in the body. A use the graph
|
|
1638
|
+
* cannot follow (passed on, assigned, spread, a method it does not know) adds `?` to each set
|
|
1639
|
+
* the dep may hide facts in.
|
|
1640
|
+
*/
|
|
1641
|
+
var Reader = class {
|
|
1642
|
+
facts = {
|
|
1643
|
+
reads: /* @__PURE__ */ new Set(),
|
|
1644
|
+
writes: /* @__PURE__ */ new Set(),
|
|
1645
|
+
calls: /* @__PURE__ */ new Set()
|
|
1646
|
+
};
|
|
1647
|
+
checker;
|
|
1648
|
+
deps;
|
|
1649
|
+
bound = /* @__PURE__ */ new Map();
|
|
1650
|
+
whole;
|
|
1651
|
+
constructor(checker, deps, param) {
|
|
1652
|
+
this.checker = checker;
|
|
1653
|
+
this.deps = deps;
|
|
1654
|
+
for (const { value } of deps.values()) if (value) this.facts.reads.add(value);
|
|
1655
|
+
if (param && ts.isIdentifier(param.name)) this.whole = checker.getSymbolAtLocation(param.name);
|
|
1656
|
+
else if (param) this.bind(param.name);
|
|
1657
|
+
}
|
|
1658
|
+
/** Every dep could hide facts: `run` handed them all on. */
|
|
1659
|
+
hideAll() {
|
|
1660
|
+
for (const dep of this.deps.values()) this.hide(dep);
|
|
1661
|
+
}
|
|
1662
|
+
/**
|
|
1663
|
+
* A `run` passed by name: no code to read. A dep the graph names hides by its unit; one it
|
|
1664
|
+
* cannot name may hide anything, so every set gets `?`.
|
|
1665
|
+
*/
|
|
1666
|
+
hideRun() {
|
|
1667
|
+
this.hideAll();
|
|
1668
|
+
if (![...this.deps.values()].every(({ named }) => named)) for (const set of allSets) this.facts[set].add(unseen);
|
|
1669
|
+
return this.facts;
|
|
1670
|
+
}
|
|
1671
|
+
hide({ hides }) {
|
|
1672
|
+
for (const set of hides) this.facts[set].add(unseen);
|
|
1673
|
+
}
|
|
1674
|
+
/** Bind each name a destructure of the deps gives. */
|
|
1675
|
+
bind(name) {
|
|
1676
|
+
if (!ts.isObjectBindingPattern(name)) return this.hideAll();
|
|
1677
|
+
for (const element of name.elements) this.bindElement(element);
|
|
1678
|
+
}
|
|
1679
|
+
/**
|
|
1680
|
+
* A rest takes every dep, and the graph cannot read a computed key: both hide every dep. A
|
|
1681
|
+
* nested pattern takes its dep apart.
|
|
1682
|
+
*/
|
|
1683
|
+
bindElement({ dotDotDotToken, propertyName, name }) {
|
|
1684
|
+
const key = keyText(propertyName ?? name);
|
|
1685
|
+
if (dotDotDotToken || key === void 0) return this.hideAll();
|
|
1686
|
+
const dep = this.deps.get(key);
|
|
1687
|
+
if (!dep) return;
|
|
1688
|
+
const symbol = ts.isIdentifier(name) ? this.checker.getSymbolAtLocation(name) : void 0;
|
|
1689
|
+
if (symbol) this.bound.set(symbol, dep);
|
|
1690
|
+
else this.hide(dep);
|
|
1691
|
+
}
|
|
1692
|
+
useDep(node, dep) {
|
|
1693
|
+
if (!dep) return;
|
|
1694
|
+
const kind = calledOn(node);
|
|
1695
|
+
const touch = kind === void 0 ? void 0 : dep.touches.get(kind);
|
|
1696
|
+
if (touch) this.facts[touch.set].add(touch.fact);
|
|
1697
|
+
else this.hide(dep);
|
|
1698
|
+
}
|
|
1699
|
+
/** A use of the deps param: a member, a destructure (bound first), or a hand-off. */
|
|
1700
|
+
useWhole(name) {
|
|
1701
|
+
const { parent } = name;
|
|
1702
|
+
if (ts.isPropertyAccessExpression(parent) && parent.expression === name) return this.useDep(parent, this.deps.get(parent.name.text));
|
|
1703
|
+
if (!destructured(name)) this.hideAll();
|
|
1704
|
+
}
|
|
1705
|
+
isWhole(name) {
|
|
1706
|
+
const symbol = this.checker.getSymbolAtLocation(name);
|
|
1707
|
+
return symbol !== void 0 && symbol === this.whole;
|
|
1708
|
+
}
|
|
1709
|
+
use(name) {
|
|
1710
|
+
const { parent } = name;
|
|
1711
|
+
if (ts.isBindingElement(parent)) return;
|
|
1712
|
+
const symbol = ts.isShorthandPropertyAssignment(parent) ? this.checker.getShorthandAssignmentValueSymbol(parent) : this.checker.getSymbolAtLocation(name);
|
|
1713
|
+
if (!symbol) return;
|
|
1714
|
+
if (symbol === this.whole) return this.useWhole(name);
|
|
1715
|
+
this.useDep(name, this.bound.get(symbol));
|
|
1716
|
+
}
|
|
1717
|
+
/**
|
|
1718
|
+
* Every use in the node's code, a callback's body too. Each destructure of the deps binds
|
|
1719
|
+
* first, so a use the code reads before it (in a callback) still counts.
|
|
1720
|
+
*/
|
|
1721
|
+
read(node) {
|
|
1722
|
+
eachName(node, (name) => {
|
|
1723
|
+
if (destructured(name) && this.isWhole(name)) this.bind(name.parent.name);
|
|
1724
|
+
});
|
|
1725
|
+
eachName(node, (name) => this.use(name));
|
|
1726
|
+
return this.facts;
|
|
1727
|
+
}
|
|
1728
|
+
};
|
|
1729
|
+
/** The function an operation's `run` is, when it is written in place. */
|
|
1730
|
+
function functionOf(run) {
|
|
1731
|
+
if (ts.isMethodDeclaration(run)) return run;
|
|
1732
|
+
if (!ts.isPropertyAssignment(run)) return void 0;
|
|
1733
|
+
const value = run.initializer;
|
|
1734
|
+
return ts.isArrowFunction(value) || ts.isFunctionExpression(value) ? value : void 0;
|
|
1735
|
+
}
|
|
1736
|
+
/** What one operation's `run` touches. A `run` written elsewhere may touch any of its deps. */
|
|
1737
|
+
function factsOf(checker, { options, run }) {
|
|
1738
|
+
const fn = functionOf(run);
|
|
1739
|
+
const [param] = fn?.parameters ?? [];
|
|
1740
|
+
const reader = new Reader(checker, depsOf(checker, options, param), param);
|
|
1741
|
+
return fn?.body ? reader.read(fn.body) : reader.hideRun();
|
|
1742
|
+
}
|
|
1743
|
+
const listed = (name, items) => `${name}{${[...items].sort().join(",")}}`;
|
|
1744
|
+
/**
|
|
1745
|
+
* The app's graph, from its code: one line per operation, sorted by label in code-unit order,
|
|
1746
|
+
* the same on every machine. `exits` are the words of ADR 0159.
|
|
1747
|
+
*/
|
|
1748
|
+
function graphOf(root) {
|
|
1749
|
+
const app = readOperations(root);
|
|
1750
|
+
if (!app) return [];
|
|
1751
|
+
return app.operations.map((operation) => {
|
|
1752
|
+
const { reads, writes, calls } = factsOf(app.checker, operation);
|
|
1753
|
+
const { path, line, label, exits } = operation;
|
|
1754
|
+
return {
|
|
1755
|
+
path,
|
|
1756
|
+
line,
|
|
1757
|
+
label,
|
|
1758
|
+
exits,
|
|
1759
|
+
parts: [
|
|
1760
|
+
listed("exits", exits),
|
|
1761
|
+
listed("reads", reads),
|
|
1762
|
+
listed("writes", writes),
|
|
1763
|
+
listed("calls", calls)
|
|
1764
|
+
]
|
|
1765
|
+
};
|
|
1766
|
+
}).sort((a, b) => a.label < b.label ? -1 : 1);
|
|
1767
|
+
}
|
|
1768
|
+
/** The graph as `tinker.graph` holds it: one line per operation, and an end of line after each. */
|
|
1769
|
+
function graphText(lines) {
|
|
1770
|
+
return lines.map(({ label, parts }) => `${[label, ...parts].join(" ")}\n`).join("");
|
|
1771
|
+
}
|
|
1772
|
+
/**
|
|
1773
|
+
* Each line of the committed file by its label, and its line number. A line may end in `\r`: a
|
|
1774
|
+
* checkout on Windows can give the file those ends.
|
|
1775
|
+
*/
|
|
1776
|
+
function linesIn(text) {
|
|
1777
|
+
const lines = /* @__PURE__ */ new Map();
|
|
1778
|
+
text.split("\n").forEach((row, index) => {
|
|
1779
|
+
const [label, ...parts] = row.trim().split(" ");
|
|
1780
|
+
if (label) lines.set(label, {
|
|
1781
|
+
line: index + 1,
|
|
1782
|
+
parts
|
|
1783
|
+
});
|
|
1784
|
+
});
|
|
1785
|
+
return lines;
|
|
1786
|
+
}
|
|
1787
|
+
/** What a code line says that the file's line does not: each part that differs. */
|
|
1788
|
+
function changed(code, file) {
|
|
1789
|
+
return code.flatMap((part, index) => {
|
|
1790
|
+
const said = file[index] ?? "nothing";
|
|
1791
|
+
return part === said ? [] : [`${part}, ${graphFile} says ${said}`];
|
|
1792
|
+
});
|
|
1793
|
+
}
|
|
1794
|
+
/**
|
|
1795
|
+
* A `tinker/graph` finding for each line where `code`, the graph `graphOf` read, and
|
|
1796
|
+
* `tinker.graph` differ (ADR 0161). A code line points at its operation; a line only the file
|
|
1797
|
+
* has points at the file. An app with no operation needs no file.
|
|
1798
|
+
*/
|
|
1799
|
+
function graphFindings(root, code) {
|
|
1800
|
+
const path = join(root, graphFile);
|
|
1801
|
+
const rule = "tinker/graph";
|
|
1802
|
+
if (!existsSync(path)) {
|
|
1803
|
+
const what = `there is no ${graphFile}: run \`tinker graph --write\` and commit it`;
|
|
1804
|
+
return code.length ? [{
|
|
1805
|
+
path: graphFile,
|
|
1806
|
+
line: 1,
|
|
1807
|
+
rule,
|
|
1808
|
+
what
|
|
1809
|
+
}] : [];
|
|
1810
|
+
}
|
|
1811
|
+
const file = linesIn(readFileSync(path, "utf8"));
|
|
1812
|
+
const found = code.flatMap(({ path, line, label, parts }) => {
|
|
1813
|
+
const said = file.get(label);
|
|
1814
|
+
file.delete(label);
|
|
1815
|
+
const diff = said ? changed(parts, said.parts) : [`not in ${graphFile}`];
|
|
1816
|
+
return diff.length ? [{
|
|
1817
|
+
path,
|
|
1818
|
+
line,
|
|
1819
|
+
rule,
|
|
1820
|
+
what: `${label}: ${diff.join("; ")}`
|
|
1821
|
+
}] : [];
|
|
1822
|
+
});
|
|
1823
|
+
const gone = [...file].map(([label, { line }]) => ({
|
|
1824
|
+
path: graphFile,
|
|
1825
|
+
line,
|
|
1826
|
+
rule,
|
|
1827
|
+
what: `${label}: in ${graphFile}, not in the code`
|
|
1828
|
+
}));
|
|
1829
|
+
return [...found, ...gone];
|
|
1830
|
+
}
|
|
1831
|
+
//#endregion
|
|
1164
1832
|
//#region src/rules.ts
|
|
1165
1833
|
/** Tinker's own rules: `check` finds them in the app's files. */
|
|
1166
1834
|
const own = [
|
|
1167
1835
|
"tinker/plain",
|
|
1168
1836
|
"tinker/one-wire",
|
|
1169
1837
|
"tinker/react-state",
|
|
1170
|
-
"tinker/gap"
|
|
1838
|
+
"tinker/gap",
|
|
1839
|
+
"tinker/barrel",
|
|
1840
|
+
"tinker/link"
|
|
1171
1841
|
];
|
|
1172
1842
|
/** A lint rule that is a gate, by its lint code: its Tinker rule id. It belongs to `types`. */
|
|
1173
1843
|
const gates = {
|
|
@@ -1190,7 +1860,8 @@ const rules = [.../* @__PURE__ */ new Set([
|
|
|
1190
1860
|
...own,
|
|
1191
1861
|
...Object.values(gates),
|
|
1192
1862
|
...Object.values(taught),
|
|
1193
|
-
"tinker/exit"
|
|
1863
|
+
"tinker/exit",
|
|
1864
|
+
"tinker/graph"
|
|
1194
1865
|
])];
|
|
1195
1866
|
//#endregion
|
|
1196
1867
|
//#region src/skills.ts
|
|
@@ -1269,148 +1940,6 @@ function loadSkill(root, use) {
|
|
|
1269
1940
|
}).content;
|
|
1270
1941
|
}
|
|
1271
1942
|
//#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
|
|
1414
1943
|
//#region src/tools.ts
|
|
1415
1944
|
const tscLine = /^(?:(.+)\((\d+),\d+\): )?error (TS\d+): (.*)$/;
|
|
1416
1945
|
const viteConfig = "vite.config.{ts,mts,js,mjs}";
|
|
@@ -1725,7 +2254,7 @@ function runTools(root, sources) {
|
|
|
1725
2254
|
* read. A page test leaves its exits in `pageExits`, which is emptied first, so an old run says
|
|
1726
2255
|
* nothing. A red run names no exit: its tests are the finding.
|
|
1727
2256
|
*/
|
|
1728
|
-
function runTests(root, command) {
|
|
2257
|
+
function runTests(root, command, declared) {
|
|
1729
2258
|
const folder = mkdtempSync(join(tmpdir(), "tinker-exits-"));
|
|
1730
2259
|
const file = join(folder, "exits.tsv");
|
|
1731
2260
|
const env = {
|
|
@@ -1744,7 +2273,7 @@ function runTests(root, command) {
|
|
|
1744
2273
|
maxBuffer: 1 << 28
|
|
1745
2274
|
});
|
|
1746
2275
|
const output = `${done.error ? `${done.error.message}\n` : ""}${done.stdout ?? ""}${done.stderr ?? ""}`;
|
|
1747
|
-
const missed = done.status === 0 ? unreached(root, file) : [];
|
|
2276
|
+
const missed = done.status === 0 ? unreached(root, file, declared) : [];
|
|
1748
2277
|
rmSync(folder, {
|
|
1749
2278
|
recursive: true,
|
|
1750
2279
|
force: true
|
|
@@ -1764,13 +2293,19 @@ function tail(output) {
|
|
|
1764
2293
|
}
|
|
1765
2294
|
const usage = `usage:
|
|
1766
2295
|
tinker check [root] [--json]
|
|
2296
|
+
tinker graph [root] [--write]
|
|
1767
2297
|
tinker skill list
|
|
1768
2298
|
tinker skill load <skill>
|
|
1769
2299
|
|
|
1770
2300
|
check runs the app's types (tsc, the kind gate, the cast gate), then its rules (Tinker's
|
|
1771
|
-
rules and the app's other lint), then its
|
|
1772
|
-
|
|
1773
|
-
|
|
2301
|
+
rules and the app's other lint), then its graph (the code's graph must match tinker.graph),
|
|
2302
|
+
then its tests when tinker.json names their command: each exit an operation declares must be
|
|
2303
|
+
reached by a test. Only the first stage that fails prints. Each finding prints its fix.
|
|
2304
|
+
"tinker check: OK" and exit 0 is the only sign that the work is done.
|
|
2305
|
+
|
|
2306
|
+
graph prints the app's graph: one line per operation, with its exits and what its run reads,
|
|
2307
|
+
writes and calls. The lines are facts; the reader judges them. --write writes them to
|
|
2308
|
+
tinker.graph, for the app to commit.
|
|
1774
2309
|
`;
|
|
1775
2310
|
/** One line per gaps row: marked lines over the row's count, as `G3 5/5`. */
|
|
1776
2311
|
function gapLine(gaps) {
|
|
@@ -1809,7 +2344,8 @@ function failed(root, stage, found, gaps) {
|
|
|
1809
2344
|
* Report the stages in order: the rules stage prints only when the types stage is clean. Tinker's
|
|
1810
2345
|
* own rules read the config, so they run first: a bad config stops the run before the tools.
|
|
1811
2346
|
* The gap rule allows a marked Tinker finding of either stage, never a `tsc` or other lint
|
|
1812
|
-
* error; its own findings are rules.
|
|
2347
|
+
* error; its own findings are rules. The graph stage runs no app code, so it comes before the
|
|
2348
|
+
* tests (ADR 0161); no gap allows a graph finding.
|
|
1813
2349
|
*/
|
|
1814
2350
|
function stages(root) {
|
|
1815
2351
|
const { sources, found, doc, tests } = readApp(root);
|
|
@@ -1831,11 +2367,26 @@ function stages(root) {
|
|
|
1831
2367
|
if (types.length) return failed(root, "types", types, []);
|
|
1832
2368
|
const broken = findings.filter((item) => !typed.has(item));
|
|
1833
2369
|
if (broken.length) return failed(root, "rules", broken, gaps);
|
|
1834
|
-
|
|
1835
|
-
|
|
2370
|
+
return afterRules(root, {
|
|
2371
|
+
ran: [...tools.ran, `rules (${sources.length} files)`],
|
|
2372
|
+
skipped: tools.skipped,
|
|
2373
|
+
gaps,
|
|
2374
|
+
...tests ? { tests } : {}
|
|
2375
|
+
});
|
|
2376
|
+
}
|
|
2377
|
+
/**
|
|
2378
|
+
* The stages after clean rules: the graph, then the tests and their exits. `ran` names the
|
|
2379
|
+
* graph only when the app has an operation: an app with none needs no `tinker.graph`.
|
|
2380
|
+
*/
|
|
2381
|
+
function afterRules(root, { ran, skipped, gaps, tests }) {
|
|
2382
|
+
const graph = graphOf(root);
|
|
2383
|
+
const changed = graphFindings(root, graph);
|
|
2384
|
+
if (changed.length) return failed(root, "graph", changed, gaps);
|
|
2385
|
+
if (graph.length) ran.push(`graph (${graph.length} operations)`);
|
|
2386
|
+
if (skipped.length) return {
|
|
1836
2387
|
kind: "incomplete",
|
|
1837
2388
|
ran,
|
|
1838
|
-
skipped
|
|
2389
|
+
skipped,
|
|
1839
2390
|
gaps
|
|
1840
2391
|
};
|
|
1841
2392
|
if (!tests) return {
|
|
@@ -1843,7 +2394,12 @@ function stages(root) {
|
|
|
1843
2394
|
ran,
|
|
1844
2395
|
gaps
|
|
1845
2396
|
};
|
|
1846
|
-
const tested = runTests(root, tests)
|
|
2397
|
+
const tested = runTests(root, tests, graph.flatMap(({ path, line, label, exits }) => exits.map((exit) => ({
|
|
2398
|
+
path,
|
|
2399
|
+
line,
|
|
2400
|
+
label,
|
|
2401
|
+
exit
|
|
2402
|
+
}))));
|
|
1847
2403
|
if (tested.status !== 0) return {
|
|
1848
2404
|
kind: "red",
|
|
1849
2405
|
output: tail(tested.output),
|
|
@@ -1950,6 +2506,27 @@ function checkCommand(root, json) {
|
|
|
1950
2506
|
};
|
|
1951
2507
|
}
|
|
1952
2508
|
}
|
|
2509
|
+
/** Print the app's graph, or write it to `tinker.graph` with `--write`. */
|
|
2510
|
+
function graphCommand(root, write) {
|
|
2511
|
+
if (!existsSync(root)) return {
|
|
2512
|
+
code: 2,
|
|
2513
|
+
out: "",
|
|
2514
|
+
err: `tinker graph: no folder at ${root}\n`
|
|
2515
|
+
};
|
|
2516
|
+
const lines = graphOf(root);
|
|
2517
|
+
const text = graphText(lines);
|
|
2518
|
+
if (!write) return {
|
|
2519
|
+
code: 0,
|
|
2520
|
+
out: text,
|
|
2521
|
+
err: ""
|
|
2522
|
+
};
|
|
2523
|
+
writeFileSync(join(root, graphFile), text);
|
|
2524
|
+
return {
|
|
2525
|
+
code: 0,
|
|
2526
|
+
out: `wrote ${graphFile}: ${lines.length} operations\n`,
|
|
2527
|
+
err: ""
|
|
2528
|
+
};
|
|
2529
|
+
}
|
|
1953
2530
|
function skillCommand(root, args) {
|
|
1954
2531
|
const [action, use, ...rest] = args;
|
|
1955
2532
|
try {
|
|
@@ -1977,27 +2554,34 @@ function skillCommand(root, args) {
|
|
|
1977
2554
|
err: usage
|
|
1978
2555
|
};
|
|
1979
2556
|
}
|
|
2557
|
+
/** The one flag each command takes: `--json` prints data, `--write` writes the file. */
|
|
2558
|
+
function flagOf(command) {
|
|
2559
|
+
if (command === "check") return "--json";
|
|
2560
|
+
return command === "graph" ? "--write" : void 0;
|
|
2561
|
+
}
|
|
1980
2562
|
/**
|
|
1981
2563
|
* The command, without the process: `argv` is what follows the program name, and `cwd` is
|
|
1982
2564
|
* the folder a relative root starts from. Exit 0 is done, 1 is a finding, 2 is a call, a
|
|
1983
2565
|
* config or a tool the command cannot use.
|
|
1984
2566
|
*/
|
|
1985
2567
|
function main(argv, cwd) {
|
|
1986
|
-
const
|
|
1987
|
-
const
|
|
1988
|
-
|
|
2568
|
+
const [command = "", ...args] = argv.filter((arg) => !arg.startsWith("-"));
|
|
2569
|
+
const flag = flagOf(command);
|
|
2570
|
+
const on = argv.some((arg) => arg === flag);
|
|
2571
|
+
if (argv.some((arg) => arg.startsWith("-") && arg !== flag)) return {
|
|
1989
2572
|
code: 2,
|
|
1990
2573
|
out: "",
|
|
1991
2574
|
err: usage
|
|
1992
2575
|
};
|
|
1993
|
-
if (command === "skill"
|
|
2576
|
+
if (command === "skill") return skillCommand(cwd, args);
|
|
1994
2577
|
const [root = ".", ...rest] = args;
|
|
1995
|
-
if (
|
|
2578
|
+
if (!flag || rest.length) return {
|
|
1996
2579
|
code: 2,
|
|
1997
2580
|
out: "",
|
|
1998
2581
|
err: usage
|
|
1999
2582
|
};
|
|
2000
|
-
|
|
2583
|
+
const at = resolve(cwd, root);
|
|
2584
|
+
return command === "graph" ? graphCommand(at, on) : checkCommand(at, on);
|
|
2001
2585
|
}
|
|
2002
2586
|
//#endregion
|
|
2003
2587
|
export { check as n, isError as r, main as t };
|
package/dist/vite.d.mts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { Plugin } from "vite-plus";
|
|
2
|
+
//#region src/vite.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* The page guard (ADR 0160): the page build stops at an import of server code, however deep
|
|
5
|
+
* the re-export that reaches it. It runs only where the page is built, the client environment,
|
|
6
|
+
* so a server build is not touched. `import type` is erased before any import resolves, so a
|
|
7
|
+
* page may still take types from a server file.
|
|
8
|
+
*/
|
|
9
|
+
export declare function pageGuard(): Plugin;
|
|
10
|
+
//#endregion
|
package/dist/vite.mjs
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { relative } from "node:path";
|
|
2
|
+
//#region src/vite.ts
|
|
3
|
+
/**
|
|
4
|
+
* Server code, by the name an import gives it or the file it resolves to (ADR 0160 decision 3).
|
|
5
|
+
* `@tinkered/bun/client` is the one entry of `@tinkered/bun` a page may import.
|
|
6
|
+
*/
|
|
7
|
+
const serverCode = [
|
|
8
|
+
/\.server\./,
|
|
9
|
+
/^(?:bun|node):/,
|
|
10
|
+
/^@tinkered\/entry(?:\/|$)/,
|
|
11
|
+
/^@tinkered\/bun(?!\/client$)(?:\/|$)/
|
|
12
|
+
];
|
|
13
|
+
/**
|
|
14
|
+
* The page guard (ADR 0160): the page build stops at an import of server code, however deep
|
|
15
|
+
* the re-export that reaches it. It runs only where the page is built, the client environment,
|
|
16
|
+
* so a server build is not touched. `import type` is erased before any import resolves, so a
|
|
17
|
+
* page may still take types from a server file.
|
|
18
|
+
*/
|
|
19
|
+
function pageGuard() {
|
|
20
|
+
return {
|
|
21
|
+
name: "tinker:page-guard",
|
|
22
|
+
enforce: "pre",
|
|
23
|
+
applyToEnvironment: (environment) => environment.config.consumer === "client",
|
|
24
|
+
async resolveId(source, importer, options) {
|
|
25
|
+
if (!importer) return null;
|
|
26
|
+
const resolved = await this.resolve(source, importer, options);
|
|
27
|
+
const isServer = (code) => code.test(source) || resolved !== null && code.test(resolved.id);
|
|
28
|
+
if (serverCode.some(isServer)) {
|
|
29
|
+
const from = relative(this.environment.config.root, importer).replaceAll("\\", "/");
|
|
30
|
+
this.error(`page imports server code "${source}" from ${from}`);
|
|
31
|
+
}
|
|
32
|
+
return resolved;
|
|
33
|
+
}
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
//#endregion
|
|
37
|
+
export { pageGuard };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tinkered/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.31.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": {
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
".": "./dist/index.mjs",
|
|
23
23
|
"./config": "./dist/config.mjs",
|
|
24
24
|
"./test": "./dist/test.mjs",
|
|
25
|
+
"./vite": "./dist/vite.mjs",
|
|
25
26
|
"./lint": "./lint/index.mjs",
|
|
26
27
|
"./tsconfig.json": "./base/tsconfig.json",
|
|
27
28
|
"./package.json": "./package.json"
|
|
@@ -36,18 +37,22 @@
|
|
|
36
37
|
"devDependencies": {
|
|
37
38
|
"@stryker-mutator/core": "^10.0.0",
|
|
38
39
|
"@stryker-mutator/vitest-runner": "^10.0.0",
|
|
39
|
-
"@tinkered/core": "^0.
|
|
40
|
+
"@tinkered/core": "^0.31.0",
|
|
40
41
|
"@types/node": "^26.1.1",
|
|
41
42
|
"vite-plus": "1.0.0",
|
|
42
43
|
"vitest": "5.0.1",
|
|
43
44
|
"zod": "^4.0.0"
|
|
44
45
|
},
|
|
45
46
|
"peerDependencies": {
|
|
46
|
-
"@tinkered/core": "^0.
|
|
47
|
+
"@tinkered/core": "^0.31.0",
|
|
48
|
+
"vite-plus": "^1.0.0"
|
|
47
49
|
},
|
|
48
50
|
"peerDependenciesMeta": {
|
|
49
51
|
"@tinkered/core": {
|
|
50
52
|
"optional": true
|
|
53
|
+
},
|
|
54
|
+
"vite-plus": {
|
|
55
|
+
"optional": true
|
|
51
56
|
}
|
|
52
57
|
},
|
|
53
58
|
"engines": {
|