IF Commons GitHub

Questions of the trace in SQL

0002Active

0002-mizan-query · owner if · domain mizan

Relations

FR-001checkpassing

The relations MUST be findings (rule, file, line, message, key, status), baseline (key, status), specs (slug, status, in_force, requirements) and requirements (spec, id, line, reviewed); the status of a finding MUST be fresh where the baseline does not hold its key and held where it does, and the status of a key of the baseline MUST be stale where no finding has it and held where one does, as judge says.

Enforced (check): .github: cd commons/mizan && bun test suite/ — query.test.ts

Proved by: mizan/suite/query.test.ts

Written in: mizan/src/query.ts

Tests: passed: suite/query.test.ts the findings are fresh or held as the baseline says, its keys are held or stale, the speci

FR-002checkpassing

traceCatalog() MUST give the catalog of those relations with the type of each column, so that a name or a column that is not there is found before a question is answered.

Enforced (check): .github: cd commons/mizan && bun test suite/ — query.test.ts

Proved by: mizan/suite/query.test.ts

Written in: mizan/src/query.ts

Tests: passed: suite/query.test.ts the findings are fresh or held as the baseline says, its keys are held or stale, the speci

Questions

FR-003checkpassing

queryTrace(records, sql, options?) MUST answer one query that the guard of the SQL language library judges to be a single read and binds to the catalog, with the engine of the same library, and MUST give an error value, never a throw, for anything else (a statement that writes, more than one statement, an unknown relation or column with the name it is closest to), with the sentence of the guard and its place; an answer MUST hold at most options.limit rows (1000 where none is given) and say whether it was cut; parameters (?) MUST be given by options.params and never read as SQL.

Enforced (check): .github: cd commons/mizan && bun test suite/ — query.test.ts

Proved by: mizan/suite/query.test.ts

Written in: mizan/src/query.ts

Tests: passed: suite/query.test.ts a question is one line of SQL (the new findings by rule, the requirements nobody reviewed,

The library and the tool

FR-004checkpassing

queryLibrary(root, sql) MUST read the findings of the trace of the library at root (its about.ts, src and tools and its suite against spec-kit/specs), its trace.baseline.txt and its specifications, and answer through queryTrace; bun tools/query.ts [--root DIR] [--limit N] "SELECT ..." MUST print the answer as an aligned table and write nothing, and end with 0 where it answered, 1 where the question is refused and 2 for a command line that does not fit.

Enforced (check): .github: cd commons/mizan && bun test suite/ — query.test.ts

Proved by: mizan/suite/query.test.ts

Written in: mizan/src/host/query.ts, mizan/tools/query.ts

Tests: passed: suite/query.test.ts the library at a folder is asked (its own findings are all held by its baseline), and the

Cited by: host/query, Mizan

FR-005checkpassing

Only src/query.ts MAY name the SQL language library (lang-sql/aide/catalog, guard, relational and text); no other module of the library names it.

Enforced (check): .github: cd commons/mizan && bun test suite/ — query.test.ts

Proved by: mizan/suite/query.test.ts

Tests: passed: suite/query.test.ts only the module of the questions names the SQL language library

Cited by: The harness of Mizan

Out of scope

  • A question over the findings of the other checks of Mizan (layers, versions, changes), over a ladder of libraries at once, and over the git history.

Edge cases

  • A library with no baseline file: every finding is fresh and the baseline has no rows, per FR-001.
  • A key of the baseline that no finding has: stale, per FR-001.

Assumptions

  • A library keeps its specifications in spec-kit/specs and its baseline in trace.baseline.txt.

Open questions

  • None.

Key entities

  • Records: the findings, the baseline and the specifications a question is about.
  • Relation: a table of values that a question may name.

Success criteria

  • The findings of a library are grouped by rule and by status with one line of SQL, from the checkout, with nothing written.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

host/query, Mizan, query, The harness of Mizan

Titles, headings, exports, tables, columns and requirements. Esc closes.