gitview 0.1.2__tar.gz → 0.1.3__tar.gz

{gitview-0.1.2/gitview.egg-info → gitview-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitview
-Version: 0.1.2
+Version: 0.1.3
 Summary: Git history analyzer with LLM-powered narrative generation
 Home-page: https://github.com/carstenbund/gitview
 Author: GitView Contributors
@@ -44,6 +44,12 @@ Dynamic: requires-python
 
 # GitView
 
+[![Github-CI][github-ci]][github-link]
+[![Coverage Status][codecov-badge]][codecov-link]
+[![PyPI][pypi-badge]][pypi-link]
+[![PyPI - Downloads][install-badge]][install-link]
+
+
 **Git history analyzer with LLM-powered narrative generation**
 
 GitView extracts your repository's git history and uses AI to generate compelling narratives about how your codebase evolved. Instead of manually reading through thousands of commits, get a comprehensive story of your project's journey.
@@ -55,17 +61,30 @@ Example run on this repository:
 
 ## Features
 
-- ** Comprehensive History Extraction**: Extracts commit metadata, LOC changes, language breakdown, README evolution, comment analysis, and more
-- ** Smart Chunking**: Automatically divides history into meaningful "phases" or "epochs" based on significant changes
-- ** LLM-Powered Summaries**: Uses Claude to generate narrative summaries for each phase
-- ** Global Story Generation**: Combines phase summaries into executive summaries, timelines, technical retrospectives, and deletion stories
-- ** Multiple Output Formats**: Generates markdown reports, JSON data, and timelines
+- **Comprehensive History Extraction**: Extracts commit metadata, LOC changes, language breakdown, README evolution, comment analysis, and more
+- **Smart Chunking**: Automatically divides history into meaningful "phases" or "epochs" based on significant changes
+- **LLM-Powered Summaries**: Uses Claude to generate narrative summaries for each phase
+- **Global Story Generation**: Combines phase summaries into executive summaries, timelines, technical retrospectives, and deletion stories
+- **Multiple Output Formats**: Generates markdown reports, JSON data, and timelines
+- **Critical Examination Mode**: Objective assessment focused on gaps, technical debt, and alignment with project goals (perfect for project leads)
 
 ## Installation
 
-### Option 1: Install with pip (recommended)
+### Option 1: Install from PyPI (recommended)
+
+Install the published package directly from PyPI to add the `gitview` command to your PATH:
+
+```bash
+pip3 install gitview
+
+# Confirm the CLI is available
+gitview --version
+gitview --help
+```
 
-This creates a `gitview` command in your PATH:
+### Option 2: Install from source (editable)
+
+This installs directly from the repository in editable mode so local changes take effect immediately:
 
 ```bash
 # Clone the repository
@@ -82,7 +101,7 @@ gitview --help
 
 **How it works:** The `pip install -e .` command reads `pyproject.toml` and `setup.py`, which define an entry point that creates `/usr/local/bin/gitview` (or similar on Windows) that calls `gitview.cli:main`.
 
-### Option 2: Run directly from repo (no installation)
+### Option 3: Run directly from repo (no installation)
 
 Use the executable wrapper in `bin/`:
 
@@ -103,7 +122,7 @@ export PATH="$PWD/bin:$PATH"
 gitview analyze
 ```
 
-### Option 3: Run as Python module
+### Option 4: Run as Python module
 
 ```bash
 # Install dependencies
@@ -159,6 +178,9 @@ gitview analyze --backend openai
 # Using local Ollama (no API key needed)
 gitview analyze --backend ollama --model llama3
 
+# Critical examination mode (for project leads)
+gitview analyze --critical --todo GOALS.md
+
 # Skip LLM summarization (just extract and chunk)
 gitview analyze --skip-llm
 ```
@@ -185,6 +207,9 @@ Options:
   --ollama-url TEXT            Ollama API URL (default: http://localhost:11434)
   --repo-name TEXT             Repository name for output
   --skip-llm                   Skip LLM summarization (extract and chunk only)
+  --todo PATH                  Path to goals/todo file for critical examination mode
+  --critical                   Enable critical examination mode (focus on gaps and issues)
+  --directives TEXT            Additional plain text directives for LLM analysis
 ```
 
 ### Extract Only
@@ -203,6 +228,85 @@ Chunk an extracted JSONL file into phases:
 gitview chunk history.jsonl --output ./phases --strategy adaptive
 ```
 
+## Critical Examination Mode
+
+For project leads who need objective assessment rather than celebratory narratives, GitView offers a critical examination mode that focuses on gaps, technical debt, and alignment with project goals.
+
+### What Changes in Critical Mode?
+
+**Tone & Focus:**
+- Removes flowery, achievement-focused language
+- Emphasizes objective assessment over celebration
+- Focuses on gaps, issues, and misalignments
+- Identifies what's missing or incomplete
+
+**Analysis:**
+- Evaluates progress against stated objectives
+- Highlights incomplete features and technical debt
+- Questions architectural decisions objectively
+- Identifies delays and resource misalignment
+- Notes concerning patterns and risks
+
+### Usage
+
+**Basic Critical Mode:**
+```bash
+gitview analyze --critical
+```
+
+**With Project Goals/TODO File:**
+```bash
+# Create a goals file (e.g., GOALS.md)
+cat > GOALS.md <<EOF
+# Project Goals Q1 2025
+- Implement user authentication system
+- Add API rate limiting
+- Improve test coverage to 80%
+- Migrate from SQLite to PostgreSQL
+- Complete API documentation
+EOF
+
+# Analyze against goals
+gitview analyze --critical --todo GOALS.md
+```
+
+**With Custom Directives:**
+```bash
+# Add specific analysis focus
+gitview analyze --critical \
+  --todo GOALS.md \
+  --directives "Focus on security vulnerabilities and performance bottlenecks"
+```
+
+**Combined Example:**
+```bash
+# Critical assessment with all options
+gitview analyze \
+  --critical \
+  --todo PROJECT_ROADMAP.md \
+  --directives "Emphasize testing gaps and code quality issues" \
+  --output ./critical-review
+```
+
+### Output in Critical Mode
+
+The LLM will generate:
+
+1. **Critical Executive Summary** - Assesses progress against goals, identifies gaps and delays
+2. **Critical Timeline** - Highlights goal alignment/misalignment per phase
+3. **Critical Technical Assessment** - Identifies architectural flaws and technical debt
+4. **Critical Deletion Analysis** - Notes incomplete cleanup and lingering technical debt
+5. **Comprehensive Critical Assessment** - Full project review with actionable insights
+
+### When to Use Critical Mode
+
+- **Project Reviews**: Objective assessment of development progress
+- **Technical Audits**: Identify technical debt and architectural issues
+- **Goal Alignment**: Measure actual work against stated objectives
+- **Resource Planning**: Understand where effort was spent vs. planned
+- **Risk Assessment**: Identify concerning patterns and project risks
+- **Leadership Reports**: Provide factual assessment to stakeholders
+
 ## Chunking Strategies
 
 GitView supports three chunking strategies:
@@ -333,6 +437,30 @@ gitview chunk history.jsonl --strategy adaptive --output ./adaptive-phases
 gitview chunk history.jsonl --strategy fixed --chunk-size 25 --output ./fixed-phases
 ```
 
+### Critical Project Assessment
+
+```bash
+# Create a goals file for your project
+cat > PROJECT_GOALS.md <<EOF
+# Q1 2025 Objectives
+- Complete user authentication with OAuth2
+- Implement API rate limiting (1000 req/hour)
+- Achieve 80% test coverage
+- Migrate database to PostgreSQL
+- Document all public APIs
+EOF
+
+# Run critical analysis
+gitview analyze \
+  --critical \
+  --todo PROJECT_GOALS.md \
+  --directives "Focus on security issues and incomplete features" \
+  --output ./project-review-q1
+
+# Review the critical assessment
+cat ./project-review-q1/history_story.md
+```
+
 ## Architecture
 
 ```
@@ -452,6 +580,7 @@ gitview analyze --backend openai --api-key "your-key"
 
 ## Use Cases
 
+### Standard Mode (Celebratory Narrative)
 - **Technical Documentation**: Automatically generate project history documentation
 - **Onboarding**: Help new developers understand codebase evolution
 - **Retrospectives**: Review what worked and what didn't
@@ -459,6 +588,14 @@ gitview analyze --backend openai --api-key "your-key"
 - **Code Archaeology**: Understand why code evolved the way it did
 - **Cleanup Planning**: Identify what to remove based on deletion history
 
+### Critical Examination Mode
+- **Project Leadership**: Objective assessment for project leads and managers
+- **Technical Audits**: Identify technical debt and architectural issues
+- **Goal Tracking**: Measure actual progress against roadmap objectives
+- **Resource Analysis**: Understand where development effort was spent
+- **Risk Management**: Identify concerning patterns and project risks
+- **Stakeholder Reports**: Provide factual, critical assessment to executives
+
 ## Contributing
 
 Contributions welcome! Please open an issue or submit a pull request.
@@ -466,3 +603,14 @@ Contributions welcome! Please open an issue or submit a pull request.
 ## License
 
 MIT License - see LICENSE file for details
+
+
+
+[github-ci]: https://github.com/carstenbund/gitview/actions/workflows/tests.yml/badge.svg?branch=master
+[github-link]: https://github.com/carstenbund/gitview
+[pypi-badge]: https://img.shields.io/pypi/v/gitview.svg
+[pypi-link]: https://pypi.org/project/gitview
+[codecov-badge]: https://codecov.io/gh/carstenbund/gitview/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/carstenbund/gitview
+[install-badge]: https://img.shields.io/pypi/dw/gitview?label=pypi%20installs
+[install-link]: https://pypistats.org/packages/gitview

{gitview-0.1.2 → gitview-0.1.3}/README.md

@@ -1,5 +1,11 @@
 # GitView
 
+[![Github-CI][github-ci]][github-link]
+[![Coverage Status][codecov-badge]][codecov-link]
+[![PyPI][pypi-badge]][pypi-link]
+[![PyPI - Downloads][install-badge]][install-link]
+
+
 **Git history analyzer with LLM-powered narrative generation**
 
 GitView extracts your repository's git history and uses AI to generate compelling narratives about how your codebase evolved. Instead of manually reading through thousands of commits, get a comprehensive story of your project's journey.
@@ -11,17 +17,30 @@ Example run on this repository:
 
 ## Features
 
-- ** Comprehensive History Extraction**: Extracts commit metadata, LOC changes, language breakdown, README evolution, comment analysis, and more
-- ** Smart Chunking**: Automatically divides history into meaningful "phases" or "epochs" based on significant changes
-- ** LLM-Powered Summaries**: Uses Claude to generate narrative summaries for each phase
-- ** Global Story Generation**: Combines phase summaries into executive summaries, timelines, technical retrospectives, and deletion stories
-- ** Multiple Output Formats**: Generates markdown reports, JSON data, and timelines
+- **Comprehensive History Extraction**: Extracts commit metadata, LOC changes, language breakdown, README evolution, comment analysis, and more
+- **Smart Chunking**: Automatically divides history into meaningful "phases" or "epochs" based on significant changes
+- **LLM-Powered Summaries**: Uses Claude to generate narrative summaries for each phase
+- **Global Story Generation**: Combines phase summaries into executive summaries, timelines, technical retrospectives, and deletion stories
+- **Multiple Output Formats**: Generates markdown reports, JSON data, and timelines
+- **Critical Examination Mode**: Objective assessment focused on gaps, technical debt, and alignment with project goals (perfect for project leads)
 
 ## Installation
 
-### Option 1: Install with pip (recommended)
+### Option 1: Install from PyPI (recommended)
+
+Install the published package directly from PyPI to add the `gitview` command to your PATH:
+
+```bash
+pip3 install gitview
+
+# Confirm the CLI is available
+gitview --version
+gitview --help
+```
 
-This creates a `gitview` command in your PATH:
+### Option 2: Install from source (editable)
+
+This installs directly from the repository in editable mode so local changes take effect immediately:
 
 ```bash
 # Clone the repository
@@ -38,7 +57,7 @@ gitview --help
 
 **How it works:** The `pip install -e .` command reads `pyproject.toml` and `setup.py`, which define an entry point that creates `/usr/local/bin/gitview` (or similar on Windows) that calls `gitview.cli:main`.
 
-### Option 2: Run directly from repo (no installation)
+### Option 3: Run directly from repo (no installation)
 
 Use the executable wrapper in `bin/`:
 
@@ -59,7 +78,7 @@ export PATH="$PWD/bin:$PATH"
 gitview analyze
 ```
 
-### Option 3: Run as Python module
+### Option 4: Run as Python module
 
 ```bash
 # Install dependencies
@@ -115,6 +134,9 @@ gitview analyze --backend openai
 # Using local Ollama (no API key needed)
 gitview analyze --backend ollama --model llama3
 
+# Critical examination mode (for project leads)
+gitview analyze --critical --todo GOALS.md
+
 # Skip LLM summarization (just extract and chunk)
 gitview analyze --skip-llm
 ```
@@ -141,6 +163,9 @@ Options:
   --ollama-url TEXT            Ollama API URL (default: http://localhost:11434)
   --repo-name TEXT             Repository name for output
   --skip-llm                   Skip LLM summarization (extract and chunk only)
+  --todo PATH                  Path to goals/todo file for critical examination mode
+  --critical                   Enable critical examination mode (focus on gaps and issues)
+  --directives TEXT            Additional plain text directives for LLM analysis
 ```
 
 ### Extract Only
@@ -159,6 +184,85 @@ Chunk an extracted JSONL file into phases:
 gitview chunk history.jsonl --output ./phases --strategy adaptive
 ```
 
+## Critical Examination Mode
+
+For project leads who need objective assessment rather than celebratory narratives, GitView offers a critical examination mode that focuses on gaps, technical debt, and alignment with project goals.
+
+### What Changes in Critical Mode?
+
+**Tone & Focus:**
+- Removes flowery, achievement-focused language
+- Emphasizes objective assessment over celebration
+- Focuses on gaps, issues, and misalignments
+- Identifies what's missing or incomplete
+
+**Analysis:**
+- Evaluates progress against stated objectives
+- Highlights incomplete features and technical debt
+- Questions architectural decisions objectively
+- Identifies delays and resource misalignment
+- Notes concerning patterns and risks
+
+### Usage
+
+**Basic Critical Mode:**
+```bash
+gitview analyze --critical
+```
+
+**With Project Goals/TODO File:**
+```bash
+# Create a goals file (e.g., GOALS.md)
+cat > GOALS.md <<EOF
+# Project Goals Q1 2025
+- Implement user authentication system
+- Add API rate limiting
+- Improve test coverage to 80%
+- Migrate from SQLite to PostgreSQL
+- Complete API documentation
+EOF
+
+# Analyze against goals
+gitview analyze --critical --todo GOALS.md
+```
+
+**With Custom Directives:**
+```bash
+# Add specific analysis focus
+gitview analyze --critical \
+  --todo GOALS.md \
+  --directives "Focus on security vulnerabilities and performance bottlenecks"
+```
+
+**Combined Example:**
+```bash
+# Critical assessment with all options
+gitview analyze \
+  --critical \
+  --todo PROJECT_ROADMAP.md \
+  --directives "Emphasize testing gaps and code quality issues" \
+  --output ./critical-review
+```
+
+### Output in Critical Mode
+
+The LLM will generate:
+
+1. **Critical Executive Summary** - Assesses progress against goals, identifies gaps and delays
+2. **Critical Timeline** - Highlights goal alignment/misalignment per phase
+3. **Critical Technical Assessment** - Identifies architectural flaws and technical debt
+4. **Critical Deletion Analysis** - Notes incomplete cleanup and lingering technical debt
+5. **Comprehensive Critical Assessment** - Full project review with actionable insights
+
+### When to Use Critical Mode
+
+- **Project Reviews**: Objective assessment of development progress
+- **Technical Audits**: Identify technical debt and architectural issues
+- **Goal Alignment**: Measure actual work against stated objectives
+- **Resource Planning**: Understand where effort was spent vs. planned
+- **Risk Assessment**: Identify concerning patterns and project risks
+- **Leadership Reports**: Provide factual assessment to stakeholders
+
 ## Chunking Strategies
 
 GitView supports three chunking strategies:
@@ -289,6 +393,30 @@ gitview chunk history.jsonl --strategy adaptive --output ./adaptive-phases
 gitview chunk history.jsonl --strategy fixed --chunk-size 25 --output ./fixed-phases
 ```
 
+### Critical Project Assessment
+
+```bash
+# Create a goals file for your project
+cat > PROJECT_GOALS.md <<EOF
+# Q1 2025 Objectives
+- Complete user authentication with OAuth2
+- Implement API rate limiting (1000 req/hour)
+- Achieve 80% test coverage
+- Migrate database to PostgreSQL
+- Document all public APIs
+EOF
+
+# Run critical analysis
+gitview analyze \
+  --critical \
+  --todo PROJECT_GOALS.md \
+  --directives "Focus on security issues and incomplete features" \
+  --output ./project-review-q1
+
+# Review the critical assessment
+cat ./project-review-q1/history_story.md
+```
+
 ## Architecture
 
 ```
@@ -408,6 +536,7 @@ gitview analyze --backend openai --api-key "your-key"
 
 ## Use Cases
 
+### Standard Mode (Celebratory Narrative)
 - **Technical Documentation**: Automatically generate project history documentation
 - **Onboarding**: Help new developers understand codebase evolution
 - **Retrospectives**: Review what worked and what didn't
@@ -415,6 +544,14 @@ gitview analyze --backend openai --api-key "your-key"
 - **Code Archaeology**: Understand why code evolved the way it did
 - **Cleanup Planning**: Identify what to remove based on deletion history
 
+### Critical Examination Mode
+- **Project Leadership**: Objective assessment for project leads and managers
+- **Technical Audits**: Identify technical debt and architectural issues
+- **Goal Tracking**: Measure actual progress against roadmap objectives
+- **Resource Analysis**: Understand where development effort was spent
+- **Risk Management**: Identify concerning patterns and project risks
+- **Stakeholder Reports**: Provide factual, critical assessment to executives
+
 ## Contributing
 
 Contributions welcome! Please open an issue or submit a pull request.
@@ -422,3 +559,14 @@ Contributions welcome! Please open an issue or submit a pull request.
 ## License
 
 MIT License - see LICENSE file for details
+
+
+
+[github-ci]: https://github.com/carstenbund/gitview/actions/workflows/tests.yml/badge.svg?branch=master
+[github-link]: https://github.com/carstenbund/gitview
+[pypi-badge]: https://img.shields.io/pypi/v/gitview.svg
+[pypi-link]: https://pypi.org/project/gitview
+[codecov-badge]: https://codecov.io/gh/carstenbund/gitview/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/carstenbund/gitview
+[install-badge]: https://img.shields.io/pypi/dw/gitview?label=pypi%20installs
+[install-link]: https://pypistats.org/packages/gitview

{gitview-0.1.2 → gitview-0.1.3}/gitview/__init__.py

@@ -1,3 +1,3 @@
 """GitView - Git history analyzer with LLM-powered narrative generation."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"