AdvChkSys/scripts/track_progress/README.md

# Progress Tracker

A comprehensive tool for tracking project progress, feature status, and generating documentation from Git history.

## Overview

The Progress Tracker analyzes your Git repository and codebase to automatically generate:

- Feature tracking documentation
- Project status reports
- Changelog based on commit messages
- Code statistics and metrics

## Installation

### Prerequisites

- Python 3.8 or higher
- Git

### Dependencies

Install the required dependencies:

```bash
pip install -r scripts/track_progress/requirements.txt
```

For development or building the executable, install all dependencies:

```bash
pip install -r scripts/track_progress/requirements.txt[all]
```

### Quick Install

Run the setup script to install the tracker to your project:

```bash
python scripts/track_progress/scripts/setup_install.py --project "Your Project Name" --dest path/to/destination
```

Options:
- `--project name`: Set your project name
- `--dest folder`: Set destination directory (default: "scripts")
- `--verbose` or `-v`: Enable verbose output
- `--force` or `-f`: Force overwrite existing files

### Manual Installation

1. Copy the `track_progress` directory to your project
2. Create a `docs/status` directory in your project root
3. Create a `docs/features.md` file if it doesn't exist
4. Create a `CHANGELOG.md` file in your project root

## Usage

### Basic Usage

Run the tracker with default settings:

```bash
# Using the Python script
python scripts/track_progress/track_progress.py

# Using the executable (if built)
scripts/track_progress/track_progress
```

### Command-Line Options

The tracker supports the following command-line options:

```
--config PATH       Path to configuration file (default: scripts/track_progress/progress_config.json)
--project NAME      Project name (overrides config)
--output-dir DIR    Output directory for status document (overrides config)
--repo PATH         Repository path to analyze (default: current directory)
--verbose, -v       Enable verbose output
```

Examples:

```bash
# Specify a custom configuration file
python scripts/track_progress/track_progress.py --config path/to/config.json

# Override project name
python scripts/track_progress/track_progress.py --project "My Project"

# Specify output directory
python scripts/track_progress/track_progress.py --output-dir docs/my-status

# Analyze a different repository
python scripts/track_progress/track_progress.py --repo path/to/repo

# Enable verbose output
python scripts/track_progress/track_progress.py --verbose
```

## Commit Message Tags

The tracker recognizes special tags in commit messages to update feature status and documentation:

| Tag | Description | Example |
|-----|-------------|---------|
| `[status:key]` | Update status of a component | `[status:database]` |
| `[feature:key]` | Mark a feature as completed | `[feature:login]` |
| `[new-feature:key:description]` | Add a new feature | `[new-feature:search:Implement search functionality]` |
| `[changelog:message]` | Add an entry to the changelog | `[changelog:Added dark mode]` |
| `[fix:description]` | Document a bug fix | `[fix:Fixed login issue]` |
| `[issue:id]` | Reference an issue | `[issue:42]` |
| `[breaking]` | Mark a breaking change | `[breaking]` |
| `[roadmap:milestone:item]` | Add an item to the roadmap | `[roadmap:v2:Add OAuth support]` |
| `[milestone:key]` | Reference a milestone | `[milestone:v1.0]` |
| `[priority:level]` | Set priority level | `[priority:high]` |
| `[owner:name]` | Assign an owner | `[owner:John]` |
| `[tag:name]` | Add a custom tag | `[tag:security]` |

Example commit message:
```
Implement search functionality [feature:search] [changelog:Added search with filtering]
```

## Configuration

The tracker uses a JSON configuration file (`progress_config.json`) with the following settings:

```json
{
    "project_name": "Your Project",
    "output_dir": "docs/status",
    "status_doc": "status.md",
    "features_file": "docs/features.md",
    "changelog_file": "CHANGELOG.md",
    "git_log_limit": 100,
    "untagged_commit_limit": 50,
    "top_files_limit": 20,
    "exclude_dirs": ["node_modules", "venv", ".git"],
    "source_extensions": [".py", ".cs", ".js"],
    "templates": {
        "status": "status_template.md",
        "features": "feature_template.md",
        "changelog": "changelog_template.md"
    }
}
```

## Output Files

The tracker generates the following files:

- `docs/features.md`: Feature tracking document
- `docs/status/status.md`: Project status document (or path specified in config)
- `CHANGELOG.md`: Project changelog

## Components

The tracker consists of the following components:

- `track_progress.py`: Main script that orchestrates the tracking process
- `config.py`: Configuration management
- `git_analyzer.py`: Git history analysis
- `code_stats.py`: Code statistics and metrics
- `feature_markdown.py`: Feature tracking utilities
- `template_engine.py`: Template rendering engine
- `changelog_generator.py`: Changelog generation
- `roadmap_generator.py`: Roadmap generation

## Building an Executable

You can build a standalone executable using Nuitka:

```bash
python scripts/track_progress/scripts/build_with_nuitka.py
```

This creates an executable in the `scripts/track_progress/dist` directory.

## Customizing Templates

The tracker uses Markdown templates to generate documentation. You can customize these templates in the `scripts/track_progress/templates` directory:

- `status_template.md`: Template for the status document
- `feature_template.md`: Template for the feature tracking document
- `changelog_template.md`: Template for the changelog

The templates use a simple syntax:
- `{{ variable }}`: Insert a variable
- `{% if condition %}...{% endif %}`: Conditional block
- `{% for item in items %}...{% endfor %}`: Loop over items

## Troubleshooting

### Common Issues

1. **Missing Git Repository**: Ensure you're running the tracker in a Git repository.
2. **No Features Found**: Create a basic `docs/features.md` file with at least one feature.
3. **Template Not Found**: Check that templates exist in the templates directory.

### Debug Mode

Run with `--verbose` to see detailed output:

```bash
python scripts/track_progress/track_progress.py --verbose
```