recma-static-refiner 0.9.0

package/README.md

@@ -0,0 +1,21 @@
+# recma-static-refiner
+
+A robust **Unified/Recma** plugin for validating, transforming, and pruning MDX props at **build time**.
+
+It allows you to enforce strict TypeScript contracts on your MDX components, derive complex data from simple props, and clean up the final output—all before the code reaches the browser.
+
+## Features
+
+- **🛡️ Build-time Validation:** Enforce schemas (Zod, Valibot, ArkType) on props passed in MDX.
+- **⚡ Computed Props (`derive`):** Generate complex runtime data (e.g., loading file contents, calculating layouts) based on static props.
+- **✂️ Pruning:** Automatically remove "Source-Only" props that shouldn't leak to the runtime bundle.
+- **✨ Zero Runtime Overhead:** All transformations happen during the AST compilation phase.
+- **🔒 Type Safety:** First-class TypeScript inference for your rule registry.
+
+## Installation
+
+```bash
+npm install recma-static-refiner
+# or
+pnpm add recma-static-refiner
+```

package/dist/index.d.ts

@@ -0,0 +1,386 @@
+import { Plugin } from 'unified';
+import { Program } from 'estree';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * The foundational structural constraint for component props.
+ *
+ * Role: Input Constraint.
+ * Aliased to `object` to serve as the generic lower bound, ensuring strict
+ * compatibility with both TypeScript Interfaces and Type Aliases across
+ * the plugin architecture.
+ */
+type BaseProps = object;
+/**
+ * The validation strategy definition for a component rule.
+ *
+ * Role: Behavioral Driver.
+ * Defines the allowed validation sources. This type acts as the control flow
+ * switch in inference utilities (e.g., `InferOutput`):
+ * - `StandardSchemaV1`: Triggers strict validation and output coercion.
+ * - `undefined`: Triggers "Passthrough Mode" (raw partial props).
+ */
+type ComponentSchema = StandardSchemaV1 | undefined;
+
+/**
+ * Internal DX Helper:
+ * Flattens the type output to improve tooltips in editors.
+ *
+ * This forces TypeScript to resolve intersections (A & B) into a single flat
+ * object structure, making hover-previews for complex types readable.
+ *
+ * @see https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ *
+ * @example
+ * ```ts
+ * type A = { x: 1 };
+ * type B = { y: 2 };
+ *
+ * // Without Simplify: Shows "A & B" on hover.
+ * type Complex = A & B;
+ *
+ * // With Simplify: Shows "{ x: 1; y: 2 }" on hover.
+ * type Flat = Simplify<A & B>;
+ * ```
+ */
+type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
+/**
+ * Helper 1: The Anchor
+ * Extracts a specific key `K` from type `T` and enforces it as strictly required.
+ *
+ * @example
+ * ```ts
+ * type T = { a?: string; b?: number };
+ *
+ * // Result: { a: string }
+ * type Anchor = OneRequired<T, 'a'>;
+ * ```
+ */
+type OneRequired<T, K extends keyof T> = Required<Pick<T, K>>;
+/**
+ * Helper 2: The Remainder
+ * Constructs a type containing all properties of `T` *except* the anchor key `K`,
+ * ensuring they are all marked as optional.
+ *
+ * @example
+ * ```ts
+ * type T = { a: string; b: number };
+ *
+ * // Result: { b?: number }
+ * type Remainder = OthersOptional<T, 'a'>;
+ * ```
+ */
+type OthersOptional<T, K extends keyof T> = Partial<Omit<T, K>>;
+/**
+ * Helper 3: The Variant Builder
+ * Composes a specific variant of the original type where the anchor key `K`
+ * is required and all other keys are optional.
+ *
+ * Utilizes {@link Simplify} to ensure the resulting type is displayed as a
+ * clean object literal rather than an intersection of helpers.
+ *
+ * @example
+ * ```ts
+ * type T = { a: string; b: string };
+ *
+ * // Result: { a: string; b?: string }
+ * type Variant = VariantWith<T, 'a'>;
+ * ```
+ */
+type VariantWith<T, K extends keyof T> = Simplify<OneRequired<T, K> & OthersOptional<T, K>>;
+/**
+ * Constructs a union type where at least one of the keys from the original
+ * type `T` is required to exist.
+ *
+ * Logic:
+ * Iterates over every key `K` in `T` and generates a corresponding {@link VariantWith}
+ * where `K` acts as the required anchor. The result is a union of all possible variants.
+ *
+ * @example
+ * ```ts
+ * type T = { schema?: S; derive?: D };
+ *
+ * type Result = RequireAtLeastOne<T>;
+ * // Resulting Union:
+ * // | { schema: S; derive?: D }  (Variant A)
+ * // | { derive: D; schema?: S }  (Variant B)
+ * ```
+ */
+type RequireAtLeastOne<T> = {
+    [K in keyof T]: VariantWith<T, K>;
+}[keyof T];
+/**
+ * Generic Logic Helper: Strict Conditional Check
+ *
+ * Branches types based on whether `Type` strictly extends `Constraint`,
+ * disabling the default distributive behavior of conditional types.
+ *
+ * Mechanism:
+ * 1. **Tuple Wrapping:** The syntax `[Type]` and `[Constraint]` wraps inputs
+ *    into tuples.
+ * 2. **Blocking Distribution:** TypeScript distributes conditional types over
+ *    unions (e.g., checking `A` and `B` separately in `A | B`). Tuples cannot
+ *    be distributed, forcing the compiler to treat `Type` as a single,
+ *    indivisible unit.
+ * 3. **Strict Comparison:** The check succeeds only if the entire `Type`
+ *    (including all union members or `undefined`) fits within `Constraint`.
+ *
+ * @example
+ * ```ts
+ * // Scenario: Checking if a Union extends a single type.
+ * type Input = string | number;
+ *
+ * // 1. Standard (Distributive) Behavior:
+ * //   (string extends string) | (number extends string)
+ * //   => 'Yes' | 'No'
+ * type Standard = Input extends string ? 'Yes' : 'No';
+ *
+ * // 2. Strict (Non-Distributive) Behavior via helper:
+ * //   [string | number] extends [string]
+ * //   => 'No' (The complete union does not extend string)
+ * type Result = IfStrictExtends<Input, string, 'Yes', 'No'>;
+ * ```
+ *
+ * @template Type       The candidate type to check.
+ * @template Constraint The target type to check against.
+ * @template True       Result if the check passes.
+ * @template False      Result if the check fails.
+ */
+type IfStrictExtends<Type, Constraint, True, False> = [Type] extends [
+    Constraint
+] ? True : False;
+
+/**
+ * Strategy A: Schema Exists
+ * Extracts the validated output type (O) from a Standard Schema.
+ *
+ * Logic:
+ * Infers the strict output type defined by the `StandardSchemaV1` interface.
+ */
+type SchemaValidatedProps<S> = S extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+/**
+ * Strategy B: No Schema
+ * Returns the raw props as optional (Passthrough).
+ *
+ * Rationale for Partial:
+ * When no schema is provided to enforce strictness or apply default values,
+ * the type assumes that authored MDX props may be incomplete subset of the
+ * full interface.
+ */
+type PassthroughProps<P> = Partial<P>;
+/**
+ * Main Utility: Output Inference
+ *
+ * Resolves the final prop type by selecting the appropriate strategy.
+ *
+ * Logic:
+ * Uses {@link IfStrictExtends} to determine if a valid schema is provided.
+ * 1. Schema provided -> Applies {@link SchemaValidatedProps} (Strict/Coerced).
+ * 2. No Schema       -> Applies {@link PassthroughProps} (Loose/Partial).
+ */
+type InferOutput<S extends ComponentSchema, Props extends BaseProps> = IfStrictExtends<S, StandardSchemaV1, SchemaValidatedProps<S>, PassthroughProps<Props>>;
+
+/**
+ * Function signature for the `derive` pipeline phase.
+ *
+ * Computes derived prop values based on the upstream input (either validated
+ * data or raw props) and emits them via the provided `set` callback.
+ *
+ * @template Props - Component props interface constraining what can be set.
+ * @template S - Schema type providing the input inference strategy.
+ *
+ * @param derivationInput - The input data for the derivation logic.
+ *                          - If `S` is a Schema: Coerced/Validated output.
+ *                          - If `S` is undefined: Raw `Partial<Props>`.
+ * @param set - Callback to emit derived key/value pairs. TypeScript enforces
+ *              that only keys from `Props` can be passed (excess property check).
+ *
+ * @example
+ * ```ts
+ * derive: (input, set) => {
+ *   set({
+ *     initialState: buildInitialState(input),
+ *     invalidProp: 'value' // Type Error: does not exist in type 'Partial<Props>'
+ *   });
+ * }
+ * ```
+ */
+type DeriveFunction<Props extends BaseProps, S extends ComponentSchema = undefined> = (derivationInput: InferOutput<S, Props>, set: (values: Partial<Props>) => void) => void;
+/**
+ * Base Configuration Shape: The available properties for a component rule.
+ *
+ * This type defines the raw structure (schema, derive, pruneKeys) where all
+ * fields are optional. It serves as the intermediate building block for the
+ * strict {@link ComponentRule} type, which enforces that at least one feature
+ * must be active.
+ */
+type ComponentRuleFeatures<Props extends BaseProps = BaseProps, S extends ComponentSchema = undefined> = {
+    /**
+     * The validation schema for this component.
+     *
+     * The generic parameter `S` captures the *specific* schema type provided
+     * (e.g. a specific Zod or Valibot instance), preserving exact output types
+     * downstream instead of widening them to the generic `StandardSchemaV1`.
+     *
+     * Type Behavior:
+     * - Constraint: `S` must satisfy the Standard Schema V1 interface.
+     * - Default: Defaults to `undefined`. If no schema is provided/inferred,
+     *   the rule operates in "Passthrough Mode" (derivation receives raw props).
+     *
+     * @example
+     *   `defineRule( { schema: MyZodSchema } )` → `S` is `MyZodSchema`
+     */
+    schema?: S;
+    /**
+     * Hook to compute new values based on the upstream input.
+     *
+     * This corresponds to the **`derive`** pipeline phase.
+     *
+     * Logic:
+     * Receives the input data (either schema-validated output or raw props) and
+     * a `set` callback to emit new prop values into the AST.
+     *
+     * @see {@link DeriveFunction} for the strict signature and usage examples.
+     */
+    derive?: DeriveFunction<Props, S>;
+    /**
+     * Explicitly removes specific root-level keys from the compiled output.
+     *
+     * Use this to strip "Source-Only" props—data that acts as an input for the
+     * build pipeline (e.g. used by `derive` to calculate other values) but
+     * is unnecessary in the final runtime execution.
+     *
+     * @example ['sourceData', 'legacyId']
+     */
+    pruneKeys?: readonly string[];
+};
+/**
+ * Public Definition: The strict contract for a component rule.
+ *
+ * Defines the configuration for validation (`schema`), data transformation
+ * (`derive`), and output cleanup (`pruneKeys`).
+ *
+ * Type Mechanics:
+ * 1. Enforcement:
+ *    Uses {@link RequireAtLeastOne} to ensure the rule is not empty
+ *    (it must define at least one active feature).
+ * 2. Safety:
+ *    Uses `NonNullable` to explicitly strip the `undefined` type that results
+ *    from mapping over entirely optional keys.
+ *    This guarantees that a `ComponentRule` is always a concrete object,
+ *    preventing "possibly undefined" errors in downstream processing.
+ */
+type ComponentRule<Props extends BaseProps = BaseProps, S extends ComponentSchema = undefined> = NonNullable<RequireAtLeastOne<ComponentRuleFeatures<Props, S>>>;
+/**
+ * A type-erased handle for a specific component rule.
+ *
+ * Purpose:
+ * Serves as the universal value type for storage. By abstracting specific `Props`
+ * into `BaseProps` (object), it allows heterogeneous rules (rules with different
+ * prop interfaces) to coexist within the same registry record.
+ *
+ * Guarantees:
+ * - Is a strict object (not undefined/null).
+ * - Has at least one active feature (schema, derive, or pruneKeys).
+ */
+type ComponentRuleBase = ComponentRule<BaseProps, ComponentSchema>;
+
+/**
+ * The generic constraint for rule inference.
+ *
+ * Purpose:
+ * Used by `defineRuleRegistry` to validate the input structure while allowing
+ * specific subtypes to pass through via generics.
+ *
+ * Structure:
+ * - Key (`string`):
+ *   Represents the component name (e.g., "CustomComponent").
+ *   Must match the identifier used in the JSX callsite.
+ * - Value ({@link ComponentRuleBase}):
+ *   The "Common Denominator" type for rules.
+ *   It allows rules with different specific prop interfaces to coexist in the
+ *   same object because they all satisfy the base contract of operating on an
+ *   `object`.
+ */
+type RuleRegistryConstraint = Record<string, ComponentRuleBase>;
+/**
+ * The concrete registry structure used by the plugin runtime.
+ *
+ * Purpose:
+ * Represents the lookup table used by the component resolver to match AST
+ * callsites. Specific prop interfaces are abstracted away at this stage;
+ * the runtime relies solely on the structural contract of {@link ComponentRuleBase}
+ * to ensure uniform and safe execution.
+ */
+type RuleMap = RuleRegistryConstraint;
+/**
+ * Creates the rule registry with strict type inference.
+ *
+ * Acts as an identity function that validates the input structure against
+ * {@link RuleRegistryConstraint} without widening the type. This preserves
+ * specific `Props` interfaces for downstream tooling while enforcing the
+ * registry contract.
+ *
+ * @template T - The specific registry shape (inferred).
+ * @param registry - The map of component names to rules.
+ * @returns The registry object with specific types preserved.
+ */
+declare function defineRuleRegistry<T extends RuleRegistryConstraint>(registry: T): T;
+/**
+ * Creates a typed rule definition helper for a specific component interface.
+ *
+ * Implementation Note:
+ * Utilizes a curried function pattern to allow explicit definition of the
+ * `Props` generic, while automatically inferring the `Schema` type from
+ * the provided configuration object.
+ *
+ * Usage:
+ * ```ts
+ * defineRule<MyProps>()({
+ *   schema: MySchema,
+ *   derive: (props, set) => { ... }
+ * })
+ * ```
+ */
+declare function defineRule<Props extends BaseProps>(): <S extends ComponentSchema = undefined>(rule: ComponentRule<Props, S>) => ComponentRule<Props, S>;
+type PluginOptions = {
+    /**
+     * Defines the behavior rules for each component.
+     * Maps component names to their validation, derivation, and pruning logic.
+     */
+    rules: RuleMap;
+    /**
+     * Controls whether validated values are written back to the compiled output.
+     *
+     * - `true`: Applies patches to the AST (Transpiler Mode).
+     * - `false`: Validates props without modifying the source (Linter / Dry-Run Mode).
+     *
+     * Scenario: Type Correction
+     * - Source:  `<Component zIndex="50" />`
+     * - Schema:  `zIndex` is a number.
+     * - `true`:  Updates AST to `zIndex={50}`.
+     * - `false`: Leaves AST as `zIndex="50"` (throws if validation fails).
+     *
+     * @default true
+     */
+    applyTransforms?: boolean;
+    /**
+     * Prop keys identifying **Dynamic Runtime Expressions** (e.g., `children`, `onClick`).
+     *
+     * Values for these keys are treated as executable code, not static data:
+     * - Extraction: Captured as-is; not resolved to static data.
+     * - Validation: Passed through via placeholders.
+     * - Patching: Protected (traversal stops; the expression remains verbatim).
+     *
+     * Use this for properties containing variables, functions, or JSX elements.
+     *
+     * @default ['children']
+     */
+    preservedKeys?: readonly string[];
+};
+
+declare const recmaStaticRefiner: Plugin<[PluginOptions], Program>;
+
+export { defineRule, defineRuleRegistry, recmaStaticRefiner };