Skip to content

Latest commit

 

History

History
119 lines (74 loc) · 4.06 KB

FAQ.md

File metadata and controls

119 lines (74 loc) · 4.06 KB

Fossiq Development FAQ

Common questions and answers about developing in the Fossiq monorepo.

Architecture & Design

Why do all packages target the browser first?

Fossiq is fundamentally a browser-first, WASM-based KQL tooling suite. All packages are designed to work in the browser using WebAssembly:

  • Browser as primary target: Tree-sitter WASM parser, DuckDB WASM, CodeMirror editor
  • Multi-runtime support: Packages also work in Node.js and Bun as a bonus, not a primary design goal
  • WASM dependency: Core parsing and execution rely on WASM binaries

This differs from typical npm packages that target Node.js primarily and add browser support later.

Why do I see "fs/promises" and "module" warnings in the Vite build?

Question: During bun run build in the UI package, Vite warns:

Module "fs/promises" has been externalized for browser compatibility,
imported by "web-tree-sitter/tree-sitter.js"

Answer: web-tree-sitter is a browser-first parser that includes fallback code for maximum runtime compatibility. It has conditional requires for Node.js modules (fs/promises, module) that are only used in Node.js environments.

Why this is expected:

  • web-tree-sitter is WASM-based and works perfectly in browsers (those requires are never executed)
  • Vite warns because it detects these Node.js imports in the source code
  • The warnings are not errors - the build succeeds and the app works correctly
  • The fallback code is intentionally there to support web-tree-sitter in multiple runtimes

Why we don't suppress the warning:

  • Suppressing warnings hides architectural issues
  • These warnings correctly alert developers to Node.js-specific code in browser packages
  • The warnings are informative: they indicate we're using browser-first packages correctly
  • No action needed - just be aware this is expected

What this means for development:

  • These warnings are safe to ignore during development
  • They do not affect the final bundle (Vite handles WASM externalization correctly)
  • If you introduce new Node.js-specific code, similar warnings will alert you

Package Development

How do I add a new operator to kql-lezer?

See the detailed step-by-step guide in packages/kql-lezer/docs/kql-lezer-dev.md under "Adding a New Operator".

Key steps:

  1. Add grammar rules in src/kql.grammar
  2. Add tests and update status docs

Build & CI

What are changesets and why are they required?

Changesets are version management for the monorepo:

  • One changeset per feature/fix describing what changed and version bump (patch/minor/major)
  • Automated releases via GitHub Actions when merged to main
  • Changelog generation from changeset descriptions

Required for PRs because:

  • Ensures version bumps are intentional
  • Documents what changed for each package
  • Prevents accidental breaking changes (you must explicitly choose "major")

How to use:

bun run changeset

Then commit the generated .changeset/*.md file.

Troubleshooting

The build fails with "Grammar compilation failed"

Check that you've run bun install and all dependencies are available. The compile step requires the tree-sitter CLI to be installed.

Tests pass locally but fail in CI

Common causes:

  • Missing changeset file (required for package changes)
  • Linting errors (run bun run lint:fix)
  • Platform-specific issues (CI runs on Linux)

Check the CI logs for details and run locally:

bun run lint
bun run build
bun run test

How do I update documentation now that .github/instructions is gone?

Each package owns its docs under packages/<name>/docs/:

  • Status files (e.g., packages/kql-lezer/docs/kql-lezer-status.md) track current feature coverage
  • Dev guides (e.g., packages/kql-lezer/docs/kql-lezer-dev.md) capture implementation details
  • Package-specific instructions live alongside the code they describe

After completing a feature:

  1. Update the package status checklist
  2. Add new patterns/gotchas to the dev guide
  3. Mention cross-package impacts in root AGENTS.md or relevant package guides