v0.5.0: let a provider select the operators it serves, and ship the generator - #12

Closes #11.

The generator narrowed the value side of a filter well and left the feature side all-or-nothing per profile. Internally it was already operator-granular — every emission site gates on ctx.enabled — but the only thing that could write to that set was the union of whole profiles. A backend with LIKE and no POSITION could not offer $like without also advertising $contains; a store with no notion of key absence could not decline $exists at all.

What this adds

Six knobs, each a CLI flag and a JS API option:

All three shapes from the issue work. Whatever a provider declines is absent from the generated schema, so a client learns it from validation rather than from a runtime error — or worse, from an empty result set.

--max-filter-depth is the one that restructures output. JSON Schema cannot count how deep an instance already is, so a bounded filter is emitted as a chain: level i offers the logical operators over level i+1 and the last offers none. Levels share the operand $defs, so the cost is n copies of a map of $refs. Unbounded stays the single self-referential object it has always been, and every default is byte-identical to before.

The spec decision

Issue #11 asked whether operator-level narrowing is a tooling change or a tooling-plus-spec one. It takes the first option it lists: a partial profile is demoted. profiles in the capability document now lists only the profiles the final operator set covers in full, the per-field operators lists carry the rest — which §2.2 already described as "a subset of those implied by profiles" — and the demotion is warned about on stderr naming the operator responsible. Declining a core operator says outright that the result is not a conforming implementation.

SPEC.md gains two clarifications, both about what an implementation may claim rather than what a filter means: §2.1 says out loud that accepting part of a profile is permitted and advertising it is not, and §2.2 documents the capability document's top-level members (limits appeared in the example and in no table; filterSchema, itemValues and nullable were emitted by the generator and described nowhere). No grammar change, no $id bump.

Two bugs found on the way

• --include pruned only the root filter, so with a depth cap every excluded path walked back in one $and down.
• An operator whose dependency was dropped stayed. --drop-operators $regex left $flags with a dependentRequired rule naming a member additionalProperties: false forbids — present in the schema and impossible to use. The closure is read off $defs/ConstraintObject, so a later dependency is handled by construction.

--max-depth also stopped coercing a non-number to NaN in silence.

Verification

132 tests pass, up from 119. The new shapes are covered by the narrowing property, not a case list: the seeded sampler in tests/fuzz.mjs now runs over dropped operators, --no-shorthand and a capped depth, with its non-vacuity assertions intact. npm run generate:example runs through examples/pet.jql.config.json and the committed outputs are byte-identical; the MCP demo transcript is unchanged.

Also carries 0ba799a, the #8 narrowing fix, which was pushed to its own branch and never opened as a PR. It is already documented in this changelog window.

Generated with Claude Code