oxlint-plugin-effect 0.2.0 → 0.2.2

package/src/vendor/effect-oxlint/Rule.ts

@@ -1,548 +0,0 @@
-/**
- * Core rule builder for Effect-first oxlint rules.
- *
- * `Rule.define` is the primary entry point. It produces a standard
- * `CreateRule` that oxlint can consume, while letting rule authors
- * write fully effectful create generators and visitor handlers.
- *
- * @since 0.1.0
- */
-import type { CreateRule, ESTree, RuleDocs, RuleMeta } from '@oxlint/plugins';
-import * as Arr from 'effect/Array';
-import * as Effect from 'effect/Effect';
-import * as Option from 'effect/Option';
-import * as P from 'effect/Predicate';
-import * as Schema from 'effect/Schema';
-
-import { pipe } from 'effect/Function';
-
-import * as AST from './AST.ts';
-import { make as makeDiagnostic } from './Diagnostic.ts';
-import { fromOxlintContext, RuleContext } from './RuleContext.ts';
-import type { EffectVisitor } from './Visitor.ts';
-import { merge as mergeVisitors, toOxlintVisitor } from './Visitor.ts';
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Extract the identifier name from a `NewExpression` callee.
- *
- * `AST.calleeName` only accepts `CallExpression`. This mirrors the
- * same logic for `NewExpression.callee`.
- *
- * @internal
- */
-const newExprCalleeName = (callee: ESTree.Expression): Option.Option<string> =>
-	callee.type === 'Identifier' && 'name' in callee && P.isString(callee.name)
-		? Option.some(callee.name)
-		: Option.none();
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * Configuration object for `Rule.define`.
- *
- * @since 0.1.0
- */
-export interface RuleConfig<Options = undefined> {
-	/** Rule name (used for tracing spans). */
-	readonly name: string;
-	/** Oxlint rule metadata. */
-	readonly meta: RuleMeta;
-	/**
-	 * Optional Schema for rule options.
-	 *
-	 * When provided, the first element of the raw JSON options array
-	 * is decoded at `create` time against this schema.
-	 */
-	readonly options?: Schema.Decoder<Options> | undefined;
-	/**
-	 * The create generator.
-	 *
-	 * Receives decoded options and returns an `EffectVisitor`.
-	 * Runs inside an Effect context where `RuleContext` is available.
-	 *
-	 * May `yield* Ref.make(...)` for state, `yield* RuleContext` for
-	 * context access, and return a visitor built with `Visitor.*` helpers.
-	 */
-	readonly create: (
-		options: Options
-	) => Effect.gen.Return<EffectVisitor, never, RuleContext>;
-}
-
-// ---------------------------------------------------------------------------
-// Builder
-// ---------------------------------------------------------------------------
-
-/**
- * Define an Effect-first oxlint lint rule.
- *
- * The `create` generator runs once per file via `Effect.runSync`.
- * Each visitor handler is also executed via `Effect.runSync` per node.
- * `Ref`-based state created in `create` persists across handler calls
- * via closure.
- *
- * `Effect.runSync` is used here at the runtime boundary — the bridge
- * between oxlint's synchronous plugin API and our Effect world.
- *
- * @since 0.1.0
- */
-export const define = <Options = undefined>(
-	config: RuleConfig<Options>
-): CreateRule => ({
-	meta: config.meta,
-	create(oxlintContext) {
-		const ruleCtx = fromOxlintContext(oxlintContext);
-
-		// Runtime boundary: execute effects with RuleContext provided.
-		// This is the FFI bridge between oxlint's sync API and Effect.
-		const run = <A>(effect: Effect.Effect<A, never, RuleContext>): A =>
-			Effect.runSync(Effect.provideService(effect, RuleContext, ruleCtx));
-
-		// Decode options from the raw JSON array.
-		// When no schema is configured, `Options` defaults to `undefined`.
-		const decodeOptions = (): Options => {
-			const schema = config.options;
-			if (schema === undefined) return undefined as Options;
-			return Schema.decodeUnknownSync(schema)(oxlintContext.options[0]);
-		};
-		const options = run(Effect.sync(decodeOptions));
-
-		// Run the create generator to set up Refs and get the visitor map.
-		// TypedEffectVisitor → EffectVisitor: the typed keys provide
-		// narrowed nodes to callers, but at runtime all handlers receive
-		// the same ESTree.Node values. The variance mismatch is safe
-		// because oxlint guarantees the node type matches the key.
-		const effectVisitor = run(
-			Effect.gen(() => config.create(options))
-		) as EffectVisitor;
-
-		// Wrap each handler: Effect<void> → plain () => void
-		return toOxlintVisitor(effectVisitor, run);
-	}
-});
-
-// ---------------------------------------------------------------------------
-// Metadata helper
-// ---------------------------------------------------------------------------
-
-/**
- * Which Effect version a rule applies to.
- *
- * Stored on `meta.docs.effectVersion` so preset authors can filter rules
- * per project. Default `both`, meaning the rule is version-agnostic.
- *
- * @since 0.2.0
- */
-export type EffectVersion = 'v3' | 'v4' | 'both';
-
-/**
- * Build `RuleMeta` with sensible defaults.
- *
- * @since 0.1.0
- */
-export const meta = (opts: {
-	readonly type: 'problem' | 'suggestion' | 'layout';
-	readonly description: string;
-	readonly fixable?: 'code' | 'whitespace' | undefined;
-	readonly hasSuggestions?: boolean | undefined;
-	readonly messages?: Record<string, string> | undefined;
-	readonly docs?: RuleDocs | undefined;
-	readonly effectVersion?: EffectVersion | undefined;
-}): RuleMeta => ({
-	type: opts.type,
-	...(opts.fixable !== undefined ? { fixable: opts.fixable } : {}),
-	...(opts.hasSuggestions !== undefined
-		? { hasSuggestions: opts.hasSuggestions }
-		: {}),
-	...(opts.messages !== undefined ? { messages: opts.messages } : {}),
-	docs: {
-		description: opts.description,
-		effectVersion: opts.effectVersion ?? 'both',
-		...opts.docs
-	}
-});
-
-// ---------------------------------------------------------------------------
-// Convenience rule factories (common patterns)
-// ---------------------------------------------------------------------------
-
-/**
- * Create a rule that bans `obj.prop` member expression access.
- *
- * Replaces the common `memberExprRule` utility pattern.
- *
- * @since 0.1.0
- */
-export const banMember = (
-	obj: string,
-	prop: string | ReadonlyArray<string>,
-	opts: {
-		readonly message: string;
-		readonly meta?:
-			| { readonly type?: 'problem' | 'suggestion'; readonly effectVersion?: EffectVersion }
-			| undefined;
-	}
-): CreateRule =>
-	define({
-		name: `ban-${obj}-${P.isString(prop) ? prop : Arr.join(prop, '-')}`,
-		meta: meta({
-			type: opts.meta?.type ?? 'suggestion',
-			description: opts.message,
-			effectVersion: opts.meta?.effectVersion
-		}),
-		create: function* () {
-			const ctx = yield* RuleContext;
-			return {
-				MemberExpression: (node: ESTree.Node) =>
-					pipe(
-						AST.narrow(node, 'MemberExpression'),
-						Option.flatMap(AST.matchMember(obj, prop)),
-						Option.match({
-							onNone: () => Effect.void,
-							onSome: (matched) =>
-								ctx.report(
-									makeDiagnostic({
-										node: matched,
-										message: opts.message
-									})
-								)
-						})
-					)
-			};
-		}
-	});
-
-/**
- * Create a rule that bans imports matching a source string or predicate.
- *
- * Replaces the common `importRule` utility pattern.
- *
- * @since 0.1.0
- */
-export const banImport = (
-	source: string | ((source: string) => boolean),
-	opts: {
-		readonly message: string;
-		readonly meta?:
-			| { readonly type?: 'problem' | 'suggestion'; readonly effectVersion?: EffectVersion }
-			| undefined;
-	}
-): CreateRule =>
-	define({
-		name: 'ban-import',
-		meta: meta({
-			type: opts.meta?.type ?? 'suggestion',
-			description: opts.message,
-			effectVersion: opts.meta?.effectVersion
-		}),
-		create: function* () {
-			const ctx = yield* RuleContext;
-			return {
-				ImportDeclaration: (node: ESTree.Node) =>
-					pipe(
-						AST.narrow(node, 'ImportDeclaration'),
-						Option.flatMap(AST.matchImport(source)),
-						Option.match({
-							onNone: () => Effect.void,
-							onSome: (matched) =>
-								ctx.report(
-									makeDiagnostic({
-										node: matched,
-										message: opts.message
-									})
-								)
-						})
-					)
-			};
-		}
-	});
-
-/**
- * Create a rule that bans bare identifier call expressions.
- *
- * Matches `CallExpression` nodes whose callee is an identifier in
- * the given list (e.g. `fetch()`, `useState()`, `readFileSync()`).
- *
- * @example
- * ```ts
- * // Ban a single call
- * Rule.banCallOf('fetch', { message: 'Use Effect HTTP client' })
- *
- * // Ban multiple calls
- * Rule.banCallOf(['useState', 'useEffect'], { message: 'Use Effect' })
- * ```
- *
- * @since 0.2.0
- */
-export const banCallOf = (
-	name: string | ReadonlyArray<string>,
-	opts: {
-		readonly message: string;
-		readonly meta?:
-			| { readonly type?: 'problem' | 'suggestion'; readonly effectVersion?: EffectVersion }
-			| undefined;
-	}
-): CreateRule => {
-	const names = P.isString(name) ? [name] : name;
-	return define({
-		name: `ban-call-${Arr.join(names, '-')}`,
-		meta: meta({
-			type: opts.meta?.type ?? 'suggestion',
-			description: opts.message,
-			effectVersion: opts.meta?.effectVersion
-		}),
-		create: function* () {
-			const ctx = yield* RuleContext;
-			return {
-				CallExpression: (node: ESTree.Node) =>
-					pipe(
-						AST.narrow(node, 'CallExpression'),
-						Option.flatMap(AST.calleeName),
-						Option.filter((n) => Arr.contains(names, n)),
-						Option.match({
-							onNone: () => Effect.void,
-							onSome: () =>
-								ctx.report(
-									makeDiagnostic({
-										node,
-										message: opts.message
-									})
-								)
-						})
-					)
-			};
-		}
-	});
-};
-
-/**
- * Create a rule that bans `new` expressions with the given callee name.
- *
- * Matches `NewExpression` nodes whose callee is an identifier in
- * the given list (e.g. `new Date()`, `new Error()`).
- *
- * @example
- * ```ts
- * // Ban a single constructor
- * Rule.banNewExpr('Date', { message: 'Use Clock service' })
- *
- * // Ban multiple constructors
- * Rule.banNewExpr(['Error', 'TypeError'], { message: 'Use tagged errors' })
- * ```
- *
- * @since 0.2.0
- */
-export const banNewExpr = (
-	name: string | ReadonlyArray<string>,
-	opts: {
-		readonly message: string;
-		readonly meta?:
-			| { readonly type?: 'problem' | 'suggestion'; readonly effectVersion?: EffectVersion }
-			| undefined;
-	}
-): CreateRule => {
-	const names = P.isString(name) ? [name] : name;
-	return define({
-		name: `ban-new-${Arr.join(names, '-')}`,
-		meta: meta({
-			type: opts.meta?.type ?? 'suggestion',
-			description: opts.message,
-			effectVersion: opts.meta?.effectVersion
-		}),
-		create: function* () {
-			const ctx = yield* RuleContext;
-			return {
-				NewExpression: (node: ESTree.Node) =>
-					pipe(
-						AST.narrow(node, 'NewExpression'),
-						Option.flatMap((n) => newExprCalleeName(n.callee)),
-						Option.filter((n) => Arr.contains(names, n)),
-						Option.match({
-							onNone: () => Effect.void,
-							onSome: () =>
-								ctx.report(
-									makeDiagnostic({
-										node,
-										message: opts.message
-									})
-								)
-						})
-					)
-			};
-		}
-	});
-};
-
-/**
- * Create a rule that bans a specific statement type.
- *
- * @since 0.1.0
- */
-export const banStatement = (
-	nodeType: string,
-	opts: {
-		readonly message: string;
-		readonly meta?:
-			| { readonly type?: 'problem' | 'suggestion'; readonly effectVersion?: EffectVersion }
-			| undefined;
-	}
-): CreateRule =>
-	define({
-		name: `ban-${nodeType}`,
-		meta: meta({
-			type: opts.meta?.type ?? 'suggestion',
-			description: opts.message,
-			effectVersion: opts.meta?.effectVersion
-		}),
-		create: function* () {
-			const ctx = yield* RuleContext;
-			return {
-				[nodeType]: (node: ESTree.Node) =>
-					ctx.report(makeDiagnostic({ node, message: opts.message }))
-			};
-		}
-	});
-
-// ---------------------------------------------------------------------------
-// Multi-ban combinator
-// ---------------------------------------------------------------------------
-
-/**
- * A single ban specification. Each spec carries its own message so
- * diagnostics are specific to the exact pattern matched.
- *
- * @since 0.3.0
- */
-export type BanSpec =
-	| { readonly type: 'member'; readonly object: string; readonly property: string | ReadonlyArray<string>; readonly message: string }
-	| { readonly type: 'call'; readonly name: string | ReadonlyArray<string>; readonly message: string }
-	| { readonly type: 'new'; readonly name: string | ReadonlyArray<string>; readonly message: string }
-	| { readonly type: 'import'; readonly source: string | ((source: string) => boolean); readonly message: string }
-	| { readonly type: 'statement'; readonly nodeType: string; readonly message: string };
-
-/**
- * Create a rule that bans multiple patterns, each with its own message.
- *
- * @example
- * ```ts
- * Rule.banMultiple({
- *   name: "no-global-date",
- *   meta: { type: "suggestion" },
- *   specs: [
- *     { type: "new", name: "Date", message: "Avoid new Date(). Use Clock service." },
- *     { type: "member", object: "Date", property: "now", message: "Avoid Date.now(). Use Clock service." },
- *   ],
- * })
- * ```
- *
- * @since 0.3.0
- */
-export const banMultiple = (config: {
-	readonly name: string;
-	readonly meta?:
-		| { readonly type?: 'problem' | 'suggestion'; readonly effectVersion?: EffectVersion }
-		| undefined;
-	readonly specs: ReadonlyArray<BanSpec>;
-}): CreateRule => {
-	const description = config.specs.map((s) => s.message).join(' ');
-	return define({
-		name: config.name,
-		meta: meta({
-			type: config.meta?.type ?? 'suggestion',
-			description,
-			effectVersion: config.meta?.effectVersion
-		}),
-		create: function* () {
-			const ctx = yield* RuleContext;
-
-			const visitors: Array<EffectVisitor> = [];
-
-			for (const spec of config.specs) {
-				switch (spec.type) {
-					case 'member': {
-						const report = (node: ESTree.Node) =>
-							ctx.report(makeDiagnostic({ node, message: spec.message }));
-						visitors.push({
-							MemberExpression: (node: ESTree.Node) =>
-								pipe(
-									AST.narrow(node, 'MemberExpression'),
-									Option.flatMap(AST.matchMember(spec.object, spec.property)),
-									Option.match({
-										onNone: () => Effect.void,
-										onSome: (matched) => report(matched)
-									})
-								)
-						});
-						break;
-					}
-					case 'call': {
-						const names = P.isString(spec.name) ? [spec.name] : spec.name;
-						const report = (node: ESTree.Node) =>
-							ctx.report(makeDiagnostic({ node, message: spec.message }));
-						visitors.push({
-							CallExpression: (node: ESTree.Node) =>
-								pipe(
-									AST.narrow(node, 'CallExpression'),
-									Option.flatMap(AST.calleeName),
-									Option.filter((n) => Arr.contains(names, n)),
-									Option.match({
-										onNone: () => Effect.void,
-										onSome: () => report(node)
-									})
-								)
-						});
-						break;
-					}
-					case 'new': {
-						const names = P.isString(spec.name) ? [spec.name] : spec.name;
-						const report = (node: ESTree.Node) =>
-							ctx.report(makeDiagnostic({ node, message: spec.message }));
-						visitors.push({
-							NewExpression: (node: ESTree.Node) =>
-								pipe(
-									AST.narrow(node, 'NewExpression'),
-									Option.flatMap((n) => newExprCalleeName(n.callee)),
-									Option.filter((n) => Arr.contains(names, n)),
-									Option.match({
-										onNone: () => Effect.void,
-										onSome: () => report(node)
-									})
-								)
-						});
-						break;
-					}
-					case 'import': {
-						const report = (node: ESTree.Node) =>
-							ctx.report(makeDiagnostic({ node, message: spec.message }));
-						visitors.push({
-							ImportDeclaration: (node: ESTree.Node) =>
-								pipe(
-									AST.narrow(node, 'ImportDeclaration'),
-									Option.flatMap(AST.matchImport(spec.source)),
-									Option.match({
-										onNone: () => Effect.void,
-										onSome: (matched) => report(matched)
-									})
-								)
-						});
-						break;
-					}
-					case 'statement': {
-						visitors.push({
-							[spec.nodeType]: (node: ESTree.Node) =>
-								ctx.report(makeDiagnostic({ node, message: spec.message }))
-						});
-						break;
-					}
-				}
-			}
-
-			return mergeVisitors(...visitors);
-		}
-	});
-};

package/src/vendor/effect-oxlint/RuleContext.ts

@@ -1,144 +0,0 @@
-/**
- * Effect service wrapping the oxlint rule context.
- *
- * Provides effectful access to the linting context — file info,
- * source code queries, diagnostics reporting, and rule options.
- *
- * @since 0.1.0
- */
-import type {
-	Context as OxlintContext,
-	Diagnostic as OxlintDiagnostic,
-	ESTree,
-	LanguageOptions,
-	Options,
-	Settings,
-	SourceCode
-} from '@oxlint/plugins';
-import * as Context from 'effect/Context';
-import * as Effect from 'effect/Effect';
-
-// ---------------------------------------------------------------------------
-// Service
-// ---------------------------------------------------------------------------
-
-/**
- * The lint rule context, provided as an Effect service.
- *
- * Available inside `Rule.define`'s `create` generator and every
- * visitor handler via `yield* RuleContext`.
- *
- * @since 0.1.0
- */
-export class RuleContext extends Context.Service<
-	RuleContext,
-	{
-		/** Report a lint diagnostic for the current file. */
-		readonly report: (diagnostic: OxlintDiagnostic) => Effect.Effect<void>;
-		/** Rule ID in `plugin/rule` form. */
-		readonly id: string;
-		/** Absolute path of the file being linted. */
-		readonly filename: string;
-		/** Current working directory. */
-		readonly cwd: string;
-		/** Raw rule options (JSON values). */
-		readonly options: Readonly<Options>;
-		/** Source code access (tokens, comments, text, scope, etc.). */
-		readonly sourceCode: SourceCode;
-		/** Language / parser options for this file. */
-		readonly languageOptions: Readonly<LanguageOptions>;
-		/** Shared settings from the oxlint config. */
-		readonly settings: Readonly<Settings>;
-	}
->()('effect-oxlint/RuleContext') {}
-
-// ---------------------------------------------------------------------------
-// Constructor from raw oxlint Context
-// ---------------------------------------------------------------------------
-
-/**
- * Build a `RuleContext` value from the raw oxlint `Context`.
- *
- * @internal
- */
-export const fromOxlintContext = (ctx: OxlintContext): RuleContext['Service'] =>
-	RuleContext.of({
-		report: (diagnostic) => Effect.sync(() => ctx.report(diagnostic)),
-		id: ctx.id,
-		filename: ctx.filename,
-		cwd: ctx.cwd,
-		options: ctx.options,
-		sourceCode: ctx.sourceCode,
-		languageOptions: ctx.languageOptions,
-		settings: ctx.settings
-	});
-
-// ---------------------------------------------------------------------------
-// Convenience accessors (yield*-able inside handlers)
-// ---------------------------------------------------------------------------
-
-/**
- * Effectful access to the rule ID.
- *
- * @since 0.1.0
- */
-export const id: Effect.Effect<string, never, RuleContext> = Effect.service(
-	RuleContext
-).pipe(Effect.map((ctx) => ctx.id));
-
-/**
- * Effectful access to the filename of the file being linted.
- *
- * @since 0.1.0
- */
-export const filename: Effect.Effect<string, never, RuleContext> =
-	Effect.service(RuleContext).pipe(Effect.map((ctx) => ctx.filename));
-
-/**
- * Effectful access to the working directory.
- *
- * @since 0.1.0
- */
-export const cwd: Effect.Effect<string, never, RuleContext> = Effect.service(
-	RuleContext
-).pipe(Effect.map((ctx) => ctx.cwd));
-
-/**
- * Effectful access to the SourceCode object.
- *
- * @since 0.1.0
- */
-export const sourceCode: Effect.Effect<SourceCode, never, RuleContext> =
-	Effect.service(RuleContext).pipe(Effect.map((ctx) => ctx.sourceCode));
-
-/**
- * Effectful access to the raw source text.
- *
- * @since 0.1.0
- */
-export const text: Effect.Effect<string, never, RuleContext> = Effect.service(
-	RuleContext
-).pipe(Effect.map((ctx) => ctx.sourceCode.text));
-
-/**
- * Effectful access to the AST root node.
- *
- * @since 0.1.0
- */
-export const ast: Effect.Effect<ESTree.Program, never, RuleContext> =
-	Effect.service(RuleContext).pipe(Effect.map((ctx) => ctx.sourceCode.ast));
-
-/**
- * Report a lint diagnostic.
- *
- * Shorthand so handlers can `yield* RuleContext.report(diagnostic)`
- * without first resolving the full service.
- *
- * @since 0.1.0
- */
-export const report = (
-	diagnostic: OxlintDiagnostic
-): Effect.Effect<void, never, RuleContext> =>
-	Effect.service(RuleContext).pipe(
-		Effect.flatMap((ctx) => ctx.report(diagnostic))
-	);