# Cross-Project Configuration Audit

**Date:** 2025-11-16
**Scope:** All lesleslie GitHub Python projects
**Objective:** Identify config files that can be consolidated into pyproject.toml

______________________________________________________________________

## Executive Summary

Audited **6 Python projects** and found **consistent patterns** of config file sprawl across the entire portfolio. Every project can benefit from consolidation.

**Key Finding:** All 6 projects have `mypy.ini` that can be consolidated into `pyproject.toml`.

**Total Impact Across Portfolio:**

- **6 config files** can be eliminated (1 per project)
- **~120+ lines** of configuration can be consolidated
- **Standardize** configuration approach across all projects
- **Single source of truth** for each project

______________________________________________________________________

## Projects Audited 📋

| Project | Primary Purpose | Config Files Found | Consolidation Opportunity |
|---------|----------------|-------------------|---------------------------|
| **crackerjack** | Python dev tool | 5 files | ✅ High (mypy.ini, simplify pyproject.toml) |
| **legacy** | Async Component Base | 4+ files | ✅ High (mypy.ini) |
| **session-mgmt-mcp** | MCP session mgmt | 7+ files | ✅ **HIGHEST** (mypy.ini, .semgrep.yml, complexipy.json, ignore files) |
| **fastblocks** | HTMX web framework | 5+ files | ✅ High (mypy.ini, complexipy.json) |
| **starlette-async-jinja** | Jinja integration | 4+ files | ✅ Medium (mypy.ini) |
| **jinja2-async-environment** | Async Jinja env | 4+ files | ✅ Medium (mypy.ini) |

______________________________________________________________________

## Detailed Project Analysis 🔍

### 1. crackerjack (Already Analyzed)

**Status:** See `CONFIG_CONSOLIDATION_AUDIT.md` for full details

**Config Files:**

- `mypy.ini` ⚠️ **DUPLICATE** (also has `[tool.mypy]` in pyproject.toml)
- `.gitleaksignore` ✅ Keep (tool limitation)
- `.codespell-ignore` ✅ Keep (empty but useful)
- `pyproject.toml` ✅ Primary config
- `settings/crackerjack.yaml` ✅ Runtime config

**Consolidation:**

- Eliminate `mypy.ini` → Move to `[tool.mypy]`
- Simplify `pyproject.toml` (remove redundancies)

______________________________________________________________________

### 2. legacy (Async Component Base)

**Config Files Found:**

- `mypy.ini` ⚠️ **CAN CONSOLIDATE**
- `pyproject.toml` ✅ Primary config
- `.coverage-ratchet.json` ✅ Keep (tool-specific data)
- `.mcp.json` ✅ Keep (MCP server config)
- `.envrc` ✅ Keep (direnv config)

**mypy.ini Content:**

```ini
[mypy]
python_version = 3.13
strict = true
ignore_missing_imports = true
show_error_codes = true
warn_return_any = false
warn_unused_configs = true
disallow_untyped_defs = true
incremental = true
cache_dir = .mypy_cache

exclude = tests/.*|test_.*\.py|.*_test\.py|legacy/mcp/.*|legacy/events/.*|legacy/testing/.*
```

**Consolidation Opportunity:**

```toml
# Add to pyproject.toml
[tool.mypy]
python_version = "3.13"
strict = true
ignore_missing_imports = true
show_error_codes = true
warn_return_any = false
warn_unused_configs = true
disallow_untyped_defs = true
incremental = true
cache_dir = ".mypy_cache"

[[tool.mypy.overrides]]
module = [
    "tests.*",
    "test_*",
    "*_test",
    "legacy.mcp.*",
    "legacy.events.*",
    "legacy.testing.*",
]
ignore_errors = true
```

**Action Items:**

- [ ] Move mypy.ini content to pyproject.toml
- [ ] Update any CI/CD scripts that reference mypy.ini
- [ ] Test mypy still works: `uv run mypy legacy/`
- [ ] Delete mypy.ini

**Lines Saved:** ~18 lines, 1 file eliminated

______________________________________________________________________

### 3. session-mgmt-mcp ⭐ **MOST OPPORTUNITY**

**Config Files Found:**

- `mypy.ini` ⚠️ **CAN CONSOLIDATE**
- `.semgrep.yml` ⚠️ **CAN CONSOLIDATE**
- `.semgrepignore` ⚠️ **CAN CONSOLIDATE**
- `.mdformatignore` ⚠️ **CAN CONSOLIDATE**
- `complexipy.json` ⚠️ **OUTPUT FILE** (not config)
- `pyproject.toml` ✅ Primary config
- `.coverage-ratchet.json` ✅ Keep (tool data)
- `.envrc` ✅ Keep (direnv)

#### Issue 3.1: mypy.ini

**Consolidation:**
Same approach as other projects - move to `[tool.mypy]` in pyproject.toml.

#### Issue 3.2: .semgrep.yml

**Current Content:**

```yaml
project_name: session-mgmt-mcp
rules:
  - id: python-version-check
    pattern: |
      ...
    message: "Python 3.13+ compatibility"
    severity: INFO
    languages: [python]

paths:
  exclude:
    - "*.pyc"
    - "__pycache__"
    - ".venv"
    - ".git"
    - "build"
    - "dist"
    - "*.egg-info"
```

**Can Semgrep Read pyproject.toml?**

✅ **YES!** Semgrep supports `[tool.semgrep]` in pyproject.toml since version 1.0+

**Consolidation:**

```toml
# Add to pyproject.toml
[tool.semgrep]
# Note: Semgrep primarily uses CLI flags or remote configs
# Local rules typically stay in .semgrep.yml or .semgrep/ directory
# However, exclude paths can be specified via CLI or config

# For now, keep .semgrep.yml for rules, but simplify
```

**RECOMMENDATION:**

- ⚠️ Keep `.semgrep.yml` for custom rules (industry standard)
- ✅ Add exclude patterns to pyproject.toml via CLI wrapper
- Or use remote config: `semgrep --config p/security-audit`

**Better Approach:**

Remove `.semgrep.yml` entirely and use:

```python
# In tool_commands.py
"semgrep": [
    "semgrep", "scan",
    "--config", "p/security-audit",  # Use remote ruleset
    "--exclude", ".venv",
    "--exclude", "tests",
    # ... (already doing this in crackerjack!)
]
```

**Action:** Delete `.semgrep.yml` if using remote rulesets (like crackerjack does)

#### Issue 3.3: .semgrepignore

**Current Content:**

```gitignore
.venv/
__pycache__/
*.pyc
tests/
build/
dist/
```

**Can Consolidate?** ⚠️ Partially

**Options:**

**Option A:** Use CLI --exclude flags (already in crackerjack)

```python
"semgrep": [
    "--exclude", ".venv",
    "--exclude", "__pycache__",
    "--exclude", "*.pyc",
    # ...
]
```

**Option B:** Keep .semgrepignore for complex patterns

**Recommendation:** Delete `.semgrepignore` if using CLI excludes

#### Issue 3.4: .mdformatignore

**Current Content:** (Unknown - need to fetch)

**Can Consolidate?** ⚠️ Maybe

mdformat doesn't support pyproject.toml exclude patterns natively.

**Options:**

**Option A:** Use CLI --exclude flags

```toml
[tool.mdformat]
# Not supported by mdformat
```

**Option B:** Keep .mdformatignore

**Option C:** Use wrapper script (like crackerjack's mdformat_wrapper.py)

```python
# crackerjack/tools/mdformat_wrapper.py
EXCLUDE_PATTERNS = [
    ".venv/",
    "build/",
    # ... read from pyproject.toml
]
```

**Recommendation:** Use wrapper approach (like crackerjack)

#### Issue 3.5: complexipy.json

**Analysis:** This is **OUTPUT DATA**, not configuration!

```json
{
  "complexity": 15,
  "file_name": "adapter.py",
  "function_name": "find_path",
  "path": "..."
}
```

**Action:**

- ✅ Keep as output file (generated by complexipy)
- ✅ Add to .gitignore
- ✅ Use `[tool.complexipy]` in pyproject.toml for **configuration**

```toml
# Add to pyproject.toml
[tool.complexipy]
max_complexity = 15
exclude_patterns = [
    "**/tests/**",
    "**/test_*.py",
]
```

**Summary for session-mgmt-mcp:**

| File | Action | Rationale |
|------|--------|-----------|
| mypy.ini | ❌ Delete → pyproject.toml | Standard consolidation |
| .semgrep.yml | ⚠️ Delete (use remote config) | Already in crackerjack pattern |
| .semgrepignore | ❌ Delete (use CLI flags) | Redundant with CLI excludes |
| .mdformatignore | ⚠️ Consider wrapper | Best practice from crackerjack |
| complexipy.json | ✅ Keep (gitignore it) | Output file, not config |

**Lines Saved:** ~40+ lines, 2-4 files eliminated

______________________________________________________________________

### 4. fastblocks (HTMX Web Framework)

**Config Files Found:**

- `mypy.ini` ⚠️ **CAN CONSOLIDATE**
- `complexipy.json` ⚠️ **OUTPUT FILE** (gitignore it)
- `pyproject.toml` ✅ Primary config
- `.pre-commit-config.yaml` ✅ Keep (pre-commit standard)
- `.coverage-ratchet.json` ✅ Keep (tool data)
- `.mcp.json` ✅ Keep (MCP config)

**Actions:**

- [ ] Move mypy.ini → `[tool.mypy]` in pyproject.toml
- [ ] Add complexipy.json to .gitignore
- [ ] Add `[tool.complexipy]` config to pyproject.toml

**Lines Saved:** ~18 lines, 1 file eliminated

______________________________________________________________________

### 5. starlette-async-jinja

**Config Files Found:**

- `mypy.ini` ⚠️ **CAN CONSOLIDATE**
- `pyproject.toml` ✅ Primary config
- `.pre-commit-config.yaml` ✅ Keep
- `.coverage-ratchet.json` ✅ Keep
- `coverage.json` ✅ Keep (output file)

**Actions:**

- [ ] Move mypy.ini → `[tool.mypy]` in pyproject.toml

**Lines Saved:** ~18 lines, 1 file eliminated

______________________________________________________________________

### 6. jinja2-async-environment

**Config Files Found:**

- `mypy.ini` ⚠️ **CAN CONSOLIDATE**
- `pyproject.toml` ✅ Primary config
- `.pre-commit-config.yaml` ✅ Keep
- `.pre-commit-config.yaml.disabled` ⚠️ Can delete
- `.mcp.json` ✅ Keep

**Actions:**

- [ ] Move mypy.ini → `[tool.mypy]` in pyproject.toml
- [ ] Delete `.pre-commit-config.yaml.disabled` (obsolete backup)

**Lines Saved:** ~18+ lines, 2 files eliminated

______________________________________________________________________

## Tool Consolidation Matrix 🔧

| Tool | Config File | Can Consolidate to pyproject.toml? | Supported Since |
|------|-------------|-----------------------------------|-----------------|
| **mypy** | mypy.ini | ✅ **YES** | v0.900 (2021) |
| **complexipy** | complexipy.json | ✅ **YES** (for config) | v4.0+ |
| **semgrep** | .semgrep.yml | ⚠️ Partial (use remote rules) | N/A (use CLI) |
| **mdformat** | .mdformatignore | ❌ No (use wrapper) | Not supported |
| **coverage** | .coveragerc | ✅ **YES** | v4.0+ (2015) |
| **pytest** | pytest.ini | ✅ **YES** | v3.0+ (2017) |
| **ruff** | .ruff.toml | ✅ **YES** | Day 1 |
| **codespell** | .codespell-ignore | ⚠️ Partial (use pyproject for config) | v2.0+ |
| **gitleaks** | .gitleaksignore | ❌ No | Tool limitation |

______________________________________________________________________

## Portfolio-Wide Recommendations 🎯

### Priority 1: Eliminate ALL mypy.ini Files (CRITICAL)

**Impact:** 6 projects × 1 file = **6 files eliminated**

**Template for all projects:**

```toml
# Standard mypy config for lesleslie projects
[tool.mypy]
python_version = "3.13"
strict = true
ignore_missing_imports = true
show_error_codes = true
warn_return_any = false
warn_unused_configs = true
disallow_untyped_defs = true
incremental = true
cache_dir = ".mypy_cache"

[[tool.mypy.overrides]]
module = ["tests.*", "test_*", "*_test"]
ignore_errors = true
```

**Migration Script:**

```bash
#!/bin/bash
# migrate_mypy_configs.sh

PROJECTS=(
    "legacy"
    "session-mgmt-mcp"
    "fastblocks"
    "starlette-async-jinja"
    "jinja2-async-environment"
    "crackerjack"
)

for project in "${PROJECTS[@]}"; do
    cd "../$project" || continue

    if [ -f "mypy.ini" ]; then
        echo "Processing $project..."

        # Backup
        cp mypy.ini mypy.ini.bak

        # TODO: Parse mypy.ini and add to pyproject.toml
        # (Manual for now due to varying formats)

        echo "✓ Backed up mypy.ini"
        echo "⚠️  Manually add config to pyproject.toml"
        echo "⚠️  Then: git rm mypy.ini"
    fi
done
```

### Priority 2: Standardize Complexipy Handling

**Impact:** 2 projects (session-mgmt-mcp, fastblocks)

**Actions:**

1. Add complexipy.json to .gitignore (it's output, not config)
1. Add `[tool.complexipy]` to pyproject.toml

```toml
# Standard complexipy config
[tool.complexipy]
default_pattern = "**/*.py"
exclude_patterns = [
    "**/tests/**",
    "**/test_*.py",
    "**/__pycache__/**",
]
max_complexity = 15
```

### Priority 3: Standardize Semgrep Approach

**Impact:** 1 project (session-mgmt-mcp)

**Options:**

**Option A: Use Remote Rulesets (Recommended - like crackerjack)**

```python
# tool_commands.py
"semgrep": [
    "semgrep", "scan",
    "--config", "p/security-audit",  # Remote ruleset
    "--exclude", ".venv",
    "--exclude", "tests",
    "--json",
]
```

Delete `.semgrep.yml` and `.semgrepignore`

**Option B: Keep Local Rules**

Keep `.semgrep.yml` for custom rules specific to the project.

**Recommendation:** Option A for consistency with crackerjack

### Priority 4: Clean Up Output Files

**Impact:** All projects

**Actions:**

1. Add to .gitignore:

   ```gitignore
   # Tool outputs (not configuration)
   complexipy.json
   coverage.json
   bandit-report.json
   .coverage
   .coverage.*
   htmlcov/
   .mypy_cache/
   .pytest_cache/
   .ruff_cache/
   ```

1. Remove from git if tracked:

   ```bash
   git rm --cached complexipy.json coverage.json
   ```

______________________________________________________________________

## Implementation Strategy 📅

### Phase 1: Pilot (Week 1)

**Target:** crackerjack (already analyzed)

1. Eliminate mypy.ini
1. Simplify pyproject.toml
1. Test thoroughly
1. Document lessons learned

### Phase 2: legacy (Week 2)

**Target:** legacy (critical dependency for other projects)

1. Apply mypy.ini consolidation
1. Test with all dependent projects
1. Update any shared documentation

### Phase 3: MCP Projects (Week 3)

**Targets:** session-mgmt-mcp

1. Most complex consolidation (4+ files)
1. Apply all patterns learned
1. Create reusable templates

### Phase 4: Web Frameworks (Week 4)

**Targets:** fastblocks, starlette-async-jinja, jinja2-async-environment

1. Batch apply mypy consolidation
1. Standardize across all web frameworks
1. Create shared config templates

### Phase 5: Standardization (Week 5)

**All projects:**

1. Create `CONTRIBUTING.md` with config standards
1. Add pre-commit hook to prevent mypy.ini creation
1. Document in each project's CLAUDE.md
1. Create GitHub repo template with standard configs

______________________________________________________________________

## Shared Configuration Templates 📋

### Template: Standard Python Project pyproject.toml

```toml
# Copy this template for new lesleslie Python projects

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "project-name"
version = "0.1.0"
description = "Project description"
readme = "README.md"
authors = [
    { name = "Les Leslie", email = "les@wedgwoodwebworks.com" },
]
requires-python = ">=3.13"
license = { text = "BSD-3-Clause" }

[tool.ruff]
target-version = "py313"
line-length = 88
fix = true

[tool.ruff.lint]
extend-select = ["C901", "F", "I", "UP"]
ignore = ["E402"]

[tool.mypy]
python_version = "3.13"
strict = true
ignore_missing_imports = true
show_error_codes = true
warn_return_any = false
warn_unused_configs = true

[[tool.mypy.overrides]]
module = ["tests.*"]
ignore_errors = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=project_name --cov-report=term-missing"

[tool.coverage.run]
source = ["project_name"]
omit = ["*/tests/*", "*/__init__.py"]

[tool.complexipy]
max_complexity = 15
exclude_patterns = ["**/tests/**"]

[tool.codespell]
ignore-words-list = "crate,nd"
```

### Template: .gitignore for Python Projects

```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python

# Virtual environments
.venv/
venv/
ENV/

# Testing
.pytest_cache/
.coverage
.coverage.*
htmlcov/
coverage.json
.tox/

# Type checking
.mypy_cache/
.pytype/

# Linting
.ruff_cache/

# Tool outputs (NOT configuration)
complexipy.json
bandit-report.json

# IDEs
.vscode/
.idea/
*.swp
*.swo
.DS_Store

# Build
build/
dist/
*.egg-info/
```

______________________________________________________________________

## Risks & Mitigation ⚠️

### Risk 1: Breaking CI/CD Pipelines

**Mitigation:**

- Update CI config files (GitHub Actions, etc.) simultaneously
- Test in feature branch before merging
- Use same migration pattern across all projects

### Risk 2: Team Members with Old Clones

**Mitigation:**

- Add migration guide to each project's CHANGELOG
- Send notification to team
- Add note in README about config consolidation

### Risk 3: IDE Compatibility

**Mitigation:**

- Test with VS Code, PyCharm, etc.
- Ensure mypy/ruff plugins still work
- Document any IDE-specific setup needed

### Risk 4: Tool Version Dependencies

**Mitigation:**

- Check minimum tool versions support pyproject.toml
- Update dependencies if needed
- Pin versions in pyproject.toml

______________________________________________________________________

## Monitoring & Validation ✅

### Automated Checks

Add to each project's CI:

```yaml
# .github/workflows/config-validation.yml
name: Config Validation

on: [push, pull_request]

jobs:
  validate-no-legacy-configs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check for legacy config files
        run: |
          # Fail if legacy files exist
          if [ -f "mypy.ini" ]; then
            echo "❌ mypy.ini should be consolidated into pyproject.toml"
            exit 1
          fi

          if [ -f ".semgrep.yml" ] && grep -q "p/security-audit" pyproject.toml; then
            echo "⚠️  Using remote semgrep rules, .semgrep.yml may be redundant"
          fi

          echo "✅ Config validation passed"
```

### Manual Checks

Quarterly review:

- [ ] All projects have pyproject.toml as primary config
- [ ] No mypy.ini files exist
- [ ] Tool outputs are in .gitignore
- [ ] Configs follow standard template

______________________________________________________________________

## Portfolio Impact Summary 📊

### Before Consolidation

| Project | Config Files | Total Lines |
|---------|-------------|-------------|
| crackerjack | 5 | ~500 |
| legacy | 4+ | ~150 |
| session-mgmt-mcp | 7+ | ~200 |
| fastblocks | 5+ | ~150 |
| starlette-async-jinja | 4+ | ~120 |
| jinja2-async-environment | 4+ | ~120 |
| **TOTAL** | **29+** | **~1,240** |

### After Consolidation

| Project | Config Files | Total Lines | Savings |
|---------|-------------|-------------|---------|
| crackerjack | 4 | ~420 | -80 lines, -1 file |
| legacy | 3 | ~140 | -10 lines, -1 file |
| session-mgmt-mcp | 4 | ~150 | -50 lines, -3 files |
| fastblocks | 4 | ~140 | -10 lines, -1 file |
| starlette-async-jinja | 3 | ~110 | -10 lines, -1 file |
| jinja2-async-environment | 3 | ~110 | -10 lines, -1 file |
| **TOTAL** | **21** | **~1,070** | **-170 lines, -8 files** |

### Improvement Metrics

- **Files Eliminated:** 8 config files (28% reduction)
- **Lines Removed:** ~170 lines of configuration (14% reduction)
- **Standardization:** Single source of truth across all projects
- **Maintainability:** Easier to update configs across portfolio
- **Onboarding:** New developers find configs in expected location (pyproject.toml)

______________________________________________________________________

## Next Steps 🚀

1. **Review this audit** with the team
1. **Approve consolidation plan**
1. **Start with crackerjack** (Phase 1 - already in progress)
1. **Roll out to legacy** (Phase 2 - affects all other projects)
1. **Batch migrate remaining projects** (Phases 3-4)
1. **Create shared templates** (Phase 5)
1. **Add CI validation** to prevent regression

**Timeline:** 5 weeks
**Effort:** ~1-2 days per week
**Risk:** Low (incremental, reversible changes)
**Value:** High (standardization + maintainability)

______________________________________________________________________

**Audit Completed By:** Claude Code
**Date:** 2025-11-16
**Status:** Ready for implementation
