ezship 0.1.11 → 0.1.13
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 +56 -8
- package/access.d.mts +120 -0
- package/access.mjs +987 -0
- package/account.d.mts +19 -0
- package/account.mjs +91 -0
- package/bindings.mjs +136 -0
- package/commands.d.mts +672 -0
- package/commands.mjs +8098 -0
- package/connections.d.mts +61 -0
- package/connections.mjs +312 -0
- package/cron.d.mts +17 -0
- package/cron.mjs +124 -0
- package/documents.d.mts +26 -0
- package/documents.mjs +242 -0
- package/editor-types.json.gz +0 -0
- package/editor.mjs +212 -0
- package/ez.mjs +1300 -2
- package/local-fetch.mjs +57 -0
- package/package.json +82 -6
- package/schema.d.mts +369 -0
- package/schema.mjs +3099 -0
- package/session.d.mts +20 -0
- package/session.mjs +142 -0
- package/shape.d.mts +14 -0
- package/shape.mjs +312 -0
- package/signup.d.mts +11 -0
- package/signup.mjs +42 -0
- package/types.d.mts +879 -0
- package/update-check.mjs +105 -0
- package/workflow.d.mts +63 -0
- package/workflow.mjs +450 -0
package/update-check.mjs
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
// Whether a newer `ez` is on npm (docs/adr/0111): at most one registry request a day, remembered in
|
|
2
|
+
// `~/.ez/update-check.json`, and a one-line notice on standard error at most once a day while one is. Nothing
|
|
3
|
+
// here ever fails a command: an offline machine, a slow registry or an unreadable file mean no notice.
|
|
4
|
+
// Zero dependencies, Node 20+.
|
|
5
|
+
|
|
6
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
7
|
+
|
|
8
|
+
/** How long a registry answer stands, and how long a shown notice stays quiet. */
|
|
9
|
+
export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
|
|
10
|
+
/** How long a check may delay the end of a command. */
|
|
11
|
+
const CHECK_TIMEOUT_MS = 1500;
|
|
12
|
+
|
|
13
|
+
/** `major.minor.patch` as numbers, or null for anything else (a prerelease is never offered). */
|
|
14
|
+
const parts = (/** @type {string} */ version) => {
|
|
15
|
+
const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
|
|
16
|
+
return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Whether `latest` is a newer release than `current`.
|
|
21
|
+
* @param {string} current
|
|
22
|
+
* @param {string} latest
|
|
23
|
+
*/
|
|
24
|
+
export function isNewer(current, latest) {
|
|
25
|
+
const a = parts(current);
|
|
26
|
+
const b = parts(latest);
|
|
27
|
+
if (!a || !b) return false;
|
|
28
|
+
for (let i = 0; i < 3; i++) if (b[i] !== a[i]) return b[i] > a[i];
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* The notice: the versions and the command that upgrades the package this `ez` was installed as.
|
|
34
|
+
* @param {string} current
|
|
35
|
+
* @param {string} latest
|
|
36
|
+
* @param {string} name `ezship` or `@ezship/cli`
|
|
37
|
+
*/
|
|
38
|
+
export const updateNotice = (current, latest, name) =>
|
|
39
|
+
`A newer ez is available: ${current} → ${latest}. Upgrade with: npm install -g ${name}@latest`;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The package `ez` runs as: the `ezship` alias when its bin started it, else `@ezship/cli`.
|
|
43
|
+
* @param {string | undefined} bin process.argv[1]
|
|
44
|
+
*/
|
|
45
|
+
export const installedAs = (bin) =>
|
|
46
|
+
bin && /[\\/]node_modules[\\/]ezship[\\/]/.test(bin) && !/[\\/]@ezship[\\/]cli[\\/]/.test(bin)
|
|
47
|
+
? "ezship"
|
|
48
|
+
: "@ezship/cli";
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* @typedef {{ checkedAt?: number, latest?: string, notifiedAt?: number }} UpdateState
|
|
52
|
+
* @typedef {{
|
|
53
|
+
* current: string,
|
|
54
|
+
* name: string,
|
|
55
|
+
* file: string,
|
|
56
|
+
* env: Record<string, string | undefined>,
|
|
57
|
+
* fetch: typeof globalThis.fetch,
|
|
58
|
+
* now?: number,
|
|
59
|
+
* }} UpdateCheck
|
|
60
|
+
*/
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The notice to print after this command, or null. Asks the registry only when the last answer is a day old,
|
|
64
|
+
* and remembers when it last spoke so a notice appears at most once a day. `EZ_NO_UPDATE_CHECK` or `CI`
|
|
65
|
+
* turns it off.
|
|
66
|
+
* @param {UpdateCheck} check
|
|
67
|
+
* @returns {Promise<string | null>}
|
|
68
|
+
*/
|
|
69
|
+
export async function checkForUpdate({ current, name, file, env, fetch, now = Date.now() }) {
|
|
70
|
+
if (env.EZ_NO_UPDATE_CHECK || env.CI) return null;
|
|
71
|
+
/** @type {UpdateState} */
|
|
72
|
+
let state = {};
|
|
73
|
+
try {
|
|
74
|
+
state = JSON.parse(await readFile(file, "utf8"));
|
|
75
|
+
} catch {
|
|
76
|
+
// No file yet, or an unreadable one: start over.
|
|
77
|
+
}
|
|
78
|
+
let changed = false;
|
|
79
|
+
if (!(typeof state.checkedAt === "number" && now - state.checkedAt < CHECK_INTERVAL_MS)) {
|
|
80
|
+
// Failed checks count as checks, so an offline machine asks once a day, not on every command.
|
|
81
|
+
state.checkedAt = now;
|
|
82
|
+
changed = true;
|
|
83
|
+
try {
|
|
84
|
+
const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {
|
|
85
|
+
headers: { accept: "application/json" },
|
|
86
|
+
signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
|
|
87
|
+
});
|
|
88
|
+
if (res.ok) {
|
|
89
|
+
const body = /** @type {{ version?: unknown }} */ (await res.json());
|
|
90
|
+
if (typeof body.version === "string") state.latest = body.version;
|
|
91
|
+
}
|
|
92
|
+
} catch {
|
|
93
|
+
// Offline or slow: no news.
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
let notice = null;
|
|
97
|
+
const quiet = typeof state.notifiedAt === "number" && now - state.notifiedAt < CHECK_INTERVAL_MS;
|
|
98
|
+
if (state.latest && isNewer(current, state.latest) && !quiet) {
|
|
99
|
+
notice = updateNotice(current, state.latest, name);
|
|
100
|
+
state.notifiedAt = now;
|
|
101
|
+
changed = true;
|
|
102
|
+
}
|
|
103
|
+
if (changed) await writeFile(file, JSON.stringify(state) + "\n", { mode: 0o600 }).catch(() => {});
|
|
104
|
+
return notice;
|
|
105
|
+
}
|
package/workflow.d.mts
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import type { Declaration } from "./schema.d.mts";
|
|
2
|
+
|
|
3
|
+
/** An action's `from` that lets an insert start with it (docs/adr/0103). */
|
|
4
|
+
export const WORKFLOW_NEW: "@new";
|
|
5
|
+
/** An action's `to` that returns the row to the state it had before its current one, from its History. */
|
|
6
|
+
export const WORKFLOW_PREVIOUS: "@previous";
|
|
7
|
+
/** A state's tones: the starter Badge's. */
|
|
8
|
+
export const WORKFLOW_TONES: readonly ["ok", "info", "warn", "danger", "dark"];
|
|
9
|
+
export type WorkflowTone = (typeof WORKFLOW_TONES)[number];
|
|
10
|
+
export const WORKFLOW_LIMITS: Readonly<{
|
|
11
|
+
states: 50;
|
|
12
|
+
actions: 100;
|
|
13
|
+
steps: 10;
|
|
14
|
+
depth: 3;
|
|
15
|
+
children: 1000;
|
|
16
|
+
}>;
|
|
17
|
+
|
|
18
|
+
/** What a workflow file declares, read without running it: enough to type the column. */
|
|
19
|
+
export type WorkflowShape = {
|
|
20
|
+
column: string;
|
|
21
|
+
initial: string;
|
|
22
|
+
states: string[];
|
|
23
|
+
/** The actions a caller may name, in the order written. */
|
|
24
|
+
actions: string[];
|
|
25
|
+
/** The automatic actions (`auto: true`), the Host's own. */
|
|
26
|
+
automatic: string[];
|
|
27
|
+
};
|
|
28
|
+
/** The names a file declares, or why they cannot be read from it (1-based line). */
|
|
29
|
+
export function readWorkflow(source: string): WorkflowShape | { error: string; line: number };
|
|
30
|
+
|
|
31
|
+
/** The readable workflows of a Global Workspace's files (paths relative to it), by Table. */
|
|
32
|
+
export function workflowShapes(files: Record<string, string>): Record<string, WorkflowShape>;
|
|
33
|
+
|
|
34
|
+
/** One action as the Host enforces it and `useWorkflow` shows it. */
|
|
35
|
+
export type WorkflowAction = {
|
|
36
|
+
label: string;
|
|
37
|
+
from: string[];
|
|
38
|
+
to: string;
|
|
39
|
+
groups: string[];
|
|
40
|
+
/** Whether it has a guard (run by the Host). */
|
|
41
|
+
guard: boolean;
|
|
42
|
+
/** The Host's own: run after a child write when `when` answers true; never a caller's. */
|
|
43
|
+
auto: boolean;
|
|
44
|
+
/** An automatic action's children: child Table -> its column that references this Table. */
|
|
45
|
+
children?: Record<string, string>;
|
|
46
|
+
};
|
|
47
|
+
/** A Table's workflow (docs/adr/0103) as the Host enforces it, checked at Push. */
|
|
48
|
+
export type WorkflowMeta = {
|
|
49
|
+
column: string;
|
|
50
|
+
initial: string;
|
|
51
|
+
states: Record<string, { label: string; tone: WorkflowTone | null }>;
|
|
52
|
+
actions: Record<string, WorkflowAction>;
|
|
53
|
+
};
|
|
54
|
+
/** A Table's workflow as its compiled file describes itself, checked against the published schema. */
|
|
55
|
+
export function checkWorkflow(
|
|
56
|
+
table: string,
|
|
57
|
+
raw: unknown,
|
|
58
|
+
schema: Declaration,
|
|
59
|
+
): { workflow: WorkflowMeta } | { error: string };
|
|
60
|
+
/** Whether the names a file declares are the ones its compiled form describes. */
|
|
61
|
+
export function sameNames(shape: WorkflowShape, meta: WorkflowMeta): boolean;
|
|
62
|
+
/** A name spaced and capitalised: the default label. */
|
|
63
|
+
export function labelOf(name: string): string;
|
package/workflow.mjs
ADDED
|
@@ -0,0 +1,450 @@
|
|
|
1
|
+
// Workflows (docs/adr/0103): a Table's status column as a declared state machine, in
|
|
2
|
+
// `global/workflows/<table>.ts`. Zero dependencies. `readWorkflow` reads the names a file declares without
|
|
3
|
+
// running it, so the contract can type the column; `checkWorkflow` checks what the compiled file describes
|
|
4
|
+
// against the schema it runs on, at Push.
|
|
5
|
+
|
|
6
|
+
/** @typedef {import("./workflow.d.mts").WorkflowShape} WorkflowShape */
|
|
7
|
+
/** @typedef {import("./workflow.d.mts").WorkflowMeta} WorkflowMeta */
|
|
8
|
+
/** @typedef {import("./schema.d.mts").Declaration} Declaration */
|
|
9
|
+
|
|
10
|
+
/** @type {typeof import("./workflow.d.mts").WORKFLOW_NEW} */
|
|
11
|
+
export const WORKFLOW_NEW = "@new";
|
|
12
|
+
/** @type {typeof import("./workflow.d.mts").WORKFLOW_PREVIOUS} */
|
|
13
|
+
export const WORKFLOW_PREVIOUS = "@previous";
|
|
14
|
+
/** @type {typeof import("./workflow.d.mts").WORKFLOW_TONES} */
|
|
15
|
+
export const WORKFLOW_TONES = Object.freeze(["ok", "info", "warn", "danger", "dark"]);
|
|
16
|
+
/** @type {typeof import("./workflow.d.mts").WORKFLOW_LIMITS} */
|
|
17
|
+
export const WORKFLOW_LIMITS = Object.freeze({
|
|
18
|
+
states: 50,
|
|
19
|
+
actions: 100,
|
|
20
|
+
/** Automatic steps per parent row after one child write. */
|
|
21
|
+
steps: 10,
|
|
22
|
+
/** Tables up a chain of parents that follow their children. */
|
|
23
|
+
depth: 3,
|
|
24
|
+
/** Child rows `when` sees per child Table. */
|
|
25
|
+
children: 1000,
|
|
26
|
+
});
|
|
27
|
+
const NAME_RE = /^[a-z][a-z0-9_]{0,62}$/;
|
|
28
|
+
|
|
29
|
+
// ---- reading the names without running the file ---------------------------------------------------------
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* @typedef {{ kind: "ident" | "string" | "punct" | "other", text: string, line: number }} Token
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/** Characters after which a `/` starts a regular expression, not a division. */
|
|
36
|
+
const REGEX_AFTER = new Set(["(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+", "-"]);
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* A TypeScript file's tokens, enough to find object keys: comments dropped, strings, template literals and
|
|
40
|
+
* regular expressions kept whole.
|
|
41
|
+
* @param {string} source
|
|
42
|
+
* @returns {Token[]}
|
|
43
|
+
*/
|
|
44
|
+
function tokenize(source) {
|
|
45
|
+
/** @type {Token[]} */
|
|
46
|
+
const out = [];
|
|
47
|
+
let line = 1;
|
|
48
|
+
let i = 0;
|
|
49
|
+
/** @param {number} from @param {number} to */
|
|
50
|
+
const lines = (from, to) => {
|
|
51
|
+
for (let k = from; k < to; k++) if (source[k] === "\n") line++;
|
|
52
|
+
};
|
|
53
|
+
/** The index just past a template literal starting at `start` (its backquote). @param {number} start */
|
|
54
|
+
const template = (start) => {
|
|
55
|
+
let j = start + 1;
|
|
56
|
+
while (j < source.length) {
|
|
57
|
+
const c = source[j];
|
|
58
|
+
if (c === "\\") j += 2;
|
|
59
|
+
else if (c === "`") return j + 1;
|
|
60
|
+
else if (c === "$" && source[j + 1] === "{") {
|
|
61
|
+
let depth = 1;
|
|
62
|
+
j += 2;
|
|
63
|
+
while (j < source.length && depth > 0) {
|
|
64
|
+
const d = source[j];
|
|
65
|
+
if (d === "`") j = template(j);
|
|
66
|
+
else if (d === "'" || d === '"') j = quoted(j);
|
|
67
|
+
else {
|
|
68
|
+
if (d === "{") depth++;
|
|
69
|
+
else if (d === "}") depth--;
|
|
70
|
+
j++;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
} else j++;
|
|
74
|
+
}
|
|
75
|
+
return j;
|
|
76
|
+
};
|
|
77
|
+
/** The index just past a quoted string starting at `start`. @param {number} start */
|
|
78
|
+
const quoted = (start) => {
|
|
79
|
+
const q = source[start];
|
|
80
|
+
let j = start + 1;
|
|
81
|
+
while (j < source.length && source[j] !== q && source[j] !== "\n")
|
|
82
|
+
j += source[j] === "\\" ? 2 : 1;
|
|
83
|
+
return j + 1;
|
|
84
|
+
};
|
|
85
|
+
while (i < source.length) {
|
|
86
|
+
const c = source[i];
|
|
87
|
+
if (c === "\n") {
|
|
88
|
+
line++;
|
|
89
|
+
i++;
|
|
90
|
+
} else if (c === " " || c === "\t" || c === "\r") i++;
|
|
91
|
+
else if (c === "/" && source[i + 1] === "/") {
|
|
92
|
+
while (i < source.length && source[i] !== "\n") i++;
|
|
93
|
+
} else if (c === "/" && source[i + 1] === "*") {
|
|
94
|
+
const end = source.indexOf("*/", i + 2);
|
|
95
|
+
const stop = end === -1 ? source.length : end + 2;
|
|
96
|
+
lines(i, stop);
|
|
97
|
+
i = stop;
|
|
98
|
+
} else if (c === "'" || c === '"') {
|
|
99
|
+
const end = quoted(i);
|
|
100
|
+
out.push({ kind: "string", text: unquote(source.slice(i + 1, end - 1)), line });
|
|
101
|
+
i = end;
|
|
102
|
+
} else if (c === "`") {
|
|
103
|
+
const end = template(i);
|
|
104
|
+
out.push({ kind: "other", text: "`", line });
|
|
105
|
+
lines(i, end);
|
|
106
|
+
i = end;
|
|
107
|
+
} else if (c === "/" && (out.length === 0 || REGEX_AFTER.has(out[out.length - 1].text))) {
|
|
108
|
+
let j = i + 1;
|
|
109
|
+
let inClass = false;
|
|
110
|
+
while (j < source.length && source[j] !== "\n") {
|
|
111
|
+
if (source[j] === "\\") j++;
|
|
112
|
+
else if (source[j] === "[") inClass = true;
|
|
113
|
+
else if (source[j] === "]") inClass = false;
|
|
114
|
+
else if (source[j] === "/" && !inClass) break;
|
|
115
|
+
j++;
|
|
116
|
+
}
|
|
117
|
+
j++;
|
|
118
|
+
while (/[a-z]/.test(source[j] ?? "")) j++;
|
|
119
|
+
out.push({ kind: "other", text: "/re/", line });
|
|
120
|
+
i = j;
|
|
121
|
+
} else if (/[A-Za-z_$]/.test(c)) {
|
|
122
|
+
const m = /^[A-Za-z0-9_$]+/.exec(source.slice(i, i + 200));
|
|
123
|
+
const text = m ? m[0] : c;
|
|
124
|
+
out.push({ kind: "ident", text, line });
|
|
125
|
+
i += text.length;
|
|
126
|
+
} else if (c === "." && source.startsWith("...", i)) {
|
|
127
|
+
out.push({ kind: "punct", text: "...", line });
|
|
128
|
+
i += 3;
|
|
129
|
+
} else if (c === "=" && source[i + 1] === ">") {
|
|
130
|
+
out.push({ kind: "punct", text: "=>", line });
|
|
131
|
+
i += 2;
|
|
132
|
+
} else {
|
|
133
|
+
out.push({ kind: "punct", text: c, line });
|
|
134
|
+
i++;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
return out;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** A string literal's text with its simple escapes resolved. @param {string} text */
|
|
141
|
+
const unquote = (text) => text.replace(/\\(.)/g, "$1");
|
|
142
|
+
|
|
143
|
+
const OPEN = new Set(["(", "[", "{"]);
|
|
144
|
+
const CLOSE = new Set([")", "]", "}"]);
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* The entries of the object literal whose `{` is at `start`: each key, its line and where its value's
|
|
148
|
+
* tokens lie. A spread, a computed key, a shorthand or a method is an error: the names must be written out.
|
|
149
|
+
* @param {Token[]} tokens @param {number} start
|
|
150
|
+
* @returns {{ entries: { key: string, line: number, from: number, to: number }[], end: number } | { error: string, line: number }}
|
|
151
|
+
*/
|
|
152
|
+
function objectEntries(tokens, start) {
|
|
153
|
+
/** @type {{ key: string, line: number, from: number, to: number }[]} */
|
|
154
|
+
const entries = [];
|
|
155
|
+
let i = start + 1;
|
|
156
|
+
for (;;) {
|
|
157
|
+
const t = tokens[i];
|
|
158
|
+
if (!t) return { error: "the object is not closed", line: tokens[start].line };
|
|
159
|
+
if (t.text === "}") return { entries, end: i };
|
|
160
|
+
if (t.text === "...")
|
|
161
|
+
return { error: "spread (...) hides names: write each one out", line: t.line };
|
|
162
|
+
if (t.kind !== "ident" && t.kind !== "string")
|
|
163
|
+
return { error: `unexpected ${t.text}: write keys as names or strings`, line: t.line };
|
|
164
|
+
const colon = tokens[i + 1];
|
|
165
|
+
if (colon?.text !== ":")
|
|
166
|
+
return {
|
|
167
|
+
error: `${t.text}: write it as ${t.text}: <value>, not a shorthand or a method`,
|
|
168
|
+
line: t.line,
|
|
169
|
+
};
|
|
170
|
+
let j = i + 2;
|
|
171
|
+
let depth = 0;
|
|
172
|
+
for (; j < tokens.length; j++) {
|
|
173
|
+
const v = tokens[j].text;
|
|
174
|
+
if (OPEN.has(v)) depth++;
|
|
175
|
+
else if (CLOSE.has(v)) {
|
|
176
|
+
if (depth === 0) break;
|
|
177
|
+
depth--;
|
|
178
|
+
} else if (v === "," && depth === 0) break;
|
|
179
|
+
}
|
|
180
|
+
entries.push({ key: t.text, line: t.line, from: i + 2, to: j });
|
|
181
|
+
i = tokens[j]?.text === "," ? j + 1 : j;
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* What a workflow file declares, read without running it (docs/adr/0103): the column, the initial state, the
|
|
187
|
+
* state names and the action names, in the order written. An error says what to write out instead.
|
|
188
|
+
* @type {typeof import("./workflow.d.mts").readWorkflow}
|
|
189
|
+
*/
|
|
190
|
+
export function readWorkflow(source) {
|
|
191
|
+
const tokens = tokenize(source);
|
|
192
|
+
let start = -1;
|
|
193
|
+
for (let i = 0; i < tokens.length; i++) {
|
|
194
|
+
if (tokens[i].kind !== "ident" || tokens[i].text !== "workflow") continue;
|
|
195
|
+
let j = i + 1;
|
|
196
|
+
if (tokens[j]?.text === "<") {
|
|
197
|
+
let depth = 0;
|
|
198
|
+
for (; j < tokens.length; j++) {
|
|
199
|
+
if (tokens[j].text === "<") depth++;
|
|
200
|
+
else if (tokens[j].text === ">" && --depth === 0) break;
|
|
201
|
+
}
|
|
202
|
+
j++;
|
|
203
|
+
}
|
|
204
|
+
if (tokens[j]?.text === "(" && tokens[j + 1]?.text === "{") {
|
|
205
|
+
start = j + 1;
|
|
206
|
+
break;
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
if (start < 0)
|
|
210
|
+
return {
|
|
211
|
+
error: 'export default workflow<"<table>">({ column, initial, states, actions })',
|
|
212
|
+
line: 1,
|
|
213
|
+
};
|
|
214
|
+
const top = objectEntries(tokens, start);
|
|
215
|
+
if ("error" in top) return top;
|
|
216
|
+
/** @type {Record<string, { key: string, line: number, from: number, to: number }>} */
|
|
217
|
+
const fields = {};
|
|
218
|
+
for (const e of top.entries) fields[e.key] = e;
|
|
219
|
+
/** @param {string} name @returns {{ text: string } | { error: string, line: number }} */
|
|
220
|
+
const literal = (name) => {
|
|
221
|
+
const e = fields[name];
|
|
222
|
+
if (!e) return { error: `${name} is missing`, line: tokens[start].line };
|
|
223
|
+
const t = tokens[e.from];
|
|
224
|
+
if (e.to - e.from !== 1 || t.kind !== "string")
|
|
225
|
+
return { error: `${name} is written as a string literal ("...")`, line: e.line };
|
|
226
|
+
return { text: t.text };
|
|
227
|
+
};
|
|
228
|
+
/**
|
|
229
|
+
* @param {string} name
|
|
230
|
+
* @returns {{ names: string[], auto: Set<string> } | { error: string, line: number }}
|
|
231
|
+
*/
|
|
232
|
+
const keys = (name) => {
|
|
233
|
+
const e = fields[name];
|
|
234
|
+
if (!e) return { error: `${name} is missing`, line: tokens[start].line };
|
|
235
|
+
if (tokens[e.from]?.text !== "{")
|
|
236
|
+
return { error: `${name} is written out as an object literal ({ ... })`, line: e.line };
|
|
237
|
+
const inner = objectEntries(tokens, e.from);
|
|
238
|
+
if ("error" in inner) return inner;
|
|
239
|
+
// An entry written { ..., auto: true, ... } is an automatic action: no caller names it.
|
|
240
|
+
const auto = new Set(
|
|
241
|
+
inner.entries
|
|
242
|
+
.filter((x) => tokens[x.from]?.text === "{" && autoAt(tokens, x.from, x.to))
|
|
243
|
+
.map((x) => x.key),
|
|
244
|
+
);
|
|
245
|
+
return { names: inner.entries.map((x) => x.key), auto };
|
|
246
|
+
};
|
|
247
|
+
const column = literal("column");
|
|
248
|
+
if ("error" in column) return column;
|
|
249
|
+
const initial = literal("initial");
|
|
250
|
+
if ("error" in initial) return initial;
|
|
251
|
+
const states = keys("states");
|
|
252
|
+
if ("error" in states) return states;
|
|
253
|
+
const actions = keys("actions");
|
|
254
|
+
if ("error" in actions) return actions;
|
|
255
|
+
return {
|
|
256
|
+
column: column.text,
|
|
257
|
+
initial: initial.text,
|
|
258
|
+
states: states.names,
|
|
259
|
+
actions: actions.names.filter((a) => !actions.auto.has(a)),
|
|
260
|
+
automatic: actions.names.filter((a) => actions.auto.has(a)),
|
|
261
|
+
};
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* Whether the object literal between `from` (its `{`) and `to` says `auto: true` at its own level.
|
|
266
|
+
* @param {Token[]} tokens @param {number} from @param {number} to
|
|
267
|
+
*/
|
|
268
|
+
function autoAt(tokens, from, to) {
|
|
269
|
+
let depth = 0;
|
|
270
|
+
for (let i = from; i < to; i++) {
|
|
271
|
+
const t = tokens[i].text;
|
|
272
|
+
if (OPEN.has(t)) depth++;
|
|
273
|
+
else if (CLOSE.has(t)) depth--;
|
|
274
|
+
else if (
|
|
275
|
+
depth === 1 &&
|
|
276
|
+
t === "auto" &&
|
|
277
|
+
tokens[i + 1]?.text === ":" &&
|
|
278
|
+
(tokens[i - 1]?.text === "{" || tokens[i - 1]?.text === ",")
|
|
279
|
+
)
|
|
280
|
+
return tokens[i + 2]?.text === "true";
|
|
281
|
+
}
|
|
282
|
+
return false;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* The names every readable `workflows/<table>.ts` of a Global Workspace declares, by Table: what generated
|
|
287
|
+
* types need. A file that cannot be read is left out; `ez check` reports it.
|
|
288
|
+
* @type {typeof import("./workflow.d.mts").workflowShapes}
|
|
289
|
+
*/
|
|
290
|
+
export function workflowShapes(files) {
|
|
291
|
+
/** @type {Record<string, WorkflowShape>} */
|
|
292
|
+
const out = {};
|
|
293
|
+
for (const [path, source] of Object.entries(files)) {
|
|
294
|
+
const m = /^workflows\/([a-z][a-z0-9_]{0,62})\.ts$/.exec(path);
|
|
295
|
+
if (!m) continue;
|
|
296
|
+
const shape = readWorkflow(source);
|
|
297
|
+
if (!("error" in shape)) out[m[1]] = shape;
|
|
298
|
+
}
|
|
299
|
+
return out;
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
// ---- what the compiled file describes, checked against the schema --------------------------------------
|
|
303
|
+
|
|
304
|
+
/** @param {unknown} v @returns {v is Record<string, unknown>} */
|
|
305
|
+
const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
306
|
+
/** @param {unknown} v @returns {v is string[]} */
|
|
307
|
+
const isStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
|
|
308
|
+
|
|
309
|
+
/** A state's or an action's name, spaced and capitalised: `sample_due` -> "Sample due". @param {string} name */
|
|
310
|
+
export const labelOf = (name) => {
|
|
311
|
+
const spaced = name.replaceAll("_", " ");
|
|
312
|
+
return spaced.charAt(0).toUpperCase() + spaced.slice(1);
|
|
313
|
+
};
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* Checks what a compiled workflow describes (the artifact's `__describe`) against the published schema and
|
|
317
|
+
* returns its normalised form, or why a Push refuses it.
|
|
318
|
+
* @type {typeof import("./workflow.d.mts").checkWorkflow}
|
|
319
|
+
*/
|
|
320
|
+
export function checkWorkflow(table, raw, schema) {
|
|
321
|
+
const where = `global/workflows/${table}.ts`;
|
|
322
|
+
const def = schema.tables[table];
|
|
323
|
+
if (!def) return { error: `${where}: no Table "${table}" in db/schema.sql.` };
|
|
324
|
+
if (!isObject(raw)) return { error: `${where}: export default workflow<"${table}">({ ... }).` };
|
|
325
|
+
const { column, initial, states, actions } = raw;
|
|
326
|
+
if (typeof column !== "string" || !Object.hasOwn(def.columns, column))
|
|
327
|
+
return { error: `${where}: column "${String(column)}" is not a column of ${table}.` };
|
|
328
|
+
const col = def.columns[column];
|
|
329
|
+
if (col.type !== "TEXT" || col.ref || col.sequence)
|
|
330
|
+
return { error: `${where}: ${table}.${column} must be a plain TEXT column to hold a state.` };
|
|
331
|
+
if (!isObject(states) || Object.keys(states).length === 0)
|
|
332
|
+
return { error: `${where}: states names at least one state.` };
|
|
333
|
+
const names = Object.keys(states);
|
|
334
|
+
if (names.length > WORKFLOW_LIMITS.states)
|
|
335
|
+
return { error: `${where}: at most ${WORKFLOW_LIMITS.states} states.` };
|
|
336
|
+
/** @type {WorkflowMeta["states"]} */
|
|
337
|
+
const outStates = {};
|
|
338
|
+
for (const name of names) {
|
|
339
|
+
if (!NAME_RE.test(name))
|
|
340
|
+
return {
|
|
341
|
+
error: `${where}: state "${name}": lowercase letters, digits and _, starting with a letter.`,
|
|
342
|
+
};
|
|
343
|
+
if (col.values && !col.values.includes(name))
|
|
344
|
+
return {
|
|
345
|
+
error: `${where}: state "${name}" is not one of ${table}.${column}'s CHECK values (${col.values.join(", ")}).`,
|
|
346
|
+
};
|
|
347
|
+
const s = states[name];
|
|
348
|
+
if (s !== undefined && s !== null && !isObject(s))
|
|
349
|
+
return { error: `${where}: state "${name}" is { label?, tone? }.` };
|
|
350
|
+
const label = s?.label;
|
|
351
|
+
const tone = s?.tone;
|
|
352
|
+
if (label !== undefined && (typeof label !== "string" || !label.trim()))
|
|
353
|
+
return { error: `${where}: state "${name}": label is a non-empty string.` };
|
|
354
|
+
if (tone !== undefined && !WORKFLOW_TONES.includes(/** @type {never} */ (tone)))
|
|
355
|
+
return { error: `${where}: state "${name}": tone is one of ${WORKFLOW_TONES.join(", ")}.` };
|
|
356
|
+
outStates[name] = {
|
|
357
|
+
label: typeof label === "string" ? label : labelOf(name),
|
|
358
|
+
tone: /** @type {WorkflowMeta["states"][string]["tone"]} */ (tone ?? null),
|
|
359
|
+
};
|
|
360
|
+
}
|
|
361
|
+
if (typeof initial !== "string" || !names.includes(initial))
|
|
362
|
+
return { error: `${where}: initial "${String(initial)}" is not one of its states.` };
|
|
363
|
+
if (col.default && !(col.default.kind === "value" && col.default.value === initial))
|
|
364
|
+
return {
|
|
365
|
+
error: `${where}: ${table}.${column} has a DEFAULT other than the initial state; remove it.`,
|
|
366
|
+
};
|
|
367
|
+
if (!isObject(actions)) return { error: `${where}: actions is an object of actions.` };
|
|
368
|
+
if (Object.keys(actions).length > WORKFLOW_LIMITS.actions)
|
|
369
|
+
return { error: `${where}: at most ${WORKFLOW_LIMITS.actions} actions.` };
|
|
370
|
+
/** @type {WorkflowMeta["actions"]} */
|
|
371
|
+
const outActions = {};
|
|
372
|
+
for (const [name, a] of Object.entries(actions)) {
|
|
373
|
+
const at = `${where}: action "${name}"`;
|
|
374
|
+
if (!NAME_RE.test(name))
|
|
375
|
+
return { error: `${at}: lowercase letters, digits and _, starting with a letter.` };
|
|
376
|
+
if (!isObject(a)) return { error: `${at} is { from, to, ... }.` };
|
|
377
|
+
if (!isStrings(a.from) || a.from.length === 0)
|
|
378
|
+
return { error: `${at}: from lists the states it runs from.` };
|
|
379
|
+
for (const f of a.from)
|
|
380
|
+
if (f !== WORKFLOW_NEW && !names.includes(f))
|
|
381
|
+
return { error: `${at}: from "${f}" is not a state (or "${WORKFLOW_NEW}").` };
|
|
382
|
+
if (typeof a.to !== "string" || (a.to !== WORKFLOW_PREVIOUS && !names.includes(a.to)))
|
|
383
|
+
return { error: `${at}: to "${String(a.to)}" is not a state (or "${WORKFLOW_PREVIOUS}").` };
|
|
384
|
+
if (a.to === WORKFLOW_PREVIOUS && a.from.includes(WORKFLOW_NEW))
|
|
385
|
+
return { error: `${at}: a new row has no previous state; name the state it starts in.` };
|
|
386
|
+
if (a.label !== undefined && (typeof a.label !== "string" || !a.label.trim()))
|
|
387
|
+
return { error: `${at}: label is a non-empty string.` };
|
|
388
|
+
const groups = a.groups ?? [];
|
|
389
|
+
if (!isStrings(groups) || groups.some((g) => !/^[a-z][a-z0-9-]{0,39}$/.test(g)))
|
|
390
|
+
return { error: `${at}: groups lists roster group names.` };
|
|
391
|
+
const auto = a.auto === true;
|
|
392
|
+
/** @type {Record<string, string>} */
|
|
393
|
+
const children = {};
|
|
394
|
+
if (auto) {
|
|
395
|
+
if (groups.length)
|
|
396
|
+
return { error: `${at}: an automatic action has no groups; the Host runs it.` };
|
|
397
|
+
if (a.from.includes(WORKFLOW_NEW))
|
|
398
|
+
return { error: `${at}: an automatic action follows children; it cannot start a row.` };
|
|
399
|
+
if (a.to === WORKFLOW_PREVIOUS)
|
|
400
|
+
return { error: `${at}: an automatic action goes to a named state.` };
|
|
401
|
+
if (a.when !== true)
|
|
402
|
+
return { error: `${at}: an automatic action needs when({ row, children }).` };
|
|
403
|
+
if (!isObject(a.children) || Object.keys(a.children).length === 0)
|
|
404
|
+
return { error: `${at}: an automatic action names its children: { <table>: "<column>" }.` };
|
|
405
|
+
for (const [child, c] of Object.entries(a.children)) {
|
|
406
|
+
const cdef = schema.tables[child];
|
|
407
|
+
if (!cdef) return { error: `${at}: children "${child}" is not a Table.` };
|
|
408
|
+
if (typeof c !== "string" || cdef.columns[c]?.ref !== table)
|
|
409
|
+
return {
|
|
410
|
+
error: `${at}: ${child}.${String(c)} is not a column that REFERENCES ${table}.`,
|
|
411
|
+
};
|
|
412
|
+
children[child] = c;
|
|
413
|
+
}
|
|
414
|
+
} else if (a.when === true || a.children !== undefined)
|
|
415
|
+
return { error: `${at}: children and when belong to an automatic action (auto: true).` };
|
|
416
|
+
outActions[name] = {
|
|
417
|
+
label: typeof a.label === "string" ? a.label : labelOf(name),
|
|
418
|
+
from: [...a.from],
|
|
419
|
+
to: a.to,
|
|
420
|
+
groups: [...groups],
|
|
421
|
+
guard: a.guard === true,
|
|
422
|
+
auto,
|
|
423
|
+
...(auto ? { children } : {}),
|
|
424
|
+
};
|
|
425
|
+
}
|
|
426
|
+
return { workflow: { column, initial, states: outStates, actions: outActions } };
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/**
|
|
430
|
+
* Whether what a file says (`readWorkflow`) is what it describes when it runs: the names the contract typed
|
|
431
|
+
* the column with are the ones the Host enforces.
|
|
432
|
+
* @type {typeof import("./workflow.d.mts").sameNames}
|
|
433
|
+
*/
|
|
434
|
+
export function sameNames(shape, meta) {
|
|
435
|
+
const same = (/** @type {string[]} */ a, /** @type {string[]} */ b) =>
|
|
436
|
+
a.length === b.length && a.every((x, i) => x === b[i]);
|
|
437
|
+
return (
|
|
438
|
+
shape.column === meta.column &&
|
|
439
|
+
shape.initial === meta.initial &&
|
|
440
|
+
same(shape.states, Object.keys(meta.states)) &&
|
|
441
|
+
same(
|
|
442
|
+
shape.actions,
|
|
443
|
+
Object.keys(meta.actions).filter((a) => !meta.actions[a].auto),
|
|
444
|
+
) &&
|
|
445
|
+
same(
|
|
446
|
+
shape.automatic,
|
|
447
|
+
Object.keys(meta.actions).filter((a) => meta.actions[a].auto),
|
|
448
|
+
)
|
|
449
|
+
);
|
|
450
|
+
}
|