IF Commons GitHub

Questions of the repository in SQL

0012Active

0012-repoctl-query · owner if · domain repoctl

Relations

FR-001checkpassing

The relations MUST be libraries (name, package, folder, version, level, npm, held), specs (library, number, slug, state: a row of registry.tsv) and requirements (library, spec, fr, mechanism, by, note: a row of enforcement.tsv, its first column split into the specification and the requirement); a library with no spec kit MUST have rows in libraries only, and a line of a table that is not a row (a header, a blank line, a line that is not an id of a requirement) MUST be left out.

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

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

Written in: repoctl/src/logical/query.ts

Tests: passed: suite/query.test.ts the libraries, specifications and requirements are relations: a library with no kit has no

Questions

FR-002checkpassing

askRepository(sources, 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 of FR-001, 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.

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

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

Written in: repoctl/src/logical/query.ts

Tests: passed: suite/query.test.ts a question is one line of SQL (the requirements nothing verifies, the specs of a state), t

FR-003checkpassing

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/repoctl && bun run verify — suite/query.test.ts

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

Written in: repoctl/src/logical/query.ts

Tests: passed: suite/query.test.ts a question is one line of SQL (the requirements nothing verifies, the specs of a state), t

The verb

FR-004checkpassing

repoctl query "<SELECT>" MUST be a verb of the public tier that only reads (it changes no file), present only where the configuration turns on the capability query (which needs libraries); it MUST read the manifests and the two tables of each library's spec kit through the ports of the world, and give the answer as an aligned table, or as the data of the JSON envelope with --json, with --limit for the most rows.

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

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

Written in: repoctl/src/physical/verbs/query.ts

Tests: passed: suite/query.test.ts the verb is declared once, public and read-only, comes only where the configuration turns

Cited by: Repoctl, physical/verbs/query

FR-005checkpassing

A question that is refused or cannot be answered MUST end the verb with a problem (E-USAGE, naming the sentence and place) and a status that is not 0; an answer, however many rows it has, MUST end with 0.

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

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

Written in: repoctl/src/physical/verbs/query.ts

Tests: passed: suite/query.test.ts the verb is declared once, public and read-only, comes only where the configuration turns

Cited by: Repoctl, physical/verbs/query

Out of scope

  • A question over the findings of check, the versions on npm, or anything the ports do not already read; a question that changes a file.

Edge cases

  • A library whose spec kit has no enforcement.tsv: no requirements, per FR-001.
  • A repository with no capability query: the verb is not in the tree, per FR-004.

Assumptions

  • The tables are tab-separated with the columns the spec kit of every library of commons keeps.

Open questions

  • None.

Key entities

  • Source: a library as the manifest says it, with the texts of its two tables.
  • Relation: a table of values that a question may name.

Success criteria

  • The questions of the examples are answered in one line of SQL each, 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

Repoctl, logical/query, physical/verbs/query

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