noeva-codebase-inspector

v1.1.0

Published

8 months ago

CLI tool per analizzare la codebase settimana per settimana con integrazione GitHub e JIRA

🔍 Noeva CodeBase Inspector

Una CLI potente per analizzare la salute e le performance della tua codebase settimana per settimana, con integrazione completa GitHub e JIRA.

🚀 Caratteristiche

📊 Analisi Settimanali: Report dettagliati dell'attività settimanale
👥 Team Analytics: Performance e collaborazione del team
🏥 Health Check: Controllo completo della salute del progetto
🎫 Integrazione JIRA: Tracciamento automatico dei ticket
🐱 GitHub Integration: Pull Request, Actions, Issues, Releases
📝 Report Markdown: Output professionale e leggibile
⚙️ Configurazione Flessibile: Setup personalizzabile per ogni team

📦 Installazione

Opzione 1: Installazione Globale (Raccomandato)

npm install -g noeva-codebase-inspector

Opzione 2: Uso Locale

npx noeva-codebase-inspector

Opzione 3: Sviluppo

git clone https://github.com/gruppo4d/noeva-codebase-inspector
cd noeva-codebase-inspector
npm install
npm link

🚀 Quick Start

1. Setup Iniziale

# Vai nella directory del tuo progetto
cd /path/to/your/project

# Inizializza NCI
nci init

Il setup ti guiderà attraverso:

Configurazione progetto e team
Setup GitHub (token e repository)
Integrazione JIRA (opzionale)
Preferenze di analisi

2. Primo Report

# Report settimanale delle ultime 4 settimane
nci weekly

# Analisi team
nci team

# Health check completo
nci health

📋 Comandi Disponibili

🔧 Setup e Configurazione

nci init                    # Setup iniziale
nci config --show          # Mostra configurazione
nci config --edit          # Modifica configurazione
nci config --reset         # Reset configurazione

📊 Analisi e Report

# Report settimanale
nci weekly                  # Ultime 4 settimane (default)
nci weekly --weeks 8        # Ultime 8 settimane
nci weekly -o report.md     # Output personalizzato
nci weekly --detailed       # Include dettagli avanzati

# Analisi team
nci team                    # Performance team
nci team --weeks 6          # Team performance 6 settimane
nci team -o team-stats.md   # Output personalizzato

# Health check
nci health                  # Controllo salute completo
nci health -o health.md     # Output personalizzato

⚙️ Configurazione

File di Configurazione

La configurazione viene salvata in .nci-config.json:

{
  "project": {
    "name": "noeva-app",
    "createdAt": "2025-06-27T10:00:00.000Z"
  },
  "git": {
    "mainBranch": "main",
    "excludeBranches": ["gh-pages", "dependabot/*"]
  },
  "github": {
    "owner": "gruppo4d",
    "repo": "noeva-app",
    "token": "ghp_xxxxxxxxxxxx"
  },
  "jira": {
    "enabled": true,
    "baseUrl": "https://gruppo4d.atlassian.net",
    "browseUrl": "https://gruppo4d.atlassian.net/browse/",
    "projects": ["NW", "NOBUG"]
  },
  "team": {
    "members": ["[email protected]", "[email protected]"],
    "defaultWeeks": 4
  }
}

GitHub Token Setup

Vai su GitHub Settings → Developer settings → Personal access tokens
Crea un nuovo token con permessi:
- repo (per repository private)
- read:org (per dati organizzazione)
- actions:read (per GitHub Actions)
Copia il token e usalo durante nci init

📊 Report Generati

Weekly Report

Sommario esecutivo con metriche chiave
Breakdown settimanale con attività dettagliata
Team performance e collaborazione
GitHub activity (PR, Actions, Issues)
Integrazione JIRA con ticket completati
Insights automatici e raccomandazioni

Team Report

Profili membri con metriche individuali
Collaboration analysis con review matrix
Work distribution e bilanciamento
Top performers per categoria
Team insights e suggerimenti

Health Report

Overall health score con breakdown
Analisi per categoria (Development, Collaboration, Quality, Delivery, Infrastructure)
Issues e warning prioritizzati
Raccomandazioni actionable
Metriche dettagliate per monitoraggio

🎯 Best Practices

Commit Messages

# ✅ Ottimi
feat(auth): implementa login OAuth2 NW-123
fix: risolve memory leak NOBUG-456
docs: aggiorna README per API v2

# ⚠️ Da migliorare
fix bug
update
WIP

Utilizzo Regolare

# Setup cron job per report automatici (opzionale)
# Ogni lunedì alle 9:00
0 9 * * 1 cd /path/to/project && nci weekly -o docs/weekly-$(date +\%Y-\%W).md

# Script per release
#!/bin/bash
nci health
if [ $? -eq 0 ]; then
  echo "Health check passed, proceeding with release"
else
  echo "Health check failed, please review"
fi

Integrazione CI/CD

# GitHub Actions esempio
name: Weekly CodeBase Report
on:
  schedule:
    - cron: "0 9 * * 1" # Ogni lunedì

jobs:
  codebase-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
      - run: npm install -g noeva-codebase-inspector
      - run: nci weekly --weeks 2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

🔍 Esempi di Output

Sommario Console

📊 Sommario Analisi:
   Periodo: 03/06/2025 - 27/06/2025
   Settimane: 4
   Commits: 127
   Pull Requests: 23
   Contributors: 3
   Branches: 12 creati, 8 mergiati
   JIRA Tickets: 15 completati
   GitHub Actions: 45 runs, 91% successo

🎯 Insights:
   ✅ Ottima collaborazione del team (87/100)
   ⚠️ Alcune PR di grandi dimensioni da suddividere
   💡 Success rate Actions in miglioramento

Report Markdown

Ogni report include:

Executive Summary con KPI principali
Trend Analysis settimana su settimana
Detailed Breakdown per periodo
Visual Metrics con emoji e colori
Actionable Insights basati sui dati

🚨 Troubleshooting

Problemi Comuni

"Configurazione non trovata"

# Soluzione
nci init

"GitHub API non accessibile"

# Verifica token
nci config --edit
# Sezione GitHub → Aggiorna token

"Nessun commit trovato"

# Verifica branch
git branch
git checkout main

# Riduce periodo analisi
nci weekly --weeks 2

"Performance lente"

# Analizza meno settimane
nci weekly --weeks 1

# Disabilita dettagli
nci weekly --no-detailed

Debug Avanzato

# Mostra configurazione
nci config --show

# Test connessioni
nci health

# Log dettagliati (se implementato)
DEBUG=nci:* nci weekly

🤝 Contribuire

Fork del repository
Crea feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push branch (git push origin feature/amazing-feature)
Apri Pull Request

Sviluppo Locale

git clone https://github.com/gruppo4d/noeva-codebase-inspector
cd noeva-codebase-inspector
npm install
npm link
npm run dev  # Development con nodemon

📄 Licenza

MIT License - vedi LICENSE per dettagli.

🆘 Supporto

Issues: GitHub Issues
Documentazione: Wiki
Email: [email protected]

🎉 Credits

Sviluppato con ❤️ dal team di Gruppo4D per migliorare la trasparenza e l'efficienza dei team di sviluppo.

Happy Coding! 🚀