From b9b62f9a7a207958d4e740b37a676941c795ae5c Mon Sep 17 00:00:00 2001
From: Patrick Lu <lightning.lu7@gmail.com>
Date: Sat, 29 Nov 2025 11:44:14 -0800
Subject: [PATCH] docs: Document tsconfig parsing limitations in webpack plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive JSDoc comments to the getAliasMap method explaining:
- Why regex parsing is used instead of JSON.parse (TypeScript allows JSON5 syntax with comments and trailing commas)
- Known limitations including multi-line paths, extends support, JSON5 edge cases, and complex path patterns
- Fallback behavior when parsing fails (Next.js convention of @ -> src)

The regex-based approach is necessary to handle tsconfig.json files with comments,
but has limitations that developers should be aware of when debugging alias resolution.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 src/webpack-plugin.ts | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/webpack-plugin.ts b/src/webpack-plugin.ts
index f445b36..479d44c 100644
--- a/src/webpack-plugin.ts
+++ b/src/webpack-plugin.ts
@@ -83,6 +83,27 @@ export default class CodePressWebpackPlugin {
    *
    * For example, with tsconfig paths: { "@/*": ["./src/*"] }
    * This returns: { "@": "src" }
+   *
+   * @remarks
+   * **Tsconfig Parsing Strategy:**
+   * This method uses regex-based parsing instead of JSON.parse() to handle tsconfig.json
+   * because TypeScript allows JSON5 syntax (comments and trailing commas), which would
+   * cause JSON.parse() to fail.
+   *
+   * **Known Limitations:**
+   * 1. **Multi-line paths:** May fail on path definitions spanning multiple lines with
+   *    nested braces or complex formatting.
+   * 2. **Extends:** Does not follow the `extends` field to resolve inherited path mappings
+   *    from base tsconfig files.
+   * 3. **JSON5 edge cases:** May not handle all JSON5 syntax variations that TypeScript
+   *    supports (e.g., comments within path arrays, unusual whitespace patterns).
+   * 4. **Complex path patterns:** Only parses simple patterns like `"@/*": ["./src/*"]`.
+   *    More complex mappings with multiple array elements may not be fully supported.
+   *
+   * **Fallback Behavior:**
+   * If tsconfig parsing fails or no paths are found, the method falls back to the Next.js
+   * convention of mapping `@` to `src` directory if it exists. Webpack's resolve.alias is
+   * always checked first before attempting tsconfig parsing.
    */
   private getAliasMap(compiler: Compiler): Map<string, string> {
     const aliases = new Map<string, string>();
@@ -121,6 +142,8 @@ export default class CodePressWebpackPlugin {
 
           // Extract paths directly using regex (avoids JSON parsing issues with comments/globs)
           // Match: "paths": { "@/*": ["./src/*"] } or similar
+          // NOTE: This regex assumes single-line path objects. Multi-line paths with nested
+          // braces may not be captured correctly. See method JSDoc for full limitations.
           const pathsMatch = tsconfigContent.match(
             /"paths"\s*:\s*\{([^}]+)\}/
           );