@vizejs/plugin-sdk 0.716.0 → 0.718.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/facts.d.ts +38 -0
- package/fixes.d.ts +1 -0
- package/index.d.ts +9 -0
- package/package.json +2 -2
- package/sandbox.d.ts +7 -0
- package/stages.d.ts +15 -0
- package/visitor.d.ts +31 -0
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @vizejs/plugin-sdk
|
|
2
2
|
|
|
3
3
|
Author synchronous rules, fact providers, native template transforms and compiled
|
|
4
|
-
output hooks. Install `@vizejs/native` **0.
|
|
4
|
+
output hooks. Install `@vizejs/native` **0.718.0 or newer** to execute plugins.
|
|
5
5
|
The optional native peer lets this package install independently for authoring;
|
|
6
6
|
its helpers alone do not compile or lint Vue files. Node 22 or newer is required.
|
|
7
7
|
|
package/facts.d.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
|
+
/** Template binding name and the position that introduced it. */
|
|
1
2
|
export interface TemplateScopeEntry {
|
|
2
3
|
readonly name: string;
|
|
3
4
|
readonly position: "value" | "key" | "index" | "slot";
|
|
4
5
|
}
|
|
6
|
+
/** Host classification for a script binding exposed to plugin facts. */
|
|
5
7
|
export type BindingKind =
|
|
6
8
|
| "setup-let"
|
|
7
9
|
| "setup-maybe-ref"
|
|
@@ -20,6 +22,7 @@ export type BindingKind =
|
|
|
20
22
|
| "js-global-bun"
|
|
21
23
|
| "vue-global"
|
|
22
24
|
| "external-module";
|
|
25
|
+
/** Script-setup marker or resolved classification for one binding. */
|
|
23
26
|
export type BindingFact =
|
|
24
27
|
| Readonly<{ scriptSetup: true }>
|
|
25
28
|
| Readonly<{
|
|
@@ -27,39 +30,47 @@ export type BindingFact =
|
|
|
27
30
|
span: readonly [number, number] | null;
|
|
28
31
|
propKey: string | null;
|
|
29
32
|
}>;
|
|
33
|
+
/** Unresolved template reference and its authored byte offset. */
|
|
30
34
|
export interface UndefinedRefFact {
|
|
31
35
|
readonly name: string;
|
|
32
36
|
readonly offset: number;
|
|
33
37
|
readonly context: string;
|
|
34
38
|
}
|
|
39
|
+
/** Authored byte span for a binding with no observed reads. */
|
|
35
40
|
export interface UnusedBindingFact {
|
|
36
41
|
readonly span: readonly [number, number];
|
|
37
42
|
}
|
|
43
|
+
/** Half-open UTF-8 byte range shared by source-backed facts. */
|
|
38
44
|
export interface FactRange {
|
|
39
45
|
readonly start: number;
|
|
40
46
|
readonly end: number;
|
|
41
47
|
}
|
|
48
|
+
/** One component prop occurrence, including dynamic-name and value state. */
|
|
42
49
|
export interface ComponentPropUsage extends FactRange {
|
|
43
50
|
readonly name: string;
|
|
44
51
|
readonly nameIsDynamic: boolean;
|
|
45
52
|
readonly value: string | null;
|
|
46
53
|
readonly isDynamic: boolean;
|
|
47
54
|
}
|
|
55
|
+
/** One component event-handler occurrence and its modifiers. */
|
|
48
56
|
export interface ComponentEventUsage extends FactRange {
|
|
49
57
|
readonly name: string;
|
|
50
58
|
readonly nameIsDynamic: boolean;
|
|
51
59
|
readonly handler: string | null;
|
|
52
60
|
readonly modifiers: readonly string[];
|
|
53
61
|
}
|
|
62
|
+
/** One component slot occurrence and its introduced scope variables. */
|
|
54
63
|
export interface ComponentSlotUsage extends FactRange {
|
|
55
64
|
readonly name: string;
|
|
56
65
|
readonly nameIsDynamic: boolean;
|
|
57
66
|
readonly scopeVars: readonly string[];
|
|
58
67
|
readonly hasScope: boolean;
|
|
59
68
|
}
|
|
69
|
+
/** One spread-prop expression applied to a component. */
|
|
60
70
|
export interface ComponentSpreadUsage extends FactRange {
|
|
61
71
|
readonly expression: string;
|
|
62
72
|
}
|
|
73
|
+
/** Complete normalized usage of one component node. */
|
|
63
74
|
export interface ComponentUsage extends FactRange {
|
|
64
75
|
readonly name: string;
|
|
65
76
|
readonly props: readonly ComponentPropUsage[];
|
|
@@ -70,19 +81,24 @@ export interface ComponentUsage extends FactRange {
|
|
|
70
81
|
readonly scopeId: number;
|
|
71
82
|
readonly vifGuard: string | null;
|
|
72
83
|
}
|
|
84
|
+
/** Resolved component tag paired with its optional usage record. */
|
|
73
85
|
export interface ComponentUsageSite {
|
|
74
86
|
readonly tag: string;
|
|
75
87
|
readonly usage: ComponentUsage | null;
|
|
76
88
|
readonly usageIndex: number | null;
|
|
77
89
|
readonly nameOrdinal: number | null;
|
|
78
90
|
}
|
|
91
|
+
/** Import/export identity and every observed site for one component. */
|
|
79
92
|
export interface ComponentUsagesFact {
|
|
80
93
|
readonly module: string | null;
|
|
81
94
|
readonly export: string;
|
|
82
95
|
readonly sites: readonly ComponentUsageSite[];
|
|
83
96
|
}
|
|
97
|
+
/** Stability class inferred for a reactive source. */
|
|
84
98
|
export type ReactivityClass = "static" | "props-stable" | "reactive" | "unstable";
|
|
99
|
+
/** Confidence verdict attached to an inferred contract. */
|
|
85
100
|
export type Verdict = "proven" | "refuted" | "unknown";
|
|
101
|
+
/** Effect that contributes to a reactive stability verdict. */
|
|
86
102
|
export type ReactivityEffect =
|
|
87
103
|
| "freeze"
|
|
88
104
|
| "capture"
|
|
@@ -92,6 +108,7 @@ export type ReactivityEffect =
|
|
|
92
108
|
| "mutate-global"
|
|
93
109
|
| "call-unknown"
|
|
94
110
|
| "allocate";
|
|
111
|
+
/** Vue API that created a reactive source. */
|
|
95
112
|
export type ReactiveSourceKind =
|
|
96
113
|
| "ref"
|
|
97
114
|
| "shallow-ref"
|
|
@@ -102,6 +119,7 @@ export type ReactiveSourceKind =
|
|
|
102
119
|
| "shallow-readonly"
|
|
103
120
|
| "to-ref"
|
|
104
121
|
| "to-refs";
|
|
122
|
+
/** Authored operation that loses or obscures reactive ownership. */
|
|
105
123
|
export type ReactivityLoss =
|
|
106
124
|
| Readonly<{
|
|
107
125
|
kind: "reactive-destructure" | "ref-value-destructure";
|
|
@@ -137,6 +155,7 @@ export type ReactivityLoss =
|
|
|
137
155
|
targetName: string;
|
|
138
156
|
}>
|
|
139
157
|
| Readonly<{ kind: "reactive-spread" | "reactive-reassign"; sourceName: string }>;
|
|
158
|
+
/** Reactive source classification or a detected reactivity-loss site. */
|
|
140
159
|
export type ReactivityFact =
|
|
141
160
|
| Readonly<{
|
|
142
161
|
kind: "source";
|
|
@@ -154,14 +173,17 @@ export type ReactivityFact =
|
|
|
154
173
|
end: number;
|
|
155
174
|
}>;
|
|
156
175
|
|
|
176
|
+
/** Normalized string or symbol key used by provide/inject. */
|
|
157
177
|
export interface ProvideKey {
|
|
158
178
|
readonly kind: "string" | "symbol";
|
|
159
179
|
readonly name: string;
|
|
160
180
|
}
|
|
181
|
+
/** Shape through which an injected value is consumed. */
|
|
161
182
|
export type InjectPattern =
|
|
162
183
|
| Readonly<{ kind: "simple" }>
|
|
163
184
|
| Readonly<{ kind: "object" | "array"; props: readonly string[] }>
|
|
164
185
|
| Readonly<{ kind: "indirect"; injectVar: string; props: readonly string[]; offset: number }>;
|
|
186
|
+
/** Provide, inject, or composable-boundary fact from one source file. */
|
|
165
187
|
export type ProvideInjectFact =
|
|
166
188
|
| Readonly<{
|
|
167
189
|
kind: "provide";
|
|
@@ -196,6 +218,7 @@ export type ProvideInjectFact =
|
|
|
196
218
|
end: number;
|
|
197
219
|
}>;
|
|
198
220
|
|
|
221
|
+
/** Async scheduling pattern that may race with a later mutation. */
|
|
199
222
|
export type RaceRisk =
|
|
200
223
|
| Readonly<{
|
|
201
224
|
kind: "async-watcher";
|
|
@@ -215,10 +238,12 @@ export type RaceRisk =
|
|
|
215
238
|
mutatedTargets: readonly string[];
|
|
216
239
|
}>
|
|
217
240
|
| Readonly<{ kind: "scheduled"; schedulerName: string; mutatedTargets: readonly string[] }>;
|
|
241
|
+
/** Source-backed asynchronous race-risk observation. */
|
|
218
242
|
export interface RaceConditionFact extends FactRange {
|
|
219
243
|
readonly kind: RaceRisk;
|
|
220
244
|
}
|
|
221
245
|
|
|
246
|
+
/** Closed reason why complete public type information was unavailable. */
|
|
222
247
|
export type UnresolvedTypeReason =
|
|
223
248
|
| "external-world-unavailable"
|
|
224
249
|
| "unbound"
|
|
@@ -229,6 +254,7 @@ export type UnresolvedTypeReason =
|
|
|
229
254
|
| "ambiguous-export"
|
|
230
255
|
| "resolution-cycle"
|
|
231
256
|
| "resolution-limit";
|
|
257
|
+
/** Authored or resolved dependency reachable from a public type. */
|
|
232
258
|
export interface TypeDependency {
|
|
233
259
|
readonly name: string;
|
|
234
260
|
readonly kind: "alias" | "interface" | "imported" | "unresolved";
|
|
@@ -240,15 +266,18 @@ export interface TypeDependency {
|
|
|
240
266
|
readonly extends: readonly string[];
|
|
241
267
|
readonly unresolved_reason: UnresolvedTypeReason | null;
|
|
242
268
|
}
|
|
269
|
+
/** Resolution state and dependencies for a public type contract. */
|
|
243
270
|
export interface TypeEnvironment {
|
|
244
271
|
/** False means some reachable type information could not be resolved. */
|
|
245
272
|
readonly complete: boolean;
|
|
246
273
|
readonly declarations: readonly TypeDependency[];
|
|
247
274
|
}
|
|
275
|
+
/** Name and optional type for a value exposed from a component instance. */
|
|
248
276
|
export interface ExposeContract {
|
|
249
277
|
readonly name: string;
|
|
250
278
|
readonly type: string | null;
|
|
251
279
|
}
|
|
280
|
+
/** Complete public component signature discovered from authored source. */
|
|
252
281
|
export interface SignatureContract {
|
|
253
282
|
readonly schema: 1;
|
|
254
283
|
readonly name: string;
|
|
@@ -268,6 +297,7 @@ export interface SignatureContract {
|
|
|
268
297
|
readonly exposes: readonly ExposeContract[];
|
|
269
298
|
readonly type_dependencies: TypeEnvironment;
|
|
270
299
|
}
|
|
300
|
+
/** Resolved public prop type, requirement, default, and dependencies. */
|
|
271
301
|
export interface PropContract {
|
|
272
302
|
readonly schema: 1;
|
|
273
303
|
readonly name: string;
|
|
@@ -277,6 +307,7 @@ export interface PropContract {
|
|
|
277
307
|
readonly model_modifiers: string | null;
|
|
278
308
|
readonly type_dependencies: TypeEnvironment;
|
|
279
309
|
}
|
|
310
|
+
/** Resolved public event payloads, validators, and dependencies. */
|
|
280
311
|
export interface EmitContract {
|
|
281
312
|
readonly schema: 1;
|
|
282
313
|
readonly name: string;
|
|
@@ -287,12 +318,14 @@ export interface EmitContract {
|
|
|
287
318
|
readonly validator_type_annotations: readonly string[];
|
|
288
319
|
readonly type_dependencies: TypeEnvironment;
|
|
289
320
|
}
|
|
321
|
+
/** Resolved public slot props and their type dependencies. */
|
|
290
322
|
export interface SlotContract {
|
|
291
323
|
readonly schema: 1;
|
|
292
324
|
readonly name: string;
|
|
293
325
|
readonly props: string | null;
|
|
294
326
|
readonly type_dependencies: TypeEnvironment;
|
|
295
327
|
}
|
|
328
|
+
/** Public spelling of a supported Vue reactive constructor. */
|
|
296
329
|
export type AlphaReactiveKind =
|
|
297
330
|
| "ref"
|
|
298
331
|
| "shallowRef"
|
|
@@ -303,6 +336,7 @@ export type AlphaReactiveKind =
|
|
|
303
336
|
| "shallowReadonly"
|
|
304
337
|
| "toRef"
|
|
305
338
|
| "toRefs";
|
|
339
|
+
/** Public reactivity contract for one component binding. */
|
|
306
340
|
export interface ReactivityContract {
|
|
307
341
|
readonly schema: 1;
|
|
308
342
|
readonly name: string;
|
|
@@ -313,6 +347,7 @@ export interface ReactivityContract {
|
|
|
313
347
|
readonly effects: readonly ReactivityEffect[];
|
|
314
348
|
readonly type_dependencies: TypeEnvironment;
|
|
315
349
|
}
|
|
350
|
+
/** Module and export identity for a component dependency. */
|
|
316
351
|
export interface ComponentContract {
|
|
317
352
|
readonly schema: 1;
|
|
318
353
|
readonly module: string | null;
|
|
@@ -341,8 +376,11 @@ export interface FactGroups {
|
|
|
341
376
|
readonly "reactivity-classes": ReadonlyMap<string, ReactivityContract>;
|
|
342
377
|
readonly "component-references": ReadonlyMap<string, ComponentContract>;
|
|
343
378
|
}
|
|
379
|
+
/** Key type used by one named host fact group. */
|
|
344
380
|
export type FactKey<K extends keyof FactGroups> =
|
|
345
381
|
FactGroups[K] extends ReadonlyMap<infer Key, unknown> ? Key : never;
|
|
382
|
+
/** Value type used by one named host fact group. */
|
|
346
383
|
export type FactValue<K extends keyof FactGroups> =
|
|
347
384
|
FactGroups[K] extends ReadonlyMap<unknown, infer Value> ? Value : never;
|
|
385
|
+
/** Serialized key/value entry used by one named host fact group. */
|
|
348
386
|
export type FactEntry<K extends keyof FactGroups> = readonly [FactKey<K>, FactValue<K>];
|
package/fixes.d.ts
CHANGED
package/index.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { FactGroups } from "./facts.js";
|
|
2
2
|
|
|
3
|
+
/** Schema version accepted by rule-plugin batch payloads. */
|
|
3
4
|
export declare const BATCH_SCHEMA: 1;
|
|
5
|
+
/** Host-owned syntax node exposed to deterministic rule plugins. */
|
|
4
6
|
export interface PluginNode {
|
|
5
7
|
readonly id: number;
|
|
6
8
|
readonly parent?: number;
|
|
@@ -14,10 +16,12 @@ export interface PluginNode {
|
|
|
14
16
|
readonly index: string | null;
|
|
15
17
|
};
|
|
16
18
|
}
|
|
19
|
+
/** Template binding visible at a node and the role that introduced it. */
|
|
17
20
|
export interface ScopeEntry {
|
|
18
21
|
readonly name: string;
|
|
19
22
|
readonly position: "value" | "key" | "index" | "slot";
|
|
20
23
|
}
|
|
24
|
+
/** Read-only host facts and reporting operations available to one rule. */
|
|
21
25
|
export interface RuleContext {
|
|
22
26
|
readonly nodes: readonly PluginNode[];
|
|
23
27
|
facts(name: "templateScopes"): ReadonlyMap<number, readonly ScopeEntry[]>;
|
|
@@ -27,6 +31,7 @@ export interface RuleContext {
|
|
|
27
31
|
/** Replace the whole reported node span; ranges are assigned by the host. */
|
|
28
32
|
report(node: PluginNode, message: string, fix?: string): void;
|
|
29
33
|
}
|
|
34
|
+
/** Authored rule-plugin definition before normalization and fingerprinting. */
|
|
30
35
|
export interface PluginDefinition {
|
|
31
36
|
name: string;
|
|
32
37
|
version: string;
|
|
@@ -44,6 +49,7 @@ export interface Plugin extends Omit<PluginDefinition, "visit" | "demands" | "ca
|
|
|
44
49
|
readonly fingerprint: string;
|
|
45
50
|
run(batchJson: string): string;
|
|
46
51
|
}
|
|
52
|
+
/** Serializable syntax and fact payload delivered to a rule plugin. */
|
|
47
53
|
export interface VisitBatch {
|
|
48
54
|
schema: 1;
|
|
49
55
|
plugin?: string;
|
|
@@ -52,12 +58,15 @@ export interface VisitBatch {
|
|
|
52
58
|
nodes: PluginNode[];
|
|
53
59
|
facts: Record<string, Array<[string | number, unknown]>>;
|
|
54
60
|
}
|
|
61
|
+
/** Validate, freeze, and fingerprint an authored rule-plugin definition. */
|
|
55
62
|
export declare function definePlugin(definition: PluginDefinition): Plugin;
|
|
63
|
+
/** Run a normalized plugin against a serialized visit batch. */
|
|
56
64
|
export declare function runBatch(
|
|
57
65
|
plugin: Plugin,
|
|
58
66
|
batch: VisitBatch,
|
|
59
67
|
): Array<{ rule: string; node: number; message: string; fix?: string }>;
|
|
60
68
|
|
|
69
|
+
/** Run every rule against an already decoded host source. */
|
|
61
70
|
export declare function runRules(
|
|
62
71
|
plugin: Plugin,
|
|
63
72
|
source: {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vizejs/plugin-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.718.0",
|
|
4
4
|
"description": "Deterministic authoring and isolated execution for Vize JavaScript plugins",
|
|
5
5
|
"homepage": "https://github.com/ubugeeei-prod/vize",
|
|
6
6
|
"bugs": {
|
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
"access": "public"
|
|
54
54
|
},
|
|
55
55
|
"devDependencies": {
|
|
56
|
-
"@vizejs/native": "0.
|
|
56
|
+
"@vizejs/native": "0.718.0"
|
|
57
57
|
},
|
|
58
58
|
"peerDependencies": {
|
|
59
59
|
"@vizejs/native": ">=0.429.0"
|
package/sandbox.d.ts
CHANGED
|
@@ -4,17 +4,20 @@ import type { NativeHook, JsonValue, HookIdentity } from "./stages.js";
|
|
|
4
4
|
* Closures and host imports are unavailable; process access stays in the container.
|
|
5
5
|
*/
|
|
6
6
|
export type CallbackSource = string;
|
|
7
|
+
/** Stable hook identity and captured inputs accepted by the sandbox boundary. */
|
|
7
8
|
export interface SandboxIdentity extends HookIdentity {
|
|
8
9
|
visit?: readonly string[];
|
|
9
10
|
demands?: readonly string[];
|
|
10
11
|
configuration?: JsonValue;
|
|
11
12
|
}
|
|
13
|
+
/** Rule, provider, transform, formatter, or output hook executable in isolation. */
|
|
12
14
|
export type SandboxDefinition = SandboxIdentity &
|
|
13
15
|
(
|
|
14
16
|
| { family?: "rule"; rules: Readonly<Record<string, CallbackSource>> }
|
|
15
17
|
| { family: "provider"; provides: readonly string[]; callback: CallbackSource }
|
|
16
18
|
| { family: "transform" | "formatter" | "output"; callback: CallbackSource }
|
|
17
19
|
);
|
|
20
|
+
/** Per-invocation time and serialized-byte limits for a sandbox process. */
|
|
18
21
|
export interface SandboxLimits {
|
|
19
22
|
/** 100..60000 ms; default 5000. Runtime check and cleanup each add at most 5000 ms. */
|
|
20
23
|
timeoutMs?: number;
|
|
@@ -27,6 +30,7 @@ export interface SandboxLimits {
|
|
|
27
30
|
* Runtime filesystem contents remain readable. Native callbacks are trusted.
|
|
28
31
|
*/
|
|
29
32
|
export type SandboxHook = NativeHook & { readonly visit?: string[]; readonly demands?: string[] };
|
|
33
|
+
/** Validate a sandbox definition and create its isolated native-hook adapter. */
|
|
30
34
|
export declare function createSandboxRunner(
|
|
31
35
|
definition: SandboxIdentity & {
|
|
32
36
|
family: "provider";
|
|
@@ -43,6 +47,7 @@ export declare function createSandboxRunner(
|
|
|
43
47
|
definition: SandboxDefinition,
|
|
44
48
|
limits?: SandboxLimits,
|
|
45
49
|
): SandboxHook;
|
|
50
|
+
/** Stable failure code reported by the sandbox runtime boundary. */
|
|
46
51
|
export type SandboxErrorCode =
|
|
47
52
|
| "runtime_unavailable"
|
|
48
53
|
| "execution_stopped"
|
|
@@ -57,10 +62,12 @@ export interface SandboxExecutionObservation {
|
|
|
57
62
|
readonly stdout: string | null;
|
|
58
63
|
readonly stderr: string | null;
|
|
59
64
|
}
|
|
65
|
+
/** Runtime failure with a stable code and optional partial execution evidence. */
|
|
60
66
|
export declare class SandboxRuntimeError extends Error {
|
|
61
67
|
readonly code: SandboxErrorCode;
|
|
62
68
|
/** Frozen and non-enumerable; the request and environment are not copied into it. */
|
|
63
69
|
readonly execution?: SandboxExecutionObservation;
|
|
64
70
|
constructor(code: SandboxErrorCode, message: string, options?: ErrorOptions);
|
|
65
71
|
}
|
|
72
|
+
/** Immutable container image reference required by sandbox runners. */
|
|
66
73
|
export declare const SANDBOX_IMAGE: string;
|
package/stages.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
/** JSON-compatible value accepted across plugin process boundaries. */
|
|
1
2
|
export type JsonValue =
|
|
2
3
|
| null
|
|
3
4
|
| boolean
|
|
@@ -5,6 +6,7 @@ export type JsonValue =
|
|
|
5
6
|
| string
|
|
6
7
|
| readonly JsonValue[]
|
|
7
8
|
| { readonly [key: string]: JsonValue };
|
|
9
|
+
/** Authored hook identity and every input captured by its fingerprint. */
|
|
8
10
|
export interface HookIdentity {
|
|
9
11
|
name: string;
|
|
10
12
|
version: string;
|
|
@@ -16,6 +18,7 @@ export interface NativeHook extends Omit<HookIdentity, "cacheInputs"> {
|
|
|
16
18
|
readonly fingerprint: string;
|
|
17
19
|
run(batchJson: string): string;
|
|
18
20
|
}
|
|
21
|
+
/** Precanonical element and attribute payload delivered to transform hooks. */
|
|
19
22
|
export interface StaticAttributeTransformBatch {
|
|
20
23
|
readonly schema: 1;
|
|
21
24
|
readonly stage: "s2-precanonical-static-attributes";
|
|
@@ -29,6 +32,7 @@ export interface StaticAttributeTransformBatch {
|
|
|
29
32
|
readonly attrs: readonly { readonly name: string; readonly value: string | null }[];
|
|
30
33
|
}[];
|
|
31
34
|
}
|
|
35
|
+
/** Static attribute names that a precanonical transform may replace. */
|
|
32
36
|
export type StaticAttributeName =
|
|
33
37
|
| "class"
|
|
34
38
|
| "id"
|
|
@@ -37,17 +41,20 @@ export type StaticAttributeName =
|
|
|
37
41
|
| "alt"
|
|
38
42
|
| `data-${string}`
|
|
39
43
|
| `aria-${string}`;
|
|
44
|
+
/** Deterministic replacement for one static element attribute. */
|
|
40
45
|
export interface StaticAttributeEdit {
|
|
41
46
|
kind: "replace-static-attribute";
|
|
42
47
|
node: number;
|
|
43
48
|
name: StaticAttributeName;
|
|
44
49
|
value: string | null;
|
|
45
50
|
}
|
|
51
|
+
/** Validate and fingerprint a static-attribute transform hook. */
|
|
46
52
|
export declare function defineTransformPlugin(
|
|
47
53
|
definition: HookIdentity & {
|
|
48
54
|
transform(batch: StaticAttributeTransformBatch): readonly StaticAttributeEdit[];
|
|
49
55
|
},
|
|
50
56
|
): NativeHook;
|
|
57
|
+
/** Compiled module output visible to formatter and output hooks. */
|
|
51
58
|
export interface CompiledArtifact {
|
|
52
59
|
readonly code: string;
|
|
53
60
|
readonly preamble: string;
|
|
@@ -56,6 +63,7 @@ export interface CompiledArtifact {
|
|
|
56
63
|
readonly helpers: readonly string[];
|
|
57
64
|
readonly templates?: readonly string[] | null;
|
|
58
65
|
}
|
|
66
|
+
/** Shared host payload delivered after compilation. */
|
|
59
67
|
export interface OutputBatch {
|
|
60
68
|
readonly schema: 1;
|
|
61
69
|
readonly plugin: string;
|
|
@@ -63,21 +71,26 @@ export interface OutputBatch {
|
|
|
63
71
|
readonly offsetEncoding: "utf8";
|
|
64
72
|
readonly compiled: CompiledArtifact;
|
|
65
73
|
}
|
|
74
|
+
/** UTF-8 replacement emitted by a formatter hook. */
|
|
66
75
|
export interface FormatEdit {
|
|
67
76
|
start: number;
|
|
68
77
|
end: number;
|
|
69
78
|
text: string;
|
|
70
79
|
}
|
|
80
|
+
/** Comment-only addition emitted before or after compiled code. */
|
|
71
81
|
export interface OutputAddition {
|
|
72
82
|
placement: "prepend" | "append";
|
|
73
83
|
comment: string;
|
|
74
84
|
}
|
|
85
|
+
/** Post-compilation payload specialized for formatter hooks. */
|
|
75
86
|
export interface FormatterBatch extends OutputBatch {
|
|
76
87
|
readonly family: "formatter";
|
|
77
88
|
}
|
|
89
|
+
/** Post-compilation payload specialized for output hooks. */
|
|
78
90
|
export interface OutputHookBatch extends OutputBatch {
|
|
79
91
|
readonly family: "output";
|
|
80
92
|
}
|
|
93
|
+
/** Validate and fingerprint a formatter or output hook. */
|
|
81
94
|
export declare function defineOutputPlugin(
|
|
82
95
|
definition: HookIdentity & {
|
|
83
96
|
family: "formatter";
|
|
@@ -90,6 +103,7 @@ export declare function defineOutputPlugin(
|
|
|
90
103
|
output(batch: OutputHookBatch): readonly OutputAddition[];
|
|
91
104
|
},
|
|
92
105
|
): NativeHook & { readonly family: "output" };
|
|
106
|
+
/** Syntax and existing facts delivered to a fact-provider hook. */
|
|
93
107
|
export interface FactProviderBatch {
|
|
94
108
|
readonly schema: 1;
|
|
95
109
|
readonly plugin: string;
|
|
@@ -98,6 +112,7 @@ export interface FactProviderBatch {
|
|
|
98
112
|
readonly nodes: readonly import("./index.js").PluginNode[];
|
|
99
113
|
readonly facts: Readonly<Record<string, readonly (readonly [string | number, JsonValue])[]>>;
|
|
100
114
|
}
|
|
115
|
+
/** Validate and fingerprint a deterministic fact-provider hook. */
|
|
101
116
|
export declare function defineFactProvider(
|
|
102
117
|
definition: HookIdentity & {
|
|
103
118
|
visit?: readonly string[];
|
package/visitor.d.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import type { PluginNode } from "./index.js";
|
|
2
2
|
import type { JsonValue } from "./stages.js";
|
|
3
3
|
|
|
4
|
+
/** Visitor protocol version understood by this SDK. */
|
|
4
5
|
export declare const VISITOR_API_VERSION: 1;
|
|
6
|
+
/** Closed capability vocabulary accepted during visitor negotiation. */
|
|
5
7
|
export declare const VISITOR_CAPABILITIES: readonly [
|
|
6
8
|
"sfc",
|
|
7
9
|
"template",
|
|
@@ -13,7 +15,9 @@ export declare const VISITOR_CAPABILITIES: readonly [
|
|
|
13
15
|
"format",
|
|
14
16
|
"devtools-trace",
|
|
15
17
|
];
|
|
18
|
+
/** One capability from the versioned visitor vocabulary. */
|
|
16
19
|
export type VisitorCapability = (typeof VISITOR_CAPABILITIES)[number];
|
|
20
|
+
/** Stable validation or negotiation failure reported by the visitor API. */
|
|
17
21
|
export type VisitorErrorCode =
|
|
18
22
|
| "invalid-definition"
|
|
19
23
|
| "invalid-name"
|
|
@@ -34,16 +38,19 @@ export type VisitorErrorCode =
|
|
|
34
38
|
| "invalid-event"
|
|
35
39
|
| "invalid-visitor-result";
|
|
36
40
|
|
|
41
|
+
/** Definition or host-contract error with a stable code and field path. */
|
|
37
42
|
export declare class VisitorPluginValidationError extends TypeError {
|
|
38
43
|
readonly code: VisitorErrorCode;
|
|
39
44
|
readonly field: string;
|
|
40
45
|
}
|
|
41
46
|
|
|
47
|
+
/** Half-open UTF-8 byte range used by visitor payloads. */
|
|
42
48
|
export interface VisitorRange {
|
|
43
49
|
readonly start: number;
|
|
44
50
|
readonly end: number;
|
|
45
51
|
readonly encoding: "utf8";
|
|
46
52
|
}
|
|
53
|
+
/** Diagnostic delivered to a visitor with source and severity metadata. */
|
|
47
54
|
export interface VisitorDiagnostic {
|
|
48
55
|
readonly code: string;
|
|
49
56
|
readonly message: string;
|
|
@@ -51,55 +58,67 @@ export interface VisitorDiagnostic {
|
|
|
51
58
|
readonly range: VisitorRange;
|
|
52
59
|
readonly source?: string;
|
|
53
60
|
}
|
|
61
|
+
/** Replacement edit associated with a lint visitor payload. */
|
|
54
62
|
export interface VisitorFix {
|
|
55
63
|
readonly range: VisitorRange;
|
|
56
64
|
readonly text: string;
|
|
57
65
|
}
|
|
66
|
+
/** One parsed block in an SFC visitor payload. */
|
|
58
67
|
export interface VisitorSfcBlock {
|
|
59
68
|
readonly kind: "template" | "script" | "script-setup" | "style" | "custom";
|
|
60
69
|
readonly language: string | null;
|
|
61
70
|
readonly range: VisitorRange;
|
|
62
71
|
readonly attributes: Readonly<Record<string, string | null>>;
|
|
63
72
|
}
|
|
73
|
+
/** Complete authored SFC source and its parsed block inventory. */
|
|
64
74
|
export interface VisitorSfcPayload {
|
|
65
75
|
readonly source: string;
|
|
66
76
|
readonly blocks: readonly VisitorSfcBlock[];
|
|
67
77
|
}
|
|
78
|
+
/** Normalized template nodes delivered to template visitors. */
|
|
68
79
|
export interface VisitorTemplatePayload {
|
|
69
80
|
readonly nodes: readonly PluginNode[];
|
|
70
81
|
}
|
|
82
|
+
/** Authored script source, language, and optional negotiated syntax data. */
|
|
71
83
|
export interface VisitorScriptPayload {
|
|
72
84
|
readonly source: string;
|
|
73
85
|
readonly language: "js" | "jsx" | "ts" | "tsx";
|
|
74
86
|
/** Host-owned serialized syntax data. Its schema belongs to the negotiated host. */
|
|
75
87
|
readonly syntax?: JsonValue;
|
|
76
88
|
}
|
|
89
|
+
/** Authored style source and its scoped or module mode. */
|
|
77
90
|
export interface VisitorStylePayload {
|
|
78
91
|
readonly source: string;
|
|
79
92
|
readonly language: string;
|
|
80
93
|
readonly scoped: boolean;
|
|
81
94
|
readonly module: boolean | string;
|
|
82
95
|
}
|
|
96
|
+
/** Source-to-generated range pair for virtual TypeScript. */
|
|
83
97
|
export interface VisitorVirtualTsMapping {
|
|
84
98
|
readonly source: VisitorRange;
|
|
85
99
|
readonly generated: VisitorRange;
|
|
86
100
|
}
|
|
101
|
+
/** Virtual TypeScript code, file identities, and source mappings. */
|
|
87
102
|
export interface VisitorVirtualTsPayload {
|
|
88
103
|
readonly sourceFile: string;
|
|
89
104
|
readonly virtualFile: string;
|
|
90
105
|
readonly code: string;
|
|
91
106
|
readonly mappings: readonly VisitorVirtualTsMapping[];
|
|
92
107
|
}
|
|
108
|
+
/** Diagnostics currently owned by the host pipeline. */
|
|
93
109
|
export interface VisitorDiagnosticsPayload {
|
|
94
110
|
readonly diagnostics: readonly VisitorDiagnostic[];
|
|
95
111
|
}
|
|
112
|
+
/** Lint diagnostics together with their available fixes. */
|
|
96
113
|
export interface VisitorLintPayload extends VisitorDiagnosticsPayload {
|
|
97
114
|
readonly fixes: readonly VisitorFix[];
|
|
98
115
|
}
|
|
116
|
+
/** Authored and formatted source delivered to format visitors. */
|
|
99
117
|
export interface VisitorFormatPayload {
|
|
100
118
|
readonly source: string;
|
|
101
119
|
readonly formatted: string;
|
|
102
120
|
}
|
|
121
|
+
/** One parented timing event from the devtools trace pipeline. */
|
|
103
122
|
export interface VisitorDevtoolsTraceEvent {
|
|
104
123
|
readonly id: string;
|
|
105
124
|
readonly parentId: string | null;
|
|
@@ -109,9 +128,11 @@ export interface VisitorDevtoolsTraceEvent {
|
|
|
109
128
|
readonly durationNs: number;
|
|
110
129
|
readonly data?: JsonValue;
|
|
111
130
|
}
|
|
131
|
+
/** Ordered trace events delivered to a devtools visitor. */
|
|
112
132
|
export interface VisitorDevtoolsTracePayload {
|
|
113
133
|
readonly events: readonly VisitorDevtoolsTraceEvent[];
|
|
114
134
|
}
|
|
135
|
+
/** Capability-to-payload mapping for every visitor event family. */
|
|
115
136
|
export interface VisitorPayloads {
|
|
116
137
|
readonly sfc: VisitorSfcPayload;
|
|
117
138
|
readonly template: VisitorTemplatePayload;
|
|
@@ -123,20 +144,25 @@ export interface VisitorPayloads {
|
|
|
123
144
|
readonly format: VisitorFormatPayload;
|
|
124
145
|
readonly "devtools-trace": VisitorDevtoolsTracePayload;
|
|
125
146
|
}
|
|
147
|
+
/** Versioned host event specialized by one visitor capability. */
|
|
126
148
|
export interface VisitorEvent<C extends VisitorCapability = VisitorCapability> {
|
|
127
149
|
readonly apiVersion: 1;
|
|
128
150
|
readonly capability: C;
|
|
129
151
|
readonly file: string;
|
|
130
152
|
readonly payload: VisitorPayloads[C];
|
|
131
153
|
}
|
|
154
|
+
/** Synchronous handler for one negotiated visitor event. */
|
|
132
155
|
export type VisitorHandler<C extends VisitorCapability> = (event: VisitorEvent<C>) => void;
|
|
156
|
+
/** Exact handler map required by a capability tuple. */
|
|
133
157
|
export type VisitorHandlers<C extends readonly VisitorCapability[]> = {
|
|
134
158
|
readonly [K in C[number]]: VisitorHandler<K>;
|
|
135
159
|
};
|
|
160
|
+
/** Captured ambient or configuration input included in a visitor fingerprint. */
|
|
136
161
|
export interface VisitorCacheInput {
|
|
137
162
|
readonly name: string;
|
|
138
163
|
readonly value: string;
|
|
139
164
|
}
|
|
165
|
+
/** Authored visitor descriptor before validation and fingerprinting. */
|
|
140
166
|
export interface VisitorPluginDefinition<C extends readonly VisitorCapability[]> {
|
|
141
167
|
readonly apiVersion: 1;
|
|
142
168
|
readonly name: string;
|
|
@@ -146,6 +172,7 @@ export interface VisitorPluginDefinition<C extends readonly VisitorCapability[]>
|
|
|
146
172
|
readonly cacheInputs: readonly VisitorCacheInput[];
|
|
147
173
|
readonly visitors: VisitorHandlers<C>;
|
|
148
174
|
}
|
|
175
|
+
/** Immutable visitor descriptor accepted by host negotiation. */
|
|
149
176
|
export interface VisitorPlugin<
|
|
150
177
|
C extends readonly VisitorCapability[] = readonly VisitorCapability[],
|
|
151
178
|
> {
|
|
@@ -158,16 +185,19 @@ export interface VisitorPlugin<
|
|
|
158
185
|
readonly visitors: VisitorHandlers<C>;
|
|
159
186
|
readonly fingerprint: string;
|
|
160
187
|
}
|
|
188
|
+
/** Visitor protocol version and capabilities supplied by a host. */
|
|
161
189
|
export interface VisitorHostContract<
|
|
162
190
|
C extends readonly VisitorCapability[] = readonly VisitorCapability[],
|
|
163
191
|
> {
|
|
164
192
|
readonly apiVersion: 1;
|
|
165
193
|
readonly capabilities: C;
|
|
166
194
|
}
|
|
195
|
+
/** Exact capabilities retained after successful host negotiation. */
|
|
167
196
|
export interface NegotiatedVisitorContract<C extends readonly VisitorCapability[]> {
|
|
168
197
|
readonly apiVersion: 1;
|
|
169
198
|
readonly capabilities: C;
|
|
170
199
|
}
|
|
200
|
+
/** Native host adapter for a virtual-TypeScript-only visitor plugin. */
|
|
171
201
|
export interface VirtualTsVisitorHostPlugin {
|
|
172
202
|
readonly name: string;
|
|
173
203
|
readonly version: string;
|
|
@@ -175,6 +205,7 @@ export interface VirtualTsVisitorHostPlugin {
|
|
|
175
205
|
/** Host-only serialized boundary consumed by `typeCheckWithVirtualTsVisitors`. */
|
|
176
206
|
readonly run: (eventJson: string) => string;
|
|
177
207
|
}
|
|
208
|
+
/** Devtools host adapter for a trace-only visitor plugin. */
|
|
178
209
|
export interface DevtoolsTraceVisitorHostPlugin {
|
|
179
210
|
readonly name: string;
|
|
180
211
|
readonly version: string;
|