Weekly - Project Quality Analyzer

AI Cost Tracking

• 🤖 LLM usage: $0.9157 (14 commits)
• 👤 Human dev: ~$1557 (15.6h @ $100/h, 30min dedup)

Generated on 2026-07-06 using openrouter/qwen/qwen3-coder-next

---

Weekly is a comprehensive Python project quality analyzer that helps developers maintain high code quality by automatically detecting issues and suggesting improvements. It analyzes various aspects of your Python projects and generates actionable reports with clear next steps.

✨ Features

• 🧪 Test Coverage Analysis: Check test coverage and test configuration (now parses coverage.xml)
• 📚 Documentation Check: Verify README, LICENSE, CHANGELOG, and API docs
• 🔄 CI/CD Integration: Detect CI/CD configuration and best practices
• 📦 Dependency Analysis: Identify outdated or vulnerable dependencies (now with pip-audit integration and AST parsing)
• 🛠️ Code Quality: Check for code style, formatting, and common issues
• 🔒 Security Checks: Detect hardcoded secrets and insecure function usage
• 📦 Packaging Check: Verify PEP 517/518 compliance and distribution metadata
• 🚀 Release Readiness: Check version consistency and changelog status
• 📊 Interactive Reports: Generate detailed reports in multiple formats (JSON, Markdown, Text, HTML)
• 🔍 Multi-Repo Scanning: Scan multiple Git repositories with parallel processing
• 📅 Date-based Filtering: Flexible date parsing for analyzing recent changes

🔍 Git Repository Scanning

Weekly can scan multiple Git repositories in a directory structure and generate comprehensive reports for each one, plus a summary report.

It also extracts Recent Changes (commits, files/lines changed, commit type breakdown) and writes a per-repo changelog.md into the report directory.

Basic Usage

# Scan all Git repositories in ~/github
weekly scan ~/github
# Only show repositories with changes in the last 7 days (default)
weekly scan ~/github --since "7 days ago"# Specify a custom output directory
weekly scan ~/github -o ./weekly-reports
# Run with 8 parallel jobs for faster scanning
weekly scan ~/github -j 8
# Generate JSON reports instead of HTML
weekly scan ~/github --format json

Recent Changes + changelog.md

When you run weekly scan ... --since "...", the per-repo reports include a Recent Changes section and a changelog.md file in the repository report directory.

• If git-cliff is available, Weekly uses it to generate changelog.md.
• If git-cliff is not available, Weekly falls back to an internal summary (commit + diff stats).

Optional installation (recommended) for richer changelog output:

cargo install git-cliff

Example Output

🔍 Scanning Git repositories in /Users/username/github...
✅ Scan complete! Generated reports for 3 repositories.
📊 Summary report: weekly-reports/summary.html
✅ org1/repo1: 5 checks
✓ style: Passed
✓ code_quality: Passed
✓ dependencies: 2 outdated packages found
✓ docs: Documentation is 85% complete
✓ tests: 92% test coverage

Command Options

Usage: weekly scan [OPTIONS] [ROOT_DIR]
Scan multiple Git repositories and generate reports.
ROOT_DIR: Directory containing Git repositories (default: current directory)
Options:
-o, --output PATH Output directory for reports (default: ./weekly-reports)
-s, --since TEXT Only include repositories with changes since this date (e.g., "7 days ago", "2023-01-01")
--recursive / --no-recursive Scan directories recursively (default: True)
-j, --jobs INTEGER Number of parallel jobs (default: 4)
-f, --format [html|json|markdown] Output format (default: html)
--summary-only Only generate a summary report, not individual reports
-v, --verbose Show detailed output
--help Show this message and exit.

Programmatic Usage

frompathlibimportPathfromdatetimeimportdatetime, timedeltafromweeklyimportGitScanner# Create a scanner instancescanner=GitScanner(
root_dir=Path.home() /"github",
output_dir="weekly-reports",
since=datetime.now() -timedelta(days=7),
recursive=True,
jobs=4
)
# Run the scanresults=scanner.scan_all()
# Process resultsforresultinresults:
print(f"{result.repo.org}/{result.repo.name}:")
forname, checkinresult.results.items():
status="✓"ifcheck.is_okelse"✗"print(f" {status}{name}: {check.message}")

🚀 Installation

Using pip

pip install weekly

Using Poetry (recommended)

poetry add weekly

For Development

# Clone the repository
git clone https://github.com/wronai/weekly.git
cd weekly
# Install with Poetry
poetry install --with dev
# Install pre-commit hooks
pre-commit install
# Activate the virtual environment
poetry shell

Usage

Basic Usage

Analyze a Python project:

weekly analyze /path/to/your/project

Command Line Options

Usage: weekly analyze [OPTIONS] PROJECT_PATH
Analyze a Python project and provide quality insights.
PROJECT_PATH: Path to the project directory (default: current directory)
Options:
-f, --format [text|json|markdown] Output format (default: text)
-o, --output FILE Output file (default: stdout)
--show-suggestions / --no-suggestions
Show improvement suggestions (default: true)
-v, --verbose Show detailed output
--help Show this message and exit.

Examples

1. Analyze current directory and show results in the terminal:

   weekly analyze .

2. Generate a Markdown report:

   weekly analyze -f markdown -o report.md /path/to/project

3. Generate a JSON report for programmatic use:

   weekly analyze -f json -o report.json /path/to/project

Output Example

Text Output

📊 Weekly Project Analysis Report
================================================================================
Project: example-project
Generated: 2025-06-07 12:34:56
Summary:
--------------------------------------------------------------------------------
✅ 5 passed
⚠️ 3 warnings
❌ 1 errors
Detailed Results:
--------------------------------------------------------------------------------
✅ Project Structure
Found Python project with proper structure
✅ Dependencies
All dependencies are properly specified
⚠️ Test Coverage
Test coverage is below 80% (currently 65%)
Suggestions:
• Add more test cases to improve coverage
• Consider using pytest-cov for coverage reporting
❌ Documentation
Missing API documentation
Suggestions:
• Add docstrings to all public functions and classes
• Consider using Sphinx or MkDocs for API documentation
Recommended Actions:
--------------------------------------------------------------------------------
1. Improve Test Coverage
• Add unit tests for untested modules
• Add integration tests for critical paths
• Set up code coverage reporting in CI
2. Enhance Documentation
• Add docstrings to all public APIs
• Create API documentation using Sphinx or MkDocs
• Add examples to the README

Programmatic Usage

frompathlibimportPathfromweeklyimportanalyze_projectfromweekly.core.reportimportReport# Analyze a projectreport=analyze_project(Path("/path/to/your/project"))
# Get report as dictionaryreport_data=report.to_dict()
# Get markdown reportmarkdown=report.to_markdown()
# Print summaryprint(f"✅ {report.summary['success']} passed")
print(f"⚠️ {report.summary['warnings']} warnings")
print(f"❌ {report.summary['errors']} errors")
# Get suggestionsforsuggestioninreport.get_suggestions():
print(f"\n{suggestion['title']}:")
foriteminsuggestion['suggestions']:
print(f" • {item}")
### Most Active Files-`src/main.py`: 12changes-`tests/test_main.py`: 8changes-`README.md`: 5changes### Languages Used-`.py`: 15files-`.md`: 3files-`.json`: 2files## 📋 Next Steps- [ ] Addtestsforrecentchanges- [ ] Refactorlargefiles: src/utils.py, src/processor.py...
## 📜 Recent Commits-`a1b2c3d`Fixbugindataprocessing (2023-05-15)
-`f4e5d6a`AddnewfeatureX (2023-05-14)
-`b3c4d5e`Updatedocumentation (2023-05-13)
-`c6d7e8f`RefactormoduleY (2023-05-12)
-`d9e0f1a`Initialcommit (2023-05-10)
*[ViewfullhistoryintheJSONfile]*

Development

Setup

1. Clone the repository:

   git clone https://github.com/wronai/weekly.git
   cd weekly

2. Install dependencies (recommended):

   poetry install --with dev

Running Tests

poetry run pytest

Code Style

This project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking

Run all checks:

black .
isort .
flake8
mypy .

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Licensed under Apache-2.0.

Author

Tom Sapletta

Acknowledgments

• Built with ❤️ by the WronAI team
• Inspired by various Git analysis tools

Status

Last updated by taskill at 2026-04-25 13:49 UTC

Metric	Value
HEAD	8545fd9
Coverage	73.0%
Failing tests	—
Commits in last cycle	21

Added a deep code analysis engine with seven supporting modules, introduced a CLI with validation and API hooks, and substantially improved test coverage and documentation. Several refactors and report-style improvements for LLM output were applied, and auto_update_config was disabled to preserve manual test strategy.