@prover-coder-ai/eslint-plugin-suggest-members 0.0.0

package/src/shell/shared/import-validation-base.ts

@@ -0,0 +1,181 @@
+// CHANGE: shared import/export validation base
+// WHY: eliminate duplication between suggest-imports and suggest-exports
+// QUOTE(TZ): n/a
+// REF: AGENTS.md SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect-based validation
+// INVARIANT: validation is deterministic for given inputs
+// COMPLEXITY: O(1)/O(n)
+import type { TSESTree } from "@typescript-eslint/utils"
+import { ESLintUtils } from "@typescript-eslint/utils"
+import type { RuleContext } from "@typescript-eslint/utils/ts-eslint"
+import type { Layer } from "effect"
+import { Effect, Exit } from "effect"
+
+import type { FilesystemError, TypeScriptServiceError } from "../effects/errors.js"
+import type { FilesystemServiceTag } from "../services/filesystem.js"
+import type { TypeScriptCompilerServiceTag } from "../services/typescript-compiler.js"
+import { makeTypeScriptCompilerServiceLayer } from "../services/typescript-compiler.js"
+import { isValidImportIdentifier, tryValidationWithFallback } from "./validation-helpers.js"
+
+export type ModuleSpecifier = TSESTree.ImportSpecifier | TSESTree.ExportSpecifier
+
+export interface TypeScriptServiceLayerContext {
+  readonly layer: Layer.Layer<TypeScriptCompilerServiceTag>
+  readonly hasTypeScript: boolean
+}
+
+export interface ImportValidationConfig<TResult> {
+  readonly validateSpecifier: (
+    specifier: ModuleSpecifier,
+    importName: string,
+    modulePath: string,
+    containingFilePath: string
+  ) => Effect.Effect<TResult, TypeScriptServiceError, TypeScriptCompilerServiceTag>
+  readonly fallbackValidationEffect?: (
+    importName: string,
+    modulePath: string,
+    contextFilePath: string
+  ) => Effect.Effect<TResult, FilesystemError, FilesystemServiceTag>
+  readonly formatMessage: (result: TResult) => string
+  readonly messageId: string
+  readonly skipWhenTypeScriptAvailable?: boolean
+}
+
+interface ValidateModuleSpecifierParams<TResult> {
+  readonly importedNode: TSESTree.Node | undefined
+  readonly specifier: ModuleSpecifier
+  readonly modulePath: string
+  readonly config: ImportValidationConfig<TResult>
+  readonly context: RuleContext<string, ReadonlyArray<string>>
+  readonly tsService: TypeScriptServiceLayerContext
+}
+
+const validateModuleSpecifier = <TResult>({
+  config,
+  context,
+  importedNode,
+  modulePath,
+  specifier,
+  tsService
+}: ValidateModuleSpecifierParams<TResult>): void => {
+  if (!importedNode) return
+  if (!isValidImportIdentifier(importedNode)) return
+
+  const imported = importedNode
+
+  executeImportValidation({
+    imported,
+    specifier,
+    modulePath,
+    config,
+    context,
+    containingFilePath: context.filename || "",
+    tsService
+  })
+}
+
+const makeSpecifierValidator = <TSpecifier extends ModuleSpecifier>(
+  getImportedNode: (specifier: TSpecifier) => TSESTree.Node | undefined
+) =>
+<TResult>(
+  specifier: TSpecifier,
+  modulePath: string,
+  config: ImportValidationConfig<TResult>,
+  context: RuleContext<string, ReadonlyArray<string>>,
+  tsService: TypeScriptServiceLayerContext
+): void => {
+  validateModuleSpecifier({
+    importedNode: getImportedNode(specifier),
+    specifier,
+    modulePath,
+    config,
+    context,
+    tsService
+  })
+}
+
+export const validateImportSpecifierBase = makeSpecifierValidator<
+  TSESTree.ImportSpecifier
+>((specifier) => specifier.imported)
+
+export const validateExportSpecifierBase = makeSpecifierValidator<
+  TSESTree.ExportSpecifier
+>((specifier) => specifier.local)
+
+const executeImportValidation = <TResult>(params: {
+  readonly imported: TSESTree.Identifier
+  readonly specifier: ModuleSpecifier
+  readonly modulePath: string
+  readonly config: ImportValidationConfig<TResult>
+  readonly context: RuleContext<string, ReadonlyArray<string>>
+  readonly containingFilePath: string
+  readonly tsService: TypeScriptServiceLayerContext
+}): void => {
+  const { config, containingFilePath, context, imported, modulePath, specifier, tsService } = params
+  const importName = imported.name
+
+  if (config.skipWhenTypeScriptAvailable === true && tsService.hasTypeScript) {
+    return
+  }
+
+  const validationEffect = Effect.provide(
+    config.validateSpecifier(specifier, importName, modulePath, containingFilePath),
+    tsService.layer
+  )
+
+  tryValidationWithFallback({
+    imported,
+    importName,
+    modulePath,
+    config,
+    context,
+    validationEffect
+  })
+}
+
+const emptyTypeScriptLayer = makeTypeScriptCompilerServiceLayer()
+
+export const createTypeScriptServiceLayerForContext = (
+  context: RuleContext<string, ReadonlyArray<string>>
+): TypeScriptServiceLayerContext => {
+  const parseResult = getParserServicesForContext(context)
+
+  if (!parseResult) {
+    return {
+      layer: emptyTypeScriptLayer,
+      hasTypeScript: false
+    }
+  }
+
+  const program = parseResult.program
+  if (!program) {
+    return {
+      layer: emptyTypeScriptLayer,
+      hasTypeScript: false
+    }
+  }
+  const checker = program.getTypeChecker()
+
+  return {
+    layer: makeTypeScriptCompilerServiceLayer(checker, program),
+    hasTypeScript: true
+  }
+}
+
+export const getParserServicesForContext = (
+  context: RuleContext<string, ReadonlyArray<string>>
+): ReturnType<typeof ESLintUtils.getParserServices> | null =>
+  Exit.match(
+    Effect.runSyncExit(
+      Effect.try({
+        try: () => ESLintUtils.getParserServices(context, false),
+        catch: () => null
+      })
+    ),
+    {
+      onFailure: () => null,
+      onSuccess: (value) => value
+    }
+  )

package/src/shell/shared/import-validation-rule-factory.ts

@@ -0,0 +1,116 @@
+// CHANGE: rule factory for import/export validations
+// WHY: shared listener wiring
+// QUOTE(TZ): n/a
+// REF: AGENTS.md SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: ESLint rule creation
+// INVARIANT: listeners are deterministic
+// COMPLEXITY: O(1)/O(n)
+import type { TSESTree } from "@typescript-eslint/utils"
+import { AST_NODE_TYPES, ESLintUtils } from "@typescript-eslint/utils"
+import type { RuleContext, RuleListener, RuleModule } from "@typescript-eslint/utils/ts-eslint"
+
+import { isTypeOnlyImport } from "../../core/validators/index.js"
+import type { ImportValidationConfig, TypeScriptServiceLayerContext } from "./import-validation-base.js"
+import {
+  createTypeScriptServiceLayerForContext,
+  validateExportSpecifierBase,
+  validateImportSpecifierBase
+} from "./import-validation-base.js"
+
+const createRule = <TResult>(
+  description: string,
+  messageId: string,
+  config: ImportValidationConfig<TResult>,
+  buildListener: (
+    context: RuleContext<string, ReadonlyArray<string>>,
+    config: ImportValidationConfig<TResult>
+  ) => RuleListener
+): RuleModule<string, ReadonlyArray<string>> =>
+  ESLintUtils.RuleCreator.withoutDocs({
+    meta: {
+      type: "problem",
+      docs: { description },
+      messages: { [messageId]: "{{message}}" },
+      schema: []
+    },
+    defaultOptions: [],
+    create(context) {
+      return buildListener(context, config)
+    }
+  })
+
+const getModulePathFromImport = (node: TSESTree.ImportDeclaration): string | undefined =>
+  typeof node.source.value === "string" ? node.source.value : undefined
+
+const getModulePathFromExport = (
+  node: TSESTree.ExportNamedDeclaration
+): string | undefined => typeof node.source?.value === "string" ? node.source.value : undefined
+
+const buildImportListeners = <TResult>(
+  context: RuleContext<string, ReadonlyArray<string>>,
+  config: ImportValidationConfig<TResult>
+): RuleListener => {
+  const tsService = createTypeScriptServiceLayerForContext(context)
+
+  return {
+    ImportDeclaration(node: TSESTree.ImportDeclaration): void {
+      if (isTypeOnlyImport(node)) return
+      const modulePath = getModulePathFromImport(node)
+      if (!modulePath) return
+
+      for (const specifier of node.specifiers) {
+        if (specifier.type === AST_NODE_TYPES.ImportSpecifier) {
+          validateImportSpecifierBase(
+            specifier,
+            modulePath,
+            config,
+            context,
+            tsService
+          )
+        }
+      }
+    }
+  }
+}
+
+export const createExportValidationListener = <TResult>(
+  context: RuleContext<string, ReadonlyArray<string>>,
+  config: ImportValidationConfig<TResult>
+): RuleListener => {
+  const tsService: TypeScriptServiceLayerContext = createTypeScriptServiceLayerForContext(context)
+
+  return {
+    ExportNamedDeclaration(node: TSESTree.ExportNamedDeclaration): void {
+      const modulePath = getModulePathFromExport(node)
+      if (!modulePath) return
+
+      for (const specifier of node.specifiers) {
+        validateExportSpecifierBase(
+          specifier,
+          modulePath,
+          config,
+          context,
+          tsService
+        )
+      }
+    }
+  }
+}
+
+const makeValidationRule = <TResult>(
+  buildListener: (
+    context: RuleContext<string, ReadonlyArray<string>>,
+    config: ImportValidationConfig<TResult>
+  ) => RuleListener
+) =>
+(
+  _ruleName: string,
+  description: string,
+  messageId: string,
+  config: ImportValidationConfig<TResult>
+): RuleModule<string, ReadonlyArray<string>> => createRule(description, messageId, config, buildListener)
+
+export const createValidationRule = makeValidationRule(buildImportListeners)
+export const createExportValidationRule = makeValidationRule(createExportValidationListener)

package/src/shell/shared/validation-helpers.ts

@@ -0,0 +1,94 @@
+// CHANGE: validation helpers for import/export rules
+// WHY: shared reporting + fallback handling
+// QUOTE(TZ): n/a
+// REF: AGENTS.md SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect.runSyncExit
+// INVARIANT: reports only when message non-empty
+// COMPLEXITY: O(1)/O(1)
+import type { TSESTree } from "@typescript-eslint/utils"
+import { AST_NODE_TYPES } from "@typescript-eslint/utils"
+import type { RuleContext } from "@typescript-eslint/utils/ts-eslint"
+import { Effect } from "effect"
+
+import { shouldSkipIdentifier } from "../../core/validators/index.js"
+import type { TypeScriptServiceError } from "../effects/errors.js"
+import { makeFilesystemServiceLayer } from "../services/filesystem.js"
+import type { ImportValidationConfig } from "./import-validation-base.js"
+import { runEffect } from "./validation-runner.js"
+
+interface BaseValidationParams<TResult> {
+  readonly imported: TSESTree.Identifier
+  readonly importName: string
+  readonly modulePath: string
+  readonly config: ImportValidationConfig<TResult>
+  readonly context: RuleContext<string, ReadonlyArray<string>>
+}
+
+export const isValidImportIdentifier = (
+  imported: TSESTree.Node
+): imported is TSESTree.Identifier => {
+  if (imported.type !== AST_NODE_TYPES.Identifier) return false
+  return !shouldSkipIdentifier(imported.name)
+}
+
+const reportValidationResult = <TResult>(
+  imported: TSESTree.Identifier,
+  config: ImportValidationConfig<TResult>,
+  context: RuleContext<string, ReadonlyArray<string>>,
+  result: TResult
+): void => {
+  const message = config.formatMessage(result)
+  if (message.length === 0) return
+
+  context.report({
+    node: imported,
+    messageId: config.messageId,
+    data: { message }
+  })
+}
+
+const tryFallbackValidationOnly = <TResult>(
+  params: BaseValidationParams<TResult>
+): void => {
+  const { config, context, importName, imported, modulePath } = params
+
+  if (!config.fallbackValidationEffect) return
+
+  const fallbackEffect = config.fallbackValidationEffect(
+    importName,
+    modulePath,
+    context.filename || ""
+  )
+
+  const result = runEffect(
+    Effect.provide(fallbackEffect, makeFilesystemServiceLayer())
+  )
+  if (!result) return
+
+  reportValidationResult(imported, config, context, result)
+}
+
+export const tryValidationWithFallback = <TResult>(
+  params: BaseValidationParams<TResult> & {
+    readonly validationEffect: Effect.Effect<TResult, TypeScriptServiceError>
+  }
+): void => {
+  const {
+    config,
+    context,
+    importName,
+    imported,
+    modulePath,
+    validationEffect
+  } = params
+
+  const result = runEffect(validationEffect)
+  if (!result) {
+    tryFallbackValidationOnly({ imported, importName, modulePath, config, context })
+    return
+  }
+
+  reportValidationResult(imported, config, context, result)
+}

package/src/shell/shared/validation-runner.ts

@@ -0,0 +1,45 @@
+// CHANGE: shared validation runner
+// WHY: execute Effect validations synchronously for ESLint
+// QUOTE(TZ): n/a
+// REF: AGENTS.md Effect
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect.runSyncExit
+// INVARIANT: reports occur in same tick
+// COMPLEXITY: O(1)/O(1)
+import type { TSESTree } from "@typescript-eslint/utils"
+import type { RuleContext } from "@typescript-eslint/utils/ts-eslint"
+import { Effect, Exit } from "effect"
+
+interface ValidationConfig<T extends { _tag: string }, E> {
+  readonly validationEffect: Effect.Effect<T, E>
+  readonly context: RuleContext<string, readonly []>
+  readonly reportNode: TSESTree.Node
+  readonly messageId: string
+  readonly formatMessage: (result: T) => string
+  readonly fallbackEffect?: Effect.Effect<T, E>
+}
+
+export const runEffect = <T, E>(effect: Effect.Effect<T, E>): T | null =>
+  Exit.match(Effect.runSyncExit(effect), {
+    onFailure: () => null,
+    onSuccess: (value) => value
+  })
+
+export const runValidationEffect = <T extends { _tag: string }, E>(
+  config: ValidationConfig<T, E>
+): void => {
+  const { context, fallbackEffect, formatMessage, messageId, reportNode, validationEffect } = config
+
+  const result = runEffect(validationEffect) ?? (fallbackEffect ? runEffect(fallbackEffect) : null)
+
+  if (!result) return
+  if (result._tag === "Valid") return
+
+  const message = formatMessage(result)
+  context.report({
+    node: reportNode,
+    messageId,
+    data: { message }
+  })
+}

package/src/shell/validation/export-validation-effect.ts

@@ -0,0 +1,54 @@
+// CHANGE: export validation effect
+// WHY: suggest similar exports for re-exports
+// QUOTE(TZ): n/a
+// REF: AGENTS.md CORE↔SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect<ExportValidationResult, TypeScriptServiceError, TypeScriptCompilerServiceTag>
+// INVARIANT: Valid | ExportNotFound
+// COMPLEXITY: O(n log n)/O(n)
+import { Match } from "effect"
+
+import type { ExportValidationResult } from "../../core/index.js"
+import { formatExportMessage, makeExportNotFoundResult, makeValidExportResult } from "../../core/index.js"
+import type { BaseESLintNode } from "../../core/types/eslint-nodes.js"
+import { baseValidationEffect, isValidExportCandidate } from "./validation-base-effect.js"
+
+export const validateExportAccessEffect = (
+  node: BaseESLintNode,
+  exportName: string,
+  modulePath: string,
+  containingFilePath: string
+) => {
+  const config = {
+    makeValidResult: makeValidExportResult,
+    makeInvalidResult: makeExportNotFoundResult,
+    isValidCandidate: isValidExportCandidate
+  }
+
+  return baseValidationEffect(node, exportName, modulePath, containingFilePath, config)
+}
+
+export const formatExportValidationMessage = (
+  result: ExportValidationResult
+): string =>
+  Match.value(result).pipe(
+    Match.when({ _tag: "Valid" }, () => ""),
+    Match.when({ _tag: "ExportNotFound" }, (invalid) => {
+      if (invalid.suggestions.length === 0) {
+        return formatExportMessage(
+          invalid.exportName,
+          invalid.modulePath,
+          invalid.typeName,
+          invalid.suggestions
+        )
+      }
+      return formatExportMessage(
+        invalid.exportName,
+        invalid.modulePath,
+        invalid.typeName,
+        invalid.suggestions
+      )
+    }),
+    Match.exhaustive
+  )

package/src/shell/validation/import-validation-effect.ts

@@ -0,0 +1,49 @@
+// CHANGE: import validation effect
+// WHY: suggest similar exports for named imports
+// QUOTE(TZ): n/a
+// REF: AGENTS.md CORE↔SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect<ImportValidationResult, TypeScriptServiceError, TypeScriptCompilerServiceTag>
+// INVARIANT: Valid | ImportNotFound
+// COMPLEXITY: O(n log n)/O(n)
+import { Match } from "effect"
+
+import type { ImportValidationResult } from "../../core/index.js"
+import { formatImportMessage, makeImportNotFoundResult, makeValidImportResult } from "../../core/index.js"
+import type { BaseESLintNode } from "../../core/types/eslint-nodes.js"
+import { baseValidationEffect, isValidImportCandidate } from "./validation-base-effect.js"
+
+export const validateImportSpecifierEffect = (
+  node: BaseESLintNode,
+  importName: string,
+  modulePath: string,
+  containingFilePath: string
+) => {
+  const config = {
+    makeValidResult: makeValidImportResult,
+    makeInvalidResult: makeImportNotFoundResult,
+    isValidCandidate: isValidImportCandidate
+  }
+
+  return baseValidationEffect(node, importName, modulePath, containingFilePath, config)
+}
+
+export const formatImportValidationMessage = (
+  result: ImportValidationResult
+): string =>
+  Match.value(result).pipe(
+    Match.when({ _tag: "Valid" }, () => ""),
+    Match.when({ _tag: "ImportNotFound" }, (invalid) => {
+      if (invalid.suggestions.length === 0) {
+        return `Variable "${invalid.importName}" is not defined.`
+      }
+      return formatImportMessage(
+        invalid.importName,
+        invalid.modulePath,
+        invalid.typeName,
+        invalid.suggestions
+      )
+    }),
+    Match.exhaustive
+  )

package/src/shell/validation/local-export-validation-effect.ts

@@ -0,0 +1,10 @@
+// CHANGE: local export validation (Effect)
+// WHY: re-export shared validator for local export identifiers
+// QUOTE(TZ): n/a
+// REF: AGENTS.md CORE↔SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: n/a
+// INVARIANT: export-only module
+// COMPLEXITY: O(1)/O(1)
+export { formatLocalExportValidationMessage, validateLocalExportIdentifierEffect } from "./missing-name-validators.js"