Resolver — Resolveur d'imports universel

Systeme de resolution d'imports par dictionnaire pour projets TypeScript/JavaScript.

Remplace les chemins relatifs (../../components/Button) et les alias fragiles (@shared/hooks/useTheme) par des cles semantiques resolues au build-time :

// Avant
import { Button } from '../../components/ui/Button';
import { useTheme } from '@shared/hooks/useTheme';

// Apres
import { Button } from 'app:components/ui/Button';
import { useTheme } from 'app:hooks/useTheme';

Objectif

Dans un projet qui grandit, les imports deviennent un probleme :

• Les chemins relatifs cassent a chaque refactoring (../../../ fragile)
• Les alias Vite/Webpack se multiplient (@shared, @mobile, @seed, @bridge...)
• Deplacer un fichier casse des dizaines d'imports
• Les imports ne disent rien sur ce qu'ils importent (quel module ? quelle seed ?)

Le Resolver centralise la connaissance de ou vit chaque module dans un dictionnaire (manifest). Le code n'a plus besoin de connaitre les chemins — il utilise des cles semantiques. Deplacer un fichier = mettre a jour le manifest (1 ligne), pas 50 imports.

Quickstart (all-in-one)

# Dry-run : analyse le projet, montre ce qui serait fait
npx tsx Resolver/scripts/setup.ts --root ./mon-projet

# Appliquer : execute toutes les etapes
npx tsx Resolver/scripts/setup.ts --root ./mon-projet --apply

Le script setup.ts enchaine automatiquement :

1. Analyse du projet → genere resolver.config.json
2. Generation du manifest
3. Verification de coherence
4. Transformation des imports
5. Instructions pour brancher le plugin Vite

Comment ca marche

1. INIT           2. SCAN+MANIFEST   3. CHECK          4. CODEMOD         5. RESOLVE        6. WATCH
┌──────────┐     ┌──────────────┐   ┌──────────┐     ┌──────────┐      ┌──────────┐     ┌──────────┐
│ Analyse  │ ──> │ key → path   │──>│ Verif    │ ──> │ Rewrite  │ ──>  │ Plugin   │ ──> │ Watchdog │
│ projet   │     │ + exports    │   │ config   │     │ imports  │      │ Vite     │     │ auto     │
└──────────┘     └──────────────┘   └──────────┘     └──────────┘      └──────────┘     └──────────┘
init-config.ts   generate-          check-            codemod-          vite-resolver-   watch-
                 manifest.ts        config.ts         imports.ts        plugin.ts        manifest.ts

Etapes detaillees

1. Generer la config automatiquement

npx tsx Resolver/scripts/init-config.ts --root ./mon-projet

Analyse le projet et genere resolver.config.json :

• Detecte les dossiers source (src/, lib/, shared/)
• Detecte les alias tsconfig.json/jsconfig.json
• Detecte les dossiers a exclure (_archives, dist)
• Propose un prefix base sur le package.json

Revoir et ajuster la config avant de continuer.

2. Generer le manifest

npx tsx Resolver/scripts/generate-manifest.ts \
  --root ./mon-projet \
  --config resolver.config.json

Produit :

• resolver-output/resolver-manifest.json — dictionnaire key → path + exports
• resolver-output/resolver-reverse.json — lookup inverse export name → keys

3. Verifier la config

npx tsx Resolver/scripts/check-config.ts \
  --root ./mon-projet \
  --config resolver.config.json

Verifie :

• Chaque namespace matche au moins 1 fichier
• Tous les fichiers source sont couverts
• Les alias pointent vers des dossiers existants
• Le manifest est a jour (pas d'entrees obsoletes, pas de fichiers oublies)
• Les imports prefix: dans le code pointent vers des cles existantes

4. Transformer les imports

# Dry-run : voir les changements
npx tsx Resolver/scripts/codemod-imports.ts \
  --root ./mon-projet \
  --config resolver.config.json

# Appliquer
npx tsx Resolver/scripts/codemod-imports.ts \
  --root ./mon-projet \
  --config resolver.config.json \
  --apply

# Limiter a un sous-dossier
npx tsx Resolver/scripts/codemod-imports.ts \
  --root ./mon-projet \
  --config resolver.config.json \
  --apply --dir src/components

5. Brancher le plugin Vite

// vite.config.ts
import { universalResolverPlugin } from './Resolver/scripts/vite-resolver-plugin';

export default defineConfig({
  plugins: [
    universalResolverPlugin({
      projectRoot: __dirname,
      manifestPath: './resolver-output/resolver-manifest.json',
      prefix: 'app',
      overrides: { desktop: 'mobile' }, // optionnel
    }),
  ],
});

6. Activer le watchdog (dev mode)

// vite.config.ts — pour hot-reload automatique du manifest
import { resolverWatchPlugin } from './Resolver/scripts/watch-manifest';

export default defineConfig({
  plugins: [
    resolverWatchPlugin({
      root: __dirname,
      config: './resolver.config.json',
    }),
    // ... autres plugins
  ],
});

Ou en standalone :

npx tsx Resolver/scripts/watch-manifest.ts \
  --root ./mon-projet \
  --config resolver.config.json

Le watchdog :

• Surveille les dossiers source via fs.watch (recursif)
• Debounce les changements (300ms par defaut)
• Regenere le manifest quand un fichier .ts/.tsx est cree ou supprime
• Ne regenere PAS pour les modifications de contenu (seul le path compte)
• S'integre comme plugin Vite pour le dev server

7. TypeScript

Pour que TypeScript accepte les imports prefix:*, ajouter dans un .d.ts :

declare module 'app:*' {}
// ou plus specifique :
declare module 'crane:*' {}

Override automatique (multi-plateforme)

Pour les projets multi-plateforme (desktop/mobile), le resolver supporte les redirections automatiques :

{
  "overrides": { "desktop": "mobile" }
}

Si un import demande app:mobile:Dashboard et qu'un app:desktop:Dashboard existe dans le manifest, le resolver utilise automatiquement la version desktop.

Config reference

{
  "prefix": "app",
  "namespaces": [
    { "id": "components", "pattern": "^src/components/(.+)$" },
    { "id": "hooks",      "pattern": "^src/hooks/(.+)$" }
  ],
  "aliases": {
    "@/": "src/",
    "@components/": "src/components/"
  },
  "exclude": ["_archives", "dist", "stubs"],
  "outputDir": "./resolver-output",
  "overrides": { "desktop": "mobile" }
}

Champ	Role
prefix	Prefixe des imports (app:hooks/useTheme)
namespaces	Regles regex ordonnees — premiere qui matche gagne
aliases	Mapping des alias existants (pour le codemod)
exclude	Dossiers exclus du scan
outputDir	Ou ecrire le manifest
overrides	Redirections namespace → namespace

Avantages

• Refactoring sans casse — deplacer un fichier = 1 ligne dans le manifest
• Imports lisibles — crane:connector:OrderFlow dit d'ou vient le module
• Zero config par fichier — plus d'alias Vite/tsconfig par couche
• Multi-plateforme natif — overrides desktop/mobile sans plugin special
• Indexable — le manifest JSON permet de chercher un export et trouver son module
• Reverse lookup — "qui exporte useConfigStore ?" → reponse immediate
• Incrementiel — migration dossier par dossier, anciens imports compatibles
• Watchdog — manifest regenere automatiquement en dev quand des fichiers changent
• All-in-one — setup.ts fait tout en une commande

Inconvenients

• Build-time only — le resolver est un plugin Vite, pas un runtime Node.js (sauf avec loader custom)
• Manifest a regenerer — apres ajout/suppression de fichiers (automatise par le watchdog)
• TypeScript declarations — les imports prefix:* necessitent un declare module global
• Codemod imparfait — template literals et imports dynamiques complexes ne sont pas transformes

Limites

• Resolution au fichier — la cle pointe vers un fichier, pas un export individuel
• Regex-based — extraction des exports par regex, pas par un parser AST. Les cas exotiques peuvent etre manques
• Packages npm non couverts — react, zustand restent en import classique
• fs.watch recursive — le watchdog utilise { recursive: true } qui n'est pas supporte sur tous les OS Linux (OK sur macOS, Windows, et Linux kernel 5.9+)

Structure

Resolver/
  README.md                           ← ce fichier
  resolver.config.example.json        ← config d'exemple
  scripts/
    setup.ts                          ← all-in-one pour debutant
    init-config.ts                    ← analyse projet → config
    scan-files.ts                     ← scanner les fichiers source
    generate-manifest.ts              ← generer le dictionnaire
    check-config.ts                   ← verifier la coherence
    codemod-imports.ts                ← transformer les imports
    vite-resolver-plugin.ts           ← plugin Vite resolution
    watch-manifest.ts                 ← watchdog + plugin Vite hot-reload