projscan 0.1.0

Scanner de dépôts git locaux et de tools uv installés.

projscan

Scanner de dépôts git locaux et de tools uv installés depuis git.
Répond à une question simple : suis-je à jour ?

Installation

uv tool install git+https://github.com/Caymaar/projscan.git

Ou en mode développement :

git clone ...
cd projscan
uv sync
uv run projscan --help

Commandes

projscan repos [PATHS]...

Scanne récursivement un ou plusieurs dossiers et affiche l'état de chaque dépôt git.

╭──────────────────────┬─────────┬─────────┬─────────────────────┬────────┬────────────────────┬─────────────╮
│ Nom                  │ Version │ Branche │ Statut              │ Commit │ Message            │ Quand       │
├──────────────────────┼─────────┼─────────┼─────────────────────┼────────┼────────────────────┼─────────────┤
│ mon-api              │ 2.1.0   │ main    │ en retard (↓3)      │ a4f2c1 │ fix: timeout retry │ 2 days ago  │
│ mon-dashboard        │ 1.0.0   │ main    │ divergé (↓1 ↑2)     │ b8e3d9 │ feat: dark mode    │ 5 hours ago │
│ projscan             │ 0.1.0   │ main    │ à jour              │ c1a2b3 │ initial commit     │ 1 hour ago  │
╰──────────────────────┴─────────┴─────────┴─────────────────────┴────────┴────────────────────┴─────────────╯
3 repos, 1 à jour, 2 à mettre à jour

Options :

Option	Description
--no-fetch	Ne pas faire git fetch — utilise le cache local (rapide)
--depth INTEGER	Profondeur max de récursion (défaut : 3)
--json	Sortie JSON machine-readable
--concurrency INTEGER	Scans parallèles (défaut : 16)

# Scanne ~/code et ~/work
projscan repos ~/code ~/work

# Rapide, sans réseau
projscan repos --no-fetch ~/code

# Pipe JSON vers jq
projscan repos --no-fetch --json ~/code | jq '.[] | select(.status != "à jour")'

projscan tools

Scanne les tools installés via uv tool install git+https://... et vérifie si des mises à jour sont disponibles (via git ls-remote, sans cloner).

╭────────────────┬─────────┬───────────────────────────────┬────────┬──────────┬───────────╮
│ Nom            │ Version │ Source                        │ Ref    │ Commit   │ Statut    │
├────────────────┼─────────┼───────────────────────────────┼────────┼──────────┼───────────┤
│ mon-tool       │ 1.2.0   │ github.com/org/mon-tool.git   │ main   │ f10c2123 │ MAJ dispo │
│ autre-tool     │ 0.9.1   │ github.com/org/autre-tool.git │ main   │ fc9e74c5 │ à jour    │
╰────────────────┴─────────┴───────────────────────────────┴────────┴──────────┴───────────╯
2 tools, 1 à jour, 1 à mettre à jour

Options :

Option	Description
--tool-dir PATH	Racine des tools uv (détection auto par défaut)
--no-remote	Liste locale sans vérifier les remotes
--json	Sortie JSON machine-readable

projscan tools
projscan tools --no-remote --json
projscan tools --tool-dir ~/.local/share/uv/tools

Codes de sortie

Code	Signification
0	Tout est à jour
1	Au moins un item à mettre à jour (ou en erreur)
2	Erreur d'exécution fatale
130	Interruption clavier (Ctrl-C)

Utile en script ou en CI :

projscan repos --no-fetch ~/code || echo "Des repos sont en retard !"

Couleurs de statut

Statut	Couleur	Signification
à jour	vert	Synchronisé avec l'upstream
en retard (↓N)	rouge	N commits distants non récupérés
en avance (↑N)	cyan	N commits locaux non poussés
divergé (↓N ↑M)	magenta	Branches divergées
MAJ dispo	jaune	Nouvelle version du tool disponible
pas d'upstream	gris	Pas de tracking branch configurée
pas git	gris	Tool installé depuis PyPI, pas git
inconnu	gris	Remote inaccessible (offline, auth...)
erreur	rouge gras	Erreur lors du scan

Usage comme bibliothèque

projscan est conçu pour être importé dans une app Textual ou tout autre code async.

from pathlib import Path
from projscan import scan_paths, scan_tools, RepoInfo, ToolInfo

# Scanne des dépôts git
repos: list[RepoInfo] = await scan_paths(
    [Path("~/code")],
    fetch=True,
    max_depth=3,
    concurrency=16,
)

for repo in repos:
    print(f"{repo.name}: {repo.status}")

# Scanne les tools uv
tools: list[ToolInfo] = await scan_tools(check_remote=True)

for tool in tools:
    if tool.status == "MAJ dispo":
        print(f"Update available: {tool.name}")

Les dataclasses exposent une méthode .as_dict() pour la sérialisation JSON :

import json
print(json.dumps([r.as_dict() for r in repos], ensure_ascii=False))

L'API publique complète :

from projscan import (
    # Git
    RepoInfo, scan_paths, scan_repo, find_repos,
    # UV tools
    ToolInfo, scan_tools, scan_tool, uv_tool_dir,
)

Développement

uv sync
uv run pytest           # 52 tests, ~5s
uv run projscan repos . # test en réel
uv run projscan tools   # test en réel