Ouvrir un depot inconnu declenche souvent les memes questions : ou se trouve le point d’entree? Quels fichiers dependent de ce module? Qui connait cette zone? Que risque-t-on de casser en la modifiant?
braedonsaunders/codeflow transforme un depot GitHub ou un projet local en carte d’architecture interactive, directement dans le navigateur. Collez une URL—ou selectionnez un dossier local—et Codeflow analyse fichiers, fonctions, dependances, patterns, signaux de securite, ownership, churn et impact sans compte ni backend applicatif.
Son idee centrale est simple : une architecture doit pouvoir s’explorer. Plutot que lire une arborescence et deviner les relations, on clique sur un noeud, suit ses dependances, mesure son blast radius et change de vue pour exposer couches ou zones chaudes.
Codeflow est sous licence MIT, fonctionne depuis un unique index.html et conserve le traitement cote client. Il est donc facile a essayer, inspecter, auto-heberger et utiliser sur des projets sensibles.
Ce que fait Codeflow
Codeflow est un outil client-side de visualisation et d’analyse statique. Il recupere les donnees d’un depot directement depuis GitHub—ou lit des fichiers locaux—puis construit un graphe de dependances navigable.
Ses fonctions actuelles comprennent :
- graphes interactifs de fichiers et dependances
- analyse du blast radius d’un fichier
- analyse d’impact depuis l’URL d’une pull request
- ownership derive de l’historique Git
- heatmap d’activite selon la frequence des commits
- detection de patterns, anti-patterns, code mort, cycles et couplage
- controles de secrets, injection SQL,
eval()dangereux et debug en production - note de sante de A a F
- analyse locale par dossier, selection ou drag-and-drop
- exports JSON, Markdown, texte, SVG, PDF et JSON brut
- graphes Markdown et wiki-links pour documentation ou vaults Obsidian
Codeflow Card ajoute une GitHub Action qui recalcule sante, echelle, fragilite et couts caches apres chaque merge, puis publie une carte SVG adaptee au theme dans le README.
Des fichiers a la carte d’architecture
L’architecture de Codeflow est volontairement compacte. L’application principale tient dans une page navigateur utilisant React 18, D3.js 7 et Babel charges depuis des CDN epingles. Aucun service d’analyse serveur et aucune installation de packages ne sont requis pour l’application.
Le parser extrait fonctions et signaux de dependances. D3 transforme ces relations en noeuds et aretes. L’API GitHub ajoute metadonnees, historique et contexte des contributeurs.
Quatre modes visuels repondent a des questions differentes :
- Folder : comprendre l’organisation physique du depot.
- Layer : distinguer UI, services, utilitaires et autres roles.
- Churn : exposer les fichiers souvent modifies.
- Blast : montrer l’impact potentiel d’un fichier selectionne.
La carte ne remplace pas la lecture du code. Elle aide a choisir ou lire en premier.
Blast radius et impact des PR
Les graphes deviennent operationnels lorsqu’ils eclairent une decision de changement.
Selectionnez un fichier : Codeflow surligne ceux qui en dependent. Cette estimation du blast radius montre souvent qu’un utilitaire partage ou un service fondamental a plus d’impact qu’un composant UI terminal.
L’analyse des PR applique la meme logique aux modifications proposees. Une URL de pull request suffit pour voir les fichiers touches et leur portee architecturale. Les reviewers peuvent ainsi cibler tests, owners supplementaires ou rollout prudent.
Le blast radius reste un signal de priorisation. Imports dynamiques, wiring runtime, reflection, code genere et conventions de framework peuvent echapper a une analyse heuristique.
Sante, patterns et signaux de securite
Codeflow resume la sante via code mort, dependances circulaires, couplage et problemes de securite. Il reconnait Singleton, Factory, Observer/Event et hooks React, et signale God Objects ou modules fortement couples.
Le scanner cherche secrets et cles API, motifs d’injection SQL, appels eval() dangereux et traces de debug. Certains controles excluent tests, fixtures, documentation et repertoires d’outillage afin de reduire le bruit, tandis que les surfaces CI et de deploiement restent inspectees pour les secrets.
Ces resultats sont des signaux de triage, pas des conclusions de securite. Une analyse heuristique peut produire faux positifs et omissions. Chaque alerte doit etre confirmee humainement.
Analyse locale et confidentialite
Codeflow traite les donnees dans le navigateur. Pour les depots publics, celui-ci appelle GitHub directement. Pour les depots prives, un token personnel ou GitHub App peut etre fourni localement; le projet indique qu’il reste en memoire et disparait a la fermeture de l’onglet.
Les projets locaux s’ouvrent par selection de dossier ou drag-and-drop, avec exclusions pour caches, uploads, assets generes ou pieces jointes. Ce chemin fonctionne hors ligne et n’impose pas de televerser le code.
Ce modele est interessant pour les projets internes. Une equipe doit neanmoins evaluer la page, ses dependances CDN, les permissions du token et l’environnement navigateur selon sa politique de securite.
Essayer ou auto-heberger Codeflow
Le plus rapide est l’application hebergee : collez l’URL d’un depot ou d’une pull request.
L’auto-hebergement est minimal :
git clone https://github.com/braedonsaunders/codeflow.git
cd codeflow
open index.html
Aucun npm install ni pipeline de build. Les dependances etant chargees depuis des CDN, un usage totalement hors ligne d’une copie fraiche peut demander de les mettre en cache ou de les heberger localement; l’analyse des fichiers reste cote client.
L’API GitHub limite l’acces non authentifie a 60 requetes par heure. Un token monte a 5 000, important pour les grands depots puisque Codeflow peut lire les contenus fichier par fichier.
Langages supportes et precision realiste
Codeflow couvre JavaScript, TypeScript, Python, Java, Go, Ruby, PHP, Vue, Svelte, Rust, C/C++, C#, Swift, Kotlin, Scala, Elixir, Erlang, Haskell, Lua, R, Julia, Dart, Shell, PowerShell, plusieurs langages fonctionnels et d’autres.
Cette largeur a un prix. Le projet qualifie explicitement l’analyse de dependances d’heuristique. Les fonctions uniques sont associees par nom; les doublons sont scopes par fichier et imports explicites. Imports dynamiques et references runtime renommees peuvent rester invisibles.
Utilisez Codeflow pour l’orientation rapide et la formulation d’hypotheses. Pour migration, validation de securite ou suppression, confirmez les relations avec outils natifs du langage, tests, telemetrie et owners.
Workflow pratique en equipe
Un parcours utile consiste a :
- Generer la vue dossier pour apprendre la forme du depot.
- Passer aux couches pour identifier les frontieres.
- Examiner le churn et les zones instables.
- Selectionner le changement prevu et son blast radius.
- Consulter l’ownership avant de choisir les reviewers.
- Exporter le rapport en JSON ou Markdown.
- Valider les constats importants avec tests et outils natifs.
- Ajouter Codeflow Card si le suivi continu de la derive architecturale apporte de la valeur.
Codeflow devient ainsi un support de conversation entre mainteneurs, reviewers et nouveaux contributeurs, pas seulement un generateur de diagrammes.
Conclusion
Codeflow reduit le cout de comprehension d’un codebase inconnu. Son approche browser-first regroupe architecture, impact des changements, ownership, churn, sante, securite, rapports et cartes README sans deployer un backend d’analyse.
Sa valeur est maximale quand on le considere comme un modele visuel rapide, pas comme une representation semantique parfaite. Ce modele repond deja aux questions quotidiennes : ou commencer, ce qui est connecte, qui connait la zone et ce qui exige plus de prudence avant livraison.