Files

Matthew Raymer eb1fc9f220 feat(docs): complete P2.6 type safety cleanup and P2.7 system invariants

P2.6: Type Safety Cleanup
- Replaced 'any' return types in vite-plugin.ts with concrete types (UserConfig, transform return type)
- Documented TypeScript mixin 'any[]' exception in PlatformServiceMixin.ts
- Audit confirmed: zero 'any' in codebase except documented TS mixin limitation
- All external boundaries use 'unknown', all data payloads use 'Record<string, unknown>'

P2.7: System Invariants Documentation
- Created SYSTEM_INVARIANTS.md documenting all 6 enforced invariants
- Added to docs/00-INDEX.md under Policy & Contracts section
- Each invariant includes: What, Why, How, Where

Progress Docs Updates:
- Updated 00-STATUS.md: marked P2.6/P2.7 complete, added type safety invariant note
- Updated 01-CHANGELOG-WORK.md: added 2025-12-22 entries for P2.6/P2.7
- Updated 03-TEST-RUNS.md: added P2.6 type safety audit test run
- Updated P2-DESIGN.md: marked P2.6 acceptance criteria complete
- Updated SYSTEM_INVARIANTS.md: added Type Safety Notes section

Baseline Tag:
- Created v1.0.11-p0-p1.4-p1.5-p2.6-p2.7-complete

TypeScript compilation: ✅ PASSES
Build: ✅ PASSES
CI: ✅ All checks pass

2025-12-22 10:56:00 +00:00

2.8 KiB

Raw Blame History

Local CI

This repo uses local CI via ./ci/run.sh (which wraps ./scripts/verify.sh).

Contract / Policy-as-code: ./ci/run.sh is the only supported CI entrypoint for this repo. Any release gate, merge gate, or automation must invoke ./ci/run.sh (not npm run build directly). ./scripts/verify.sh encodes enforced invariants (packaging + core purity + exports).
See also: docs/progress/00-STATUS.md for invariants and baseline tags.

Quick Start

./ci/run.sh

What It Checks

The CI runs ./scripts/verify.sh, which performs:

Environment Diagnostics - Node.js, npm, Java, Swift, xcodebuild availability
Dependencies - npm install if needed
Native Code Location - Ensures no native code in src/ directories
TypeScript - Lint, typecheck, unit tests
Build - npm run build must succeed
Package - npm pack --dry-run with forbidden files check
Android - Build check (if gradlew available)
iOS - Build and test check (if xcodebuild available)

Platform-Specific Behavior

Linux (CI/Development)

✅ TypeScript checks
✅ Build checks
✅ Package checks (forbidden files)
⚠️ Android builds: Skipped (requires gradlew)
⚠️ iOS builds: Skipped (requires xcodebuild)

macOS (Full CI)

✅ All Linux checks
✅ iOS builds: Run if xcodebuild available
✅ iOS tests: Run if xcodebuild available

Required Tooling

Linux

Node.js 18+
npm
Java 17+ (for Android builds, optional)
TypeScript compiler

macOS

All Linux requirements
Xcode (for iOS builds/tests)
xcodebuild command-line tools

Integration Points

Release Gate

Add to your release process:

./ci/run.sh && npm publish

Pre-Merge Gate

Run before merging PRs:

./ci/run.sh

Git Hook (Recommended)

Install the pre-push hook to automatically run CI before pushing:

# One-time setup
git config core.hooksPath githooks

After setup, githooks/pre-push will automatically run ./ci/run.sh before allowing pushes.

To skip the hook (not recommended):

git push --no-verify

Makefile Target

# Run local CI
make ci

This is equivalent to ./ci/run.sh and provides a convenient alias.

Exit Codes

0 - All checks passed
1 - Verification failed

Forbidden Files Check

The CI hard-fails if npm pack --dry-run contains:

xcuserdata/
*.xcuserstate
DerivedData/
ios/App/
.DS_Store
*.swp, *.swo
*.orig, *.rej

This ensures the package is publish-safe.

2.8 KiB Raw Blame History