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

package/src/shell/services/typescript-compiler-helpers.ts

@@ -0,0 +1,89 @@
+// CHANGE: helper functions for TypeScript module resolution
+// WHY: keep TS resolution logic isolated
+// QUOTE(TZ): n/a
+// REF: AGENTS.md SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: n/a
+// INVARIANT: deterministic resolution for given program
+// COMPLEXITY: O(n)/O(1)
+import * as ts from "typescript"
+
+export const findContextFile = (program: ts.Program): ts.SourceFile | undefined => {
+  const files = program.getSourceFiles()
+  return (
+    files.find((file) => !file.isDeclarationFile && file.fileName.endsWith(".ts")) ??
+      files[0]
+  )
+}
+
+export const resolveModuleSymbol = (
+  checker: ts.TypeChecker,
+  program: ts.Program,
+  moduleResolution: ts.ResolvedModuleWithFailedLookupLocations
+): ts.Symbol | undefined => {
+  if (!moduleResolution.resolvedModule) {
+    return undefined
+  }
+
+  const resolvedFile = program.getSourceFile(
+    moduleResolution.resolvedModule.resolvedFileName
+  )
+
+  if (!resolvedFile) return undefined
+  return checker.getSymbolAtLocation(resolvedFile)
+}
+
+export const findGlobalModuleSymbol = (
+  checker: ts.TypeChecker,
+  contextFile: ts.SourceFile,
+  modulePath: string
+): ts.Symbol | undefined => {
+  const symbols = checker.getSymbolsInScope(
+    contextFile,
+    ts.SymbolFlags.Module | ts.SymbolFlags.Namespace
+  )
+
+  return symbols.find((symbol) => {
+    const name = symbol.getName()
+    return name === modulePath || name === `"${modulePath}"` || name.includes(modulePath)
+  })
+}
+
+export const findAmbientModuleSymbol = (
+  checker: ts.TypeChecker,
+  modulePath: string
+): ts.Symbol | undefined =>
+  checker
+    .getAmbientModules()
+    .find((symbol) => symbol.getName() === `"${modulePath}"` || symbol.getName() === modulePath)
+
+export const extractExportNames = (
+  checker: ts.TypeChecker,
+  moduleSymbol: ts.Symbol
+): ReadonlyArray<string> =>
+  checker
+    .getExportsOfModule(moduleSymbol)
+    .map((symbol) => symbol.getName())
+    .filter((name) => name.length > 0)
+
+export const findModuleSymbol = (
+  checker: ts.TypeChecker,
+  program: ts.Program,
+  modulePath: string,
+  contextFile: ts.SourceFile
+): ts.Symbol | undefined => {
+  const compilerOptions = program.getCompilerOptions()
+  const moduleResolution = ts.resolveModuleName(
+    modulePath,
+    contextFile.fileName,
+    compilerOptions,
+    ts.sys
+  )
+
+  return (
+    resolveModuleSymbol(checker, program, moduleResolution) ??
+      findGlobalModuleSymbol(checker, contextFile, modulePath) ??
+      findAmbientModuleSymbol(checker, modulePath)
+  )
+}

package/src/shell/services/typescript-compiler-module-effects.ts

@@ -0,0 +1,296 @@
+// CHANGE: TypeScript module-level effects
+// WHY: resolve module exports + signatures
+// QUOTE(TZ): n/a
+// REF: AGENTS.md SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect<T, TypeScriptServiceError>
+// INVARIANT: module resolution is deterministic
+// COMPLEXITY: O(n)/O(1)
+import { Effect, pipe } from "effect"
+import * as ts from "typescript"
+
+import { getNodeBuiltinExports, isNodeBuiltinModule } from "../../core/validation/node-builtin-exports.js"
+import type { TypeScriptServiceError } from "../effects/errors.js"
+import { makeModuleNotFoundError, makeTypeCheckerUnavailableError, makeTypeResolutionError } from "../effects/errors.js"
+import { ignoreErrorToUndefined } from "../shared/effect-utils.js"
+import { findContextFile, findModuleSymbol } from "./typescript-compiler-helpers.js"
+import { createUndefinedResultEffect, formatTypeName, formatTypeSignature } from "./typescript-effect-utils.js"
+
+export const tryGetBuiltinExports = (
+  modulePath: string
+): ReadonlyArray<string> | null => {
+  if (!isNodeBuiltinModule(modulePath)) return null
+  return getNodeBuiltinExports(modulePath) ?? null
+}
+
+export const resolveContextFileEffect = (
+  program: ts.Program,
+  modulePath: string,
+  containingFilePath?: string
+): Effect.Effect<ts.SourceFile, TypeScriptServiceError> =>
+  Effect.try({
+    try: () => {
+      if (containingFilePath) {
+        const direct = program.getSourceFile(containingFilePath)
+        if (direct) return direct
+      }
+
+      const fallback = findContextFile(program)
+      if (!fallback) {
+        throw new Error("context-file-not-found")
+      }
+      return fallback
+    },
+    catch: () => makeModuleNotFoundError(modulePath)
+  })
+
+export const resolveModuleSymbolEffect = (
+  checker: ts.TypeChecker,
+  program: ts.Program,
+  modulePath: string,
+  contextFile: ts.SourceFile
+): Effect.Effect<ts.Symbol, TypeScriptServiceError> =>
+  Effect.try({
+    try: () => {
+      const symbol = findModuleSymbol(checker, program, modulePath, contextFile)
+      if (!symbol) {
+        throw new Error("module-symbol-not-found")
+      }
+      return symbol
+    },
+    catch: () => makeModuleNotFoundError(modulePath)
+  })
+
+const filterExportSymbols = (
+  symbols: ReadonlyArray<ts.Symbol>
+): Array<string> => {
+  const names: Array<string> = []
+
+  for (const symbol of symbols) {
+    names.push(symbol.getName())
+  }
+
+  return names
+}
+
+interface ModuleContext {
+  readonly moduleSymbol: ts.Symbol
+  readonly contextFile: ts.SourceFile
+}
+
+interface ModuleLookupParams {
+  readonly modulePath: string
+  readonly containingFilePath?: string
+}
+
+const resolveModuleContextEffect = (
+  checker: ts.TypeChecker,
+  program: ts.Program,
+  modulePath: string,
+  containingFilePath?: string
+): Effect.Effect<ModuleContext, TypeScriptServiceError> =>
+  pipe(
+    resolveContextFileEffect(program, modulePath, containingFilePath),
+    Effect.flatMap((contextFile) =>
+      pipe(
+        resolveModuleSymbolEffect(checker, program, modulePath, contextFile),
+        Effect.map((moduleSymbol) => ({ moduleSymbol, contextFile }))
+      )
+    )
+  )
+
+const createModuleLookupEffect = <T, TParams extends ModuleLookupParams>(
+  checker: ts.TypeChecker | undefined,
+  program: ts.Program | undefined,
+  build: (
+    availableChecker: ts.TypeChecker,
+    moduleSymbol: ts.Symbol,
+    contextFile: ts.SourceFile,
+    params: TParams
+  ) => Effect.Effect<T | undefined, TypeScriptServiceError>
+) => {
+  if (!checker || !program) {
+    return createUndefinedResultEffect<T>()
+  }
+
+  return (params: TParams): Effect.Effect<T | undefined, TypeScriptServiceError> =>
+    pipe(
+      resolveModuleContextEffect(
+        checker,
+        program,
+        params.modulePath,
+        params.containingFilePath
+      ),
+      Effect.flatMap(({ contextFile, moduleSymbol }) => build(checker, moduleSymbol, contextFile, params)),
+      ignoreErrorToUndefined
+    )
+}
+
+export const createGetExportsOfModuleEffect = (
+  checker: ts.TypeChecker | undefined,
+  program: ts.Program | undefined
+) =>
+(
+  modulePath: string,
+  containingFilePath?: string
+): Effect.Effect<ReadonlyArray<string>, TypeScriptServiceError> =>
+  Effect.gen(function*(_) {
+    const builtin = tryGetBuiltinExports(modulePath)
+    if (builtin) return builtin
+
+    if (!checker || !program) {
+      return yield* _(Effect.fail(makeTypeCheckerUnavailableError()))
+    }
+
+    const contextFile = yield* _(
+      resolveContextFileEffect(program, modulePath, containingFilePath)
+    )
+    const moduleSymbol = yield* _(
+      resolveModuleSymbolEffect(checker, program, modulePath, contextFile)
+    )
+
+    const exportSymbols = checker.getExportsOfModule(moduleSymbol)
+    return filterExportSymbols(exportSymbols)
+  })
+
+const resolveModuleNameEffect = (
+  program: ts.Program,
+  modulePath: string,
+  containingFile: string
+): Effect.Effect<string, TypeScriptServiceError> =>
+  Effect.try({
+    try: () => {
+      const resolved = ts.resolveModuleName(
+        modulePath,
+        containingFile,
+        program.getCompilerOptions(),
+        ts.sys
+      )
+
+      const resolvedFile = resolved.resolvedModule?.resolvedFileName
+      if (resolvedFile && resolvedFile.length > 0) {
+        return resolvedFile
+      }
+
+      throw new Error("module-not-found")
+    },
+    catch: () => makeModuleNotFoundError(modulePath)
+  })
+
+export const createResolveModulePathEffect = (
+  program: ts.Program | undefined
+) =>
+(
+  modulePath: string,
+  containingFile: string
+): Effect.Effect<string, TypeScriptServiceError> =>
+  program
+    ? resolveModuleNameEffect(program, modulePath, containingFile)
+    : Effect.fail(makeTypeCheckerUnavailableError())
+
+const findExportSymbol = (
+  checker: ts.TypeChecker,
+  moduleSymbol: ts.Symbol,
+  exportName: string
+): ts.Symbol | undefined =>
+  checker
+    .getExportsOfModule(moduleSymbol)
+    .find((symbol) => symbol.getName() === exportName)
+
+const createTypeResolutionEffect = (
+  resolve: () => string | undefined,
+  errorLabel: string
+): Effect.Effect<string | undefined, TypeScriptServiceError> =>
+  Effect.try({
+    try: resolve,
+    catch: (error) =>
+      makeTypeResolutionError(
+        error instanceof Error ? error.message : errorLabel
+      )
+  })
+
+const getExportSignatureEffect = (
+  checker: ts.TypeChecker,
+  moduleSymbol: ts.Symbol,
+  exportName: string,
+  contextFile: ts.SourceFile
+): Effect.Effect<string | undefined, TypeScriptServiceError> =>
+  createTypeResolutionEffect(() => {
+    const targetSymbol = findExportSymbol(checker, moduleSymbol, exportName)
+    if (!targetSymbol) return
+
+    const symbolType = checker.getTypeOfSymbolAtLocation(
+      targetSymbol,
+      contextFile
+    )
+
+    return formatTypeSignature(checker, symbolType)
+  }, "export-signature-error")
+
+export const createGetExportTypeSignatureEffect = (
+  checker: ts.TypeChecker | undefined,
+  program: ts.Program | undefined
+) => {
+  interface ExportLookupParams extends ModuleLookupParams {
+    readonly exportName: string
+  }
+
+  const lookup = createModuleLookupEffect<string, ExportLookupParams>(
+    checker,
+    program,
+    (availableChecker, moduleSymbol, contextFile, params) =>
+      getExportSignatureEffect(
+        availableChecker,
+        moduleSymbol,
+        params.exportName,
+        contextFile
+      )
+  )
+
+  return (
+    modulePath: string,
+    exportName: string,
+    containingFilePath?: string
+  ): Effect.Effect<string | undefined, TypeScriptServiceError> => {
+    const params = containingFilePath
+      ? { modulePath, exportName, containingFilePath }
+      : { modulePath, exportName }
+    return lookup(params)
+  }
+}
+
+const getModuleTypeNameEffect = (
+  checker: ts.TypeChecker,
+  moduleSymbol: ts.Symbol,
+  contextFile: ts.SourceFile
+): Effect.Effect<string | undefined, TypeScriptServiceError> =>
+  createTypeResolutionEffect(() => {
+    const moduleType = checker.getTypeOfSymbolAtLocation(
+      moduleSymbol,
+      contextFile
+    )
+    return formatTypeName(checker, moduleType, contextFile)
+  }, "module-type-error")
+
+export const createGetModuleTypeNameEffect = (
+  checker: ts.TypeChecker | undefined,
+  program: ts.Program | undefined
+) => {
+  const lookup = createModuleLookupEffect<string, ModuleLookupParams>(
+    checker,
+    program,
+    (availableChecker, moduleSymbol, contextFile) =>
+      getModuleTypeNameEffect(availableChecker, moduleSymbol, contextFile)
+  )
+
+  return (
+    modulePath: string,
+    containingFilePath?: string
+  ): Effect.Effect<string | undefined, TypeScriptServiceError> => {
+    const params = containingFilePath
+      ? { modulePath, containingFilePath }
+      : { modulePath }
+    return lookup(params)
+  }
+}

package/src/shell/services/typescript-compiler.ts

@@ -0,0 +1,112 @@
+// CHANGE: TypeScript compiler service (Effect + Layer)
+// WHY: typed dependency injection for compiler operations
+// QUOTE(TZ): n/a
+// REF: AGENTS.md Effect Layer
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect<Success, Error, Requirements>
+// INVARIANT: service ops are total over errors
+// COMPLEXITY: O(1)/O(n)
+import type { Effect } from "effect"
+import { Context, Layer } from "effect"
+import type * as ts from "typescript"
+
+import type { TypeScriptServiceError } from "../effects/errors.js"
+import {
+  createGetContextualTypeEffect,
+  createGetPropertiesOfTypeEffect,
+  createGetSymbolAtLocationEffect,
+  createGetSymbolsInScopeEffect,
+  createGetTypeAtLocationEffect
+} from "./typescript-compiler-effects.js"
+import {
+  createGetExportsOfModuleEffect,
+  createGetExportTypeSignatureEffect,
+  createGetModuleTypeNameEffect,
+  createResolveModulePathEffect
+} from "./typescript-compiler-module-effects.js"
+import { createGetSymbolTypeSignatureEffect, createGetTypeNameEffect } from "./typescript-effect-utils.js"
+
+export interface TypeScriptCompilerService {
+  readonly getSymbolAtLocation: (
+    node: ts.Node
+  ) => Effect.Effect<ts.Symbol, TypeScriptServiceError>
+
+  readonly getSymbolsInScope: (
+    node: ts.Node,
+    flags: ts.SymbolFlags
+  ) => Effect.Effect<ReadonlyArray<ts.Symbol>, TypeScriptServiceError>
+
+  readonly getTypeAtLocation: (
+    node: ts.Node
+  ) => Effect.Effect<ts.Type, TypeScriptServiceError>
+
+  readonly getContextualType: (
+    node: ts.Expression
+  ) => Effect.Effect<ts.Type | undefined, TypeScriptServiceError>
+
+  readonly getTypeName: (
+    type: ts.Type,
+    location?: ts.Node
+  ) => Effect.Effect<string, TypeScriptServiceError>
+
+  readonly getPropertiesOfType: (
+    type: ts.Type
+  ) => Effect.Effect<ReadonlyArray<ts.Symbol>, TypeScriptServiceError>
+
+  readonly getExportsOfModule: (
+    modulePath: string,
+    containingFilePath?: string
+  ) => Effect.Effect<ReadonlyArray<string>, TypeScriptServiceError>
+
+  readonly getModuleTypeName: (
+    modulePath: string,
+    containingFilePath?: string
+  ) => Effect.Effect<string | undefined, TypeScriptServiceError>
+
+  readonly resolveModulePath: (
+    modulePath: string,
+    containingFile: string
+  ) => Effect.Effect<string, TypeScriptServiceError>
+
+  readonly getExportTypeSignature: (
+    modulePath: string,
+    exportName: string,
+    containingFilePath?: string
+  ) => Effect.Effect<string | undefined, TypeScriptServiceError>
+
+  readonly getSymbolTypeSignature: (
+    symbol: ts.Symbol,
+    location?: ts.Node
+  ) => Effect.Effect<string | undefined, TypeScriptServiceError>
+}
+
+export class TypeScriptCompilerServiceTag extends Context.Tag(
+  "TypeScriptCompilerService"
+)<TypeScriptCompilerServiceTag, TypeScriptCompilerService>() {}
+
+export const makeTypeScriptCompilerService = (
+  checker: ts.TypeChecker | undefined,
+  program: ts.Program | undefined
+): TypeScriptCompilerService => ({
+  getSymbolAtLocation: createGetSymbolAtLocationEffect(checker),
+  getSymbolsInScope: createGetSymbolsInScopeEffect(checker),
+  getTypeAtLocation: createGetTypeAtLocationEffect(checker),
+  getContextualType: createGetContextualTypeEffect(checker),
+  getTypeName: createGetTypeNameEffect(checker),
+  getPropertiesOfType: createGetPropertiesOfTypeEffect(checker),
+  getExportsOfModule: createGetExportsOfModuleEffect(checker, program),
+  getModuleTypeName: createGetModuleTypeNameEffect(checker, program),
+  resolveModulePath: createResolveModulePathEffect(program),
+  getExportTypeSignature: createGetExportTypeSignatureEffect(checker, program),
+  getSymbolTypeSignature: createGetSymbolTypeSignatureEffect(checker)
+})
+
+export const makeTypeScriptCompilerServiceLayer = (
+  checker?: ts.TypeChecker,
+  program?: ts.Program
+): Layer.Layer<TypeScriptCompilerServiceTag> =>
+  Layer.succeed(
+    TypeScriptCompilerServiceTag,
+    makeTypeScriptCompilerService(checker, program)
+  )

package/src/shell/services/typescript-effect-utils.ts

@@ -0,0 +1,123 @@
+// CHANGE: shared TypeScript effect utilities
+// WHY: reusable Effect wrappers for compiler operations
+// QUOTE(TZ): n/a
+// REF: AGENTS.md Effect composition
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect<T, TypeScriptServiceError>
+// INVARIANT: checker must exist to run operation
+// COMPLEXITY: O(1)/O(1)
+import { Effect, pipe } from "effect"
+import * as ts from "typescript"
+
+import type { TypeScriptServiceError } from "../effects/errors.js"
+import { makeTypeCheckerUnavailableError, makeTypeResolutionError } from "../effects/errors.js"
+
+export const createTypeScriptEffect = <T>(
+  checker: ts.TypeChecker | undefined,
+  operation: (checker: ts.TypeChecker) => Effect.Effect<T, TypeScriptServiceError>
+): Effect.Effect<T, TypeScriptServiceError> =>
+  pipe(
+    Effect.sync(() => checker ? operation(checker) : Effect.fail(makeTypeCheckerUnavailableError())),
+    Effect.flatten
+  )
+
+export const createUndefinedResultEffect = <T>() => (): Effect.Effect<T | undefined, TypeScriptServiceError> =>
+  Effect.sync((): T | undefined => undefined)
+
+const findSymbolNode = (symbol: ts.Symbol): ts.Declaration | undefined =>
+  [symbol.valueDeclaration, ...(symbol.declarations ?? [])].find(
+    (node): node is ts.Declaration => node !== undefined
+  )
+
+export const formatTypeSignature = (
+  checker: ts.TypeChecker,
+  symbolType: ts.Type,
+  locationNode?: ts.Node
+): string =>
+  checker.typeToString(
+    symbolType,
+    locationNode,
+    ts.TypeFormatFlags.NoTruncation |
+      ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope
+  )
+
+export const formatTypeName = (
+  checker: ts.TypeChecker,
+  type: ts.Type,
+  locationNode?: ts.Node
+): string =>
+  checker.typeToString(
+    type,
+    locationNode,
+    ts.TypeFormatFlags.NoTruncation |
+      ts.TypeFormatFlags.UseFullyQualifiedType |
+      ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope
+  )
+
+const preferImportedTypeName = (primary: string, fallback: string): string =>
+  fallback.includes("import(") ? fallback : primary
+
+export const createGetTypeNameEffect = (
+  checker: ts.TypeChecker | undefined
+) =>
+(
+  type: ts.Type,
+  location?: ts.Node
+): Effect.Effect<string, TypeScriptServiceError> =>
+  createTypeScriptEffect(checker, (availableChecker) =>
+    Effect.try({
+      try: () => {
+        const primary = formatTypeName(availableChecker, type, location)
+        const fallback = formatTypeName(availableChecker, type)
+        return preferImportedTypeName(primary, fallback)
+      },
+      catch: (error) =>
+        makeTypeResolutionError(
+          error instanceof Error ? error.message : "type-name-error"
+        )
+    }))
+
+const buildSymbolSignature = (
+  checker: ts.TypeChecker,
+  symbol: ts.Symbol,
+  fallbackNode?: ts.Node
+): Effect.Effect<string | undefined, TypeScriptServiceError> =>
+  pipe(
+    Effect.sync(() => findSymbolNode(symbol) ?? fallbackNode),
+    Effect.flatMap((locationNode) =>
+      locationNode
+        ? Effect.try({
+          try: () => {
+            const symbolType = checker.getTypeOfSymbolAtLocation(
+              symbol,
+              locationNode
+            )
+
+            return formatTypeSignature(checker, symbolType, locationNode)
+          },
+          catch: (error) =>
+            makeTypeResolutionError(
+              error instanceof Error ? error.message : "symbol-signature-error"
+            )
+        })
+        : Effect.sync((): string | undefined => undefined)
+    )
+  )
+
+export const createGetSymbolTypeSignatureEffect = (
+  checker: ts.TypeChecker | undefined
+): (
+  symbol: ts.Symbol,
+  fallbackNode?: ts.Node
+) => Effect.Effect<string | undefined, TypeScriptServiceError> => {
+  if (!checker) {
+    return createUndefinedResultEffect<string>()
+  }
+
+  return (
+    symbol: ts.Symbol,
+    fallbackNode?: ts.Node
+  ): Effect.Effect<string | undefined, TypeScriptServiceError> =>
+    createTypeScriptEffect(checker, (availableChecker) => buildSymbolSignature(availableChecker, symbol, fallbackNode))
+}

package/src/shell/shared/effect-utils.ts

@@ -0,0 +1,18 @@
+// CHANGE: Effect helpers for optional fallbacks
+// WHY: de-duplicate error-to-undefined mappings in SHELL
+// QUOTE(TZ): n/a
+// REF: AGENTS.md SHELL
+// SOURCE: n/a
+// PURITY: SHELL
+// EFFECT: Effect
+// INVARIANT: failure -> undefined, success -> value
+// COMPLEXITY: O(1)/O(1)
+import { Effect } from "effect"
+
+export const ignoreErrorToUndefined = <A, E, R>(
+  effect: Effect.Effect<A, E, R>
+): Effect.Effect<A | undefined, never, R> =>
+  Effect.matchEffect(effect, {
+    onFailure: () => Effect.sync((): A | undefined => undefined),
+    onSuccess: (value) => Effect.succeed(value)
+  })