@vizejs/plugin-sdk 0.429.0

package/README.md

@@ -0,0 +1,224 @@
+# @vizejs/plugin-sdk
+
+Author synchronous rules, fact providers, native template transforms and compiled
+output hooks. Install `@vizejs/native` **0.429.0 or newer** to execute plugins.
+The optional native peer lets this package install independently for authoring;
+its helpers alone do not compile or lint Vue files. Node 22 or newer is required.
+
+## Lint rules and autofixes
+
+```js
+import * as native from "@vizejs/native";
+import { definePlugin, applyFixes } from "@vizejs/plugin-sdk";
+
+const rule = definePlugin({
+  name: "team-rule",
+  version: "1.0.0",
+  visit: ["ui.bind"],
+  demands: [],
+  cacheInputs: [],
+  rules: {
+    check(ctx) {
+      for (const node of ctx.nodes) {
+        if (node.name === "disabled" && node.value === "true") {
+          ctx.report(node, "Use a literal boolean attribute.", "disabled");
+        }
+      }
+    },
+  },
+});
+const output = native.lintWithPlugins(source, [rule], {
+  filename: "Button.vue",
+  cache: true,
+  validateDeterminism: true,
+});
+const fixed = applyFixes(source, output.fixes);
+```
+
+A report names a visited L2 node. Rust assigns its authored UTF-8 byte range;
+a fix replaces that whole range. `applyFixes` preserves other source,
+deduplicates identical suggestions and refuses conflicting edits atomically.
+Apply suggestions deliberately, then rerun the compiler and linter.
+
+Rules receive immutable batches. `ctx.facts(name)` requires the group in the
+static `demands` list; no undeclared table crosses the boundary. Native groups
+include `templateScopes` and the registered Croquis producers `bindings`,
+`undefined-refs`, `component-usages`, `reactivity`, `provide-inject` and
+`race-conditions` and `unused-bindings`. The latter computes its registered
+`bindings` dependency. The `bindings` and `unused-bindings` spans are authored
+SFC UTF-8 byte ranges, mapped by the shared producer even for reordered split
+scripts. Other primary position fields retain their Croquis analysis frame:
+undefined references/component usage are template-relative; reactivity,
+provide/inject and race positions are script-relative (the merged normal/setup
+script when both exist). Reports and fixes always use the host's SFC ranges. Public component interface pages are `component-signature`,
+`prop-types`, `emit-types`, `slot-types`, `reactivity-classes` and
+`component-references`. Each interface value preserves the producer's schema,
+nullable unknowns and type dependency completeness. The signature's
+`props_complete` separately records whether all property names were enumerated.
+The source-only SDK route has no resolved catalog proof, so it reports false
+without reading imported files from disk. Imported types which this
+analysis cannot resolve remain explicit unknowns. Primary Croquis facts require
+a JavaScript or TypeScript script; other script dialects are refused explicitly.
+
+Plugin visits require inline HTML templates. Authored foreign template dialects
+and external template blocks are refused before callbacks; the SDK does not
+pretend their source is HTML or invent source maps for a preprocessing pass.
+
+TypeScript infers each native group's exact map keys and deeply readonly values
+from `ctx.facts("prop-types")`, including authored interface order and all emit
+overloads. The package exports `FactGroups`, `FactKey`, `FactValue`, `FactEntry`
+and the individual native contracts. Custom provider groups can use
+`ctx.facts<MyFact>("design/labels")`; unknown groups default to `unknown`.
+
+## Fact providers
+
+```js
+import { defineFactProvider, definePlugin } from "@vizejs/plugin-sdk";
+const labels = defineFactProvider({
+  name: "design",
+  version: "1",
+  provides: ["design/labels"],
+  visit: ["ui.element"],
+  demands: ["bindings"],
+  cacheInputs: [],
+  provide(batch) {
+    return { "design/labels": batch.nodes.map((node) => [node.id, node.name]) };
+  },
+});
+const consumer = definePlugin({
+  name: "labels",
+  version: "1",
+  demands: ["design/labels"],
+  cacheInputs: [],
+  rules: {
+    check(ctx) {
+      const labels = ctx.facts("design/labels");
+    },
+  },
+});
+native.lintWithPlugins(source, [consumer], { cache: true, factProviders: [labels] });
+```
+
+A provider declares every output group as `provider-name/group`, its required
+facts and node visits. The host computes the dependency closure and refuses
+cycles, collisions, undeclared output and malformed tables before using facts.
+Each table contains `[stringOrNumericKey, jsonValue]` rows with unique keys.
+Provider dependency stamps enter the consumer cache key automatically.
+
+## Native template transforms
+
+```js
+import { defineTransformPlugin } from "@vizejs/plugin-sdk";
+const design = defineTransformPlugin({
+  name: "design-system",
+  version: "1",
+  cacheInputs: [],
+  transform(batch) {
+    return batch.nodes
+      .filter((node) =>
+        node.attrs.some((attr) => attr.name === "class" && attr.value === "legacy-btn"),
+      )
+      .map((node) => ({
+        kind: "replace-static-attribute",
+        node: node.id,
+        name: "class",
+        value: "ds-button",
+      }));
+  },
+});
+const transformed = native.compileWithTransformPlugins(template, [design], {
+  filename: "Button.vue",
+  sourceMap: true,
+  cache: true,
+  cacheDir: ".vize-cache",
+});
+```
+
+The hook runs at the native pre-canonical L2 point. It can replace existing
+static HTML attributes from the host's allowed set; dynamic attributes,
+structural edits, template carriers and foreign namespaces refuse. Values are
+semantic text, not entity spelling. Unknown targets or duplicate edits refuse
+the entire response. The compiler applies typed edits to its real arena and
+emits code and authored maps; no guest AST JSON is accepted. The result is a
+module with prefixed identifiers. `plugins` contains per-plugin costs.
+
+## Formatter and output hooks
+
+```js
+import { defineOutputPlugin } from "@vizejs/plugin-sdk";
+const license = defineOutputPlugin({
+  name: "license",
+  version: "1",
+  family: "output",
+  cacheInputs: [],
+  output() {
+    return [{ placement: "prepend", comment: "Copyright Example" }];
+  },
+});
+const compiled = native.compileWithOutputPlugins(template, [license], options);
+const decorated = native.applyOutputPlugins(transformed.result, [license], { cache: true });
+```
+
+`family: "formatter"` returns `{start,end,text}` edits using UTF-8 byte offsets.
+Only whitespace formatting which preserves the parsed program and comments is
+accepted. `family: "output"` appends or prepends ordinary block comments;
+source-map directives and executable additions refuse. The host rebases existing
+map anchors and preserves source content. Each pipeline key includes preceding
+output. Function-mode results carry `preamble` separately from `code`.
+
+## Determinism, caches and costs
+
+Declare every captured configuration or ambient input in `cacheInputs`, even
+when the list is empty. Names beginning `@vize/` are host-reserved. Source,
+filename, native build, SDK runtime bytes, plugin version/code, static demands,
+visits and inputs participate in keys. A cached lint miss always audits two
+identical batches. Providers and transforms audit misses. Cached output hooks also always audit;
+uncached output hooks audit by default. Different validated outputs refuse before caching. All hook families
+have bounded in-process caches and opt-in `cacheDir` persistence. Disk hits
+validate their schema, keys and host-confined outputs before reuse.
+
+Costs include elapsed host work and JavaScript call time, including audit calls.
+A cache hit executes no callback; its `jsNs` and batch crossing bytes are zero.
+A determinism audit observes repeated output. Trusted callbacks can conceal
+ambient reads; their declarations remain the author's responsibility.
+
+## Isolated callback sources
+
+```js
+import {
+  createSandboxRunner,
+  SANDBOX_IMAGE,
+  SandboxRuntimeError,
+} from "@vizejs/plugin-sdk/sandbox";
+const isolated = createSandboxRunner(
+  {
+    name: "isolated-rule",
+    version: "1",
+    cacheInputs: [],
+    configuration: { message: "Use our design system" },
+    rules: { check: "(ctx, config) => { ctx.report(ctx.nodes[0], config.message); }" },
+  },
+  { timeoutMs: 5000, maxBytes: 1048576 },
+);
+native.lintWithPlugins(source, [isolated], { cache: true });
+```
+
+Install Docker, start its daemon and pull the exported pinned `SANDBOX_IMAGE`
+before use. Callback source and explicit JSON configuration cross stdin; host
+closures and imports do not. Each invocation uses a nonroot, read-only container
+without host mounts, host environment, external network or capabilities, with
+memory/CPU/PID/file-descriptor limits. The host bounds request/output bytes and
+execution time, then confirms container removal. Runtime checking and cleanup
+each add at most five seconds to `timeoutMs`.
+
+`SandboxRuntimeError.code` distinguishes `runtime_unavailable`,
+`execution_stopped`, `execution_failed` and `cleanup_failed`. Unavailable Docker
+or a missing image refuses execution; it never runs the guest as trusted code.
+The image's own filesystem remains readable. Docker supplies the isolation;
+this API does not claim virtual-machine isolation.
+
+`definePlugin` and the other ordinary helpers execute trusted application code
+synchronously in the calling Node process and have no execution deadline.
+Freezing batches and auditing output do not isolate those callbacks. The measured
+proxy handle remains for spike compatibility. `@vizejs/extension-sdk` is the
+separate versioned WIT guest interface.

package/facts.d.ts

@@ -0,0 +1,348 @@
+export interface TemplateScopeEntry {
+  readonly name: string;
+  readonly position: "value" | "key" | "index" | "slot";
+}
+export type BindingKind =
+  | "setup-let"
+  | "setup-maybe-ref"
+  | "setup-ref"
+  | "setup-reactive-const"
+  | "setup-const"
+  | "props"
+  | "props-aliased"
+  | "data"
+  | "options"
+  | "literal-const"
+  | "js-global-universal"
+  | "js-global-browser"
+  | "js-global-node"
+  | "js-global-deno"
+  | "js-global-bun"
+  | "vue-global"
+  | "external-module";
+export type BindingFact =
+  | Readonly<{ scriptSetup: true }>
+  | Readonly<{
+      kind: BindingKind | null;
+      span: readonly [number, number] | null;
+      propKey: string | null;
+    }>;
+export interface UndefinedRefFact {
+  readonly name: string;
+  readonly offset: number;
+  readonly context: string;
+}
+export interface UnusedBindingFact {
+  readonly span: readonly [number, number];
+}
+export interface FactRange {
+  readonly start: number;
+  readonly end: number;
+}
+export interface ComponentPropUsage extends FactRange {
+  readonly name: string;
+  readonly nameIsDynamic: boolean;
+  readonly value: string | null;
+  readonly isDynamic: boolean;
+}
+export interface ComponentEventUsage extends FactRange {
+  readonly name: string;
+  readonly nameIsDynamic: boolean;
+  readonly handler: string | null;
+  readonly modifiers: readonly string[];
+}
+export interface ComponentSlotUsage extends FactRange {
+  readonly name: string;
+  readonly nameIsDynamic: boolean;
+  readonly scopeVars: readonly string[];
+  readonly hasScope: boolean;
+}
+export interface ComponentSpreadUsage extends FactRange {
+  readonly expression: string;
+}
+export interface ComponentUsage extends FactRange {
+  readonly name: string;
+  readonly props: readonly ComponentPropUsage[];
+  readonly events: readonly ComponentEventUsage[];
+  readonly slots: readonly ComponentSlotUsage[];
+  readonly hasSpreadAttrs: boolean;
+  readonly spreadProps: readonly ComponentSpreadUsage[];
+  readonly scopeId: number;
+  readonly vifGuard: string | null;
+}
+export interface ComponentUsageSite {
+  readonly tag: string;
+  readonly usage: ComponentUsage | null;
+  readonly usageIndex: number | null;
+  readonly nameOrdinal: number | null;
+}
+export interface ComponentUsagesFact {
+  readonly module: string | null;
+  readonly export: string;
+  readonly sites: readonly ComponentUsageSite[];
+}
+export type ReactivityClass = "static" | "props-stable" | "reactive" | "unstable";
+export type Verdict = "proven" | "refuted" | "unknown";
+export type ReactivityEffect =
+  | "freeze"
+  | "capture"
+  | "read-prop"
+  | "read-reactive"
+  | "mutate-local"
+  | "mutate-global"
+  | "call-unknown"
+  | "allocate";
+export type ReactiveSourceKind =
+  | "ref"
+  | "shallow-ref"
+  | "reactive"
+  | "shallow-reactive"
+  | "computed"
+  | "readonly"
+  | "shallow-readonly"
+  | "to-ref"
+  | "to-refs";
+export type ReactivityLoss =
+  | Readonly<{
+      kind: "reactive-destructure" | "ref-value-destructure";
+      sourceName: string;
+      destructuredProps: readonly string[];
+    }>
+  | Readonly<{ kind: "ref-value-extract"; sourceName: string; targetName: string }>
+  | Readonly<{
+      kind: "reactive-property-extract";
+      sourceName: string;
+      propName: string;
+      targetName: string;
+    }>
+  | Readonly<{ kind: "props-destructure"; destructuredProps: readonly string[] }>
+  | Readonly<{
+      kind: "function-argument-extract";
+      sourceName: string;
+      argumentName: string;
+      calleeName: string;
+    }>
+  | Readonly<{
+      kind: "getter-call-extract";
+      contextName: string;
+      getterName: string;
+      targetName: string;
+      calleeName: string;
+      sourceName: string;
+    }>
+  | Readonly<{
+      kind: "plain-value-alias";
+      sourceName: string;
+      aliasName: string;
+      targetName: string;
+    }>
+  | Readonly<{ kind: "reactive-spread" | "reactive-reassign"; sourceName: string }>;
+export type ReactivityFact =
+  | Readonly<{
+      kind: "source";
+      name: string;
+      sourceKind: ReactiveSourceKind;
+      declarationOffset: number;
+      class: ReactivityClass;
+      verdict: Verdict;
+      effects: readonly ReactivityEffect[];
+    }>
+  | Readonly<{
+      kind: "loss";
+      loss: ReactivityLoss;
+      start: number;
+      end: number;
+    }>;
+
+export interface ProvideKey {
+  readonly kind: "string" | "symbol";
+  readonly name: string;
+}
+export type InjectPattern =
+  | Readonly<{ kind: "simple" }>
+  | Readonly<{ kind: "object" | "array"; props: readonly string[] }>
+  | Readonly<{ kind: "indirect"; injectVar: string; props: readonly string[]; offset: number }>;
+export type ProvideInjectFact =
+  | Readonly<{
+      kind: "provide";
+      id: number;
+      key: ProvideKey;
+      value: string;
+      valueType: string | null;
+      fromComposable: string | null;
+      start: number;
+      end: number;
+    }>
+  | Readonly<{
+      kind: "inject";
+      key: ProvideKey;
+      localName: string;
+      defaultValue: string | null;
+      expectedType: string | null;
+      pattern: InjectPattern;
+      fromComposable: string | null;
+      start: number;
+      end: number;
+    }>
+  | Readonly<{
+      kind: "composable";
+      name: string;
+      source: string;
+      localName: string | null;
+      usesProvide: boolean;
+      usesInject: boolean;
+      usesReactivity: boolean;
+      start: number;
+      end: number;
+    }>;
+
+export type RaceRisk =
+  | Readonly<{
+      kind: "async-watcher";
+      watcherName: string;
+      asyncOperation: string;
+      mutatedTargets: readonly string[];
+    }>
+  | Readonly<{
+      kind: "async-watch-effect" | "promise-continuation";
+      asyncOperation: string;
+      mutatedTargets: readonly string[];
+    }>
+  | Readonly<{
+      kind: "async-lifecycle";
+      hookName: string;
+      asyncOperation: string;
+      mutatedTargets: readonly string[];
+    }>
+  | Readonly<{ kind: "scheduled"; schedulerName: string; mutatedTargets: readonly string[] }>;
+export interface RaceConditionFact extends FactRange {
+  readonly kind: RaceRisk;
+}
+
+export type UnresolvedTypeReason =
+  | "external-world-unavailable"
+  | "unbound"
+  | "missing-module"
+  | "incomplete-module"
+  | "unsupported-declaration"
+  | "unsupported-qualification"
+  | "ambiguous-export"
+  | "resolution-cycle"
+  | "resolution-limit";
+export interface TypeDependency {
+  readonly name: string;
+  readonly kind: "alias" | "interface" | "imported" | "unresolved";
+  readonly module: string | null;
+  readonly export: string | null;
+  /** Authored type text, including literal whitespace. */
+  readonly body: string | null;
+  readonly parameters: string | null;
+  readonly extends: readonly string[];
+  readonly unresolved_reason: UnresolvedTypeReason | null;
+}
+export interface TypeEnvironment {
+  /** False means some reachable type information could not be resolved. */
+  readonly complete: boolean;
+  readonly declarations: readonly TypeDependency[];
+}
+export interface ExposeContract {
+  readonly name: string;
+  readonly type: string | null;
+}
+export interface SignatureContract {
+  readonly schema: 1;
+  readonly name: string;
+  readonly declared_name: string | null;
+  readonly generic: string | null;
+  readonly component_shape: "unspecified" | "class-api";
+  readonly script_setup: boolean;
+  readonly prop_type_arguments: string | null;
+  readonly emit_type_arguments: string | null;
+  readonly slot_type_arguments: string | null;
+  /** Public names in authored completion order, without folio key encoding. */
+  readonly props_complete: boolean;
+  readonly with_defaults: string | null;
+  readonly prop_order: readonly string[];
+  readonly slot_order: readonly string[];
+  readonly exposes_complete: boolean;
+  readonly exposes: readonly ExposeContract[];
+  readonly type_dependencies: TypeEnvironment;
+}
+export interface PropContract {
+  readonly schema: 1;
+  readonly name: string;
+  readonly type: string | null;
+  readonly required: boolean | null;
+  readonly default: string | null;
+  readonly model_modifiers: string | null;
+  readonly type_dependencies: TypeEnvironment;
+}
+export interface EmitContract {
+  readonly schema: 1;
+  readonly name: string;
+  readonly payload: string | null;
+  readonly overload_payloads: readonly (string | null)[];
+  readonly unresolved_type_arguments: string | null;
+  readonly validator_signatures: readonly string[];
+  readonly validator_type_annotations: readonly string[];
+  readonly type_dependencies: TypeEnvironment;
+}
+export interface SlotContract {
+  readonly schema: 1;
+  readonly name: string;
+  readonly props: string | null;
+  readonly type_dependencies: TypeEnvironment;
+}
+export type AlphaReactiveKind =
+  | "ref"
+  | "shallowRef"
+  | "reactive"
+  | "shallowReactive"
+  | "computed"
+  | "readonly"
+  | "shallowReadonly"
+  | "toRef"
+  | "toRefs";
+export interface ReactivityContract {
+  readonly schema: 1;
+  readonly name: string;
+  readonly type: string | null;
+  readonly kind: AlphaReactiveKind | null;
+  readonly class: ReactivityClass | null;
+  readonly verdict: Verdict;
+  readonly effects: readonly ReactivityEffect[];
+  readonly type_dependencies: TypeEnvironment;
+}
+export interface ComponentContract {
+  readonly schema: 1;
+  readonly module: string | null;
+  readonly export: string;
+}
+
+/** Exact native group names and map key/value contracts. */
+export interface FactGroups {
+  readonly templateScopes: ReadonlyMap<number, readonly TemplateScopeEntry[]>;
+  readonly bindings: ReadonlyMap<string, BindingFact>;
+  readonly "undefined-refs": ReadonlyMap<number, UndefinedRefFact>;
+  readonly "unused-bindings": ReadonlyMap<string, UnusedBindingFact>;
+  /** Keys are serialized JSON tuples [module | null, export]. */
+  readonly "component-usages": ReadonlyMap<string, ComponentUsagesFact>;
+  readonly reactivity: ReadonlyMap<`source:${number}` | `loss:${number}`, ReactivityFact>;
+  readonly "provide-inject": ReadonlyMap<
+    `provide:${number}` | `inject:${number}` | `composable:${number}`,
+    ProvideInjectFact
+  >;
+  readonly "race-conditions": ReadonlyMap<number, RaceConditionFact>;
+  /** Alpha keys are canonical folio declaration keys. */
+  readonly "component-signature": ReadonlyMap<string, SignatureContract>;
+  readonly "prop-types": ReadonlyMap<string, PropContract>;
+  readonly "emit-types": ReadonlyMap<string, EmitContract>;
+  readonly "slot-types": ReadonlyMap<string, SlotContract>;
+  readonly "reactivity-classes": ReadonlyMap<string, ReactivityContract>;
+  readonly "component-references": ReadonlyMap<string, ComponentContract>;
+}
+export type FactKey<K extends keyof FactGroups> =
+  FactGroups[K] extends ReadonlyMap<infer Key, unknown> ? Key : never;
+export type FactValue<K extends keyof FactGroups> =
+  FactGroups[K] extends ReadonlyMap<unknown, infer Value> ? Value : never;
+export type FactEntry<K extends keyof FactGroups> = readonly [FactKey<K>, FactValue<K>];

package/fixes.d.ts

@@ -0,0 +1,9 @@
+export interface PluginFix {
+  ruleId?: string;
+  plugin?: string;
+  start: number;
+  end: number;
+  text: string;
+}
+/** Apply all nonoverlapping host-owned UTF-8 ranges, or throw without editing. */
+export declare function applyFixes(source: string, fixes: readonly PluginFix[]): string;

package/fixes.js

@@ -0,0 +1,42 @@
+import { Buffer } from "node:buffer";
+
+/** Apply host-owned UTF-8 ranges atomically; overlapping suggestions refuse. */
+export function applyFixes(source, fixes) {
+  const bytes = Buffer.from(source);
+  const sorted = [...fixes].sort((left, right) => left.start - right.start || left.end - right.end);
+  const parts = [];
+  let cursor = 0;
+  let previous;
+  for (const fix of sorted) {
+    if (
+      !Number.isInteger(fix.start) ||
+      !Number.isInteger(fix.end) ||
+      fix.start < 0 ||
+      fix.end < fix.start ||
+      fix.end > bytes.length ||
+      typeof fix.text !== "string" ||
+      !boundary(bytes, fix.start) ||
+      !boundary(bytes, fix.end)
+    )
+      throw new RangeError("plugin autofix must use valid UTF-8 source boundaries");
+    if (
+      previous &&
+      fix.start === previous.start &&
+      fix.end === previous.end &&
+      fix.text === previous.text
+    )
+      continue;
+    if (fix.start < cursor || (previous && fix.start === previous.start)) {
+      throw new Error("overlapping plugin autofixes cannot be applied together");
+    }
+    parts.push(bytes.subarray(cursor, fix.start), Buffer.from(fix.text));
+    cursor = fix.end;
+    previous = fix;
+  }
+  parts.push(bytes.subarray(cursor));
+  return Buffer.concat(parts).toString();
+}
+
+function boundary(bytes, offset) {
+  return offset === bytes.length || (bytes[offset] & 0xc0) !== 0x80;
+}

package/identity.js

@@ -0,0 +1,10 @@
+// Cache identity includes the authoring runtime itself, including dirty edits.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+const hash = createHash("sha256");
+for (const file of ["index.js", "stages.js", "identity.js", "package.json"]) {
+  const bytes = readFileSync(new URL(file, import.meta.url));
+  hash.update(file).update(String(bytes.length)).update(bytes);
+}
+export const SDK_FINGERPRINT = hash.digest("hex");