EngiScope (sem-cli) — Software Engineering Metrics & Intelligence CLI

Course: ISWE402L – Software Metrics
Product: Software Engineering Metrics Ingestion, Analysis, and Decision Support Platform
PyPI Package: engiscope | CLI Command: sem
Interface: Terminal-based, Unicode TUI inspired by Claude Code
Provider: Google Gemini API (optional, offline-first fallback)

1. Product Overview

sem-cli (distributed as engiscope on PyPI) transforms Git repositories into an evidence-grounded software engineering analytics environment directly from your terminal. It measures source code, mines Git history, audits quality and security, calculates empirical distributions and correlations, ranks engineering hotspots, and optionally provides Gemini AI-powered business and architectural insights.

Core Principles

• Local-first: Runs entirely on the user's workstation without requiring cloud databases, Docker, or Redis.
• Metrics before AI: Numeric measurements originate from deterministic static analysis and Git mining algorithms. AI is an optional interpretation layer, not a dependency for calculating metrics.
• Evidence-backed: Every finding and hotspot links to exact files, line numbers, commits, and formula derivations.
• Reproducible: Measurements are pinned to exact 40-character Git commit SHAs and recorded in local SQLite database snapshots.
• Privacy & Security: Full source code is never sent to Gemini by default; sensitive tokens and credentials are automatically redacted.

📖 Deep Dive Documentation: For complete architectural diagrams, mathematical metric formulations, AST parsers, and command-by-command internal execution flows, see the Technical Implementation Guide.

2. Installation & Quickstart

Install directly from PyPI via pip:

pip install engiscope

Verify your installation:

# Check version and doctor diagnostics
sem --version
sem doctor

(For development or contributing from source: pip install -e ".[dev]")

3. Architecture & Design

engiscope (sem-cli)
├── CLI Layer           (Typer, Rich, interactive TUI, Claude Code styling)
├── Services Layer      (Analysis orchestration, history mining, reports, AI)
├── Ingestion Engine    (Git client, clone manager, revision resolver, inventory)
├── Analysis Engine     (Radon, Lizard, AST structural analyzers, secrets & deps)
├── Metrics Catalogue   (Product size, complexity, CK OO suite, process, quality)
├── Analytics Layer     (Descriptive statistics, IQR outliers, correlations, hotspots, risk)
└── Persistence Layer   (SQLite transactional snapshots, runs, comparisons)

4. Complete Software Metrics Catalogue

5. Hotspot Prioritization Model

To prioritize technical debt without pretending to predict defects without training data, sem-cli computes:

$$H_f = C_f \times N_f$$

Where:

• $C_f$ is min-max normalized maximum cyclomatic complexity for file $f \in [0.0, 1.0]$.
• $N_f$ is min-max normalized historical change frequency for file $f \in [0.0, 1.0]$.
• $H_f$ is a transparent prioritization score highlighting modules that combine high structural complexity with frequent churn.

6. CLI Command Reference

Interactive Workspace

# Launch interactive terminal TUI
sem

Ingestion & Analysis

# Analyze local repository
sem analyze .

# Analyze remote Git repository URL
sem analyze https://github.com/owner/repository.git

# Analyze specific branch, tag, or commit revision
sem analyze https://github.com/owner/repository.git --ref main

# Limit history depth and select profile
sem analyze . --history-depth 500 --profile full

# Provide optional business context for AI interpretation
sem analyze . --business-context "Payment gateway and billing engine"

Focused Exploration

# Explore software metrics catalogue
sem metrics .

# Rank complexity and churn hotspots
sem hotspots . --limit 15

# Mine Git history, contributors, and churn concentration
sem history . --depth 200

# Run security and secret audit
sem security .

# Run descriptive statistics and empirical correlations
sem stats .

# Compare two analysis revisions or stored snapshots
sem compare . --from v1.0.0 --to v1.1.0
sem compare --run-a <RUN_ID_1> --run-b <RUN_ID_2>

# Ask Google Gemini evidence-grounded questions
sem ask . "Which modules present the highest maintenance risk and why?"

# Generate and export reports
sem report . --format markdown --output REPORT.md
sem export . --format json --output report.json
sem export . --format csv --output metrics.csv

# List past analysis runs
sem runs

# System diagnostics
sem doctor

# Initialize user configuration
sem init

7. Exit Codes

8. Gemini AI Integration & Guardrails

• Configured via environment variable: export GEMINI_API_KEY="your-api-key".
• Offline by Default: Complete metrics, hotspots, statistics, and reports operate offline without an API key.
• Minimized Evidence Payload: Only structured metric aggregates, hotspot rankings, and findings are sent to Gemini. Full source code is never uploaded by default.
• Guardrails: AI is instructed never to invent metrics, never to claim vulnerabilities without supporting evidence, and to label operational implications as hypotheses.