Repository Evaluation Framework

A structured set of dimensions for periodically assessing the health of this codebase. Review quarterly, or before any significant release.

Score each dimension 1–5:

1 — not addressed, actively harmful
2 — partially addressed, gaps present
3 — adequate for current project stage
4 — well handled
5 — exemplary

Dimensions

1. Code health

Check	Notes
Modules are single-responsibility	`App.jsx` currently does too much — known debt
Business logic separated from UI	Sync and DB logic in `db.js` / `supabase.js` — good
No obvious duplication	Review for repeated patterns
File sizes are reasonable	Flag any file >300 lines for review
Imports are clean and intentional	No unused imports

Target for v1: 3/5
Target for v2: 4/5 (requires App.jsx refactor)

2. Commit discipline

Check	Notes
Each commit represents one logical change
Commit messages follow Conventional Commits	See `CONTRIBUTING.md`
`main` has never been broken	Verify with build history
No debug commits (`fix typo`, `WIP`, `asdfgh`) on main
Sensitive data never committed	Audit with `git log --all -S "sk-ant"`

How to audit:

# Check for any potential secrets in history
git log --all --oneline | head -20
git log --all -S "sk-ant" --source --all
git log --all -S "supabase" --source --all

3. Documentation

Check	Notes
README covers setup from scratch	Test by following it cold
Architecture decisions are recorded	`docs/architecture.md`
Supabase setup is documented	`docs/supabase-setup.md`
CHANGELOG is current	Updated before every release
Non-obvious code has inline comments	Check sync and migration logic

4. Dependency hygiene

Check	Notes
No known vulnerabilities	Run `npm audit`
Dependencies are up to date	Run `npm outdated`
Each dependency is justified	Review `package.json`
Dev vs runtime dependencies correctly separated
`package-lock.json` committed	✓

How to check:

npm audit
npm outdated

5. Security posture

Check	Notes
`.env` is gitignored	Verify with `git check-ignore .env`
No secrets in commit history	See audit commands above
Only `anon` key used client-side	`service_role` must never appear
Row-level security enabled on all tables	Verify in Supabase dashboard
User data not logged to console	Grep for `console.log`

How to check:

git check-ignore -v .env
grep -r "service_role" src/
grep -r "console.log" src/

6. Test coverage

Check	Notes
Critical sync logic tested	`db.js` — mergeCloudRecords, outbox
Import/export tested	Schema migration paths
Auth flow tested	Sign in, sign out, session restore

Current state: No tests. Acceptable for v1 personal tool.
Target for public release: Unit tests on db.js and supabase.js.

7. Release discipline

Check	Notes
Releases tagged with semver	`git tag v1.0.0`
CHANGELOG updated before tagging
Tag pushed to remote	`git push --tags`
Netlify deploy confirmed after release

Evaluation log

Date	Code	Commits	Docs	Deps	Security	Tests	Release	Notes
2026-03-26	3	—	4	4	4	1	—	Initial commit

Add a row after each quarterly review or significant release.