|
| 1 | +# Thinker-FTS - Agent Guide |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +Thinker-FTS is a fast, extendable, and standalone pure JavaScript full-text search engine that works across Node.js, Deno, and browsers. |
| 6 | + |
| 7 | +## Project Structure |
| 8 | + |
| 9 | +``` |
| 10 | +thinker-fts/ |
| 11 | +├── src/ # Source code |
| 12 | +│ ├── Thinker.js # Main entry point |
| 13 | +│ ├── Thinker.single.js # Single export wrapper |
| 14 | +│ ├── index.js # Index backend |
| 15 | +│ ├── processors.js # Word/field processors (stemmers, soundex, etc.) |
| 16 | +│ ├── rankers.js # Result ranking algorithms |
| 17 | +│ └── utils.js # Helper utilities |
| 18 | +├── test/ # Test files |
| 19 | +│ ├── test.js # Main test entry (ESM) |
| 20 | +│ ├── test.cjs # CommonJS test entry |
| 21 | +│ └── suites/ # Test suites |
| 22 | +│ └── default.cjs # Main test suite |
| 23 | +├── dist/ # Built distribution files |
| 24 | +│ ├── thinker.cjs # UMD module |
| 25 | +│ ├── thinker.mjs # ES module |
| 26 | +│ └── thinker.min.* # Minified versions |
| 27 | +└── rollup.config.js # Build configuration |
| 28 | +``` |
| 29 | + |
| 30 | +## Development Environment |
| 31 | + |
| 32 | +The project uses **Node.js** as the primary development runtime with ES modules. |
| 33 | + |
| 34 | +### Setup |
| 35 | +```bash |
| 36 | +npm ci |
| 37 | +``` |
| 38 | + |
| 39 | +## Contribution Guidelines |
| 40 | + |
| 41 | +### Pre-commit Checks |
| 42 | + |
| 43 | +Before committing changes, always run: |
| 44 | +```bash |
| 45 | +npm run test |
| 46 | +``` |
| 47 | + |
| 48 | +This executes: |
| 49 | +- **Linting**: `eslint ./**/*.js` - checks for code quality issues |
| 50 | +- **Testing**: `mocha` - runs the test suite |
| 51 | + |
| 52 | +### Testing |
| 53 | + |
| 54 | +Run tests during development: |
| 55 | +```bash |
| 56 | +npm run test |
| 57 | +``` |
| 58 | + |
| 59 | +Run tests with coverage: |
| 60 | +```bash |
| 61 | +npm run test:coverage |
| 62 | +``` |
| 63 | + |
| 64 | +### Full Build |
| 65 | + |
| 66 | +Before submitting a PR, run the full build to ensure all checks pass: |
| 67 | +```bash |
| 68 | +npm run build:ci |
| 69 | +``` |
| 70 | + |
| 71 | +This runs linting, builds distribution files, and runs tests with coverage. |
| 72 | + |
| 73 | +### Key Points |
| 74 | + |
| 75 | +- Base work on the `master` branch |
| 76 | +- Add test cases for all changes |
| 77 | +- The project has few external dependencies - avoid adding new runtime dependencies |
| 78 | +- Follow existing code style (tabs, double quotes, semicolons) |
| 79 | +- Update documentation if changing public APIs |
| 80 | +- The `dist/` files are committed to the repository |
| 81 | + |
| 82 | +## Features |
| 83 | + |
| 84 | +- In-memory full-text search |
| 85 | +- Natural language search with modifiers (+, -, "exact") |
| 86 | +- Partial matching with wildcards |
| 87 | +- Weighted ranker with configurable field weights |
| 88 | +- Word processors: stemmers (English, Swedish), soundex, stopwords |
| 89 | +- Field processors: HTML stripper |
| 90 | +- Result filtering and reduction |
| 91 | +- Metadata collection |
0 commit comments