Parameter kinds, fixtures and documentation rules¶

Parameter kinds¶

Build every parameter with param.<kind>(id, label, options) from transformers/_kit. The kind decides the inspector's editor, a fresh node's empty value, and how the value reaches SQL — which is what the SQL guard and the escaping contract test key on.

Options every kind accepts:

expression and query values are untrusted SQL. A transformer must splice them only with the kit's spliceExpression(fragment) and spliceQuery(fragment, relation), which build exactly the form the SQL guard validated (docs/security.md).

Generated schemas¶

schemas/params.schema.json holds the JSON Schema of every transformer's params object (under $defs.<Id>), and schemas/transformer.schema.json the shape of a catalogue entry — the declaration without its hooks, as the assistant sees it. Both are generated from the kit (transformers/_kit/value-schemas.js) and the registry by npm run build:schemas; npm run check fails when they are out of date. Every fixture case's params must validate against them.

Fixtures (tests.json)¶

{
  "transformer": "Tester",
  "cases": [
    {
      "name": "AND of two conditions; NULL goes to failed",
      "params": { "logic": "AND", "conditions": [{ "column": "v", "operator": ">", "value": "5" }] },
      "inputs": {
        "input": {
          "crs": "EPSG:4326",
          "columns": [{ "name": "id", "type": "INTEGER" }, { "name": "v", "type": "DOUBLE" }],
          "rows": [[1, 10.5], [2, null]]
        }
      },
      "expect": {
        "passed": { "columns": [{ "name": "id", "type": "INTEGER" }, { "name": "v", "type": "DOUBLE" }], "rows": [[1, 10.5]] },
        "failed": { "columns": [{ "name": "id", "type": "INTEGER" }, { "name": "v", "type": "DOUBLE" }], "rows": [[2, null]] }
      }
    }
  ]
}

• Inputs are typed tables (GEOMETRY cells as WKT). Each is fed through a test-only FixtureSource carrying the case's crs, so projected inputs can be tested. An input with no rows is still typed.
• source instead of inputs writes a real Parquet file (fileName, columns, rows, readerParams) and reads it through a real Reader — for behaviour that depends on the file, such as H3 defaults from the file name.
• expect has one entry per output port (columns compared by name, order and type; rows as a multiset unless "ordered": true), an optional crs, or { "error": "<substring>" }.
• assert instead of expect, for random output: rowCount { min, max }, subsetOf: "input", columnsEqual: "input", unique: [columns].
• sink: true cases run the Writer and compare the file: expect.file with name and text (text formats) or table (binary formats, read back through the Reader).
• Values: 64-bit integers, dates and timestamps are written as text; GEOMETRY as WKT.
• geometry: { "mode": "exact" } (default — same type, dimensions, part order, ring start and orientation, coordinates within tolerance), relaxed per case with "ignore": ["ringStart", "orientation", "partOrder"] and a required "why"; or { "mode": "topology", "tolerance", "areaTolerance" } for algorithm output (symmetric-difference area and Hausdorff distance).

npm run check:fixtures enforces the rules: the file exists and has cases; every output port is exercised; every select option has a case (a warning until v0.2, except coverage: "one"); at most 50 KB per file and 50 rows per input; a why for every ignore. Whether the cases pass is npm run test:browser. Capture a new case's expectation with node scripts/capture-expectations.js --only <Id> — then read it before committing it.

Documentation rules¶

npm run check:docs refuses a transformer unless:

and its README.md has these headings, in order, none empty: What it does · When to use it · When not to use it · Parameters · Output ports · Examples · Limitations · Credits. Placeholder text (TODO, the scaffold's guidance comments) fails the check.