PluginContext

import type { PluginContext } from "@shadow-js/compiler";

interface PluginContext {
  /** The `filename` option of the compilation (default `"module.tsx"`). */
  readonly filename: string;
  /** The `generate` option: `"dom"` or `"ssr"`. */
  readonly target: "dom" | "ssr";
  /** The stage this call belongs to. */
  readonly stage: PluginStage;
  /** The `dev` option. */
  readonly dev: boolean;
  /** The text the tree was parsed from; every offset of the tree and of the edits refers to it. */
  readonly source: string;
  /** Builders for source text. */
  readonly create: NodeFactory;
  /**
   * Reports a finding. An `"error"` stops the compilation after `transform` returns, as a
   * {@link CompileError} with the plugin's name.
   * @param diagnostic The finding.
   */
  report(diagnostic: PluginDiagnostic): void;
  /**
   * Visits `root` and its descendants depth first, in source order, without recursion.
   * @param visitor Callbacks by node type.
   * @param root Where to start. Default: the whole tree.
   */
  walk(visitor: Visitor, root?: PluginNode): void;
  /**
   * Narrows a node to the typed interface of its type.
   * @param node A node, or `null` or `undefined` (for an optional child), which is never a match.
   * @param type A key of {@link NodeMap}.
   * @returns True when `node.type` is `type`.
   */
  is<K extends keyof NodeMap>(node: PluginNode | null | undefined, type: K): node is NodeMap[K];
  /**
   * The text of a span.
   * @param range A node or any `{ start, end }`.
   * @returns `source.slice(range.start, range.end)`.
   */
  text(range: PluginRange): string;
  /**
   * Replaces the text of a span. When the span is exactly one identifier, its original name is kept
   * in the source map.
   * @param range The span to replace.
   * @param code The new text.
   * @throws RangeError When the span is outside the source or reversed.
   */
  replace(range: PluginRange, code: string): void;
  /**
   * Inserts text where a span starts. Several inserts at one position keep their call order.
   * @param range Where to insert (at `range.start`).
   * @param code The text.
   * @throws RangeError When the span is outside the source or reversed.
   */
  insertBefore(range: PluginRange, code: string): void;
  /**
   * Inserts text where a span ends. Several inserts at one position keep their call order.
   * @param range Where to insert (at `range.end`).
   * @param code The text.
   * @throws RangeError When the span is outside the source or reversed.
   */
  insertAfter(range: PluginRange, code: string): void;
  /**
   * Removes a span.
   * @param range The span to remove.
   * @throws RangeError When the span is outside the source or reversed.
   */
  remove(range: PluginRange): void;
  /**
   * Adds `import { imported as <local> } from "from"` to the module (once per pair, after the
   * directive prologue) and returns the local name. The pair must be listed in the plugin's
   * {@link CompilerPlugin.imports}.
   * @param from The module specifier.
   * @param imported The exported name (`default` for the default export).
   * @returns A local name that does not collide with a name of the module.
   * @throws CompileError `PLUGIN_UNDECLARED_IMPORT` when the pair is not declared.
   */
  addImport(from: string, imported: string): string;
}