lukaszraczylo/claude-mnemonic
1
0
Fork 0
mirror of https://github.com/lukaszraczylo/claude-mnemonic.git synced 2026-06-05 23:03:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: remove outdated macOS limitation documentation

Browse Source 
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:
Lukasz Raczylo
2026-01-07 21:58:18 +00:00
parent 57e0db5b1e
commit 187be22071
2 changed files with 0 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/TESTING.md
-93
View File
@@ -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
internal/vector/hybrid/README.md
-32
View File
@@ -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.