docs: Document Next.js @ alias fallback behavior

[lightninglu10]

Summary

• Added comprehensive JSDoc comments to the webpack plugin's getAliasMap method
• Documents the automatic @ alias detection fallback behavior
• Clarifies when the fallback applies and how to override it

Changes

The webpack plugin has a fallback that auto-detects the @ alias for Next.js projects. This PR adds detailed documentation explaining:

1. When the fallback activates:

   • Only when no @ alias is found in tsconfig.json paths
   • Only when no @ alias is found in webpack resolve.alias
   • Only when a "src" directory exists in the project root

2. What it does:

   • Assumes Next.js convention: @/* → ./src/*
   • Enables imports like: import { Button } from "@/components/Button"

3. How to override it:

   • For non-Next.js projects or custom structures
   • Use explicit tsconfig.json paths configuration
   • Example: { "compilerOptions": { "paths": { "@/*": ["./app/*"] } } }

Test Plan

• Documentation only change, no functional changes
• Existing behavior remains unchanged
• The fallback continues to work as before for Next.js projects
• Users can still override with explicit configuration

🤖 Generated with Claude Code

[github-actions]

❇️ CodePress Review Summary

👋 Hey team,

Overall the changes look great! No specific issues found.

Here's the quick rundown:

✅ Decision: APPROVE
Change is documentation-only with no impact on behavior or build; safe to merge.