♻️ chore(config): Convert to jsdoc explicit exports (#589)

## Description

Converts @evmts/config to js with jsdoc. Makes public exports explicit

Addresses #586
Addresses #517

## Testing

Explain the quality checks that have been done on the code changes

## Additional Information

- [ ] I read the [contributing docs](../docs/contributing.md) (if this
is your first contribution)

Your ENS/address:

---------

Co-authored-by: Will Cory <[email protected]>

.changeset/brave-owls-explain.md

@@ -0,0 +1,5 @@
+---
+"@evmts/config": patch
+---
+
+Converted @evmts/config to js with jsdoc and explicit exports

config/package.json

@@ -23,7 +23,7 @@
 	],
 	"type": "module",
 	"main": "dist/index.cjs",
-	"module": "dist/index.js",
+	"module": "src/index.js",
 	"types": "types/src/index.d.ts",
 	"files": [
 		"dist",

config/src/Config.js

@@ -0,0 +1,21 @@
+import { getDefaultSolcVersion } from './getDefaultSolcVersion.js'
+import { z } from 'zod'
+
+export const CompilerConfigValidator = z
+	.strictObject({
+		name: z.literal('@evmts/ts-plugin').optional(),
+		solcVersion: z.string().optional(),
+		foundryProject: z.union([z.boolean(), z.string()]).optional(),
+		libs: z.array(z.string()).optional(),
+		remappings: z.record(z.string()).optional(),
+	})
+	.describe('Configuration for EVMts')
+
+export const defaultConfig = {
+	get solcVersion() {
+		return getDefaultSolcVersion()
+	},
+	foundryProject: false,
+	remappings: {},
+	libs: [],
+}

config/src/defineConfig.ts → config/src/defineConfig.js

@@ -1,17 +1,11 @@
-import {
-	type CompilerConfig,
-	CompilerConfigValidator,
-	type ResolvedCompilerConfig,
-	defaultConfig,
-} from './Config.js'
+import { CompilerConfigValidator, defaultConfig } from './Config.js'
 import { execSync } from 'child_process'
 import * as path from 'path'
 
-export type DefineConfig = (configFactory: () => CompilerConfig) => {
-	configFn: (configFilePath: string) => ResolvedCompilerConfig
-}
-
-export const defineConfig: DefineConfig = (configFactory) => ({
+/**
+ * @type {import("./types.js").DefineConfig}
+ */
+export const defineConfig = (configFactory) => ({
 	configFn: (configFilePath) => {
 		const parsedConfig = CompilerConfigValidator.safeParse(
 			configFactory() ?? {},
@@ -51,8 +45,10 @@ or lib directly in your EVMts compiler config
 				)
 			}
 
-			// Process remappings
-			const remappings: Record<string, string> = {}
+			/**
+			 * @type {Record<string, string>}
+			 */
+			const remappings = {}
 			if (forgeConfig.remappings) {
 				for (const remap of forgeConfig.remappings) {
 					const parts = remap.split('=')

config/src/defineConfig.spec.ts

@@ -1,5 +1,4 @@
-import { type CompilerConfig, defaultConfig } from './Config.js'
-import { defineConfig } from './defineConfig.js'
+import { type CompilerConfig, defaultConfig, defineConfig } from './index.js'
 import { execSync } from 'child_process'
 import { type MockedFunction, describe, expect, it, vi } from 'vitest'
 

config/src/fileExists.js

@@ -0,0 +1,23 @@
+import { constants } from 'fs'
+import { access } from 'fs/promises'
+
+/**
+ * Checks if a file exists at the given path
+ * @param {string} path - path to check
+ * @returns {Promise<boolean>} true if the file exists, false otherwise
+ * @example
+ * ```typescript
+ * import { fileExists } from '@eth-optimism/config'
+ * await fileExists('./someFile.txt')
+ * ```
+ */
+export const fileExists = async (path) => {
+	try {
+		// TODO not the most robust check for existence here
+		await access(path, constants.F_OK)
+		return true
+	} catch (e) {
+		// TODO should be inspecting the error here
+		return false
+	}
+}

config/src/getDefaultSolcVersion.ts → config/src/getDefaultSolcVersion.js

@@ -1,5 +1,11 @@
 import { createRequire } from 'module'
 
+/**
+ * Gets the solc version of node_modules
+ * @returns {string} version
+ * @example
+ * getDefaultSolcVersion() // "0.8.16"
+ */
 export const getDefaultSolcVersion = () => {
 	const moduleRequire = createRequire(import.meta.url ?? __dirname)
 	const solc = moduleRequire('solc')

config/src/index.js

@@ -0,0 +1,9 @@
+/**
+ * @typedef {import('./types.js').CompilerConfig} CompilerConfig
+ * @typedef {import('./types.js').ResolvedCompilerConfig} ResolvedCompilerConfig
+ */
+
+export { defaultConfig } from './Config.js'
+export { loadConfig } from './loadConfig.js'
+export { loadConfigAsync } from './loadConfigAsync.js'
+export { defineConfig } from './defineConfig.js'

config/src/loadConfig.ts → config/src/loadConfig.js

@@ -1,15 +1,12 @@
-import type { CompilerConfig, ResolvedCompilerConfig } from './Config.js'
 import { defineConfig } from './defineConfig.js'
 import { existsSync, readFileSync } from 'fs'
 import { parse } from 'jsonc-parser'
 import * as path from 'path'
 
-type LoadConfig = (
-	configFilePath: string,
-	logger?: Pick<typeof console, 'error' | 'warn'>,
-) => ResolvedCompilerConfig
-
-export const loadConfig: LoadConfig = (configFilePath, logger = console) => {
+/**
+ * @type {import("./types.js").LoadConfig}
+ */
+export const loadConfig = (configFilePath, logger = console) => {
 	/**
 	 * evmts.config.ts currently doesn't work for ts-plugin because it is not syncronous
 	 * for now load config will load from tsconfig instead until fixed
@@ -27,12 +24,10 @@ export const loadConfig: LoadConfig = (configFilePath, logger = console) => {
 			`Failed to read the file at ${tsConfigPath}. Make sure the file exists and is accessible.`,
 		)
 	}
-	let configJson: {
-		compilerOptions: {
-			plugins?: Array<{ name: '@evmts/ts-plugin' } & CompilerConfig>
-			baseUrl?: string
-		}
-	}
+	/**
+	 * @type {{compilerOptions: {plugins?: Array<{ name: '@evmts/ts-plugin' } & import("./types.js").CompilerConfig>, baseUrl?: string }}}
+	 */
+	let configJson
 	try {
 		configJson = parse(configStr)
 		if (!configJson.compilerOptions) {
@@ -43,10 +38,12 @@ export const loadConfig: LoadConfig = (configFilePath, logger = console) => {
 		throw new Error(`tsconfig.json at ${tsConfigPath} is not valid json`)
 	}
 
-	let config: CompilerConfig | undefined =
-		configJson?.compilerOptions?.plugins?.find(
-			(plugin) => plugin.name === '@evmts/ts-plugin',
-		)
+	/**
+	 * @type {import("./types.js").CompilerConfig | undefined}
+	 */
+	let config = configJson?.compilerOptions?.plugins?.find(
+		(plugin) => plugin.name === '@evmts/ts-plugin',
+	)
 
 	if (!config) {
 		logger.warn(

config/src/loadConfigAsync.ts → config/src/loadConfigAsync.js

@@ -1,17 +1,13 @@
-import type { CompilerConfig, ResolvedCompilerConfig } from './Config.js'
 import { defineConfig } from './defineConfig.js'
 import { fileExists as defaultFileExists } from './fileExists.js'
 import { readFile } from 'fs/promises'
 import { parse } from 'jsonc-parser'
 import * as path from 'path'
 
-export type LoadConfigAsync = (
-	configFilePath: string,
-	logger?: Pick<typeof console, 'error' | 'warn'>,
-	fileExists?: typeof defaultFileExists,
-) => Promise<ResolvedCompilerConfig>
-
-export const loadConfigAsync: LoadConfigAsync = async (
+/**
+ * @type {import("./types.js").LoadConfigAsync}
+ */
+export const loadConfigAsync = async (
 	configFilePath,
 	logger = console,
 	fileExists = defaultFileExists,
@@ -33,12 +29,10 @@ export const loadConfigAsync: LoadConfigAsync = async (
 			`Failed to read the file at ${tsConfigPath}. Make sure the file exists and is accessible.`,
 		)
 	}
-	let configJson: {
-		compilerOptions: {
-			plugins?: Array<{ name: '@evmts/ts-plugin' } & CompilerConfig>
-			baseUrl?: string
-		}
-	}
+	/**
+	 * @type {{compilerOptions: {plugins?: Array<{ name: '@evmts/ts-plugin' } & import("./types.js").CompilerConfig>, baseUrl?: string }}}
+	 */
+	let configJson
 	try {
 		configJson = parse(configStr)
 		if (!configJson.compilerOptions) {
@@ -49,10 +43,12 @@ export const loadConfigAsync: LoadConfigAsync = async (
 		throw new Error(`tsconfig.json at ${tsConfigPath} is not valid json`)
 	}
 
-	let config: CompilerConfig | undefined =
-		configJson?.compilerOptions?.plugins?.find(
-			(plugin) => plugin.name === '@evmts/ts-plugin',
-		)
+	/**
+	 * @type {import("./types.js").CompilerConfig | undefined}
+	 */
+	let config = configJson?.compilerOptions?.plugins?.find(
+		(plugin) => plugin.name === '@evmts/ts-plugin',
+	)
 
 	if (!config) {
 		logger.warn(

config/src/Config.ts → config/src/types.ts

@@ -1,5 +1,4 @@
-import { getDefaultSolcVersion } from './getDefaultSolcVersion.js'
-import { z } from 'zod'
+import { fileExists as defaultFileExists } from './fileExists.js'
 
 /**
  * Configuration of the solidity compiler
@@ -29,21 +28,17 @@ export type CompilerConfig = {
 
 export type ResolvedCompilerConfig = Required<CompilerConfig>
 
-export const CompilerConfigValidator = z
-	.strictObject({
-		name: z.literal('@evmts/ts-plugin').optional(),
-		solcVersion: z.string().optional(),
-		foundryProject: z.union([z.boolean(), z.string()]).optional(),
-		libs: z.array(z.string()).optional(),
-		remappings: z.record(z.string()).optional(),
-	})
-	.describe('Configuration for EVMts')
-
-export const defaultConfig = {
-	get solcVersion() {
-		return getDefaultSolcVersion()
-	},
-	foundryProject: false,
-	remappings: {},
-	libs: [],
+export type DefineConfig = (configFactory: () => CompilerConfig) => {
+	configFn: (configFilePath: string) => ResolvedCompilerConfig
 }
+
+export type LoadConfig = (
+	configFilePath: string,
+	logger?: Pick<typeof console, 'error' | 'warn'>,
+) => ResolvedCompilerConfig
+
+export type LoadConfigAsync = (
+	configFilePath: string,
+	logger?: Pick<typeof console, 'error' | 'warn'>,
+	fileExists?: typeof defaultFileExists,
+) => Promise<ResolvedCompilerConfig>

config/tsup.config.ts

@@ -2,9 +2,9 @@ import { defineConfig } from 'tsup'
 
 export default defineConfig({
 	name: '@evmts/core',
-	entry: ['src/index.ts'],
+	entry: ['src/index.js'],
 	outDir: 'dist',
-	format: ['esm', 'cjs'],
+	format: ['cjs'],
 	splitting: false,
 	sourcemap: true,
 	clean: true,

config/typedoc.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://typedoc.org/schema.json",
 	"out": "../docs/reference/config",
-	"entryPoints": ["./src/index.ts"],
+	"entryPoints": ["./src/index.js"],
 	"publicPath": "/reference/config/",
 	"plugin": ["typedoc-plugin-markdown"],
 	"gitRevision": "main"