@niwa-labs/workflow 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +13 -2
- package/package.json +55 -4
- package/src/actions.ts +408 -0
- package/src/agent.ts +211 -0
- package/src/ask.ts +84 -0
- package/src/bridge.ts +710 -0
- package/src/catalogue.ts +74 -0
- package/src/check.ts +880 -0
- package/src/child.ts +1378 -0
- package/src/cockpit/actions.ts +128 -0
- package/src/cockpit/catalogue-actions.ts +97 -0
- package/src/cockpit/dashboard.tsx +134 -0
- package/src/cockpit/groups.ts +45 -0
- package/src/cockpit/index.tsx +50 -0
- package/src/cockpit/launch.tsx +136 -0
- package/src/cockpit/plan.ts +101 -0
- package/src/cockpit/run-commands.tsx +102 -0
- package/src/cockpit/run-page.tsx +140 -0
- package/src/cockpit/run-summary.ts +16 -0
- package/src/cockpit/runs.tsx +73 -0
- package/src/cockpit/statistics.tsx +176 -0
- package/src/cockpit/track.tsx +159 -0
- package/src/cockpit/workflows.tsx +383 -0
- package/src/describe-cache.ts +122 -0
- package/src/describe.ts +174 -0
- package/src/guide.ts +213 -0
- package/src/index.ts +2813 -0
- package/src/inspect.ts +235 -0
- package/src/installation.ts +90 -0
- package/src/language.ts +217 -0
- package/src/records-entry.ts +63 -0
- package/src/records.ts +574 -0
- package/src/registry.ts +250 -0
- package/src/revise.ts +89 -0
- package/src/runner.ts +339 -0
- package/src/script-types.ts +549 -0
- package/src/stats.ts +460 -0
- package/src/status.ts +512 -0
- package/src/store.ts +259 -0
- package/src/subscriptions.ts +102 -0
- package/src/waiting.ts +61 -0
- package/test/cockpit-actions.test.ts +20 -0
- package/test/cockpit-groups.test.ts +42 -0
- package/test/cockpit-plan.test.ts +118 -0
- package/test/fixtures/branches-host.ts +58 -0
- package/test/fixtures/branches-script.js +23 -0
- package/test/fixtures/bridge-host.ts +23 -0
- package/test/fixtures/bridge-keys-script.js +15 -0
- package/test/fixtures/bridge-wait-script.js +8 -0
- package/test/fixtures/cancel-host.ts +58 -0
- package/test/fixtures/cancel-script.js +12 -0
- package/test/fixtures/crash-host.ts +61 -0
- package/test/fixtures/crash-script.js +14 -0
- package/test/fixtures/ping-records.ts +20 -0
- package/test/fixtures/revision-host.ts +57 -0
- package/test/fixtures/revision-script.js +11 -0
- package/test/fixtures/running-host.ts +61 -0
- package/test/fixtures/running-script.js +12 -0
- package/test/fixtures/with-data/flow.ts +2 -0
- package/test/fixtures/with-data/table.json +1 -0
- package/test/git-repo.ts +45 -0
- package/test/git-worktree.test.ts +413 -0
- package/test/question-format.test.ts +279 -0
- package/test/workflow-agent-caps.test.ts +91 -0
- package/test/workflow-agent-lifetime.test.ts +93 -0
- package/test/workflow-agent-options.test.ts +216 -0
- package/test/workflow-agent-schema.test.ts +386 -0
- package/test/workflow-agent-typings.test.ts +241 -0
- package/test/workflow-ask-resume.test.ts +145 -0
- package/test/workflow-branch-keys.test.ts +133 -0
- package/test/workflow-bridge-inproc.test.ts +230 -0
- package/test/workflow-bridge.test.ts +141 -0
- package/test/workflow-builtin-candidate.test.ts +230 -0
- package/test/workflow-builtin.test.ts +197 -0
- package/test/workflow-cancel-agent.test.ts +144 -0
- package/test/workflow-cancel.test.ts +166 -0
- package/test/workflow-chain.test.ts +84 -0
- package/test/workflow-check-options.test.ts +144 -0
- package/test/workflow-check-uses.test.ts +148 -0
- package/test/workflow-check.test.ts +282 -0
- package/test/workflow-contract.test.ts +295 -0
- package/test/workflow-crash-resume.test.ts +141 -0
- package/test/workflow-deadline.test.ts +102 -0
- package/test/workflow-describe-cache.test.ts +240 -0
- package/test/workflow-directory.test.ts +73 -0
- package/test/workflow-emits.test.ts +261 -0
- package/test/workflow-group-keys.test.ts +72 -0
- package/test/workflow-harnesses.test.ts +262 -0
- package/test/workflow-inspect.test.ts +152 -0
- package/test/workflow-language-types.test.ts +148 -0
- package/test/workflow-manifest.test.ts +93 -0
- package/test/workflow-manual-pause.test.ts +116 -0
- package/test/workflow-owners.test.ts +154 -0
- package/test/workflow-pause.test.ts +200 -0
- package/test/workflow-phases.test.ts +445 -0
- package/test/workflow-plugin-entries.test.ts +59 -0
- package/test/workflow-record-refs.test.ts +310 -0
- package/test/workflow-replay.test.ts +206 -0
- package/test/workflow-resume-once.test.ts +188 -0
- package/test/workflow-revision.test.ts +216 -0
- package/test/workflow-scope.test.ts +505 -0
- package/test/workflow-script-defaults.test.ts +119 -0
- package/test/workflow-script-error.test.ts +228 -0
- package/test/workflow-script-libraries.test.ts +88 -0
- package/test/workflow-script-packages.test.ts +119 -0
- package/test/workflow-stdout.test.ts +89 -0
- package/test/workflow-stop.test.ts +299 -0
- package/test/workflow-store.test.ts +220 -0
- package/test/workflow-visible.test.ts +136 -0
- package/test/workflow-wait-version.test.ts +54 -0
- package/test/workflow-wait.test.ts +224 -0
- package/test/workflow-waiting-agent.test.ts +64 -0
- package/tsconfig.json +15 -0
package/src/check.ts
ADDED
|
@@ -0,0 +1,880 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The check of a script: the script is type-checked against the
|
|
3
|
+
* typing generated from the host's actions, and what it declares is read.
|
|
4
|
+
*
|
|
5
|
+
* The script is `export default workflow({ description, input, output, uses, on }, fn)`. `uses` is
|
|
6
|
+
* the actions it calls, as names or masks (`task.*`): the typing of a check holds only those, so a
|
|
7
|
+
* call outside `uses` is an error of the type checker, with the place in the file. `name`, `uses`,
|
|
8
|
+
* `on` and `phases` are read from the text of the declaration, as literals, so they are known
|
|
9
|
+
* without running anything; the schemas (`input`, `output`) are read by loading the module in a
|
|
10
|
+
* disposable process (`describe.ts`). The function of the script is never run.
|
|
11
|
+
*
|
|
12
|
+
* The checker is the repo's `typescript`, loaded when the first script is checked. The script and
|
|
13
|
+
* the generated typing are given to it from memory: the text that was hashed is the text that is
|
|
14
|
+
* checked, and nothing is written to the disk.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { createHash } from "node:crypto";
|
|
18
|
+
import { join, resolve } from "node:path";
|
|
19
|
+
import { fileURLToPath } from "node:url";
|
|
20
|
+
|
|
21
|
+
import { isOwnerGrant, isRuleTemplate, narrow, rule, ruleTemplate, ruleText } from "@niwa-labs/core";
|
|
22
|
+
import type { ActionDescription, ActionName, Grant, JsonSchema } from "@niwa-labs/core";
|
|
23
|
+
import { bare, declarationField, declarationOf, literalOf, onOf, placeOf } from "@niwa-labs/script";
|
|
24
|
+
import type { ScriptSource } from "@niwa-labs/script";
|
|
25
|
+
import type * as Ts from "typescript";
|
|
26
|
+
import { z } from "zod";
|
|
27
|
+
|
|
28
|
+
import type { Describer } from "./describe-cache.ts";
|
|
29
|
+
import { contractOf, emittedTypesOf } from "./describe.ts";
|
|
30
|
+
import { SCRIPT_TYPES, WorkflowPhases } from "./language.ts";
|
|
31
|
+
import type { ScriptBox } from "./runner.ts";
|
|
32
|
+
import { ContractHash, JsonSchemaValue, Subscription } from "./records.ts";
|
|
33
|
+
import { SCRIPT_API, typeRoots } from "./installation.ts";
|
|
34
|
+
import { allowedFor, harnessOfAction, matches, scriptTyping } from "./script-types.ts";
|
|
35
|
+
import type { HarnessBlock } from "./script-types.ts";
|
|
36
|
+
|
|
37
|
+
/** What a check says: the errors it found, what the script declares, and that its function was not run. */
|
|
38
|
+
export interface CheckReport {
|
|
39
|
+
file: string;
|
|
40
|
+
ok: boolean;
|
|
41
|
+
errors: CheckError[];
|
|
42
|
+
/** What the check could not settle and the author should look at; absent when there is none. A warning does not fail the check. */
|
|
43
|
+
warnings?: CheckError[];
|
|
44
|
+
note: "described, the script was not run";
|
|
45
|
+
/** What the script says it is. */
|
|
46
|
+
description?: string;
|
|
47
|
+
/** The JSON Schema of the input of the script; absent when it takes none, or declares the record it starts on. */
|
|
48
|
+
input?: JsonSchemaValue;
|
|
49
|
+
/** The JSON Schema of what the script returns; absent when it returns nothing. */
|
|
50
|
+
output?: JsonSchemaValue;
|
|
51
|
+
/** The records the script emits: the name it gives each, its type `wf.<name>.<record>`, and the JSON Schema of its data; absent when it declares no `emits`. */
|
|
52
|
+
emits?: Array<{ record: string; type: string; schema: JsonSchemaValue }>;
|
|
53
|
+
/** The phases the script declares, in order; absent when it declares none. */
|
|
54
|
+
phases?: WorkflowPhases;
|
|
55
|
+
/** The hash of the contract; absent when the module could not be read. */
|
|
56
|
+
contract?: ContractHash;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** One error, with its place in the file. */
|
|
60
|
+
export interface CheckError {
|
|
61
|
+
file: string;
|
|
62
|
+
line: number;
|
|
63
|
+
column: number;
|
|
64
|
+
/** The code of the type checker (`TS2339`), `workflow` for a script that is not `export default workflow({ ... }, fn)`, `uses` for a mask of `uses` that names no action or an `ask()` call on a harness `uses` does not list, `emit` for a record the script may not write, `on` for an `on` the host cannot serve, `wait` for a filter of a wait no record of its type can hold or a type it names by reference that the host does not know or writes at another version, `read` for such a type of a read, `schema` for an `input`, `output` or record of `emits` that is not a JSON Schema, `phases` for phases that are not a list of `{ title, detail? }` with titles of their own, written in the declaration, or `describe` for a module that could not be read. */
|
|
65
|
+
code: string;
|
|
66
|
+
message: string;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Where the generated typing lives for the checker: a name no real file has. */
|
|
70
|
+
const TYPING_FILE = join(fileURLToPath(new URL(".", import.meta.url)), "niwa-script.generated.ts");
|
|
71
|
+
const TYPE_ROOTS = typeRoots();
|
|
72
|
+
|
|
73
|
+
const CACHE_LIMIT = 64;
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The installed packages the checker reads (the libraries of the language, the types of bun and node),
|
|
77
|
+
* parsed once. A check that parsed them again took most of its time over them; they are the same for
|
|
78
|
+
* every script, and a program only reads a parsed file. The files of a script's own folder are read
|
|
79
|
+
* again by every check: they may have been edited.
|
|
80
|
+
*/
|
|
81
|
+
const parsedFiles = new Map<string, Ts.SourceFile>();
|
|
82
|
+
|
|
83
|
+
const sha256 = (text: string): string => createHash("sha256").update(text).digest("hex");
|
|
84
|
+
|
|
85
|
+
/** A name or a mask of `uses`, with the place it is written at. */
|
|
86
|
+
interface Use {
|
|
87
|
+
mask: string;
|
|
88
|
+
line: number;
|
|
89
|
+
column: number;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** What `uses` holds: the masks, or the place where it is not a list of text. */
|
|
93
|
+
export type Uses = { masks: Use[] } | { bad: { line: number; column: number } };
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The name mask of an entry of `uses`: an action name or a mask (`task.create`, `task.*`, `*`),
|
|
97
|
+
* the same with a target (`forge.pr.read@git.example.com/acme/*`), or with a target template filled
|
|
98
|
+
* from the input of the run (`forge.pr.merge@{repo.host}/{repo.path}/pr/*`). Undefined for anything
|
|
99
|
+
* else, a rule of another verb among them.
|
|
100
|
+
*/
|
|
101
|
+
export function useName(text: string): string | undefined {
|
|
102
|
+
try {
|
|
103
|
+
if (isRuleTemplate(text)) ruleTemplate(text);
|
|
104
|
+
const at = text.indexOf("@");
|
|
105
|
+
const parsed = rule(at === -1 || isRuleTemplate(text) ? text.slice(0, at === -1 ? undefined : at) : text);
|
|
106
|
+
if (parsed.verb !== "call" || text.startsWith("call:")) return undefined;
|
|
107
|
+
return parsed.name;
|
|
108
|
+
} catch {
|
|
109
|
+
return undefined;
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** Is the text an entry `uses` may hold? */
|
|
114
|
+
export function isUse(text: string): boolean {
|
|
115
|
+
return useName(text) !== undefined;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** The `name` of a parsed script, when it is written as text. */
|
|
119
|
+
function nameOf(ts: typeof Ts, source: Ts.SourceFile): string | undefined {
|
|
120
|
+
const field = declarationField(ts, source, "name");
|
|
121
|
+
const text = field === undefined || !("value" in field) ? undefined : bare(ts, field.value);
|
|
122
|
+
return text !== undefined && (ts.isStringLiteral(text) || ts.isNoSubstitutionTemplateLiteral(text)) ? text.text : undefined;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** The calls of a function of the language in the script, by its name: `emit(...)`, `wait(...)`. */
|
|
126
|
+
function callsOf(ts: typeof Ts, source: Ts.SourceFile, name: string): Ts.CallExpression[] {
|
|
127
|
+
const found: Ts.CallExpression[] = [];
|
|
128
|
+
const visit = (node: Ts.Node): void => {
|
|
129
|
+
if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name) found.push(node);
|
|
130
|
+
ts.forEachChild(node, visit);
|
|
131
|
+
};
|
|
132
|
+
visit(source);
|
|
133
|
+
return found;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* The errors of the emits of a script: it emits only what it lists in `emits`, written as it is written there, and a
|
|
138
|
+
* script that lists any has a `name`, the prefix of its records.
|
|
139
|
+
*/
|
|
140
|
+
function emitErrors(ts: typeof Ts, source: Ts.SourceFile, file: string): CheckError[] {
|
|
141
|
+
const errors: CheckError[] = [];
|
|
142
|
+
const field = declarationField(ts, source, "emits");
|
|
143
|
+
const list = field === undefined || !("value" in field) ? undefined : bare(ts, field.value);
|
|
144
|
+
if (field !== undefined && "unsettled" in field) {
|
|
145
|
+
errors.push({ file, ...placeOf(ts, source, field.unsettled), code: "emit", message: "emits must be a list of records written in the declaration: emits: [Blocked]; a spread or a computed key may decide it" });
|
|
146
|
+
} else if (list !== undefined && field !== undefined) {
|
|
147
|
+
if (!ts.isArrayLiteralExpression(list)) errors.push({ file, ...placeOf(ts, source, field.value), code: "emit", message: "emits must be a list of records written in the declaration: emits: [Blocked]" });
|
|
148
|
+
else if (nameOf(ts, source) === undefined) {
|
|
149
|
+
errors.push({ file, ...placeOf(ts, source, field.value), code: "emit", message: `a script that emits declares a name: its records are "${SCRIPT_TYPES}<name>.<record>"` });
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
const listed = list !== undefined && ts.isArrayLiteralExpression(list) ? list.elements.map((element) => bare(ts, element).getText(source)) : [];
|
|
153
|
+
for (const call of callsOf(ts, source, "emit")) {
|
|
154
|
+
const declared = call.arguments[0];
|
|
155
|
+
if (declared === undefined || listed.includes(bare(ts, declared).getText(source))) continue;
|
|
156
|
+
errors.push({
|
|
157
|
+
file,
|
|
158
|
+
...placeOf(ts, source, declared),
|
|
159
|
+
code: "emit",
|
|
160
|
+
message: `emit ${bare(ts, declared).getText(source)}: a script emits only the records it lists in workflow({ emits }), written as they are written there`,
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
return errors;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/** `uses` of a script, read from the text without running it; absent when the script has none. */
|
|
167
|
+
export async function scriptUses(source: ScriptSource): Promise<Uses | undefined> {
|
|
168
|
+
const ts = (await import("typescript")).default;
|
|
169
|
+
return usesOf(ts, ts.createSourceFile(source.file, source.text, ts.ScriptTarget.ESNext, true));
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** The records of scripts (`wf.<name>.<record>`) a script waits for or reads by name, written out as text. */
|
|
173
|
+
export async function scriptReads(source: ScriptSource): Promise<string[]> {
|
|
174
|
+
const ts = (await import("typescript")).default;
|
|
175
|
+
const parsed = ts.createSourceFile(source.file, source.text, ts.ScriptTarget.ESNext, true);
|
|
176
|
+
const named = [...waitsOf(ts, parsed).map((wait) => wait.type), ...readTypesOf(ts, parsed)];
|
|
177
|
+
return [...new Set(named.filter((type) => type.startsWith(SCRIPT_TYPES)))];
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* `uses` of a parsed script.
|
|
182
|
+
*
|
|
183
|
+
* Absent when the script declares no `uses`: what such a script may call depends on who
|
|
184
|
+
* starts it (see `allowedFor`).
|
|
185
|
+
*/
|
|
186
|
+
function usesOf(ts: typeof Ts, source: Ts.SourceFile): Uses | undefined {
|
|
187
|
+
const field = declarationField(ts, source, "uses");
|
|
188
|
+
if (field === undefined) return undefined;
|
|
189
|
+
// A spread, a computed key or an accessor may decide `uses`: the masks are not the text's to give, and a run is not left unrestricted by it.
|
|
190
|
+
if ("unsettled" in field) return { bad: placeOf(ts, source, field.unsettled) };
|
|
191
|
+
const list = bare(ts, field.value);
|
|
192
|
+
if (!ts.isArrayLiteralExpression(list)) return { bad: placeOf(ts, source, list) };
|
|
193
|
+
const masks: Use[] = [];
|
|
194
|
+
for (const element of list.elements) {
|
|
195
|
+
if (!ts.isStringLiteral(element) && !ts.isNoSubstitutionTemplateLiteral(element)) return { bad: placeOf(ts, source, element) };
|
|
196
|
+
masks.push({ mask: element.text, ...placeOf(ts, source, element) });
|
|
197
|
+
}
|
|
198
|
+
return { masks };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* `phases` of a parsed script, read from the text: the titles the typing of a script's `phase` option is made of.
|
|
203
|
+
* Absent when the script declares none; a list that is not written as a literal, or is not phases, is bad.
|
|
204
|
+
*/
|
|
205
|
+
function phasesOf(ts: typeof Ts, source: Ts.SourceFile): { phases: WorkflowPhases } | { bad: { line: number; column: number; message: string } } | undefined {
|
|
206
|
+
const field = declarationField(ts, source, "phases");
|
|
207
|
+
if (field === undefined) return undefined;
|
|
208
|
+
if ("unsettled" in field) return { bad: { ...placeOf(ts, source, field.unsettled), message: "phases is not settled by the declaration: a spread or a computed key may decide it" } };
|
|
209
|
+
const written = literalOf(ts, field.value);
|
|
210
|
+
if (written === undefined) return { bad: { ...placeOf(ts, source, field.value), message: "phases must be written in the declaration as a list: phases: [{ title: \"Review\" }, { title: \"Fix\", detail: \"...\" }]" } };
|
|
211
|
+
const parsed = WorkflowPhases.safeParse(written.value);
|
|
212
|
+
return parsed.success ? { phases: parsed.data } : { bad: { ...placeOf(ts, source, field.value), message: `phases: ${z.prettifyError(parsed.error)}` } };
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** The plan declared in the header of these exact script bytes. */
|
|
216
|
+
export async function scriptPhases(source: ScriptSource): Promise<WorkflowPhases | undefined> {
|
|
217
|
+
const ts = (await import("typescript")).default;
|
|
218
|
+
const read = phasesOf(ts, ts.createSourceFile(source.file, source.text, ts.ScriptTarget.ESNext, true));
|
|
219
|
+
return read !== undefined && "phases" in read ? read.phases : undefined;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** The options of the check: a `.ts` script is strict, a `.js` one is read for its syntax unless it opts in with `// @ts-check`. */
|
|
223
|
+
function optionsFor(ts: typeof Ts, file: string): Ts.CompilerOptions {
|
|
224
|
+
const typescript = /\.[cm]?ts$/.test(file);
|
|
225
|
+
return {
|
|
226
|
+
target: ts.ScriptTarget.ESNext,
|
|
227
|
+
module: ts.ModuleKind.ESNext,
|
|
228
|
+
moduleResolution: ts.ModuleResolutionKind.Bundler,
|
|
229
|
+
lib: ["lib.esnext.d.ts"],
|
|
230
|
+
strict: typescript,
|
|
231
|
+
noEmit: true,
|
|
232
|
+
skipLibCheck: true,
|
|
233
|
+
allowJs: true,
|
|
234
|
+
checkJs: false,
|
|
235
|
+
allowImportingTsExtensions: true,
|
|
236
|
+
resolveJsonModule: true,
|
|
237
|
+
// A script imports its types from the script package; the checker reads the file that holds them and nothing else of it.
|
|
238
|
+
paths: { "@niwa-labs/script": [SCRIPT_API] },
|
|
239
|
+
...(TYPE_ROOTS === undefined ? {} : { typeRoots: [TYPE_ROOTS], types: ["bun"] }),
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** The harnesses an `ask()` call may name: the ones the host serves, and the ones of them `uses` lets the script call. */
|
|
244
|
+
interface Harnesses {
|
|
245
|
+
hosted: ReadonlySet<string>;
|
|
246
|
+
allowed: ReadonlySet<string>;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** What a script's checker says: the errors, and what it could not settle. */
|
|
250
|
+
interface Found {
|
|
251
|
+
errors: CheckError[];
|
|
252
|
+
warnings: CheckError[];
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/** What the checker says, and the program it read: the script's references are followed in it. */
|
|
256
|
+
interface Diagnosis extends Found {
|
|
257
|
+
program: Ts.Program;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/** The names a type of a harness can be, or `"dynamic"` when it is text known only when the script runs. Absent when the call names none. */
|
|
261
|
+
function harnessTypes(ts: typeof Ts, type: Ts.Type): string[] | "dynamic" | undefined {
|
|
262
|
+
const names: string[] = [];
|
|
263
|
+
for (const member of type.isUnion() ? type.types : [type]) {
|
|
264
|
+
if (member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) continue;
|
|
265
|
+
if (!member.isStringLiteral()) return "dynamic";
|
|
266
|
+
names.push(member.value);
|
|
267
|
+
}
|
|
268
|
+
return names.length === 0 ? undefined : names;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* The `ask()` calls that start a session on a harness `uses` does not list, read from what the checker knows of the
|
|
273
|
+
* `harness` of each call: a text, a constant that holds one, or a choice between them. A call whose harness is only known
|
|
274
|
+
* when the script runs is a warning, since a run pauses on the first harness outside `uses`. The type of the options
|
|
275
|
+
* refuses an unlisted harness in a script that is type checked, in the terms of overloads; the error here says which
|
|
276
|
+
* entry of `uses` is missing, and is the only one for a script that is not type checked.
|
|
277
|
+
*/
|
|
278
|
+
function harnessUses(ts: typeof Ts, program: Ts.Program, source: ScriptSource, harnesses: Harnesses): Found {
|
|
279
|
+
const found: Found = { errors: [], warnings: [] };
|
|
280
|
+
const parsed = program.getSourceFile(source.file);
|
|
281
|
+
if (parsed === undefined || harnesses.hosted.size === 0) return found;
|
|
282
|
+
const checker = program.getTypeChecker();
|
|
283
|
+
const uncovered = [...harnesses.hosted].filter((name) => !harnesses.allowed.has(name));
|
|
284
|
+
for (const call of [...callsOf(ts, parsed, "ask"), ...callsOf(ts, parsed, "session")]) {
|
|
285
|
+
const options = call.arguments[0] === undefined ? undefined : bare(ts, call.arguments[0]);
|
|
286
|
+
if (options === undefined) continue;
|
|
287
|
+
const written = ts.isObjectLiteralExpression(options)
|
|
288
|
+
? options.properties.find((property): property is Ts.PropertyAssignment | Ts.ShorthandPropertyAssignment => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && property.name.getText(parsed) === "harness")
|
|
289
|
+
: undefined;
|
|
290
|
+
const spread = ts.isObjectLiteralExpression(options) ? options.properties.some((property) => ts.isSpreadAssignment(property)) : true;
|
|
291
|
+
const place = { file: source.file, ...placeOf(ts, parsed, written ?? call) };
|
|
292
|
+
const valueType = (property: Ts.PropertyAssignment | Ts.ShorthandPropertyAssignment): Ts.Type | undefined => {
|
|
293
|
+
if (ts.isPropertyAssignment(property)) return checker.getTypeAtLocation(property.initializer);
|
|
294
|
+
const value = checker.getShorthandAssignmentValueSymbol(property);
|
|
295
|
+
return value === undefined ? undefined : checker.getTypeOfSymbolAtLocation(value, property.name);
|
|
296
|
+
};
|
|
297
|
+
// Options that are not written in the call (`ask(opts, p)`, `{ ...opts }`) are read by the type they have.
|
|
298
|
+
const member = written === undefined && spread ? checker.getTypeAtLocation(options).getProperty("harness") : undefined;
|
|
299
|
+
const type =
|
|
300
|
+
written !== undefined
|
|
301
|
+
? valueType(written)
|
|
302
|
+
: member === undefined
|
|
303
|
+
? undefined
|
|
304
|
+
: checker.getTypeOfSymbolAtLocation(member, options);
|
|
305
|
+
const names = type === undefined ? undefined : harnessTypes(ts, type);
|
|
306
|
+
if (names === undefined) continue;
|
|
307
|
+
if (names === "dynamic") {
|
|
308
|
+
if (uncovered.length > 0) {
|
|
309
|
+
found.warnings.push({ ...place, code: "uses", message: `${call.expression.getText(parsed)}() takes a harness that is known only when the script runs: uses needs an entry for each harness it may name (session.start.<harness>, or session.start.*), or a run pauses on the first that is missing` });
|
|
310
|
+
}
|
|
311
|
+
continue;
|
|
312
|
+
}
|
|
313
|
+
// A harness the host does not serve is the options' to refuse, with the ones it does.
|
|
314
|
+
for (const name of names.filter((one) => harnesses.hosted.has(one) && !harnesses.allowed.has(one))) {
|
|
315
|
+
found.errors.push({ ...place, code: "uses", message: `${call.expression.getText(parsed)}() starts a session on the harness "${name}", which uses does not list: add "session.start.${name}" (or "session.start.*") to uses` });
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
return found;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
function diagnose(ts: typeof Ts, source: ScriptSource, typing: string, harnesses: Harnesses): Diagnosis {
|
|
322
|
+
const options = optionsFor(ts, source.file);
|
|
323
|
+
const memory = new Map<string, string>([
|
|
324
|
+
[source.file, source.text],
|
|
325
|
+
[TYPING_FILE, typing],
|
|
326
|
+
]);
|
|
327
|
+
const host = ts.createCompilerHost(options, true);
|
|
328
|
+
const { fileExists, readFile, getSourceFile } = host;
|
|
329
|
+
host.fileExists = (name) => memory.has(name) || fileExists.call(host, name);
|
|
330
|
+
host.readFile = (name) => memory.get(name) ?? readFile.call(host, name);
|
|
331
|
+
host.getSourceFile = (name, languageVersion, onError, shouldCreate) => {
|
|
332
|
+
const text = memory.get(name);
|
|
333
|
+
if (text !== undefined) return ts.createSourceFile(name, text, languageVersion, true);
|
|
334
|
+
const installed = name.includes("/node_modules/");
|
|
335
|
+
const kept = installed ? parsedFiles.get(name) : undefined;
|
|
336
|
+
if (kept !== undefined) return kept;
|
|
337
|
+
const parsed = getSourceFile.call(host, name, languageVersion, onError, shouldCreate);
|
|
338
|
+
if (installed && parsed !== undefined) parsedFiles.set(name, parsed);
|
|
339
|
+
return parsed;
|
|
340
|
+
};
|
|
341
|
+
const program = ts.createProgram([source.file, TYPING_FILE], options, host);
|
|
342
|
+
// A package the script imports is read under the options of the script, not its own: what it says of the package is
|
|
343
|
+
// not the script's error, and it is not checked, only read for the types the script takes from it.
|
|
344
|
+
const own = program.getSourceFiles().filter((file) => !program.isSourceFileFromExternalLibrary(file));
|
|
345
|
+
const errors = [
|
|
346
|
+
...program.getOptionsDiagnostics(),
|
|
347
|
+
...program.getGlobalDiagnostics(),
|
|
348
|
+
...own.flatMap((file) => [...program.getSyntacticDiagnostics(file), ...program.getSemanticDiagnostics(file)]),
|
|
349
|
+
]
|
|
350
|
+
.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
|
|
351
|
+
.map((diagnostic): CheckError => {
|
|
352
|
+
const where =
|
|
353
|
+
diagnostic.file === undefined || diagnostic.start === undefined
|
|
354
|
+
? { line: 1, column: 1 }
|
|
355
|
+
: (({ line, character }) => ({ line: line + 1, column: character + 1 }))(
|
|
356
|
+
diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start),
|
|
357
|
+
);
|
|
358
|
+
return {
|
|
359
|
+
file: diagnostic.file?.fileName ?? source.file,
|
|
360
|
+
...where,
|
|
361
|
+
code: `TS${String(diagnostic.code)}`,
|
|
362
|
+
message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
|
|
363
|
+
};
|
|
364
|
+
});
|
|
365
|
+
const uses = harnessUses(ts, program, source, harnesses);
|
|
366
|
+
return { errors: [...errors, ...uses.errors], warnings: uses.warnings, program };
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/** What a check needs to know about the host. */
|
|
370
|
+
export interface Catalogue {
|
|
371
|
+
/** Every action the host describes. */
|
|
372
|
+
actions: readonly ActionDescription[];
|
|
373
|
+
/** The actions the caller may call: the seam where rights narrow what a script may use. */
|
|
374
|
+
callable: readonly ActionName[];
|
|
375
|
+
/** The grant of the caller, which `uses` is narrowed from; absent means nothing limits it. */
|
|
376
|
+
rights?: Grant | "unlimited";
|
|
377
|
+
/**
|
|
378
|
+
* The options block each harness takes, by its id, as the sessions module binds it (`harness.list`): what the
|
|
379
|
+
* block of an `ask()` call is typed by. A harness not in it takes no block.
|
|
380
|
+
*/
|
|
381
|
+
blocks?: ReadonlyMap<string, HarnessBlock>;
|
|
382
|
+
/**
|
|
383
|
+
* The records the host lets a script start on (`on`), with the schema of their data. Part of what a wait and a read are
|
|
384
|
+
* typed by too. The list may grow from the journal (the records registered workflows declare in `emits`), so it is
|
|
385
|
+
* part of the key of a kept answer.
|
|
386
|
+
*/
|
|
387
|
+
triggers?: readonly Trigger[];
|
|
388
|
+
/**
|
|
389
|
+
* The schema of the data of a record type the host knows, by its name: what a wait or a read of the script is typed
|
|
390
|
+
* by. Types are fixed for the life of a host, so the names a script writes, pinned by the hash of its text, give the
|
|
391
|
+
* same answers.
|
|
392
|
+
*/
|
|
393
|
+
records?: (type: string) => JsonSchema | undefined;
|
|
394
|
+
/** The version of a record type the host knows, by its name: what a script that names the type by reference must name. */
|
|
395
|
+
versions?: (type: string) => number | undefined;
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
/** Which of the described actions are irreversible: a mask of `uses` does not grant them. */
|
|
399
|
+
function irreversibleIn(actions: readonly ActionDescription[]): (name: string) => boolean {
|
|
400
|
+
const named = new Set(actions.filter((action) => action.effect === "irreversible").map((action) => String(action.name)));
|
|
401
|
+
return (name) => named.has(name);
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
/** A record type a script may start on, with the schema of the data of its records. */
|
|
405
|
+
export interface Trigger {
|
|
406
|
+
name: string;
|
|
407
|
+
schema: JsonSchema;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/** The places of the keys of the declaration that read the schemas, for the errors about them. */
|
|
411
|
+
export interface Places {
|
|
412
|
+
declaration: { line: number; column: number };
|
|
413
|
+
input?: { line: number; column: number };
|
|
414
|
+
output?: { line: number; column: number };
|
|
415
|
+
emits?: { line: number; column: number };
|
|
416
|
+
phases?: { line: number; column: number };
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/** What the text and the typing say of a script: the part of a check that does not load the module. */
|
|
420
|
+
export interface TextCheck {
|
|
421
|
+
file: string;
|
|
422
|
+
ok: boolean;
|
|
423
|
+
errors: CheckError[];
|
|
424
|
+
/** What the text could not settle; a warning does not fail the check. */
|
|
425
|
+
warnings: CheckError[];
|
|
426
|
+
/** The module can be loaded for its schemas: it is `export default workflow({ ... }, fn)`. */
|
|
427
|
+
readable: boolean;
|
|
428
|
+
places: Places;
|
|
429
|
+
phases?: WorkflowPhases;
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
/**
|
|
433
|
+
* A checker that keeps the answers it gave.
|
|
434
|
+
*
|
|
435
|
+
* What the text and the typing say is kept by the file, the hash of the script and the hash of the
|
|
436
|
+
* catalogue it was checked against, so the same script on the same host is checked once. The file is
|
|
437
|
+
* part of the key: its extension decides how strictly the text is read, and its folder where imports
|
|
438
|
+
* go. What the module declares is not kept here (`withDeclaration`): it is read by the describer, which keeps
|
|
439
|
+
* it for the version of the script, the hash of its source closure.
|
|
440
|
+
*/
|
|
441
|
+
export function scriptChecker(): (source: ScriptSource, catalogue: Catalogue) => Promise<TextCheck> {
|
|
442
|
+
const answers = new Map<string, TextCheck>();
|
|
443
|
+
return async (source, catalogue) => {
|
|
444
|
+
const file = resolve(source.file);
|
|
445
|
+
const key = `${file}:${sha256(source.text)}:${sha256(JSON.stringify([catalogue.actions, catalogue.callable, catalogue.rights ?? "unlimited", catalogue.triggers ?? [], [...(catalogue.blocks ?? [])]]))}`;
|
|
446
|
+
let kept = answers.get(key);
|
|
447
|
+
if (kept === undefined) {
|
|
448
|
+
kept = await check({ file, text: source.text }, catalogue);
|
|
449
|
+
if (answers.size >= CACHE_LIMIT) {
|
|
450
|
+
for (const oldest of answers.keys()) {
|
|
451
|
+
answers.delete(oldest);
|
|
452
|
+
break;
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
answers.set(key, kept);
|
|
456
|
+
}
|
|
457
|
+
return { ...kept, file };
|
|
458
|
+
};
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
/** The report of a check: what the text said, and what the module declares, read from its file. */
|
|
462
|
+
export async function withDeclaration(text: TextCheck, describe: Describer, box?: ScriptBox): Promise<CheckReport> {
|
|
463
|
+
const { file } = text;
|
|
464
|
+
const errors = [...text.errors];
|
|
465
|
+
const warned = text.warnings.length === 0 ? {} : { warnings: text.warnings };
|
|
466
|
+
if (!text.readable) return { file, ok: errors.length === 0, errors, ...warned, note: "described, the script was not run" };
|
|
467
|
+
const read = await describe(file, box);
|
|
468
|
+
if ("failed" in read) {
|
|
469
|
+
errors.push({ file, ...text.places.declaration, code: "describe", message: `the module could not be read for its schemas: ${read.failed}` });
|
|
470
|
+
return { file, ok: false, errors, ...warned, note: "described, the script was not run" };
|
|
471
|
+
}
|
|
472
|
+
const { description, input, output, emits, problems } = read.described;
|
|
473
|
+
for (const problem of problems) {
|
|
474
|
+
// Phases the text already shows to be wrong are not said twice.
|
|
475
|
+
if (problem.key === "phases" && errors.some((error) => error.code === "phases")) continue;
|
|
476
|
+
errors.push({ file, ...(text.places[problem.key] ?? text.places.declaration), code: problem.key === "phases" ? "phases" : "schema", message: problem.message });
|
|
477
|
+
}
|
|
478
|
+
return {
|
|
479
|
+
file,
|
|
480
|
+
ok: errors.length === 0,
|
|
481
|
+
errors,
|
|
482
|
+
...warned,
|
|
483
|
+
note: "described, the script was not run",
|
|
484
|
+
...(description === undefined ? {} : { description }),
|
|
485
|
+
...(input === undefined ? {} : { input }),
|
|
486
|
+
...(output === undefined ? {} : { output }),
|
|
487
|
+
...(emits === undefined ? {} : { emits: emittedTypesOf(read) }),
|
|
488
|
+
...(text.phases === undefined ? {} : { phases: text.phases }),
|
|
489
|
+
...(problems.length === 0 ? { contract: contractOf(read.described) } : {}),
|
|
490
|
+
};
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
/** The keys of the declaration that hold the schemas, with their places. */
|
|
494
|
+
function placesOf(ts: typeof Ts, source: Ts.SourceFile): Places {
|
|
495
|
+
const declaration = declarationOf(ts, source);
|
|
496
|
+
const places: Places = { declaration: { line: 1, column: 1 } };
|
|
497
|
+
if (declaration === undefined) return places;
|
|
498
|
+
if ("opaque" in declaration) return { declaration: declaration.opaque };
|
|
499
|
+
places.declaration = placeOf(ts, source, declaration.object);
|
|
500
|
+
for (const key of ["input", "output", "emits", "phases"] as const) {
|
|
501
|
+
const field = declarationField(ts, source, key);
|
|
502
|
+
if (field !== undefined) places[key] = placeOf(ts, source, "value" in field ? field.value : field.unsettled);
|
|
503
|
+
}
|
|
504
|
+
return places;
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/** The leaves a schema is at a point: the references followed, and the unions and intersections opened. */
|
|
508
|
+
function leavesOf(root: unknown, schema: unknown, depth = 0): Array<Record<string, unknown>> {
|
|
509
|
+
if (depth > 16 || typeof schema !== "object" || schema === null || Array.isArray(schema)) return [{}];
|
|
510
|
+
const here = schema as Record<string, unknown>;
|
|
511
|
+
const ref = here.$ref;
|
|
512
|
+
if (typeof ref === "string") {
|
|
513
|
+
if (ref === "#") return [{}];
|
|
514
|
+
const target = ref.startsWith("#/$defs/") ? (root as { $defs?: Record<string, unknown> }).$defs?.[ref.slice("#/$defs/".length)] : undefined;
|
|
515
|
+
return target === undefined ? [{}] : leavesOf(root, target, depth + 1);
|
|
516
|
+
}
|
|
517
|
+
const parts = [here.anyOf, here.oneOf, here.allOf].flatMap((part) => (Array.isArray(part) ? part : []));
|
|
518
|
+
return parts.length > 0 ? parts.flatMap((part) => leavesOf(root, part, depth + 1)) : [here];
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/** The leaves of the schema at a path of field names, or `undefined` when no such field can exist. */
|
|
522
|
+
function leavesAt(root: unknown, schema: unknown, path: readonly string[]): Array<Record<string, unknown>> | undefined {
|
|
523
|
+
const leaves = leavesOf(root, schema);
|
|
524
|
+
const [name, ...rest] = path;
|
|
525
|
+
if (name === undefined) return leaves;
|
|
526
|
+
const found: Array<Record<string, unknown>> = [];
|
|
527
|
+
for (const leaf of leaves) {
|
|
528
|
+
const properties = typeof leaf.properties === "object" && leaf.properties !== null ? (leaf.properties as Record<string, unknown>) : undefined;
|
|
529
|
+
const member = properties !== undefined && name in properties ? properties[name] : undefined;
|
|
530
|
+
// A leaf that says nothing of its fields, or lets any field in, holds any path.
|
|
531
|
+
const open = (leaf.type === undefined && properties === undefined) || (leaf.type === "object" && properties === undefined && leaf.additionalProperties !== false) || leaf.additionalProperties === true;
|
|
532
|
+
if (member !== undefined) found.push(...(leavesAt(root, member, rest) ?? []));
|
|
533
|
+
else if (typeof leaf.additionalProperties === "object" && leaf.additionalProperties !== null) found.push(...(leavesAt(root, leaf.additionalProperties, rest) ?? []));
|
|
534
|
+
else if (open) found.push({});
|
|
535
|
+
}
|
|
536
|
+
return found.length === 0 ? undefined : found;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
/** Can a field of this schema hold the literal a filter names? */
|
|
540
|
+
function fits(leaf: Record<string, unknown>, value: unknown): boolean {
|
|
541
|
+
if ("const" in leaf) return leaf.const === value;
|
|
542
|
+
if (Array.isArray(leaf.enum)) return leaf.enum.includes(value);
|
|
543
|
+
const types = Array.isArray(leaf.type) ? leaf.type : leaf.type === undefined ? undefined : [leaf.type];
|
|
544
|
+
if (types === undefined) return true;
|
|
545
|
+
const kind = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
|
|
546
|
+
return types.some((type) => type === kind || (type === "integer" && kind === "number" && Number.isInteger(value)));
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
/** A filter written in the script, of `on` or of a wait: the type it filters, the filter, and where it is. */
|
|
550
|
+
interface WrittenFilter extends Subscription {
|
|
551
|
+
line: number;
|
|
552
|
+
column: number;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
/** The errors of a filter of `on` or of a wait: a path no record of the type holds, or a literal its field cannot hold. */
|
|
556
|
+
function filterErrors(file: string, code: "on" | "wait", written: WrittenFilter, schema: unknown): CheckError[] {
|
|
557
|
+
const errors: CheckError[] = [];
|
|
558
|
+
const never = code === "on" ? "the script would never start" : "the wait would never end";
|
|
559
|
+
for (const [path, value] of Object.entries(written.filter ?? {})) {
|
|
560
|
+
const place = { file, line: written.line, column: written.column, code };
|
|
561
|
+
const leaves = leavesAt(schema, schema, path.split("."));
|
|
562
|
+
if (leaves === undefined) errors.push({ ...place, message: `${code} "${written.type}": the filter names "${path}", which no record of this type holds, so ${never}` });
|
|
563
|
+
else if (!leaves.some((leaf) => fits(leaf, value))) {
|
|
564
|
+
errors.push({ ...place, message: `${code} "${written.type}": the filter says ${JSON.stringify(value)} for "${path}", which the field cannot hold` });
|
|
565
|
+
}
|
|
566
|
+
}
|
|
567
|
+
return errors;
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
/** The text of a literal of text, when the expression is one. */
|
|
571
|
+
function textOf(ts: typeof Ts, expression: Ts.Expression | undefined): string | undefined {
|
|
572
|
+
const inner = expression === undefined ? undefined : bare(ts, expression);
|
|
573
|
+
return inner !== undefined && (ts.isStringLiteral(inner) || ts.isNoSubstitutionTemplateLiteral(inner)) ? inner.text : undefined;
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
/** The value of a key of an object written as a literal, when the expression is one and the key is there. */
|
|
577
|
+
function keyOf(ts: typeof Ts, expression: Ts.Expression | undefined, key: string): Ts.Expression | undefined {
|
|
578
|
+
const inner = expression === undefined ? undefined : bare(ts, expression);
|
|
579
|
+
if (inner === undefined || !ts.isObjectLiteralExpression(inner)) return undefined;
|
|
580
|
+
for (const property of inner.properties) {
|
|
581
|
+
if (ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text === key) return property.initializer;
|
|
582
|
+
}
|
|
583
|
+
return undefined;
|
|
584
|
+
}
|
|
585
|
+
|
|
586
|
+
/** The waits whose type is written out, with their filter when it is written as a literal. */
|
|
587
|
+
function waitsOf(ts: typeof Ts, source: Ts.SourceFile): WrittenFilter[] {
|
|
588
|
+
const waits: WrittenFilter[] = [];
|
|
589
|
+
for (const call of callsOf(ts, source, "wait")) {
|
|
590
|
+
const type = textOf(ts, call.arguments[0]);
|
|
591
|
+
if (type === undefined) continue;
|
|
592
|
+
const filter = keyOf(ts, call.arguments[1], "filter");
|
|
593
|
+
const written = filter === undefined ? undefined : literalOf(ts, filter)?.value;
|
|
594
|
+
const fields = typeof written === "object" && written !== null && !Array.isArray(written) ? (written as Record<string, unknown>) : undefined;
|
|
595
|
+
waits.push({ type, ...(fields === undefined ? {} : { filter: fields }), ...placeOf(ts, source, call) });
|
|
596
|
+
}
|
|
597
|
+
return waits;
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
/** The record types `read.records({ types: [...] })` names as text. */
|
|
601
|
+
function readTypesOf(ts: typeof Ts, source: Ts.SourceFile): string[] {
|
|
602
|
+
const types: string[] = [];
|
|
603
|
+
const visit = (node: Ts.Node): void => {
|
|
604
|
+
if (
|
|
605
|
+
ts.isCallExpression(node) &&
|
|
606
|
+
ts.isPropertyAccessExpression(node.expression) &&
|
|
607
|
+
ts.isIdentifier(node.expression.expression) &&
|
|
608
|
+
node.expression.expression.text === "read" &&
|
|
609
|
+
node.expression.name.text === "records"
|
|
610
|
+
) {
|
|
611
|
+
const list = keyOf(ts, node.arguments[0], "types");
|
|
612
|
+
const inner = list === undefined ? undefined : bare(ts, list);
|
|
613
|
+
if (inner !== undefined && ts.isArrayLiteralExpression(inner)) {
|
|
614
|
+
for (const element of inner.elements) {
|
|
615
|
+
const type = textOf(ts, element);
|
|
616
|
+
if (type !== undefined) types.push(type);
|
|
617
|
+
}
|
|
618
|
+
}
|
|
619
|
+
}
|
|
620
|
+
ts.forEachChild(node, visit);
|
|
621
|
+
};
|
|
622
|
+
visit(source);
|
|
623
|
+
return types;
|
|
624
|
+
}
|
|
625
|
+
|
|
626
|
+
/** A type a wait or a read of the script names by reference, followed to the declaration the reference is made by. */
|
|
627
|
+
interface Referenced {
|
|
628
|
+
code: "wait" | "read";
|
|
629
|
+
/** The reference as the script writes it. */
|
|
630
|
+
written: string;
|
|
631
|
+
/** The name and the version the declaration gives the type. */
|
|
632
|
+
name: string;
|
|
633
|
+
version: number;
|
|
634
|
+
/** The filter of a wait, when it is written as a literal. */
|
|
635
|
+
filter?: Record<string, unknown>;
|
|
636
|
+
line: number;
|
|
637
|
+
column: number;
|
|
638
|
+
}
|
|
639
|
+
|
|
640
|
+
/** How many calls deep the check follows a query builder to the type it names. */
|
|
641
|
+
const BUILDER_DEPTH = 4;
|
|
642
|
+
|
|
643
|
+
/** What a function gives back: the body of an arrow written as an expression, or what its own `return`s give. */
|
|
644
|
+
function returnedBy(ts: typeof Ts, declaration: Ts.Declaration | undefined): Ts.Expression[] {
|
|
645
|
+
const fn =
|
|
646
|
+
declaration !== undefined && ts.isVariableDeclaration(declaration) && declaration.initializer !== undefined
|
|
647
|
+
? bare(ts, declaration.initializer)
|
|
648
|
+
: declaration;
|
|
649
|
+
if (fn === undefined || !(ts.isFunctionDeclaration(fn) || ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) || fn.body === undefined) return [];
|
|
650
|
+
if (!ts.isBlock(fn.body)) return [fn.body];
|
|
651
|
+
const found: Ts.Expression[] = [];
|
|
652
|
+
const visit = (node: Ts.Node): void => {
|
|
653
|
+
if (ts.isReturnStatement(node)) {
|
|
654
|
+
if (node.expression !== undefined) found.push(node.expression);
|
|
655
|
+
} else if (!ts.isFunctionLike(node) && !ts.isClassLike(node)) ts.forEachChild(node, visit);
|
|
656
|
+
};
|
|
657
|
+
ts.forEachChild(fn.body, visit);
|
|
658
|
+
return found;
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/**
|
|
662
|
+
* The type a reference names: the reference is followed through its import to where it is made, `record("name",
|
|
663
|
+
* schema, { version })` with the name and the version written as literals. A query a builder gives (`taskDone(id)`) is
|
|
664
|
+
* followed into the builder to the `queryOf(Type, filter)` it returns, and from there to the type. A reference made
|
|
665
|
+
* any other way, and a record of the script itself (made by its own `record`), name nothing the check can follow: the
|
|
666
|
+
* host refuses a reference it does not know when the script runs.
|
|
667
|
+
*/
|
|
668
|
+
function referencedType(ts: typeof Ts, checker: Ts.TypeChecker, expression: Ts.Expression, depth = 0): { name: string; version: number } | undefined {
|
|
669
|
+
const resolved = (node: Ts.Node): Ts.Symbol | undefined => {
|
|
670
|
+
const symbol = checker.getSymbolAtLocation(node);
|
|
671
|
+
return symbol !== undefined && symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
|
|
672
|
+
};
|
|
673
|
+
const inner = bare(ts, expression);
|
|
674
|
+
if (ts.isCallExpression(inner)) {
|
|
675
|
+
if (depth >= BUILDER_DEPTH) return undefined;
|
|
676
|
+
const callee = ts.isPropertyAccessExpression(inner.expression) ? inner.expression.name : inner.expression;
|
|
677
|
+
if (ts.isIdentifier(callee) && callee.text === "queryOf") {
|
|
678
|
+
const [type] = inner.arguments;
|
|
679
|
+
return type === undefined ? undefined : referencedType(ts, checker, type, depth + 1);
|
|
680
|
+
}
|
|
681
|
+
// A builder names one type: every `return` of it must lead to the same one.
|
|
682
|
+
const types = returnedBy(ts, resolved(callee)?.valueDeclaration).map((returned) => referencedType(ts, checker, returned, depth + 1));
|
|
683
|
+
const [first] = types;
|
|
684
|
+
return first !== undefined && types.every((one) => one?.name === first.name && one.version === first.version) ? first : undefined;
|
|
685
|
+
}
|
|
686
|
+
if (!ts.isIdentifier(inner) && !ts.isPropertyAccessExpression(inner)) return undefined;
|
|
687
|
+
const declaration = resolved(inner)?.valueDeclaration;
|
|
688
|
+
if (declaration === undefined || !ts.isVariableDeclaration(declaration) || declaration.initializer === undefined) return undefined;
|
|
689
|
+
const made = bare(ts, declaration.initializer);
|
|
690
|
+
if (!ts.isCallExpression(made)) return undefined;
|
|
691
|
+
const callee = ts.isPropertyAccessExpression(made.expression) ? made.expression.name : made.expression;
|
|
692
|
+
if (!ts.isIdentifier(callee)) return undefined;
|
|
693
|
+
// A query a builder gave, kept in a constant: followed as the call it was made by.
|
|
694
|
+
if (callee.text !== "record") return referencedType(ts, checker, made, depth + 1);
|
|
695
|
+
if ((resolved(callee)?.declarations ?? []).some((one) => one.getSourceFile().fileName === TYPING_FILE)) return undefined;
|
|
696
|
+
const name = textOf(ts, made.arguments[0]);
|
|
697
|
+
if (name === undefined) return undefined;
|
|
698
|
+
const options = made.arguments[2];
|
|
699
|
+
if (options === undefined) return { name, version: 1 };
|
|
700
|
+
if (!ts.isObjectLiteralExpression(bare(ts, options))) return undefined;
|
|
701
|
+
const written = keyOf(ts, options, "version");
|
|
702
|
+
const version = written === undefined ? 1 : literalOf(ts, written)?.value;
|
|
703
|
+
return typeof version === "number" ? { name, version } : undefined;
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
/** The waits and the reads of the script that name a type by reference, each followed to the type it names. */
|
|
707
|
+
function referencesOf(ts: typeof Ts, program: Ts.Program, file: string): Referenced[] {
|
|
708
|
+
const source = program.getSourceFile(file);
|
|
709
|
+
if (source === undefined) return [];
|
|
710
|
+
const checker = program.getTypeChecker();
|
|
711
|
+
const found: Referenced[] = [];
|
|
712
|
+
const add = (code: Referenced["code"], expression: Ts.Expression, filter?: Ts.Expression): void => {
|
|
713
|
+
if (textOf(ts, expression) !== undefined) return;
|
|
714
|
+
const type = referencedType(ts, checker, expression);
|
|
715
|
+
if (type === undefined) return;
|
|
716
|
+
const written = filter === undefined ? undefined : literalOf(ts, filter)?.value;
|
|
717
|
+
const fields = typeof written === "object" && written !== null && !Array.isArray(written) ? (written as Record<string, unknown>) : undefined;
|
|
718
|
+
found.push({ code, written: bare(ts, expression).getText(source), ...type, ...(fields === undefined ? {} : { filter: fields }), ...placeOf(ts, source, expression) });
|
|
719
|
+
};
|
|
720
|
+
const visit = (node: Ts.Node): void => {
|
|
721
|
+
if (ts.isCallExpression(node)) {
|
|
722
|
+
const [first, second] = node.arguments;
|
|
723
|
+
if (ts.isIdentifier(node.expression) && node.expression.text === "wait" && first !== undefined) {
|
|
724
|
+
add("wait", first, keyOf(ts, second, "filter"));
|
|
725
|
+
} else if (
|
|
726
|
+
ts.isPropertyAccessExpression(node.expression) &&
|
|
727
|
+
ts.isIdentifier(node.expression.expression) &&
|
|
728
|
+
node.expression.expression.text === "read" &&
|
|
729
|
+
node.expression.name.text === "records" &&
|
|
730
|
+
first !== undefined
|
|
731
|
+
) {
|
|
732
|
+
const list = keyOf(ts, first, "types");
|
|
733
|
+
const types = list === undefined ? undefined : bare(ts, list);
|
|
734
|
+
if (types !== undefined && ts.isArrayLiteralExpression(types)) for (const element of types.elements) add("read", element);
|
|
735
|
+
else if (list === undefined) add("read", first);
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
ts.forEachChild(node, visit);
|
|
739
|
+
};
|
|
740
|
+
visit(source);
|
|
741
|
+
return found;
|
|
742
|
+
}
|
|
743
|
+
|
|
744
|
+
/**
|
|
745
|
+
* The errors of the types a script names by reference: one the host does not know, so a wait for it would never end,
|
|
746
|
+
* or one at a version the host does not write; and a filter of a wait no record of the type can hold.
|
|
747
|
+
*/
|
|
748
|
+
function referenceErrors(file: string, references: readonly Referenced[], catalogue: Catalogue): CheckError[] {
|
|
749
|
+
const errors: CheckError[] = [];
|
|
750
|
+
for (const reference of references) {
|
|
751
|
+
const place = { file, line: reference.line, column: reference.column, code: reference.code };
|
|
752
|
+
const said = `${reference.code} ${reference.written}`;
|
|
753
|
+
const schema = catalogue.records?.(reference.name);
|
|
754
|
+
if (catalogue.records !== undefined && schema === undefined) {
|
|
755
|
+
const never = reference.code === "wait" ? ", so the wait would never end" : "";
|
|
756
|
+
errors.push({ ...place, message: `${said}: the host knows no record type "${reference.name}"${never}` });
|
|
757
|
+
continue;
|
|
758
|
+
}
|
|
759
|
+
const version = catalogue.versions?.(reference.name);
|
|
760
|
+
if (version !== undefined && version !== reference.version) {
|
|
761
|
+
errors.push({ ...place, message: `${said}: the script names version ${String(reference.version)} of "${reference.name}", and the host writes version ${String(version)}` });
|
|
762
|
+
continue;
|
|
763
|
+
}
|
|
764
|
+
if (reference.code === "wait" && schema !== undefined) {
|
|
765
|
+
errors.push(...filterErrors(file, "wait", { type: reference.name, ...(reference.filter === undefined ? {} : { filter: reference.filter }), line: reference.line, column: reference.column }, schema));
|
|
766
|
+
}
|
|
767
|
+
}
|
|
768
|
+
return errors;
|
|
769
|
+
}
|
|
770
|
+
|
|
771
|
+
/**
|
|
772
|
+
* The record types the typing of a script describes, with the schema of their data: the types it may start on, and the
|
|
773
|
+
* types it waits for or reads by name that the host knows. A record of a script that no schema describes carries data
|
|
774
|
+
* of any shape; a type the host does not know is not described, so a typed wait for it is an error of the type checker.
|
|
775
|
+
*/
|
|
776
|
+
function recordCatalogue(catalogue: Catalogue, named: readonly string[]): Trigger[] {
|
|
777
|
+
const known = new Map((catalogue.triggers ?? []).map((trigger) => [trigger.name, trigger]));
|
|
778
|
+
for (const name of new Set(named)) {
|
|
779
|
+
if (known.has(name)) continue;
|
|
780
|
+
const schema = catalogue.records?.(name) ?? (name.startsWith(SCRIPT_TYPES) ? {} : undefined);
|
|
781
|
+
if (schema !== undefined) known.set(name, { name, schema });
|
|
782
|
+
}
|
|
783
|
+
return [...known.values()];
|
|
784
|
+
}
|
|
785
|
+
|
|
786
|
+
async function check(source: ScriptSource, catalogue: Catalogue): Promise<TextCheck> {
|
|
787
|
+
const ts = (await import("typescript")).default;
|
|
788
|
+
const parsed = ts.createSourceFile(source.file, source.text, ts.ScriptTarget.ESNext, true);
|
|
789
|
+
const declaration = declarationOf(ts, parsed);
|
|
790
|
+
const places = placesOf(ts, parsed);
|
|
791
|
+
const errors: CheckError[] = [];
|
|
792
|
+
if (declaration === undefined || "opaque" in declaration) {
|
|
793
|
+
errors.push({
|
|
794
|
+
file: source.file,
|
|
795
|
+
...places.declaration,
|
|
796
|
+
code: "workflow",
|
|
797
|
+
message:
|
|
798
|
+
declaration === undefined
|
|
799
|
+
? "the script must be `export default workflow({ ... }, async (input) => { ... })`"
|
|
800
|
+
: "workflow() is given its declaration as an object written in the call: `workflow({ description, input, output, uses, on }, fn)`",
|
|
801
|
+
});
|
|
802
|
+
} else if (declarationField(ts, parsed, "on") !== undefined && declarationField(ts, parsed, "input") !== undefined) {
|
|
803
|
+
errors.push({ file: source.file, ...places.declaration, code: "workflow", message: "a script has an `input` or it starts `on` records, not both: its function is given the record" });
|
|
804
|
+
}
|
|
805
|
+
const uses = usesOf(ts, parsed);
|
|
806
|
+
if (uses !== undefined && "bad" in uses) {
|
|
807
|
+
errors.push({ file: source.file, ...uses.bad, code: "uses", message: "uses must be a list of action names or masks written as text" });
|
|
808
|
+
}
|
|
809
|
+
const on = onOf(ts, parsed);
|
|
810
|
+
if (on !== undefined && "bad" in on) errors.push({ file: source.file, ...on.bad, code: "on" });
|
|
811
|
+
const phases = phasesOf(ts, parsed);
|
|
812
|
+
if (phases !== undefined && "bad" in phases) errors.push({ file: source.file, ...phases.bad, code: "phases" });
|
|
813
|
+
for (const subscription of on !== undefined && "subscriptions" in on ? on.subscriptions : []) {
|
|
814
|
+
const trigger = catalogue.triggers?.find((one) => one.name === subscription.type);
|
|
815
|
+
if (catalogue.triggers !== undefined && !subscription.type.startsWith(SCRIPT_TYPES) && trigger === undefined) {
|
|
816
|
+
errors.push({
|
|
817
|
+
file: source.file,
|
|
818
|
+
line: subscription.line,
|
|
819
|
+
column: subscription.column,
|
|
820
|
+
code: "on",
|
|
821
|
+
message: `on "${subscription.type}": the host does not start scripts on this record type`,
|
|
822
|
+
});
|
|
823
|
+
} else if (trigger !== undefined) {
|
|
824
|
+
errors.push(...filterErrors(source.file, "on", subscription, trigger.schema));
|
|
825
|
+
}
|
|
826
|
+
}
|
|
827
|
+
const waits = waitsOf(ts, parsed);
|
|
828
|
+
const records = recordCatalogue(catalogue, [...waits.map((wait) => wait.type), ...readTypesOf(ts, parsed)]);
|
|
829
|
+
for (const wait of waits) {
|
|
830
|
+
const described = records.find((one) => one.name === wait.type);
|
|
831
|
+
if (described !== undefined) errors.push(...filterErrors(source.file, "wait", wait, described.schema));
|
|
832
|
+
}
|
|
833
|
+
// A script writes only the records it declares, under its own `wf.<name>.`, so it cannot speak as another workflow.
|
|
834
|
+
errors.push(...emitErrors(ts, parsed, source.file));
|
|
835
|
+
const masks = uses !== undefined && "masks" in uses ? uses.masks : undefined;
|
|
836
|
+
const rights = catalogue.rights ?? "unlimited";
|
|
837
|
+
// The same narrowing `workflow.start` makes: a mask the caller's grant does not hold is refused.
|
|
838
|
+
const wider = new Set<string>();
|
|
839
|
+
// A template is filled from the input of a run, so it is held to the rights when a run starts, not here.
|
|
840
|
+
if (rights !== "unlimited") {
|
|
841
|
+
const fixed = (masks ?? []).filter((use) => isUse(use.mask) && !isRuleTemplate(use.mask)).map((use) => use.mask);
|
|
842
|
+
const narrowed = narrow(rights, fixed, isOwnerGrant(rights) ? {} : { irreversible: irreversibleIn(catalogue.actions) });
|
|
843
|
+
if ("refused" in narrowed) for (const refused of narrowed.refused) wider.add(refused);
|
|
844
|
+
}
|
|
845
|
+
for (const use of masks ?? []) {
|
|
846
|
+
const place = { file: source.file, line: use.line, column: use.column, code: "uses" };
|
|
847
|
+
const name = useName(use.mask);
|
|
848
|
+
if (name === undefined) {
|
|
849
|
+
errors.push({ ...place, message: `uses "${use.mask}" is not an action name, a rule or a target template` });
|
|
850
|
+
} else if (!isRuleTemplate(use.mask) && wider.has(ruleText(rule(use.mask)))) {
|
|
851
|
+
errors.push({ ...place, message: `uses "${use.mask}" is wider than the caller's rights` });
|
|
852
|
+
} else if (!catalogue.callable.some((callable) => matches(name, callable))) {
|
|
853
|
+
errors.push({ ...place, message: `uses "${use.mask}" names no action the caller may call` });
|
|
854
|
+
}
|
|
855
|
+
}
|
|
856
|
+
const allowed = allowedFor(catalogue.callable, masks?.flatMap((use) => useName(use.mask) ?? []), rights);
|
|
857
|
+
const listed = on !== undefined && "subscriptions" in on ? on.subscriptions.map((subscription) => subscription.type) : [];
|
|
858
|
+
// A record of a script that no schema describes carries data of any shape.
|
|
859
|
+
const known = catalogue.triggers ?? [];
|
|
860
|
+
const described = [
|
|
861
|
+
...known,
|
|
862
|
+
...listed.filter((type) => type.startsWith(SCRIPT_TYPES) && !known.some((trigger) => trigger.name === type)).map((name) => ({ name, schema: {} })),
|
|
863
|
+
];
|
|
864
|
+
const plan = phases !== undefined && "phases" in phases ? phases.phases : undefined;
|
|
865
|
+
const titles = (plan ?? []).map((phase) => phase.title);
|
|
866
|
+
const typing = scriptTyping(catalogue.actions, allowed, described.filter((trigger) => listed.includes(trigger.name)), records, catalogue.blocks, titles);
|
|
867
|
+
const harnessesOf = (names: readonly string[]) => new Set(names.flatMap((name) => harnessOfAction(name) ?? []));
|
|
868
|
+
const diagnosis = diagnose(ts, source, typing.declarations, { hosted: harnessesOf(catalogue.actions.map((action) => action.name)), allowed: harnessesOf(allowed) });
|
|
869
|
+
errors.push(...referenceErrors(source.file, referencesOf(ts, diagnosis.program, source.file), catalogue));
|
|
870
|
+
errors.push(...diagnosis.errors);
|
|
871
|
+
return {
|
|
872
|
+
file: source.file,
|
|
873
|
+
ok: errors.length === 0,
|
|
874
|
+
errors,
|
|
875
|
+
warnings: diagnosis.warnings,
|
|
876
|
+
readable: declaration !== undefined && "object" in declaration,
|
|
877
|
+
places,
|
|
878
|
+
...(plan === undefined ? {} : { phases: plan }),
|
|
879
|
+
};
|
|
880
|
+
}
|