better-review 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Levasseur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# better-review
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interface web locale pour relire les pull requests GitHub : tout est déplié, le « vu » est suivi finement
+(fichier synchronisé avec GitHub, hunk / commit / thread en local) et la relecture se fait au clavier.
+
+Besoin détaillé : [`docs/besoin.md`](https://github.com/victorlevasseur/better-review/blob/main/docs/besoin.md) ·
+maquettes : [`mockups/index.html`](https://github.com/victorlevasseur/better-review/blob/main/mockups/index.html).
+
+## Prérequis
+
+- Node ≥ 24
+- Un token GitHub avec le scope `repo` : `GITHUB_TOKEN`, sinon celui de la CLI (`gh auth login`).
+  Le token reste côté serveur, il n'est jamais envoyé au navigateur.
+
+## Lancer
+
+```sh
+npx better-review              # http://127.0.0.1:4180
+# ou installé globalement :
+npm install -g better-review && better-review
+```
+
+Depuis les sources (pnpm ≥ 10) :
+
+```sh
+pnpm install
+pnpm build && pnpm start      # http://127.0.0.1:4180
+# ou en développement (Vite + rechargement du serveur) :
+pnpm dev                       # http://127.0.0.1:5173
+```
+
+Le serveur affiche au démarrage une URL `…/auth?token=…` : l'ouvrir une fois pose le cookie de session
+(valable 400 jours). Sans lui, l'API refuse les appels (protection contre les autres sites ouverts dans le
+navigateur). Le jeton est généré au premier lancement et conservé dans `BR_DATA_DIR/session-token` (0600) :
+redémarrer le serveur ne déconnecte pas. Le cookie est lié à l'hôte : `127.0.0.1` et `localhost` sont deux
+sessions distinctes.
+
+Puis « Repos suivis » : ajouter des repos (`owner/repo`) ou des orgs / comptes. L'inbox ne montre que cette liste.
+
+## Configuration
+
+| Variable           | Défaut                         | Rôle                                                                                    |
+| ------------------ | ------------------------------ | --------------------------------------------------------------------------------------- |
+| `PORT`             | `4180`                         | Port du serveur (API + front compilé)                                                   |
+| `WEB_PORT`         | `5173`                         | Port Vite en développement                                                              |
+| `GITHUB_TOKEN`     | `gh auth token`                | Token GitHub                                                                            |
+| `BR_CONFIG_DIR`    | `~/.config/better-review`      | `config.json` (repos / orgs suivis, `staleDays`) — éditable à la main, rechargé à chaud |
+| `BR_DATA_DIR`      | `~/.local/share/better-review` | `state.db` (SQLite : visites, hunks vus, threads lus, cache des diffs)                  |
+| `BR_SESSION_TOKEN` | `BR_DATA_DIR/session-token`    | Jeton de session imposé (scripts, tests)                                                |
+
+## Raccourcis (vue PR)
+
+`j`/`k` fichier · `n`/`p` hunk · `]`/`[` thread non résolu · `v` fichier vu puis fichier suivant (Focus : fichier non
+vu suivant), comme le bouton « Vu » d'un fichier · `h` hunk vu · `r` répondre · `x` résoudre · `m` continu/focus · `u` côte à côte/unifié ·
+`t` conversations · `d` description · `f` panneau fichiers · `Maj+S` review · `i` inbox · `Ctrl+K` aller à une PR ·
+`?` aide.
+
+Commenter : clic sur un numéro de ligne (« + » au survol), côté ancien code pour une ligne supprimée ou côté
+nouveau code pour une ligne ajoutée, `Maj+clic` pour une plage ; bouton « Commenter » dans l'en-tête d'un fichier
+pour le fichier entier. Chaque commentaire part seul ou dans la review en attente.
+
+## Naviguer dans les fichiers
+
+Le panneau de gauche (360 px, masquable avec `f`) propose trois vues. **La vue choisie fixe l'ordre des fichiers** :
+le diff, `j`/`k`, le mode Focus et « Vu → fichier suivant » suivent l'ordre affiché (les filtres masquent des lignes
+sans changer l'ordre).
+
+| Vue   | Ce qu'elle montre (et l'ordre qu'elle impose)                                                                  |
+| ----- | -------------------------------------------------------------------------------------------------------------- |
+| Liste | Fichiers par chemin, groupés par dossier (A→Z), ou du plus gros au plus petit (Taille) ; barre +/− par fichier |
+| Arbre | Dossiers repliables (sous-dossiers avant fichiers, A→Z ou Taille) avec changements, fichiers vus, threads      |
+| Liens | Fichiers en ordre de lecture « base d'abord », nombre d'imports / d'utilisateurs, graphe plein écran           |
+
+Les liens sont calculés côté serveur sur le contenu complet des fichiers au head de la PR : AST TypeScript pour
+TS/JS (y compris `.js` → `.ts`, `require`, `import()`), règles dédiées pour Python, CSS/SCSS/Less, Go, Java/Kotlin,
+C/C++, Rust, Ruby, Vue/Svelte. Les mentions (nom de fichier en CamelCase, ou nom avec extension, ou chemin) couvrent
+la doc et les autres langages. Les alias `tsconfig` `paths` autres que `@/`, `~/`, `#` ne sont pas résolus.
+
+**Ordre « base d'abord »** (vue Liens) : ordre topologique, chaque fichier après ceux qu'il importe ou mentionne, les
+plus utilisés en premier, les cycles départagés de la même façon et les fichiers sans lien à la fin. On relit la PR de
+ses fondations vers ce qui les assemble.
+
+**Voisinage** (onglet du panneau de droite, 520 px, quelle que soit la vue de gauche) : graphe du fichier courant, ce
+qu'il utilise → fichier → ce qui l'utilise, avec tous ses voisins ; clic sur un voisin pour l'ouvrir.
+
+**Monorepos** : chaque dossier contenant un manifeste (`package.json`, `pyproject.toml`, `setup.py`, `go.mod`,
+`Cargo.toml`, `pom.xml`, `build.gradle`, `composer.json`) est un package ; à partir de deux, l'ordre devient
+hiérarchique : packages du plus utilisé au plus dépendant (dépendances déclarées entre packages du workspace, y
+compris via un package non modifié, + imports entre fichiers), puis la base d'abord dans chaque package. Les imports
+par nom de package (`@acme/shared`, `@acme/shared/x`, crates Rust) sont résolus vers le point d'entrée du package
+(`exports` / `main` / `types` de `package.json`, sources `src/` correspondantes, `src/index.*`, `src/lib.rs`). La
+vue Liens groupe les fichiers par package et le graphe plein écran les encadre ; il affiche aussi les autres packages du
+monorepo et les dépendances entre packages (option « Autres packages du monorepo ») : en couleur uniquement les
+packages qui contiennent des fichiers modifiés (et les liens entre eux), le reste en gris. Le graphe de voisinage
+mélange fichiers et packages : à gauche les packages que le fichier importe par leur nom, à droite les packages qui
+dépendent de son package (quand aucun de leurs fichiers n'y figure déjà), mêmes couleurs ; un voisin d'un autre package
+porte le nom de son package, et un clic sur un package modifié ouvre son premier fichier dans l'ordre courant.
+
+La description de la PR s'ouvre dans l'onglet « Description » du panneau de droite.
+
+## Architecture
+
+```
+apps/cli        paquet npm `better-review` : serveur + packages du workspace groupés par esbuild, front compilé dans dist/web
+apps/server     Node + Hono + tRPC v11 : proxy GitHub (GraphQL, diffs REST), SQLite, polling → subscriptions SSE
+apps/web        Vite + React + Mantine, TanStack Router / Query, diff virtualisé, coloration Shiki en Web Worker
+packages/shared schémas zod, parseur de diff unifié (empreinte de hunk partagée serveur / navigateur)
+```
+
+- Les diffs sont demandés entre deux SHA (immuables) et mis en cache définitivement.
+- L'inbox fait une recherche « ids seulement » par section puis charge chaque PR une seule fois
+  (≈ 1 point de quota GraphQL par PR).
+- Une PR ouverte est surveillée toutes les 30 s, l'inbox toutes les 2 min ; un changement côté GitHub
+  rafraîchit l'écran sans rechargement.
+
+## Développement
+
+```sh
+pnpm lint && pnpm typecheck && pnpm test
+pnpm format
+```
+
+### Publier sur npm
+
+```sh
+cd apps/cli
+npm version <patch|minor|major> --no-git-tag-version   # version du paquet publié
+pnpm pack                                               # inspecter l'archive (facultatif)
+pnpm publish                                            # prepack : build complet + README / LICENSE
+```
+
+`pnpm publish` exige un arbre git propre sur `main` : committer le changement de version avant. Seul `typescript`
+reste une dépendance d'exécution (analyse des liens) ; le reste est inclus dans `dist/cli.js`.