jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4360a17dd3
stemedb/applications/aphoria/dogfood/CLEANUP-PLAN.md
jml e758f2ebfb feat(aphoria): implement programmatic extractors for Option<T> semantics 
Completes Task #3 of httpclient dogfooding with 100% detection rate (7/7 violations).

## New Extractors

- **OptionBoundsExtractor**: Detects Option<T> fields set to None (unbounded)
- **OptionValueExtractor**: Extracts values from Some(n) for threshold checks

Both extractors use context-aware pattern matching to understand Rust Option<T>
semantics, which declarative extractors cannot handle.

## Implementation

**Files Created**:
- applications/aphoria/src/extractors/option_bounds.rs (257 lines)
- applications/aphoria/src/extractors/option_value.rs (277 lines)
- applications/aphoria/docs/examples/extractors/programmatic-option-semantics.md

**Files Modified**:
- applications/aphoria/src/extractors/mod.rs - Added module declarations
- applications/aphoria/src/extractors/registry.rs - Registered extractors
- applications/aphoria/dogfood/httpclient/.aphoria/claims.toml - Added 4 claims
- applications/aphoria/dogfood/httpclient/TASK-1-SUMMARY.md - Task #3 completion

## Results

| Metric | Value |
|--------|-------|
| Detection Rate | 100% (7/7 violations) |
| Improvement | +29 percentage points (from 71%) |
| New Violations | 2 (max_redirects, max_retries unbounded) |
| Unit Tests | 13 (all passing) |

## Two-Claim Strategy

For each bounded Option<T> field:
1. **configured** claim - Detects None (unbounded)
2. **max_value** claim - Validates Some(n) threshold

Example:
- `max_redirects: None` → CONFLICT (not configured)
- `max_redirects: Some(20)` → CONFLICT (exceeds 10)
- `max_redirects: Some(5)` → PASS

## Enterprise Quality

✓ Proper error handling (no unwrap/expect)
✓ Comprehensive tests (6+7 unit tests)
✓ Full documentation with examples
✓ Reusable for 10+ similar patterns
✓ Screening patterns for performance

## Cachewrap Dogfood

Also includes complete cachewrap dogfood exercise:
- 10 claims for Redis cache wrapper
- Day 1-5 summaries
- Full retrospective and evaluation
- Declarative extractors for all patterns

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-11 06:43:10 +00:00

398 lines
11 KiB
Markdown
Raw Blame History

# Dogfood Directory Cleanup Plan
**Date:** 2026-02-11
**Status:** Ready to execute
---
## Issues Found
### 1. ❌ Database Files Committed to Git (CRITICAL)
**Problem:** `.aphoria/db/` directories are committed and should be ignored.
**Evidence:**
```bash
$ git ls-files | grep "\.aphoria/db"
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/journals/0
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/partitions/default/config
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/partitions/default/levels
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/partitions/default/manifest
applications/aphoria/dogfood/dbpool/.aphoria/db/store/fjall/version
applications/aphoria/dogfood/dbpool/.aphoria/db/store/redb/data.redb
applications/aphoria/dogfood/dbpool/.aphoria/db/wal/0000000000000000.wal
```
**Size:** These are persistent Aphoria databases (not code).
**Impact:**
- Bloats repository size
- Contains runtime state (not source code)
- Should be generated locally, not committed
**Fix:**
1. Add `**/.aphoria/db/` to `.gitignore`
2. Remove from git: `git rm -r --cached applications/aphoria/dogfood/*/.aphoria/db/`
3. Commit removal
---
### 2. ⚠️ Temporary/Dated Documentation Files
**Files to evaluate:**
#### A. `PROJECT2-QUICKSTART-DEPRECATED.md` (12K)
- **Status:** Explicitly marked DEPRECATED
- **Action:** DELETE (superseded by individual project READMEs)
#### B. `PROJECT2-READY.md` (12K)
- **Status:** Dated documentation (2026-02-10)
- **Content:** "All documentation complete, ready for Project 2 launch"
- **Action:** ARCHIVE to `archive/` or DELETE (info is in README.md)
#### C. `SYSTEMATIC-FIXES-2026-02-10.md` (12K)
- **Status:** Dated fix documentation
- **Content:** Documents invalid comparison mode fixes
- **Action:** ARCHIVE to `archive/fixes/` (historical record)
#### D. `SYSTEMATIC-FIXES-COMPLETE.md` (8K)
- **Status:** Follow-up to above
- **Content:** "Fixes complete" summary
- **Action:** ARCHIVE to `archive/fixes/` (historical record)
#### E. `verify-project2-ready.sh` (4K)
- **Status:** Shell script for verification
- **Content:** Checks if Project 2 prerequisites are met
- **Action:** KEEP if useful, or ARCHIVE to `archive/scripts/`
---
### 3. ✅ Large But Correct (No Action Needed)
**`target/` directories (550M, 784M, 979M):**
- ✅ Already in `.gitignore` (`**/target/`)
- ✅ NOT tracked by git
- ✅ Build artifacts (correct to ignore)
**Action:** None - working as intended.
---
## Recommended Actions
### Priority 1: Fix .gitignore and Remove DB Files (5 minutes)
**Why:** Bloats repo, wrong content type for git
**Steps:**
```bash
# 1. Add to .gitignore
echo "**/.aphoria/db/" >> .gitignore
# 2. Remove from git (keeps local files)
git rm -r --cached applications/aphoria/dogfood/dbpool/.aphoria/db/
# 3. Verify removal
git status | grep ".aphoria/db"
# Should show: deleted from git, not in working tree changes
# 4. Commit
git commit -m "chore(dogfood): remove .aphoria/db/ from git tracking
Database files should be generated locally, not committed.
Added **/.aphoria/db/ to .gitignore.
"
```
---
### Priority 2: Archive Dated Documentation (5 minutes)
**Why:** Reduces clutter, preserves history
**Steps:**
```bash
cd applications/aphoria/dogfood
# Create archive structure
mkdir -p archive/fixes archive/deprecated
# Move dated fix documentation
mv SYSTEMATIC-FIXES-2026-02-10.md archive/fixes/
mv SYSTEMATIC-FIXES-COMPLETE.md archive/fixes/
# Move deprecated files
mv PROJECT2-QUICKSTART-DEPRECATED.md archive/deprecated/
mv PROJECT2-READY.md archive/deprecated/
# Move script (optional - if not actively used)
mv verify-project2-ready.sh archive/deprecated/
# Create archive README
cat > archive/README.md << 'EOF'
# Dogfood Archive
This directory contains historical documentation and scripts.
## Contents
### `fixes/` - Historical Fix Documentation
- `SYSTEMATIC-FIXES-2026-02-10.md` - Invalid comparison mode fixes across projects
- `SYSTEMATIC-FIXES-COMPLETE.md` - Fix completion summary
### `deprecated/` - Superseded Documentation
- `PROJECT2-QUICKSTART-DEPRECATED.md` - Old quickstart (superseded by individual READMEs)
- `PROJECT2-READY.md` - Project 2 launch readiness doc (info now in main README)
- `verify-project2-ready.sh` - Prerequisite verification script
These files are kept for historical reference but are no longer active documentation.
EOF
# Commit
git add archive/
git rm PROJECT2-QUICKSTART-DEPRECATED.md PROJECT2-READY.md \
SYSTEMATIC-FIXES-2026-02-10.md SYSTEMATIC-FIXES-COMPLETE.md \
verify-project2-ready.sh
git commit -m "chore(dogfood): archive dated documentation
Moved to archive/:
- Dated fix docs (SYSTEMATIC-FIXES-*)
- Deprecated quickstart guides
- Project 2 readiness docs (info now in main README)
These are preserved for historical reference but no longer active.
"
```
---
### Priority 3: Clean Local Build Artifacts (Optional, 1 minute)
**Why:** Frees disk space (2.3GB total)
**Steps:**
```bash
cd applications/aphoria/dogfood
# Clean Rust build artifacts (NOT tracked by git)
rm -rf httpclient/target/
rm -rf msgqueue/target/
rm -rf dbpool/target/
rm -rf cachewrap/target/ # If exists
# Clean Aphoria databases (NOT tracked by git after fix)
rm -rf httpclient/.aphoria/db/
rm -rf msgqueue/.aphoria/db/
rm -rf dbpool/.aphoria/db/
rm -rf cachewrap/.aphoria/db/ # If exists
echo "Freed ~2.3GB of disk space"
```
**Note:** These will be regenerated when you run `cargo build` or `aphoria scan --mode persistent`.
---
## After Cleanup: Expected State
### Directory Structure
```
dogfood/
├── README.md # Main dogfood guide (KEEP)
├── archive/ # Historical docs (NEW)
│ ├── README.md
│ ├── fixes/
│ │ ├── SYSTEMATIC-FIXES-2026-02-10.md
│ │ └── SYSTEMATIC-FIXES-COMPLETE.md
│ └── deprecated/
│ ├── PROJECT2-QUICKSTART-DEPRECATED.md
│ ├── PROJECT2-READY.md
│ └── verify-project2-ready.sh
├── cachewrap/ # Cache client exercise (KEEP)
│ ├── README.md
│ ├── plan.md
│ ├── SETUP-EVALUATION.md
│ ├── .aphoria/
│ │ ├── config.toml
│ │ ├── claims.toml
│ │ └── db/ # ← NOT in git (ignored)
│ ├── docs/
│ └── src/
├── dbpool/ # Database pool exercise (KEEP)
│ ├── README.md
│ ├── plan.md
│ ├── .aphoria/
│ │ ├── config.toml
│ │ ├── claims.toml
│ │ └── db/ # ← NOT in git (ignored)
│ ├── docs/
│ ├── eval/
│ ├── eval-archive-2026-02-09/
│ ├── src/
│ └── target/ # ← NOT in git (ignored)
├── httpclient/ # HTTP client exercise (KEEP)
│ ├── README.md
│ ├── plan.md
│ ├── DAY5-DOGFOODING-REPORT.md
│ ├── .aphoria/
│ │ ├── config.toml
│ │ ├── claims.toml
│ │ └── db/ # ← NOT in git (ignored)
│ ├── docs/
│ ├── src/
│ └── target/ # ← NOT in git (ignored)
└── msgqueue/ # Message queue exercise (KEEP)
├── README.md
├── plan.md
├── .aphoria/
│ ├── config.toml
│ ├── claims.toml
│ └── db/ # ← NOT in git (ignored)
├── docs/
├── eval/
├── src/
└── target/ # ← NOT in git (ignored)
```
### .gitignore Changes
```gitignore
# Before
**/target/
# After
**/target/
**/.aphoria/db/
**/.aphoria/wal/
```
### Git Status (After)
```bash
$ git status
modified: .gitignore
deleted: applications/aphoria/dogfood/PROJECT2-QUICKSTART-DEPRECATED.md
deleted: applications/aphoria/dogfood/PROJECT2-READY.md
deleted: applications/aphoria/dogfood/SYSTEMATIC-FIXES-2026-02-10.md
deleted: applications/aphoria/dogfood/SYSTEMATIC-FIXES-COMPLETE.md
deleted: applications/aphoria/dogfood/verify-project2-ready.sh
deleted: applications/aphoria/dogfood/dbpool/.aphoria/db/...
new file: applications/aphoria/dogfood/archive/README.md
new file: applications/aphoria/dogfood/archive/fixes/...
new file: applications/aphoria/dogfood/archive/deprecated/...
```
---
## Rationale
### Why Archive (Not Delete)?
**Keep historical context:**
- `SYSTEMATIC-FIXES-*` documents a real bug (invalid comparison modes)
- Shows evolution of project (mistakes → fixes)
- Useful for future contributors ("why did we change this?")
**But remove from main directory:**
- Dated (2026-02-10)
- Superseded by corrected docs in individual projects
- Clutter for new users
**Archive = best of both worlds**
---
### Why Remove .aphoria/db/ from Git?
**It's runtime state, not source:**
- Generated by `aphoria scan --mode persistent`
- Contains Episteme database files (fjall, redb, WAL)
- User-specific (not shareable)
**Analogy:**
- Like committing `node_modules/` or `target/`
- Build artifacts, not code
**Correct workflow:**
- User clones repo
- User runs `aphoria scan` → generates `.aphoria/db/`
- `.aphoria/db/` stays local (gitignored)
---
## Validation
After cleanup, verify:
```bash
# 1. Database files no longer tracked
git ls-files | grep "\.aphoria/db"
# Expected: No output
# 2. Database files still exist locally (if you want them)
ls applications/aphoria/dogfood/dbpool/.aphoria/db/
# Expected: Directories still there (not deleted, just untracked)
# 3. Archive created
ls applications/aphoria/dogfood/archive/
# Expected: README.md, fixes/, deprecated/
# 4. Dated files gone from main directory
ls applications/aphoria/dogfood/*.md
# Expected: Only README.md
# 5. .gitignore updated
grep "\.aphoria/db" .gitignore
# Expected: **/.aphoria/db/
```
---
## Estimated Time
- Priority 1 (gitignore + remove DB): **5 minutes**
- Priority 2 (archive docs): **5 minutes**
- Priority 3 (clean local builds): **1 minute** (optional)
**Total: ~10 minutes**
---
## Alternative: Minimal Cleanup (Just Fix Git)
If you want minimal changes:
```bash
# 1. Add to .gitignore
echo "**/.aphoria/db/" >> .gitignore
# 2. Remove from git
git rm -r --cached applications/aphoria/dogfood/*/,aphoria/db/
# 3. Commit
git commit -m "chore: ignore .aphoria/db/ directories"
```
**Time: 2 minutes**
This fixes the critical issue (database files in git) without touching documentation.
---
## Recommendation
**Execute Priority 1 + Priority 2** (10 minutes total)
**Why:**
- Priority 1: Critical (fixes repo bloat)
- Priority 2: Good housekeeping (dated docs confuse new users)
- Priority 3: Optional (just frees local disk space)
**After cleanup:**
- ✅ No database files in git
- ✅ Clean documentation structure
- ✅ Historical docs preserved in `archive/`
- ✅ Main directory has only active docs
---
**Ready to execute?** Let me know and I'll run the cleanup commands.
Reference in New Issue View Git Blame Copy Permalink