IF Commons GitHub

Generators

0010Active

0010-sql-generators · owner if · domain data

The generator

FR-001checkpassing

A generator MUST be a value with an identifier and a function from a logical schema, a naming and an optional dialect to files (a path and a text) or to error values; an extension MUST contribute it through the engine's point physical.generators, and generate MUST run every generator it is given and return every file in the order of the generators, or all the errors together.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: extensions contribute generators through the engine and generate returns every file in their order, or every error, and a path made twice is an error value

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/mod.ts, data/sql/physical/generate.ts

Tests: passed: suite/generators.test.ts extensions contribute generators through the engine and generate returns every file in the

FR-002checkpassing

A generator MUST give the same files for the same input every time: no clock, no environment, no random value; each text MUST end with one newline.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the same input gives the same files, each ending in one newline, with names written by the case style and no reading of anything else

Proved by: data/suite/generators.test.ts

Written in: data/sql/physical/generate.ts

Tests: passed: suite/generators.test.ts the same input gives the same files, each ending in one newline, with names written by the

FR-003checkpassing

Two files with the same path MUST be an error value naming the path, and the path of each generator MUST be made from the name of the schema's domain, in the case style's words, so that two schemas never collide.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: extensions contribute generators through the engine and generate returns every file in their order, or every error, and a path made twice is an error value

Proved by: data/suite/generators.test.ts

Written in: data/sql/physical/generate.ts

Tests: passed: suite/generators.test.ts extensions contribute generators through the engine and generate returns every file in the

FR-004checkpassing

A generator MUST read the logical schema, the naming and the dialect and nothing else: it MUST NOT connect to a database, read a file or call another generator, and it MUST write the name of every table and column as the case style writes it.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the same input gives the same files, each ending in one newline, with names written by the case style and no reading of anything else

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/model.ts, data/sql/physical/generate.ts

Tests: passed: suite/generators.test.ts the same input gives the same files, each ending in one newline, with names written by the

What is generated

FR-005checkpassing

The Mermaid generator MUST make an erDiagram of every table with each column's type, its key marks (PK, FK) and, between tables, a relationship for each foreign key; the D2 generator MUST make the same as sql_table shapes with a connection for each foreign key.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the Mermaid and D2 diagrams hold every table with its types and key marks and a relationship for each foreign key, and a closed list is an enum

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/diagrams.ts

Tests: passed: suite/generators.test.ts the Mermaid and D2 diagrams hold every table with its types and key marks and a relationsh

Cited by: Data, sql/extensions/generators/diagrams

FR-006checkpassing

The dictionary generator MUST make, for each table, a section with its description, its owner (what governance names as the owner of its domain or concept), its primary key and a table of its columns with the type, whether it may be null, the column it points to, its description and the personal data it holds; the type MUST be the dialect's where a dialect is given, and the logical type's where none is.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the dictionary has each table's description, owner, key and columns with their types, null, target, description and personal data, and the page has the same with links

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/dictionary.ts, data/sql/extensions/generators/model.ts

Tests: passed: suite/generators.test.ts the dictionary has each table's description, owner, key and columns with their types, null

Cited by: Data, sql/extensions/generators/dictionary

FR-007checkpassing

The HTML generator MUST make one self-contained page of the same content as the dictionary, with a link from each foreign key to the table it points to, no script and no outside resource, and every text escaped.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the dictionary has each table's description, owner, key and columns with their types, null, target, description and personal data, and the page has the same with links

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/dictionary.ts

Tests: passed: suite/generators.test.ts the dictionary has each table's description, owner, key and columns with their types, null

Cited by: Data, sql/extensions/generators/dictionary

FR-008checkpassing

The Rust generator MUST make a struct of each table with a field for each column (an Option where it may be null) and the description as documentation, and an enum for each column that only a closed list of codes may fill.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: Rust gets a struct with Options and an enum for a closed list, Zod a schema with nullable and z.enum, and every logical type has a form in both

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/code.ts

Tests: passed: suite/generators.test.ts Rust gets a struct with Options and an enum for a closed list, Zod a schema with nullable

Cited by: Data, sql/extensions/generators/code

FR-009checkpassing

The Zod generator MUST make a schema of each table with a field for each column (.nullable() where it may be null), and z.enum for each column that only a closed list of codes may fill.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: Rust gets a struct with Options and an enum for a closed list, Zod a schema with nullable and z.enum, and every logical type has a form in both

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/code.ts

Tests: passed: suite/generators.test.ts Rust gets a struct with Options and an enum for a closed list, Zod a schema with nullable

Cited by: Data, sql/extensions/generators/code

FR-010checkpassing

The register generator MUST make a Markdown register of every table and column that governance says holds personal data (its category, the class the category is in, the purposes and the retention) and of every one that carries a classification, access, scope or mask, so that what governance says of privacy and security is read in one place.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the register lists personal data with its category, class and purposes and every classification, access, scope and mask

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/register.ts

Tests: passed: suite/generators.test.ts the register lists personal data with its category, class and purposes and every classific

Cited by: Data, sql/extensions/generators/register

FR-011checkpassing

Every logical type MUST have a form in each generator that writes types, so that a type added to the logical schema is refused by the compiler wherever a generator does not yet write it, never written wrongly.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: Rust gets a struct with Options and an enum for a closed list, Zod a schema with nullable and z.enum, and every logical type has a form in both

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/code.ts

Tests: passed: suite/generators.test.ts Rust gets a struct with Options and an enum for a closed list, Zod a schema with nullable

Cited by: Data, sql/extensions/generators/code

FR-012checkpassing

A text that governance wrote (a description, a code) MUST be escaped for the format it goes into: a pipe in a Markdown table, markup in HTML, a quote in a string, a line break in a documentation comment.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: a text of governance is escaped for the format it goes into

Proved by: data/suite/generators.test.ts

Written in: data/sql/extensions/generators/code.ts, data/sql/extensions/generators/dictionary.ts, data/sql/extensions/generators/model.ts, data/sql/extensions/generators/register.ts

Tests: passed: suite/generators.test.ts a text of governance is escaped for the format it goes into

Cited by: Data, sql/extensions/generators/code, sql/extensions/generators/dictionary

What the files hold

FR-013checkpassing

The Zod file MUST be a module that a project can import and that validates the rows of its tables: a row that fits parses, and a row with a missing, wrong or unknown value is refused; and the Rust file MUST compile.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the Zod module validates rows and refuses what does not fit, and the Rust file compiles

Proved by: data/suite/generators.test.ts

Tests: passed: suite/generators.test.ts the Zod module validates rows and refuses what does not fit, and the Rust file compiles

FR-014checkpassing

The files of Arca's party model MUST hold every table, every column and every foreign key of its logical schema, in each diagram, dictionary, struct and schema, and nothing more.

Enforced (check): .github: cd commons/data && bun run verify — suite/generators.test.ts: the files of Arca's party model hold every table, column and foreign key of its logical schema and nothing more

Proved by: data/suite/generators.test.ts

Tests: passed: suite/generators.test.ts the files of Arca's party model hold every table, column and foreign key of its logical sc

Out of scope

  • Diagrams drawn from governance concepts and relationships rather than tables: later.
  • Rendering Mermaid or D2 to an image, or publishing the files: a tool's, not a generator's.
  • Generators for other languages: an extension a project writes with FR-001.
  • Writing the files to disk: the command line's (a later phase); a generator returns text.

Edge cases

  • A schema with no table: files with a heading and no section, per FR-006.
  • A column that only a closed list fills: enum in the diagram, an enum in Rust and z.enum in Zod, per FR-005, FR-008 and FR-009.
  • A description with a pipe in it: escaped in a Markdown table, per FR-012.
  • A vector column: Vec<f32> in Rust and an array of its dimensions in Zod, per FR-011.
  • Two generators that write the same path: an error value, per FR-003.
  • A dictionary with no dialect: the logical types, per FR-006.
  • A column that holds personal data of a category in no register: a row with the category and no purposes, per FR-010.

Assumptions

  • Governance is read from what the logical schema carries on each table and column (0006-logical); a generator needs no domain of its own.
  • The class a category of personal data is in is the one the privacy vocabulary of governance gives.

Open questions

OQ-1open question

Whether the register is also a machine-readable form (CSV or JSON) beside the Markdown, and whether it follows a standard layout of a record of processing.

Key entities

  • Generator - an extension's function from a logical schema to files.
  • Artifact - a file a generator makes: a path and a text.
  • Register - the privacy and security of a schema, read in one place.

Success criteria

SC-001success criterion

A project composes the generators it wants and gets the same files every time, which it can check in and compare.

SC-002success criterion

Nothing governance says of a table or a column is missing from the files that describe it.

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

Data, sql/extensions/generators/code, sql/extensions/generators/diagrams, sql/extensions/generators/dictionary, sql/extensions/generators/mod, sql/extensions/generators/register, sql/physical/generate

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