SignalQL quality checklist
Self-assessment against the public bar for v0.1. Status: Met, Partial, or Gap.
Language design
| Criterion | Status | Notes |
|---|---|---|
| v0.1 scope small and enforced | Met | scope + compiler limits (limits.ts) |
| Readable syntax; AI-generatable | Met | Grammar pack + examples |
| Deterministic compile → predictable SQL | Met | Same input → same SQL/params (see compiler tests) |
| Invalid queries → useful errors | Partial | ParseError includes clause + token index where applicable; codegen limits use RangeError |
| Not “SQL with renamed keywords” | Met | FUNNEL / DURING / portable model are semantic lifts |
| Funnels, segmentation, aggregation, time solve real jobs | Met | Example library |
Specification
| Criterion | Status | Notes |
|---|---|---|
| Grammar implementable | Met | EBNF in spec |
| Core concepts defined | Met | Events, users, sessions, properties, time |
| Portable data model | Met | Data model |
| Examples cover common questions | Met | Spec + examples + fixtures |
| Valid and invalid examples | Met | Scope |
| Versioning strategy clear | Met | Schema $id, spec version, release |
Compiler / parser
| Criterion | Status | Notes |
|---|---|---|
| Parser tests for v0.1 syntax | Partial | Parser + compiler tests; expand with golden invalid corpus |
| AST stable, documented, versioned | Met | AST schema, JSON Schema file |
| Parameterized SQL | Met | Compiler pipeline |
| Query limits enforced | Met | Day span, funnel steps |
| Deterministic output | Met | Asserted in compile tests |
| Errors point to clause/token | Partial | Lexer + parser attach offset/token index; not full spans |
| Postgres end-to-end first | Met | CLI run + fixtures/seed.sql; Local Postgres |
Data model
| Criterion | Status | Notes |
|---|---|---|
| Tables/fields documented | Met | Data model page |
| Required vs optional | Met | |
| Property access rules | Met | |
| Custom mapping guidance | Met | Adapters + model doc |
| Sample dataset matches standard | Met | fixtures/seed.sql |
Docs / content
| Criterion | Status | Notes |
|---|---|---|
| README < 1 minute | Met | Repository root README.md |
| Neutral and implementation-agnostic | Met | Why SignalQL |
| Spec readable | Met | |
| Copy-paste examples | Met | Library + fixtures |
| How + why | Met | Guide + spec + AI docs |
| AI prompting practical | Met | Prompting guide |
| Cursor, Claude, ChatGPT, MCP | Met | Integrations |
| GitHub / site in sync | Met | Site = VitePress build of docs/; release |
Playground
| Criterion | Status | Notes |
|---|---|---|
| Public first query without setup | Gap | No hosted or embedded playground runner on the docs site today |
| Local playground compile path | Met | npm run dev -w @signalql/playground from a repo checkout |
| CLI first query path | Met | First query guide with local commands |
| Errors teach fixes | Partial | Messages improved; add “did you mean” later |
| Generated SQL visible | Met | Toggle + panel |
| Sample data meaningful | Partial | Illustrative result table for preset queries + seed for CLI/Postgres |
| Easy example switching | Met | Buttons |
| Reinforces v0.1 scope | Met | Subtitle on playground |
AI readiness
| Criterion | Status | Notes |
|---|---|---|
| AST JSON schema | Met | schemas/ + docs |
| LLM grammar pack concise | Met | Grammar pack |
| MCP safe tools | Met | @signalql/mcp |
| Event discovery | Met | list_events / describe_event |
| Good/bad prompt examples | Met | Prompting guide |
Open source quality
| Criterion | Status | Notes |
|---|---|---|
| License MIT | Met | LICENSE |
| Contributing clear | Met | CONTRIBUTING.md |
| One-command tests | Met | npm test |
| No private vendor infrastructure in repo | Met | By policy |
| Release process documented | Met | This release page |
| Invites external implementers | Met | Spec + schema + contribution guide |
Adoption
| Criterion | Status | Notes |
|---|---|---|
| Works with neutral Postgres/CSV paths | Partial | Postgres: CLI + seed. CSV: adapter is demo-oriented; use Postgres for full path |
| SDK/CLI quickstart | Met | README |
| Canonical examples (funnel, retention, …) | Met | Example library |
| Implementation-neutral positioning | Met | Positioning docs + integrations |
| Launch “why AI-native” | Met | Distribution |
Summary: Core quality bar is met for spec, safety, docs, and Postgres path. The current playground experience is local-only (repo checkout + dev server), so a public no-setup runner remains a gap. Other next investments: deeper parser test matrix, optional live playground execution, and a production-grade CSV path.