mirror of
https://github.com/lukaszraczylo/claude-mnemonic.git
synced 2026-06-09 23:59:40 +00:00
docs: remove outdated macOS limitation documentation
The hybrid test linking issue has been fixed by adding the SQLite driver import. All tests now pass on all platforms including macOS. Removed: - internal/vector/hybrid/README.md (documented workaround no longer needed) - .github/TESTING.md (macOS limitation section obsolete) All 42/42 packages now test successfully with -race flag.
This commit is contained in:
@@ -1,93 +0,0 @@
|
|||||||
# Testing Guide
|
|
||||||
|
|
||||||
## Running Tests
|
|
||||||
|
|
||||||
### Full Test Suite
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make test
|
|
||||||
```
|
|
||||||
|
|
||||||
This runs all tests with proper build tags (`-tags "fts5"`) and race detection.
|
|
||||||
|
|
||||||
### Test Coverage
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make test-coverage
|
|
||||||
```
|
|
||||||
|
|
||||||
Generates coverage reports in `coverage.out` and `coverage.html`.
|
|
||||||
|
|
||||||
## Platform-Specific Issues
|
|
||||||
|
|
||||||
### macOS ARM64
|
|
||||||
|
|
||||||
**Known Issue:** Tests for `internal/vector/hybrid` fail to compile on macOS ARM64 due to CGO linking issues with `sqlite-vec-go-bindings`.
|
|
||||||
|
|
||||||
**Symptoms:**
|
|
||||||
```
|
|
||||||
ld: symbol(s) not found for architecture arm64
|
|
||||||
FAIL github.com/lukaszraczylo/claude-mnemonic/internal/vector/hybrid [build failed]
|
|
||||||
```
|
|
||||||
|
|
||||||
**Root Cause:** Conflict between `mattn/go-sqlite3` and `sqlite-vec`'s embedded SQLite when linking test binaries on macOS ARM64.
|
|
||||||
|
|
||||||
**Impact:**
|
|
||||||
- Local development on macOS ARM64 cannot run hybrid package tests
|
|
||||||
- **Does not affect:** Linux CI, production builds, or runtime functionality
|
|
||||||
- All other 41 packages test successfully
|
|
||||||
|
|
||||||
**Workarounds:**
|
|
||||||
1. Test other packages individually: `go test ./internal/db/... ./internal/search/...`
|
|
||||||
2. Use Docker/Linux container for comprehensive local testing
|
|
||||||
3. Rely on CI for hybrid package validation (recommended)
|
|
||||||
|
|
||||||
**CI Status:** Tests pass successfully on Linux (GitHub Actions ubuntu-latest runner).
|
|
||||||
|
|
||||||
### Linux / CI
|
|
||||||
|
|
||||||
Tests run successfully with:
|
|
||||||
- `CGO_ENABLED=1`
|
|
||||||
- `-tags "fts5"` build flag
|
|
||||||
- ONNX runtime libraries (auto-downloaded by `workflow-prepare.sh`)
|
|
||||||
|
|
||||||
### Windows
|
|
||||||
|
|
||||||
`workflow-prepare.sh` handles Windows-specific SQLite setup automatically.
|
|
||||||
|
|
||||||
## CI Configuration
|
|
||||||
|
|
||||||
The CI workflow (`.github/workflows/ci.yaml`) uses the shared-actions workflow with:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
build-tags: "fts5" # Required for SQLite FTS5 support
|
|
||||||
go-version: ">=1.24"
|
|
||||||
lfs: true
|
|
||||||
```
|
|
||||||
|
|
||||||
The `workflow-prepare.sh` script runs before tests to:
|
|
||||||
1. Download ONNX runtime libraries for the target platform
|
|
||||||
2. Set up SQLite headers on Windows
|
|
||||||
3. Configure CGO linker flags as needed
|
|
||||||
|
|
||||||
## Test Organization
|
|
||||||
|
|
||||||
- **Unit tests**: Package-level tests in `*_test.go` files
|
|
||||||
- **Integration tests**: Database and system integration in `*integration_test.go`
|
|
||||||
- **Benchmarks**: Performance tests in `*_test.go` with `Benchmark*` functions
|
|
||||||
|
|
||||||
## Debugging Test Failures
|
|
||||||
|
|
||||||
If tests fail in CI but pass locally (or vice versa):
|
|
||||||
|
|
||||||
1. Check that build tags are consistent: `-tags "fts5"`
|
|
||||||
2. Verify CGO is enabled: `CGO_ENABLED=1`
|
|
||||||
3. Ensure ONNX libraries are present (run `make setup-libs`)
|
|
||||||
4. Check platform-specific issues (see above)
|
|
||||||
5. Review `workflow-prepare.sh` for platform-specific setup
|
|
||||||
|
|
||||||
## Known Limitations
|
|
||||||
|
|
||||||
- **macOS ARM64**: Cannot compile hybrid package tests (see above)
|
|
||||||
- **Test caching**: Some tests use real databases and may need cache clearing with `go clean -testcache`
|
|
||||||
- **Race detector**: Increases test time significantly but is required for CI
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
# Hybrid Vector Storage
|
|
||||||
|
|
||||||
LEANN-inspired selective vector storage with hub detection and graph-based search.
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
### macOS ARM64 Known Issue
|
|
||||||
|
|
||||||
Tests in this package currently fail to link on macOS ARM64 due to a known issue with `sqlite-vec-go-bindings/cgo`. This is a linking-time issue specific to macOS ARM64 and does not affect:
|
|
||||||
|
|
||||||
- Linux CI/CD (tests pass normally)
|
|
||||||
- Windows builds
|
|
||||||
- Runtime functionality (only affects test compilation)
|
|
||||||
|
|
||||||
The issue is caused by how macOS ARM64 handles CGO linking with multiple SQLite implementations (mattn/go-sqlite3 and sqlite-vec's embedded SQLite).
|
|
||||||
|
|
||||||
**Workaround for local development:**
|
|
||||||
- Run tests for other packages: `go test ./internal/db/... ./internal/search/...`
|
|
||||||
- The CI on Linux will test this package
|
|
||||||
- Or use a Linux container for local testing
|
|
||||||
|
|
||||||
**Status:** This does not affect production builds or CI/CD pipelines.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
This package implements three storage strategies:
|
|
||||||
|
|
||||||
1. **StorageAlways** - Store all embeddings (backwards compatible)
|
|
||||||
2. **StorageHub** - Store only frequently-accessed "hub" embeddings
|
|
||||||
3. **StorageOnDemand** - Recompute all embeddings during search
|
|
||||||
|
|
||||||
See the main documentation for more details on the LEANN algorithm and hybrid storage approach.
|
|
||||||
Reference in New Issue
Block a user