oxlint-plugin-effect 0.0.0

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

@@ -0,0 +1,144 @@
+/**
+ * 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))
+	);

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

@@ -0,0 +1,177 @@
+/**
+ * Scope analysis helpers for Effect-first lint rules.
+ *
+ * Wraps oxlint's scope manager types (`Scope`, `Variable`, `Reference`,
+ * `Definition`) with `Option`-returning lookups and convenience predicates.
+ *
+ * For scope queries that require `SourceCode` access (e.g. `getScope`,
+ * `getDeclaredVariables`), see the `SourceCode` module which provides
+ * effectful wrappers.
+ *
+ * @since 0.2.0
+ */
+import type {
+	Reference,
+	Scope as OxlintScope,
+	Variable
+} from '@oxlint/plugins';
+import * as Arr from 'effect/Array';
+import { dual, pipe } from 'effect/Function';
+import * as Option from 'effect/Option';
+
+// ---------------------------------------------------------------------------
+// Variable lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a variable by name in a scope.
+ *
+ * Searches the scope's `set` (a `Map<string, Variable>`).
+ *
+ * @since 0.2.0
+ */
+export const findVariable: {
+	(name: string): (scope: OxlintScope) => Option.Option<Variable>;
+	(scope: OxlintScope, name: string): Option.Option<Variable>;
+} = dual(
+	2,
+	(scope: OxlintScope, name: string): Option.Option<Variable> =>
+		Option.fromNullishOr(scope.set.get(name))
+);
+
+/**
+ * Find a variable by name, walking up the scope chain.
+ *
+ * Starts at the given scope and checks each `upper` scope until found
+ * or the global scope is exhausted.
+ *
+ * @since 0.2.0
+ */
+export const findVariableUp: {
+	(name: string): (scope: OxlintScope) => Option.Option<Variable>;
+	(scope: OxlintScope, name: string): Option.Option<Variable>;
+} = dual(2, (scope: OxlintScope, name: string): Option.Option<Variable> => {
+	const walk = (current: OxlintScope): Option.Option<Variable> =>
+		pipe(
+			Option.fromNullishOr(current.set.get(name)),
+			Option.orElse(() =>
+				pipe(
+					Option.fromNullishOr(current.upper),
+					Option.flatMap((parent) => walk(parent))
+				)
+			)
+		);
+	return walk(scope);
+});
+
+// ---------------------------------------------------------------------------
+// Variable predicates
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a variable has any read references.
+ *
+ * A variable is considered "used" if at least one reference reads it.
+ *
+ * @since 0.2.0
+ */
+export const isUsed = (variable: Variable): boolean =>
+	Arr.some(variable.references, (ref) => ref.isRead());
+
+/**
+ * Check whether a variable has any write references.
+ *
+ * @since 0.2.0
+ */
+export const isWritten = (variable: Variable): boolean =>
+	Arr.some(variable.references, (ref) => ref.isWrite());
+
+/**
+ * Check whether a variable is only read (no writes).
+ *
+ * @since 0.2.0
+ */
+export const isReadOnly = (variable: Variable): boolean =>
+	Arr.some(variable.references, (ref) => ref.isReadOnly());
+
+// ---------------------------------------------------------------------------
+// Reference helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all references for a variable.
+ *
+ * @since 0.2.0
+ */
+export const getReferences = (variable: Variable): ReadonlyArray<Reference> =>
+	variable.references;
+
+/**
+ * Get the read references for a variable.
+ *
+ * @since 0.2.0
+ */
+export const getReadReferences = (
+	variable: Variable
+): ReadonlyArray<Reference> =>
+	pipe(
+		variable.references,
+		Arr.filter((ref) => ref.isRead())
+	);
+
+/**
+ * Get the write references for a variable.
+ *
+ * @since 0.2.0
+ */
+export const getWriteReferences = (
+	variable: Variable
+): ReadonlyArray<Reference> =>
+	pipe(
+		variable.references,
+		Arr.filter((ref) => ref.isWrite())
+	);
+
+// ---------------------------------------------------------------------------
+// Scope navigation
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the parent (upper) scope.
+ *
+ * @since 0.2.0
+ */
+export const upper = (scope: OxlintScope): Option.Option<OxlintScope> =>
+	Option.fromNullishOr(scope.upper);
+
+/**
+ * Get the child scopes.
+ *
+ * @since 0.2.0
+ */
+export const childScopes = (scope: OxlintScope): ReadonlyArray<OxlintScope> =>
+	scope.childScopes;
+
+/**
+ * Get all variables in a scope.
+ *
+ * @since 0.2.0
+ */
+export const variables = (scope: OxlintScope): ReadonlyArray<Variable> =>
+	scope.variables;
+
+/**
+ * Get "through" references (unresolved in this scope).
+ *
+ * @since 0.2.0
+ */
+export const throughReferences = (
+	scope: OxlintScope
+): ReadonlyArray<Reference> => scope.through;
+
+/**
+ * Check whether a scope is strict mode.
+ *
+ * @since 0.2.0
+ */
+export const isStrict = (scope: OxlintScope): boolean => scope.isStrict;

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

@@ -0,0 +1,377 @@
+/**
+ * Effect-wrapped queries over oxlint's `SourceCode` object.
+ *
+ * Every method that may return `null` is lifted to `Option`. Methods
+ * that return arrays stay as-is (empty array = no results). All
+ * functions read from the `RuleContext` service, so they return
+ * `Effect<T, never, RuleContext>` and can be `yield*`'d in handlers.
+ *
+ * @since 0.2.0
+ */
+import type {
+	Comment,
+	ESTree,
+	LineColumn,
+	Range,
+	Scope,
+	SourceCode as OxlintSourceCode,
+	Token,
+	Variable
+} from '@oxlint/plugins';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { RuleContext } from './RuleContext.ts';
+
+// ---------------------------------------------------------------------------
+// Internal: read sourceCode from RuleContext
+// ---------------------------------------------------------------------------
+
+/** @internal */
+const withSourceCode = <A>(
+	fn: (sc: OxlintSourceCode) => A
+): Effect.Effect<A, never, RuleContext> =>
+	Effect.service(RuleContext).pipe(Effect.map((ctx) => fn(ctx.sourceCode)));
+
+// ---------------------------------------------------------------------------
+// Source text
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the source text for a node, optionally with surrounding characters.
+ *
+ * When called with no arguments, returns the entire source text.
+ * Pass an `Option<ESTree.Node>` to get text for a specific node.
+ *
+ * @since 0.2.0
+ */
+export const getText: {
+	(): Effect.Effect<string, never, RuleContext>;
+	(
+		node: Option.Option<ESTree.Node>,
+		beforeCount?: number,
+		afterCount?: number
+	): Effect.Effect<string, never, RuleContext>;
+} = (
+	node?: Option.Option<ESTree.Node>,
+	beforeCount?: number,
+	afterCount?: number
+): Effect.Effect<string, never, RuleContext> =>
+	withSourceCode((sc) =>
+		sc.getText(
+			node === undefined
+				? null
+				: Option.getOrElse(node, () => null as never),
+			beforeCount,
+			afterCount
+		)
+	);
+
+// ---------------------------------------------------------------------------
+// Ancestry
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the ancestor nodes of the given node, from innermost to outermost.
+ *
+ * Note: oxlint types `getAncestors` as returning `Node[]` where `Node`
+ * is the base `Span` interface. At runtime these are full `ESTree.Node`
+ * values — the cast bridges this upstream type gap at the FFI boundary.
+ *
+ * @since 0.2.0
+ */
+export const getAncestors = (
+	node: ESTree.Node
+): Effect.Effect<ReadonlyArray<ESTree.Node>, never, RuleContext> =>
+	withSourceCode(
+		// oxlint-ignore(casting-awareness,avoid-any): FFI boundary —
+		// oxlint's `Node` (Span) is structurally narrower than `ESTree.Node`
+		// but the runtime values are full ESTree nodes.
+		(sc) => sc.getAncestors(node) as unknown as ReadonlyArray<ESTree.Node>
+	);
+
+// ---------------------------------------------------------------------------
+// Location / Range
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the AST node that contains the given source offset.
+ *
+ * Returns `Option.none()` when no node spans that offset.
+ *
+ * @since 0.2.0
+ */
+export const getNodeByRangeIndex = (
+	offset: number
+): Effect.Effect<Option.Option<ESTree.Node>, never, RuleContext> =>
+	withSourceCode((sc) =>
+		Option.fromNullishOr(sc.getNodeByRangeIndex(offset))
+	);
+
+/**
+ * Convert a source offset (0-based) to a `{ line, column }` location.
+ *
+ * @since 0.2.0
+ */
+export const getLocFromIndex = (
+	offset: number
+): Effect.Effect<LineColumn, never, RuleContext> =>
+	withSourceCode((sc) => sc.getLocFromIndex(offset));
+
+/**
+ * Convert a `{ line, column }` location to a source offset (0-based).
+ *
+ * @since 0.2.0
+ */
+export const getIndexFromLoc = (
+	loc: LineColumn
+): Effect.Effect<number, never, RuleContext> =>
+	withSourceCode((sc) => sc.getIndexFromLoc(loc));
+
+/**
+ * Get the range `[start, end]` for a node or token.
+ *
+ * @since 0.2.0
+ */
+export const getRange = (
+	nodeOrToken: ESTree.Node | Token | Comment
+): Effect.Effect<Range, never, RuleContext> =>
+	withSourceCode((sc) => sc.getRange(nodeOrToken));
+
+// ---------------------------------------------------------------------------
+// Token queries (single node)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the first token of a node.
+ *
+ * @since 0.2.0
+ */
+export const getFirstToken = (
+	node: ESTree.Node
+): Effect.Effect<Option.Option<Token>, never, RuleContext> =>
+	withSourceCode((sc) => Option.fromNullishOr(sc.getFirstToken(node)));
+
+/**
+ * Get the last token of a node.
+ *
+ * @since 0.2.0
+ */
+export const getLastToken = (
+	node: ESTree.Node
+): Effect.Effect<Option.Option<Token>, never, RuleContext> =>
+	withSourceCode((sc) => Option.fromNullishOr(sc.getLastToken(node)));
+
+/**
+ * Get all tokens for a node.
+ *
+ * @since 0.2.0
+ */
+export const getTokens = (
+	node: ESTree.Node
+): Effect.Effect<ReadonlyArray<Token>, never, RuleContext> =>
+	withSourceCode((sc) => sc.getTokens(node));
+
+// ---------------------------------------------------------------------------
+// Token queries (before / after)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the token before a node or token.
+ *
+ * @since 0.2.0
+ */
+export const getTokenBefore = (
+	nodeOrToken: ESTree.Node | Token | Comment
+): Effect.Effect<Option.Option<Token>, never, RuleContext> =>
+	withSourceCode((sc) =>
+		Option.fromNullishOr(sc.getTokenBefore(nodeOrToken))
+	);
+
+/**
+ * Get the token after a node or token.
+ *
+ * @since 0.2.0
+ */
+export const getTokenAfter = (
+	nodeOrToken: ESTree.Node | Token | Comment
+): Effect.Effect<Option.Option<Token>, never, RuleContext> =>
+	withSourceCode((sc) => Option.fromNullishOr(sc.getTokenAfter(nodeOrToken)));
+
+/**
+ * Get all tokens between two nodes/tokens.
+ *
+ * @since 0.2.0
+ */
+export const getTokensBetween = (
+	left: ESTree.Node | Token | Comment,
+	right: ESTree.Node | Token | Comment
+): Effect.Effect<ReadonlyArray<Token>, never, RuleContext> =>
+	withSourceCode((sc) => sc.getTokensBetween(left, right));
+
+/**
+ * Get the first token between two nodes/tokens.
+ *
+ * @since 0.2.0
+ */
+export const getFirstTokenBetween = (
+	left: ESTree.Node | Token | Comment,
+	right: ESTree.Node | Token | Comment
+): Effect.Effect<Option.Option<Token>, never, RuleContext> =>
+	withSourceCode((sc) =>
+		Option.fromNullishOr(sc.getFirstTokenBetween(left, right))
+	);
+
+/**
+ * Find a token by its range start offset.
+ *
+ * @since 0.2.0
+ */
+export const getTokenByRangeStart = (
+	offset: number
+): Effect.Effect<Option.Option<Token>, never, RuleContext> =>
+	withSourceCode((sc) =>
+		Option.fromNullishOr(sc.getTokenByRangeStart(offset))
+	);
+
+// ---------------------------------------------------------------------------
+// Comment queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all comments in the file.
+ *
+ * @since 0.2.0
+ */
+export const getAllComments = (): Effect.Effect<
+	ReadonlyArray<Comment>,
+	never,
+	RuleContext
+> => withSourceCode((sc) => sc.getAllComments());
+
+/**
+ * Get comments before a node or token.
+ *
+ * @since 0.2.0
+ */
+export const getCommentsBefore = (
+	nodeOrToken: ESTree.Node | Token | Comment
+): Effect.Effect<ReadonlyArray<Comment>, never, RuleContext> =>
+	withSourceCode((sc) => sc.getCommentsBefore(nodeOrToken));
+
+/**
+ * Get comments after a node or token.
+ *
+ * @since 0.2.0
+ */
+export const getCommentsAfter = (
+	nodeOrToken: ESTree.Node | Token | Comment
+): Effect.Effect<ReadonlyArray<Comment>, never, RuleContext> =>
+	withSourceCode((sc) => sc.getCommentsAfter(nodeOrToken));
+
+/**
+ * Get comments inside a node.
+ *
+ * @since 0.2.0
+ */
+export const getCommentsInside = (
+	node: ESTree.Node
+): Effect.Effect<ReadonlyArray<Comment>, never, RuleContext> =>
+	withSourceCode((sc) => sc.getCommentsInside(node));
+
+/**
+ * Check whether comments exist between two nodes/tokens.
+ *
+ * @since 0.2.0
+ */
+export const commentsExistBetween = (
+	left: ESTree.Node | Token | Comment,
+	right: ESTree.Node | Token | Comment
+): Effect.Effect<boolean, never, RuleContext> =>
+	withSourceCode((sc) => sc.commentsExistBetween(left, right));
+
+/**
+ * Get the JSDoc comment for a node.
+ *
+ * @deprecated Upstream deprecation. Use `getCommentsBefore` instead.
+ * @since 0.2.0
+ */
+export const getJSDocComment = (
+	node: ESTree.Node
+): Effect.Effect<Option.Option<Comment>, never, RuleContext> =>
+	withSourceCode((sc) => Option.fromNullishOr(sc.getJSDocComment(node)));
+
+// ---------------------------------------------------------------------------
+// Scope queries (delegated to SourceCode)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the scope for a node.
+ *
+ * @since 0.2.0
+ */
+export const getScope = (
+	node: ESTree.Node
+): Effect.Effect<Scope, never, RuleContext> =>
+	withSourceCode((sc) => sc.getScope(node));
+
+/**
+ * Get declared variables for a node.
+ *
+ * @since 0.2.0
+ */
+export const getDeclaredVariables = (
+	node: ESTree.Node
+): Effect.Effect<ReadonlyArray<Variable>, never, RuleContext> =>
+	withSourceCode((sc) => sc.getDeclaredVariables(node));
+
+/**
+ * Check whether a node is a global reference.
+ *
+ * @since 0.2.0
+ */
+export const isGlobalReference = (
+	node: ESTree.Node
+): Effect.Effect<boolean, never, RuleContext> =>
+	withSourceCode((sc) => sc.isGlobalReference(node));
+
+/**
+ * Mark a variable as used in the scope of the given node.
+ *
+ * @since 0.2.0
+ */
+export const markVariableAsUsed = (
+	name: string,
+	refNode?: ESTree.Node
+): Effect.Effect<boolean, never, RuleContext> =>
+	withSourceCode((sc) => sc.markVariableAsUsed(name, refNode));
+
+// ---------------------------------------------------------------------------
+// Spacing
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether there is a space between two nodes/tokens.
+ *
+ * @since 0.2.0
+ */
+export const isSpaceBetween = (
+	first: ESTree.Node | Token | Comment,
+	second: ESTree.Node | Token | Comment
+): Effect.Effect<boolean, never, RuleContext> =>
+	withSourceCode((sc) => sc.isSpaceBetween(first, second));
+
+// ---------------------------------------------------------------------------
+// Lines
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all source lines.
+ *
+ * @since 0.2.0
+ */
+export const getLines = (): Effect.Effect<
+	ReadonlyArray<string>,
+	never,
+	RuleContext
+> => withSourceCode((sc) => sc.getLines());