@openrewrite/rewrite 8.66.0 → 8.66.2

package/dist/javascript/templating/capture.d.ts

@@ -0,0 +1,293 @@
+import { Cursor } from '../..';
+import { J, Type } from '../../java';
+import { Any, Capture, CaptureOptions, ConstraintFunction, TemplateParam, VariadicOptions } from './types';
+/**
+ * Combines multiple constraints with AND logic.
+ * All constraints must return true for the combined constraint to pass.
+ *
+ * @example
+ * const largeEvenNumber = capture('n', {
+ *     constraint: and(
+ *         (node) => typeof node.value === 'number',
+ *         (node) => node.value > 100,
+ *         (node) => node.value % 2 === 0
+ *     )
+ * });
+ */
+export declare function and<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]): (node: T, cursor?: Cursor) => boolean;
+/**
+ * Combines multiple constraints with OR logic.
+ * At least one constraint must return true for the combined constraint to pass.
+ *
+ * @example
+ * const stringOrNumber = capture('value', {
+ *     constraint: or(
+ *         (node) => node.kind === J.Kind.Literal && typeof node.value === 'string',
+ *         (node) => node.kind === J.Kind.Literal && typeof node.value === 'number'
+ *     )
+ * });
+ */
+export declare function or<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]): (node: T, cursor?: Cursor) => boolean;
+/**
+ * Negates a constraint.
+ * Returns true when the constraint returns false, and vice versa.
+ *
+ * @example
+ * const notString = capture('value', {
+ *     constraint: not((node) => typeof node.value === 'string')
+ * });
+ */
+export declare function not<T>(constraint: (node: T, cursor?: Cursor) => boolean): (node: T, cursor?: Cursor) => boolean;
+export declare const CAPTURE_NAME_SYMBOL: unique symbol;
+export declare const CAPTURE_VARIADIC_SYMBOL: unique symbol;
+export declare const CAPTURE_CONSTRAINT_SYMBOL: unique symbol;
+export declare const CAPTURE_CAPTURING_SYMBOL: unique symbol;
+export declare const CAPTURE_TYPE_SYMBOL: unique symbol;
+export declare const RAW_CODE_SYMBOL: unique symbol;
+export declare class CaptureImpl<T = any> implements Capture<T> {
+    readonly name: string;
+    [CAPTURE_NAME_SYMBOL]: string;
+    [CAPTURE_VARIADIC_SYMBOL]: VariadicOptions | undefined;
+    [CAPTURE_CONSTRAINT_SYMBOL]: ConstraintFunction<T> | undefined;
+    [CAPTURE_CAPTURING_SYMBOL]: boolean;
+    [CAPTURE_TYPE_SYMBOL]: string | Type | undefined;
+    constructor(name: string, options?: CaptureOptions<T>, capturing?: boolean);
+    getName(): string;
+    isVariadic(): boolean;
+    getVariadicOptions(): VariadicOptions | undefined;
+    getConstraint(): ConstraintFunction<T> | undefined;
+    isCapturing(): boolean;
+    getType(): string | Type | undefined;
+}
+export declare class TemplateParamImpl<T = any> implements TemplateParam<T> {
+    readonly name: string;
+    constructor(name: string);
+    getName(): string;
+}
+/**
+ * Represents a property access on a captured value.
+ * When you access a property on a Capture (e.g., method.name), you get a CaptureValue
+ * that knows how to resolve that property from the matched values.
+ */
+export declare class CaptureValue {
+    readonly rootCapture: Capture;
+    readonly propertyPath: string[];
+    readonly arrayOperation?: {
+        type: "index" | "slice" | "length";
+        args?: number[];
+    } | undefined;
+    constructor(rootCapture: Capture, propertyPath: string[], arrayOperation?: {
+        type: "index" | "slice" | "length";
+        args?: number[];
+    } | undefined);
+    /**
+     * Resolves this capture value by looking up the root capture in the values map
+     * and navigating through the property path.
+     */
+    resolve(values: Pick<Map<string, J | J[]>, 'get'>): any;
+    /**
+     * Checks if this CaptureValue will resolve to an array that should be expanded.
+     */
+    isArrayExpansion(): boolean;
+}
+export declare function capture<T = any>(options: CaptureOptions<T> & {
+    variadic?: never;
+}): Capture<T> & T;
+export declare function capture<T = any>(options: {
+    name?: string;
+    variadic: true | VariadicOptions;
+    constraint?: ConstraintFunction<T[]>;
+    min?: number;
+    max?: number;
+}): Capture<T[]> & T[];
+export declare function capture<T = any>(name?: string): Capture<T> & T;
+export declare namespace capture {
+    var nextUnnamedId: number;
+}
+/**
+ * Creates a non-capturing pattern match for use in patterns.
+ *
+ * Use `any()` when you need to match AST structure without binding the matched value to a name.
+ * This is useful for validation patterns where you care about structure but not the specific values.
+ *
+ * **Key Differences from `capture()`:**
+ * - `any()` returns `Any<T>` type (not `Capture<T>`)
+ * - Cannot be used in templates (TypeScript compiler prevents this)
+ * - Does not bind matched values (more memory efficient for patterns)
+ * - Supports same features: constraints, variadic matching
+ *
+ * @template T The expected type of the matched AST node (for TypeScript autocomplete and constraints)
+ * @param options Optional configuration (variadic, constraint)
+ * @returns An Any object that matches patterns without capturing
+ *
+ * @example
+ * // Match any single argument without capturing
+ * const pat = pattern`foo(${any()})`;
+ *
+ * @example
+ * // Match with constraint validation
+ * const numericArg = any<J.Literal>({
+ *     constraint: (node) => typeof node.value === 'number'
+ * });
+ * const pat = pattern`process(${numericArg})`;
+ *
+ * @example
+ * // Variadic any - match zero or more without capturing
+ * const rest = any({ variadic: true });
+ * const first = capture('first');
+ * const pat = pattern`foo(${first}, ${rest})`;
+ *
+ * @example
+ * // Mixed with captures - capture some, ignore others
+ * const important = capture('important');
+ * const pat = pattern`
+ *     if (${any()}) {
+ *         ${important}
+ *     }
+ * `;
+ *
+ * @example
+ * // Variadic with constraints
+ * const numericArgs = any<J.Literal>({
+ *     variadic: true,
+ *     constraint: (nodes) => nodes.every(n => typeof n.value === 'number')
+ * });
+ * const pat = pattern`sum(${numericArgs})`;
+ */
+export declare function any<T = any>(options: {
+    constraint: ConstraintFunction<T>;
+} & {
+    variadic?: never;
+}): Any<T> & T;
+export declare function any<T = any>(options: {
+    variadic: true | VariadicOptions;
+    constraint?: ConstraintFunction<T[]>;
+    min?: number;
+    max?: number;
+}): Any<T[]> & T[];
+export declare function any<T = any>(options?: CaptureOptions<T>): Any<T> & T;
+export declare namespace any {
+    var nextAnonId: number;
+}
+/**
+ * Creates a parameter specification for use in standalone templates (not used with patterns).
+ *
+ * Use `param()` when creating templates that are not used with pattern matching.
+ * Use `capture()` when the template works with a pattern.
+ *
+ * @template T The expected type of the parameter value (for TypeScript autocomplete only)
+ * @param name Optional name for the parameter. If not provided, an auto-generated name is used.
+ * @returns A TemplateParam object (simpler than Capture, no property access support)
+ *
+ * @remarks
+ * **When to use `param()` vs `capture()`:**
+ *
+ * - Use `param()` in **standalone templates** (no pattern matching involved)
+ * - Use `capture()` in **patterns** and templates used with patterns
+ *
+ * **Key Differences:**
+ * - `TemplateParam` is simpler - no property access proxy overhead
+ * - `Capture` supports property access (e.g., `capture('x').name.simpleName`)
+ * - Both work in templates, but `param()` makes intent clearer for standalone use
+ *
+ * @example
+ * // ✅ GOOD: Use param() for standalone templates
+ * const value = param<J.Literal>('value');
+ * const tmpl = template`return ${value} * 2;`;
+ * await tmpl.apply(cursor, node, new Map([['value', someLiteral]]));
+ *
+ * @example
+ * // ✅ GOOD: Use capture() with patterns
+ * const value = capture('value');
+ * const pat = pattern`foo(${value})`;
+ * const tmpl = template`bar(${value})`;  // capture() makes sense here
+ *
+ * @example
+ * // ⚠️ CONFUSING: Using capture() in standalone template
+ * const value = capture('value');
+ * template`return ${value} * 2;`;  // "Capturing" what? There's no pattern!
+ *
+ * @example
+ * // ❌ WRONG: param() doesn't support property access
+ * const node = param<J.MethodInvocation>('invocation');
+ * template`console.log(${node.name})`  // Error! Use capture() for property access
+ */
+export declare function param<T = any>(name?: string): TemplateParam<T>;
+/**
+ * Represents raw code that should be inserted verbatim into templates at construction time.
+ * This is useful for dynamic code generation where the code structure is determined at runtime.
+ */
+export declare class RawCode {
+    readonly code: string;
+    [RAW_CODE_SYMBOL]: boolean;
+    constructor(code: string);
+}
+/**
+ * Creates a raw code specification for inserting literal code strings into templates.
+ *
+ * Use `raw()` when you need to insert code that is generated dynamically (e.g., from recipe options,
+ * computed field names, or programmatic string manipulation) directly into a template at construction time.
+ *
+ * The string is spliced into the template before parsing, so it becomes part of the template's AST.
+ * This is different from `param()` or `capture()` which are placeholders replaced during application.
+ *
+ * @param code The code string to insert verbatim into the template
+ * @returns A RawCode object that will be spliced into the template
+ *
+ * @remarks
+ * **When to use `raw()` vs `param()` vs `capture()`:**
+ *
+ * - Use `raw()` when you have a **code string** to insert at **template construction time**
+ * - Use `param()` when you have an **AST node** to substitute at **template application time**
+ * - Use `capture()` when working with **pattern matching** and need to reference matched values
+ *
+ * **Safety Considerations:**
+ * - No validation is performed on the code string
+ * - The code must be syntactically valid at the position where it's inserted
+ * - Recipe authors are trusted to provide valid code
+ *
+ * @example
+ * // Recipe option determines the log level
+ * class MyRecipe extends Recipe {
+ *     @Option
+ *     logLevel: string = "info";
+ *
+ *     getVisitor() {
+ *         // Template constructed with dynamic method name
+ *         const replacement = template`logger.${raw(this.logLevel)}(${_('msg')})`;
+ *         // Produces: logger.info(...) or logger.warn(...) etc.
+ *     }
+ * }
+ *
+ * @example
+ * // Build object literal from collected field names
+ * const fields = ["userId", "timestamp", "status"];
+ * template`{ ${raw(fields.join(', '))} }`
+ * // Produces: { userId, timestamp, status }
+ *
+ * @example
+ * // Dynamic import path
+ * const modulePath = "./utils";
+ * template`import { helper } from ${raw(`'${modulePath}'`)}`
+ * // Produces: import { helper } from './utils'
+ *
+ * @example
+ * // Configurable operator
+ * const operator = ">=";
+ * template`${_('value')} ${raw(operator)} threshold`
+ * // Produces: value >= threshold
+ */
+export declare function raw(code: string): RawCode;
+/**
+ * Concise alias for `capture`. Works well for inline captures in patterns and templates.
+ *
+ * @param name Optional name for the capture. If not provided, an auto-generated name is used.
+ * @returns A Capture object
+ *
+ * @example
+ * // Inline captures with _ alias
+ * pattern`isDate(${_('dateArg')})`
+ * template`${_('dateArg')} instanceof Date`
+ */
+export declare const _: typeof capture;
+//# sourceMappingURL=capture.d.ts.map

package/dist/javascript/templating/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/javascript/templating/capture.ts"],"names":[],"mappings":"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"}