@jesscss/plugin-js 2.0.0-alpha.1 → 2.0.0-alpha.10

package/lib/index.d.ts

@@ -1,4 +1,16 @@
 import { AbstractPlugin } from '@jesscss/core';
+/**
+ * A failure raised BY a `@plugin` script (its own `throw`, or a shim member it
+ * cannot use), as distinct from a value the engine simply could not compute.
+ * The distinction is what lets the compiler report a plugin fault loudly and
+ * attributably instead of preserving the call verbatim.
+ */
+export declare class PluginFunctionError extends Error {
+    readonly functionName: string;
+    readonly pluginStack: string | undefined;
+    readonly originalName: string;
+    constructor(functionName: string, reason: string, pluginStack?: string, originalName?: string);
+}
 export type JavaScriptSandboxConfig = {
     allowHttp?: boolean;
     allowNetHosts?: string[];
@@ -6,20 +18,92 @@ export type JavaScriptSandboxConfig = {
 };
 export interface JsPluginOptions extends JavaScriptSandboxConfig {
     denoCommand?: string;
+    /**
+     * Runtime API exposed inside the Deno worker.
+     *
+     * Jess `@-use`/script imports run as plain ESM modules. Legacy Less
+     * `@plugin` loading can opt into the Less-compatible global shape.
+     */
+    runtimeApi?: 'module' | 'less';
+}
+/**
+ * Returns a copy of `env` with Node debugger/inspector-attach variables removed,
+ * so a spawned Deno subprocess starts regardless of the parent's debug env.
+ * The Deno permission sandbox is untouched; this only stops leaking the debugger
+ * into it.
+ */
+export declare const sanitizeSpawnEnv: (env?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+/**
+ * One scope/built-in fact resolved on the HOST and handed to the sandbox so a
+ * synchronous Less-4 plugin body can read it. See {@link PluginCallCapabilities}.
+ */
+export type PluginCallFacts = {
+    vars: Record<string, {
+        value: unknown;
+        important?: boolean;
+    } | null>;
+    calls: Record<string, unknown>;
+    fileInfo: {
+        filename: string;
+        entryPath: string;
+    } | null;
+};
+export type PluginLogRecord = {
+    level: 'warn' | 'error' | 'info' | 'debug';
+    message: string;
+};
+/**
+ * The compiler-side capabilities a legacy `@plugin` function body needs. The
+ * dialect adapter supplies these bound to the LIVE evaluation frame of the call
+ * site; the sandbox reaches them only through the resolve-and-replay protocol,
+ * never as a live object.
+ */
+export interface PluginCallCapabilities {
+    /** Resolve `@name` at the call site. `null` means "no such variable". */
+    lookupVariable?(name: string): {
+        value: unknown;
+        important?: boolean;
+    } | null;
+    /** Evaluate a built-in function (`less.functions.functionRegistry.get(...)`). */
+    callFunction?(name: string, args: unknown[]): unknown;
+    /** The file/entry pair a plugin reads through `this.currentFileInfo`. */
+    currentFileInfo?: {
+        filename: string;
+        entryPath: string;
+    };
+    /** Records a diagnostic emitted by the plugin through `less.logger`. */
+    log?(record: PluginLogRecord): void;
+    /** Propagates `!important` picked up while resolving a variable. */
+    markImportant?(): void;
 }
+/** A `@plugin` function bound to the live call-site capabilities. */
+export type ContextualPluginFunction = (args: readonly unknown[], capabilities: PluginCallCapabilities) => unknown | Promise<unknown>;
 export declare class JsPlugin extends AbstractPlugin {
     opts: JsPluginOptions;
+    private static cleanupRegistered;
+    private static liveInstances;
     name: string;
     supportedExtensions: string[];
     private runtimeState;
+    private shuttingDown;
     private brokerServer;
     private brokerSocketPath;
     private worker;
     private workerBuffer;
     private nextRequestId;
     private pending;
+    private idleTimer;
+    /**
+     * Variable names each legacy plugin function has been observed to read,
+     * keyed by module+options+function. Prefetching them turns the steady-state
+     * call into a single round trip instead of one round trip per read.
+     */
+    private readonly factMemo;
     constructor(opts?: JsPluginOptions);
     prewarm(): Promise<void | undefined>;
+    private static registerProcessCleanup;
+    private clearIdleTimer;
+    private scheduleIdleShutdown;
     private ensureRuntimeAvailable;
     private ensureRuntime;
     private createBrokerPath;
@@ -36,6 +120,29 @@ export declare class JsPlugin extends AbstractPlugin {
     dispose(): void;
     private assertAllowedPath;
     import(absoluteFilePath: string): Promise<Record<string, any>>;
+    /**
+     * Loads a legacy Less `@plugin` wrapper file in Deno Less-compat mode.
+     *
+     * @deprecated Less `@plugin` is deprecated. Prefer `@-from` for
+     * ESM-style script imports or `@-use` for Sass-module-style namespace imports.
+     */
+    importLessPlugin(absoluteFilePath: string, options?: string | null): Promise<{
+        functions: Record<string, ContextualPluginFunction>;
+    }>;
+    /**
+     * Runs one legacy `@plugin` function, resolving the scope/built-in facts its
+     * body reads. The sandbox reports one unmet fact at a time; the host answers
+     * it from the LIVE call-site capabilities and replays. The names a function
+     * asked for are remembered per function, so steady-state calls ship the facts
+     * up front and complete in a single round trip.
+     */
+    private invokePluginFunction;
+    private resolveVariableFact;
+    private resolveCallFact;
+    /** Context-facing executable-plugin capability used by the direct AST path. */
+    importPlugin(absoluteFilePath: string, options?: string | null): Promise<{
+        functions: Record<string, ContextualPluginFunction>;
+    }>;
 }
 /**
  * Global flag set when @jesscss/plugin-js is loaded.

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACf,MAAM,eAAe,CAAC;AAOvB,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoGD,qBAAa,QAAS,SAAQ,cAAc;IAevB,IAAI,EAAE,eAAe;IAdxC,IAAI,SAAQ;IACZ,mBAAmB,WAAiC;IACpD,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,OAAO,CAIV;gBAEc,IAAI,GAAE,eAAoB;IAI7C,OAAO;IAIP,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,mBAAmB;YA0Bb,WAAW;IA2CzB,OAAO,CAAC,WAAW;YAkEL,YAAY;IAW1B,OAAO,CAAC,cAAc;IA6BtB,OAAO,CAAC,gBAAgB;YAQV,UAAU;IAqBxB,OAAO,CAAC,QAAQ;IAqBhB,OAAO;IAKP,OAAO,CAAC,iBAAiB;IAgBnB,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CA6CrE;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAOpE,QAAA,MAAM,QAAQ,UAAY,eAAe,aAEtB,CAAC;AAEpB,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}