fix: add core project files and configuration

2026-02-01 08:18:39 +00:00
parent 6c1c242d80
commit 8afe16407c
1 changed files with 120 additions and 49 deletions
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@

 A powerful CLI tool that analyzes git repositories to generate developer productivity insights, code quality metrics, and commit pattern analysis. Works entirely offline using local git data with no external API dependencies.

-[![CI Status](https://img.shields.io/badge/CI-Passing-green)](https://7000pct.gitea.bloupla.net/7000pctAUTO/git-insights-cli/actions)
+![CI Status](https://img.shields.io/badge/CI-Passing-green)
 ![Python Version](https://img.shields.io/badge/Python-3.8%2B-blue)
 ![License](https://img.shields.io/badge/License-MIT-yellow)

@@ -98,14 +98,15 @@ Export analysis results to a file in the specified format.
 git-insights export [OPTIONS] [PATH]

 Options:
+  --days INTEGER     Number of days to analyze (default: 30)
  --format TEXT      Output format: json, markdown, html (default: json)
-  --output TEXT      Output file path
+  --output FILE      Output file path (default: stdout)
 ```

 **Example:**

 ```bash
-git-insights export /my/project --format json --output report.json
+git-insights export /my/project --format markdown --output report.md
 ```

 ### report
@@ -117,25 +118,23 @@ git-insights report [OPTIONS] [PATH]

 Options:
  --days INTEGER     Number of days to analyze (default: 30)
-  --output TEXT      Output file path for HTML report
+  --output FILE      Output file path
 ```

 **Example:**

 ```bash
-git-insights report /my/project --days 30 --output report.html
+git-insights report /my/project --output report.html
 ```

 ## Configuration

-Git Insights CLI supports configuration via YAML files. Create a `.git-insights/config.yaml` file in your repository or use `~/.git-insights/config.yaml` for user-wide settings.
-
-### Default Configuration
+Create a `.git-insights/config.yaml` file in your project root or home directory:

 ```yaml
-repository_path: .
+repository_path: "."
 analysis_days: 30
-output_format: json
+output_format: "json"
 churn_threshold: 500
 risky_commit_threshold: 500
 merge_commit_flag: true
@@ -143,8 +142,58 @@ merge_commit_flag: true

 ### Environment Variables

- `GIT_INSIGHTS_REPO_PATH` - Override repository path
- `GIT_INSIGHTS_DAYS` - Default number of days to analyze
+| Variable | Default | Description |
+|----------|---------|-------------|
+| GIT_INSIGHTS_REPO_PATH | "." | Repository path to analyze |
+| GIT_INSIGHTS_DAYS | "30" | Default analysis period in days |
+| GIT_INSIGHTS_OUTPUT_FORMAT | "json" | Default output format |
+
+## Output Formats
+
+### Console Dashboard
+
+The default console output uses Rich library to display colorful, formatted metrics directly in your terminal:
+
+```
+╔════════════════════════════════════════════════════════════╗
+║          Git Insights - Productivity Dashboard              ║
+╠════════════════════════════════════════════════════════════╣
+║  Total Commits: 147    │  Authors: 5                       ║
+║  Lines Added: 12,453   │  Lines Deleted: 4,231             ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+### JSON
+
+```json
+{
+  "summary": {
+    "total_commits": 147,
+    "authors": 5,
+    "lines_added": 12453,
+    "lines_deleted": 4231
+  },
+  "commit_patterns": {...},
+  "code_churn": {...}
+}
+```
+
+### Markdown
+
+```markdown
+# Git Insights Report
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Commits | 147 |
+| Authors | 5 |
+```
+
+### HTML
+
+Generates a self-contained HTML report with interactive charts and tables.

 ## Development

@@ -163,23 +212,10 @@ source venv/bin/activate  # On Windows: venv\Scripts\activate
 pip install -e ".[dev]"

 # Run tests
-pytest tests/ -v
+pytest tests/ -v --cov=src

 # Run linting
-ruff check .
-```
-
-### Running Tests
-
-```bash
-# Run all tests with coverage
-pytest tests/ -v --cov=src --cov-report=term-missing
-
-# Run specific test file
-pytest tests/test_cli.py -v
-
-# Run with verbose output
-pytest tests/ -vv
+ruff check src/ tests/
 ```

 ### Project Structure
@@ -187,35 +223,63 @@ pytest tests/ -vv
 ```
 git-insights-cli/
 ├── src/
-│   ├── git_insights.py      # Main orchestrator
-│   ├── cli.py               # CLI commands
+│   ├── __init__.py          # Package marker with version
+│   ├── cli.py               # CLI commands and entry point
+│   ├── git_insights.py      # Main orchestrator class
 │   ├── analyzers/
+│   │   ├── __init__.py
 │   │   ├── git_repository.py     # Git repository wrapper
 │   │   ├── commit_pattern.py     # Commit pattern analysis
 │   │   ├── code_churn.py         # Code churn tracking
-│   │   ├── velocity.py       # Velocity analysis
-│   │   └── risky_commit.py   # Risky commit detection
-│   ├── models/
-│   │   └── data_structures.py # Data models
+│   │   ├── risky_commit.py       # Risky commit detection
+│   │   └── velocity.py           # Velocity analysis
 │   ├── formatters/
-│   │   ├── base.py           # Base formatter
+│   │   ├── __init__.py
+│   │   ├── base.py               # Base formatter abstract class
 │   │   ├── json_formatter.py     # JSON output
 │   │   ├── markdown_formatter.py # Markdown output
 │   │   ├── html_formatter.py     # HTML output
-│   │   └── dashboard.py      # Terminal dashboard
+│   │   └── dashboard.py          # Rich console dashboard
+│   ├── models/
+│   │   ├── __init__.py
+│   │   └── data_structures.py    # Dataclass models
 │   └── utils/
-│       ├── date_utils.py     # Date utilities
-│       └── config.py         # Configuration loading
+│       ├── __init__.py
+│       ├── date_utils.py         # Date/time utilities
+│       └── config.py             # Configuration loader
 ├── tests/
+│   ├── __init__.py
 │   ├── conftest.py              # Pytest fixtures
 │   ├── test_cli.py              # CLI tests
 │   ├── test_models.py           # Model tests
+│   ├── test_analyzers.py        # Analyzer tests
 │   └── test_formatters.py       # Formatter tests
-├── pyproject.toml           # Project configuration
+├── .git-insights/
+│   └── config.yaml              # Default configuration
+├── .gitea/
+│   └── workflows/
+│       └── ci.yml               # Gitea Actions CI workflow
 ├── requirements.txt             # Dependencies
+├── setup.py                     # Package setup
+├── pyproject.toml              # Project configuration
+├── .gitignore                  # Git ignore patterns
+├── .pre-commit-config.yaml     # Pre-commit hooks
 └── README.md                   # This file
 ```

+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ -v --cov=src --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_cli.py -v
+```
+
 ## Contributing

 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -223,3 +287,10 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 ## License

 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- [Click](https://click.palletsprojects.com/) - CLI framework
+- [Rich](https://github.com/Textualize/rich) - Terminal formatting
+- [GitPython](https://gitpython.readthedocs.io/) - Git bindings
+- [Jinja2](https://jinja.palletsprojects.com/) - Template engine