chore: remove dead #* path aliases and redundant /index exports

The #constants/#env/#lib/#packages/#types/#utils aliases were defined
in tsconfig.external-aliases.json and wired through esbuild, vitest,
and a dedicated fix script — but zero src/ files actually used them.
Dead plumbing that added indirection without saving keystrokes.

Also drop duplicate `./themes/index` and `./links/index` exports
(identical targets to `./themes` and `./links`). Update the
generator to stop emitting `dir/index` subpaths for index files.

Author: jdalton

.config/esbuild.config.mts

@@ -198,55 +198,6 @@ function createPathShorteningPlugin() {
   }
 }
 
-/**
- * Plugin to resolve internal path aliases (#lib/*, #constants/*, etc.) to relative paths
- */
-function createPathAliasPlugin() {
-  return {
-    name: 'internal-path-aliases',
-    setup(build) {
-      // Map of path aliases to their actual directories
-      const pathAliases = {
-        '#lib/': srcPath,
-        '#constants/': path.join(srcPath, 'constants'),
-        '#env/': path.join(srcPath, 'env'),
-        '#packages/': path.join(srcPath, 'packages'),
-        '#utils/': path.join(srcPath, 'utils'),
-        '#types': path.join(srcPath, 'types'),
-      }
-
-      // Intercept imports for path aliases
-      for (const [alias, basePath] of Object.entries(pathAliases)) {
-        const isExact = !alias.endsWith('/')
-        const filter = isExact
-          ? new RegExp(`^${alias.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`)
-          : new RegExp(`^${alias.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`)
-
-        build.onResolve({ filter }, args => {
-          // Calculate the subpath after the alias
-          const subpath = isExact ? '' : args.path.slice(alias.length)
-          const targetPath = subpath ? path.join(basePath, subpath) : basePath
-
-          // Calculate relative path from the importing file to the target
-          const importer = args.importer || srcPath
-          const importerDir = path.dirname(importer)
-          let relativePath = path.relative(importerDir, targetPath)
-
-          // Ensure relative paths start with ./ or ../
-          if (!relativePath.startsWith('.')) {
-            relativePath = `./${relativePath}`
-          }
-
-          // Normalize to forward slashes for consistency
-          relativePath = relativePath.replace(/\\/g, '/')
-
-          return { path: relativePath, external: true }
-        })
-      }
-    },
-  }
-}
-
 // Build configuration for CommonJS output
 export const buildConfig = {
   entryPoints,
@@ -266,10 +217,8 @@ export const buildConfig = {
   metafile: true,
   logLevel: 'info',
 
-  // Use plugins for path shortening and aliases
-  plugins: [createPathShorteningPlugin(), createPathAliasPlugin()].filter(
-    Boolean,
-  ),
+  // Use plugins for path shortening
+  plugins: [createPathShorteningPlugin()].filter(Boolean),
 
   // Note: Cannot use "external" with bundle: false.
   // esbuild automatically treats all imports as external when not bundling.

.config/tsconfig.external-aliases.json

@@ -3,12 +3,6 @@
   "compilerOptions": {
     "declarationMap": false,
     "paths": {
-      "#constants/*": ["../src/constants/*"],
-      "#env/*": ["../src/env/*"],
-      "#lib/*": ["../src/*"],
-      "#packages/*": ["../src/packages/*"],
-      "#types": ["../src/types"],
-      "#utils/*": ["../src/utils/*"],
       "cacache": ["../src/external/cacache"],
       "make-fetch-happen": ["../src/external/make-fetch-happen"],
       "fast-sort": ["../src/external/fast-sort"],

.config/vitest.config.isolated.mts

@@ -19,13 +19,6 @@ const vitestConfigIsolated = defineConfig({
     preserveSymlinks: false,
     extensions: ['.mts', '.ts', '.mjs', '.js', '.json'],
     alias: {
-      '#env/ci': path.resolve(projectRoot, 'src/env/ci.ts'),
-      '#env': path.resolve(projectRoot, 'src/env'),
-      '#constants': path.resolve(projectRoot, 'src/constants'),
-      '#lib': path.resolve(projectRoot, 'src/lib'),
-      '#packages': path.resolve(projectRoot, 'src/lib/packages'),
-      '#types': path.resolve(projectRoot, 'src/types.ts'),
-      '#utils': path.resolve(projectRoot, 'src/utils'),
       cacache: path.resolve(projectRoot, 'src/external/cacache'),
       'make-fetch-happen': path.resolve(
         projectRoot,

CLAUDE.md

@@ -143,7 +143,9 @@ Color the icon only, not the message. Use `yoctocolors-cjs` (not the ESM `yoctoc
 
 Core infrastructure library for Socket.dev security tools.
 
-**Path aliases** (from `.config/tsconfig.external-aliases.json`): `#constants/*`, `#env/*`, `#lib/*`, `#packages/*`, `#types`, `#utils/*` — all map to `src/` subdirectories. Always use aliases for internal imports (never relative paths).
+**Internal imports**: Use relative paths (e.g., `'../constants/packages'`). Path aliases are intentionally avoided — they add indirection without saving keystrokes and mask structural coupling.
+
+**Vendored externals**: `cacache`, `make-fetch-happen`, `fast-sort`, `pacote`, `adm-zip`, `tar-fs`, `picomatch` are vendored in `src/external/` and remapped via `tsconfig.json` `paths`. Always import these by their bare package name; the tsconfig resolves them to the vendored copy.
 
 ### Commands
 
@@ -199,7 +201,7 @@ Core infrastructure library for Socket.dev security tools.
 1. Node.js built-ins (with `node:` prefix)
 2. External dependencies
 3. `@socketsecurity/*` packages
-4. Internal path aliases (`#constants/*`, `#env/*`, `#lib/*`, etc.)
+4. Internal relative paths (`../constants/*`, `../env/*`, etc.)
 5. Type imports (separate)
 
 Blank lines between groups, alphabetical within groups.
@@ -237,7 +239,7 @@ Custom optimized pipeline in `.github/workflows/ci.yml`: separate lint job (runs
 
 ### Environment Variables
 
-Access via typed getter functions in `src/env/`. Each module exports a pure getter. Test rewiring via `#env/rewire` (`setEnv`, `clearEnv`, `resetEnv`) without modifying `process.env`.
+Access via typed getter functions in `src/env/`. Each module exports a pure getter. Test rewiring via `src/env/rewire.ts` (`setEnv`, `clearEnv`, `resetEnv`) without modifying `process.env`.
 
 ### Working Directory
 

package.json

@@ -415,10 +415,6 @@
       "types": "./dist/links/index.d.ts",
       "default": "./dist/links/index.js"
     },
-    "./links/index": {
-      "types": "./dist/links/index.d.ts",
-      "default": "./dist/links/index.js"
-    },
     "./logger": {
       "types": "./dist/logger.d.ts",
       "default": "./dist/logger.js"
@@ -631,10 +627,6 @@
       "types": "./dist/themes/context.d.ts",
       "default": "./dist/themes/context.js"
     },
-    "./themes/index": {
-      "types": "./dist/themes/index.d.ts",
-      "default": "./dist/themes/index.js"
-    },
     "./themes/themes": {
       "types": "./dist/themes/themes.d.ts",
       "default": "./dist/themes/themes.js"

scripts/fix/generate-package-exports.mts

@@ -102,31 +102,26 @@ async function main(): Promise<void> {
     if (ext === EXT_JSON) {
       jsonExports[`./${exportPath}`] = filePath
     } else {
-      const extLessExportPath = `./${exportPath.slice(0, -ext.length)}`
       const isDts = ext === EXT_DTS
-      if (o[extLessExportPath]) {
-        o[extLessExportPath][isDts ? 'types' : 'default'] = filePath
+      const basename = path.basename(exportPath, ext)
+      // For index files, expose only the directory path (e.g., './themes'),
+      // not the redundant './themes/index' form.
+      let publicPath: string
+      if (basename === 'index') {
+        const dirname = path.dirname(exportPath)
+        publicPath = dirname === '.' ? '.' : `./${dirname}`
+      } else {
+        publicPath = `./${exportPath.slice(0, -ext.length)}`
+      }
+      if (o[publicPath]) {
+        o[publicPath][isDts ? 'types' : 'default'] = filePath
       } else {
-        o[extLessExportPath] = {
+        o[publicPath] = {
           // Order is significant. Default should be specified last.
           types: isDts ? filePath : undefined,
           default: isDts ? undefined : filePath,
         }
       }
-      const basename = path.basename(exportPath, ext)
-      if (basename === 'index') {
-        const dirname = path.dirname(exportPath)
-        const dirPath = dirname === '.' ? dirname : `./${dirname}`
-        if (o[dirPath]) {
-          o[dirPath][isDts ? 'types' : 'default'] = filePath
-        } else {
-          o[dirPath] = {
-            // Order is significant. Default should be specified last.
-            types: isDts ? filePath : undefined,
-            default: isDts ? undefined : filePath,
-          }
-        }
-      }
     }
     return o
   }, {})

scripts/fix/main.mts

@@ -36,10 +36,6 @@ async function main(): Promise<void> {
       args: ['scripts/fix/generate-package-exports.mts', ...fixArgs],
       command: 'node',
     },
-    {
-      args: ['scripts/fix/path-aliases.mts', ...fixArgs],
-      command: 'node',
-    },
     {
       args: ['scripts/fix/external-imports.mts', ...fixArgs],
       command: 'node',