IF Commons GitHub

Kanon checker

0001Draft

0001-kanon-checker · owner if · domain commons

The table

FR-001checkpassing

The library MUST give the type of a table (a package name and units, each unit a folder with a layer of Governance, Logical or Physical, or own), the three layers with their ranks, and a decoder that reads a table from the kanon field of a manifest; WHEN a unit declares a layer that is not one of the three, a folder with no trailing slash, a folder twice, a unit in no layer that is not own, an own unit with a layer, or a mayImport naming no unit, the decoder MUST refuse the table with one sentence naming the unit.

Enforced (check): .github: cd commons/kanon && bun run verify — table.test.ts: a table is decoded and every malformed table is refused with a sentence naming the unit

Proved by: kanon/suite/table.test.ts

Written in: kanon/src/mod.ts, kanon/src/model.ts, kanon/src/names.ts, kanon/src/table.ts

Tests: passed: suite/table.test.ts a unit is a sum: a layered unit has a layer and an own unit has none; passed: suite/table.test.ts a folder and a package name are made only by their smart constructors, which refuse what i; passed: suite/table.test.ts a folder with no trailing slash, a folder twice and a unit in no layer are refused; passed: suite/table.test.ts a layer that is not one of the three is refused; passed: suite/table.test.ts a table is decoded, with the three layers ranked from the top and 2 more

FR-002checkpassing

WHEN a file's path is given, the library MUST name the unit it is in, the most specific folder winning, and for a unit with instances one unit for each folder under it; a path that no unit holds MUST be found as none.

Enforced (check): .github: cd commons/kanon && bun run verify — imports.test.ts: a file is placed in the most specific unit, instances one unit each, none where no unit holds it

Proved by: kanon/suite/imports.test.ts

Written in: kanon/src/imports.ts

Tests: passed: suite/imports.test.ts a file is in the most specific unit, an instance in the unit of its folder, and none where

The check

FR-003checkpassing

The library MUST read every import of a file's text as data, with its line: static, side-effect, re-export and dynamic imports and import type, skipping comment lines.

Enforced (check): .github: cd commons/kanon && bun run verify — imports.test.ts: static, side-effect, re-export and dynamic imports are read with their lines and comments are skipped

Proved by: kanon/suite/imports.test.ts

Written in: kanon/src/imports.ts

Tests: passed: suite/imports.test.ts static, side-effect, re-export and dynamic imports are read with their lines, and a commen

FR-004checkpassing

The import check MUST be pure and MUST give, from a table, the files and the exports map of the package, a finding with a code, a file, a line, a sentence and a key for each of: a file in no unit (layers/unclassified), a file of another unit imported by a relative path (layers/relative), an import of the package by a path exports does not name (layers/private), an import of a package the unit's row does not allow (layers/external), an import of a unit that stands below the importer (layers/above), an import of a unit of the same layer or one the row does not list (layers/around) and a loop among the instances of one class (layers/cycle, once, at the import that closes it); a unit that is own MUST be exempt from the relative-import and reach rules.

Enforced (check): .github: cd commons/kanon && bun run verify — imports.test.ts: every code of the check is found from a table, a file set and an exports map, and an own unit is exempt

Proved by: kanon/suite/imports.test.ts, kanon/suite/table.test.ts

Written in: kanon/src/family.ts, kanon/src/imports.ts

Tests: passed: suite/imports.test.ts a file in no unit is layers/unclassified; passed: suite/imports.test.ts a loop among instances of one class is layers/cycle, once, at the import that closes it; passed: suite/imports.test.ts a relative import of a file of another unit is layers/relative, and an own unit may; passed: suite/imports.test.ts an import of a package the row does not allow is layers/external, and a row with no list a; passed: suite/imports.test.ts an import of a unit below is layers/above, and of a unit above is allowed and 4 more

FR-005checkpassing

The library MUST find each annotation of an element of the first layer of a LayeredModel that no disposition of the model accounts for as kanon/dropped, and a disposition that names a target that is no element of the model, or an unexpressed annotation with no reason, MUST be the same finding.

Enforced (check): .github: cd commons/kanon && bun run verify — dropped.test.ts: an annotation no disposition accounts for, a missing target and an unexplained unexpressed are kanon/dropped

Proved by: kanon/suite/dropped.test.ts

Written in: kanon/src/dropped.ts, kanon/src/family.ts

Tests: passed: suite/dropped.test.ts a model with no layers has no finding; passed: suite/dropped.test.ts a target that is no element, and an unexpressed annotation with no reason, are findings; passed: suite/dropped.test.ts an annotation that nothing accounts for is kanon/dropped, named by element and annotation; passed: suite/dropped.test.ts carried, expressed and unexpressed with a reason each account for an annotation

The contract

FR-006checkpassing

The library MUST give LayeredModel as types only (no value but the lists of agreed kinds and the builders of the ids: headless:<program>/<verb-path>, cli:<program> <verb path>, mcp:<tool_name>, rest:<METHOD> <path>, and <verb id>#--flag or <verb id>#<operand>), in the shape of the layered model of the documentation generator with the account of the annotations added.

Enforced (check): .github: cd commons/kanon && bun run verify — model.test.ts: the ids are built as agreed, and a model is assignable to the shape of the documentation generator's layered model

Proved by: kanon/suite/model.test.ts

Written in: kanon/src/extensions.ts, kanon/src/model.ts

Tests: passed: suite/model.test.ts text that is not an id is refused, as a value and not a throw; passed: suite/model.test.ts the agreed kinds are the six a program says and the three a surface projects them into; passed: suite/model.test.ts the ids are built as agreed

The host and the package

FR-007checkpassing

The library MUST read from the file system, in its host entry only, a library's manifest for its table, the exports of its package and its .ts files (leaving out node_modules, dist and the spec kit), and MUST judge the findings against a baseline of keys that only shrinks: a finding the baseline does not hold, and a line of it that no longer occurs, MUST each fail the command check (exit 1), and a table that cannot be read MUST exit 2.

Enforced (check): .github: cd commons/kanon && bun run verify — host.test.ts: the table, the exports and the files are read from a folder, and the command judges against a baseline with exit 0, 1 and 2

Proved by: kanon/suite/host.test.ts

Written in: kanon/src/check.ts, kanon/src/host.ts

Tests: passed: suite/host.test.ts a package that is not JSON, and a folder that is not there, are values and not throws; passed: suite/host.test.ts the host reads through a port: a record of functions that a test can give; passed: suite/host.test.ts a manifest with no table, or a table that is not one, exits 2; passed: suite/host.test.ts the command exits 1 on a new finding, 0 where it is held, and 1 on a held line that no lon; passed: suite/host.test.ts the table, the exports and the files are read from a library's folder, leaving out node_mo

Cited by: Kanon content checks, Kanon

FR-008checkno test run

The library MUST be published as compiled modules with their declarations (commons 0032-libraries-by-concern FR-005, FR-013): the entries ., ./check and ./host, each with a types file, and it MUST be proved by bun run verify in its folder.

Enforced (check): .github: cd commons/kanon && bun run verify — packing: bun tools/pack.ts --check compiles the package, inspects its declarations and packs it

Written in: kanon/about.ts, kanon/library.ts, kanon/tools/check.ts, kanon/tools/pack.ts

The typing

FR-009checkpassing

The library MUST be typed as an algebra (commons 0033-kanon FR-018): the layers, the finding codes and the kinds of a unit are closed unions matched exhaustively, a unit is a sum of a layered unit and an own unit, a folder, a package name and an element id are branded types made only by a smart constructor that returns a Result, the records are readonly, the host reads through a port (a record of functions) and returns a Result for a failure it can cause, and the pure modules throw nothing, use no any, no non-null assertion and no enum.

Enforced (check): .github: cd commons/kanon && bun run verify — table.test.ts, model.test.ts, host.test.ts: smart constructors refuse what is not a folder, a package or an id, a unit is a sum, the codes are a closed union with a registry, a failure of the host is a value, and the host reads through a port; the compiler holds the exhaustive matches

Proved by: kanon/suite/host.test.ts, kanon/suite/model.test.ts, kanon/suite/table.test.ts

Tests: passed: suite/host.test.ts a package that is not JSON, and a folder that is not there, are values and not throws; passed: suite/host.test.ts the host reads through a port: a record of functions that a test can give; passed: suite/model.test.ts text that is not an id is refused, as a value and not a throw; passed: suite/table.test.ts a unit is a sum: a layered unit has a layer and an own unit has none; passed: suite/table.test.ts the codes are a closed union with a summary and a family for each

Cited by: Kanon content checks

Instances, plugins and families

FR-010checkpassing

The decoder MUST read, in the table, the optional family (two name templates, dialect and plugin, each with {host} once and {name} once, and optionally contract, an export subpath), instances (each a name, the instanceOf unit it is an instance of and a placement of folder or package), plugins (each a noun and optional dependsOn nouns of other plugins) and extends (the host package of a package that is a dialect or a plugin), into a Table that always has instances and plugins; it MUST refuse, with one sentence, instances or plugins with no family, a template without its two holes or with the same text for dialect and plugin, an instance of no layered unit, a folder instance of a unit that has no instances, a name or noun that is declared twice or is not a name, a plugin noun that would read as a dialect, a dependency on itself, on no plugin or in a loop, a contract that is not an export subpath, and a table that both extends a host and declares members.

Enforced (check): .github: cd commons/kanon && bun run verify — extensions.test.ts: the family, instances, plugins and extends are decoded, each malformed form is refused with a sentence, and any JSON value is a table or a sentence

Proved by: kanon/suite/extensions.test.ts

Written in: kanon/src/family.ts, kanon/src/table.ts

Tests: passed: suite/extensions.test.ts decoding any value gives a table or a sentence and never throws; passed: suite/extensions.test.ts a host's table declares its family, instances and plugins, and the package of each comes f; passed: suite/extensions.test.ts a malformed instance, plugin or family is refused with a sentence

Cited by: Kanon content checks

FR-011checkpassing

The library MUST derive the package of each member from the family's rule and never from a second spelling (memberPackage), and MUST read a package name back as the host, a dialect, a plugin or none (classify), a dialect before a plugin and only within the host's scope; a name made for any dialect name round-trips to that dialect, and one made for any plugin noun that is not dialect-... to that plugin.

Enforced (check): .github: cd commons/kanon && bun run verify — extensions.test.ts: a package is read as host, dialect or plugin by the rule, and a name made from any name or noun reads back as it (property test)

Proved by: kanon/suite/extensions.test.ts

Written in: kanon/src/family.ts

Tests: passed: suite/extensions.test.ts decoding any value gives a table or a sentence and never throws; passed: suite/extensions.test.ts a package is read as the host, a dialect or a plugin by the family's rule, a dialect befor; passed: suite/extensions.test.ts the name a rule makes is read back as the same member, for every dialect name and plugin n

FR-012checkpassing

The checks MUST give, as data in the form of the others, these further codes: instances/sibling (an instance imports another instance of its unit, or a dialect another dialect), instances/undeclared (a folder under a unit whose instances the table declares that no instance names), plugins/inverted (a host's file outside its own checking imports a dialect or a plugin of its family), plugins/undeclared (an extension imports a member of the family it declares no dependency on), plugins/contract (the family's contract is not among the host's exports, or a plugin does not import it) and family/name (a package that extends a host is not one the host's table declares by the family's rule, or names another host); extensionFindings MUST be pure, take the host's table and exports with the extension's table, files and exports, reach the host only through the host's exports (layers/private otherwise), let a dialect reach the units its instance's unit may import and a plugin any unit the exports name, and treat a relative import that leaves the package as layers/relative; the host side MUST find the host beside the extension by the package name of extends.

Enforced (check): .github: cd commons/kanon && bun run verify — extensions.test.ts: the fixture host with two dialects and two plugins passes, and each new code is found from a table, files and exports

Proved by: kanon/suite/extensions.test.ts

Written in: kanon/src/extensions.ts, kanon/src/host.ts, kanon/src/imports.ts

Tests: passed: suite/extensions.test.ts a dialect reaches the layers above it and its port and no other physical unit; passed: suite/extensions.test.ts a dialect that imports another dialect is instances/sibling, and a plugin it does not depe; passed: suite/extensions.test.ts a host that imports a member of its family is plugins/inverted, in a unit and not in its o; passed: suite/extensions.test.ts a package the host does not declare, or one that extends another host, is family/name; passed: suite/extensions.test.ts a plugin imports another plugin only through a declared dependency, and a dialect never and 6 more

FR-013checkpassing

WHERE a model has instances, the check of FR-005 MUST be made for each instance: an annotation of Governance MUST end, for each instance, expressed, carried or unexpressed with a reason, by a disposition given for that instance or else by one given for none; an annotation with none for an instance, a target that is no element or that belongs to another instance, an unexpressed one with no reason, and a disposition for an instance the model does not have, MUST each be a kanon/dropped finding whose key names the instance; ModelElement MUST be able to say which instance it belongs to.

Enforced (check): .github: cd commons/kanon && bun run verify — matrix.test.ts: the check of dropped annotations is made for each instance, with the instance in the key

Proved by: kanon/suite/matrix.test.ts

Written in: kanon/src/account.ts, kanon/src/dropped.ts

Tests: passed: suite/matrix.test.ts for any dispositions, the dropped cells of the matrix are the findings of the check; passed: suite/matrix.test.ts a disposition for no instance holds for every instance, and one for an instance wins over ; passed: suite/matrix.test.ts a target that belongs to another instance, a missing target, an empty reason and an unknow; passed: suite/matrix.test.ts an annotation accounted for in one dialect and not the other is kanon/dropped naming the o; passed: suite/matrix.test.ts the fixture model accounts for every annotation in each dialect

FR-014checkpassing

The library MUST build, from a model and with no other input, the matrix of requirement by instance (buildMatrix): a row for each annotation of each element of the first layer and a cell for each instance, each cell one of expressed, carried, unexpressed (with its reason) or dropped, made from the same reading of the dispositions as FR-013 so that a dropped cell is a finding and no other cell is; it MUST render it as a Markdown table (matrixMarkdown) and as JSON (matrixJson), both pure and in the order of the model, and count its cells by outcome (matrixTotals).

Enforced (check): .github: cd commons/kanon && bun run verify — matrix.test.ts: the matrix of the fixture, its Markdown and JSON, and for any dispositions the dropped cells are the findings (property test)

Proved by: kanon/suite/matrix.test.ts

Written in: kanon/src/matrix.ts

Tests: passed: suite/matrix.test.ts for any dispositions, the dropped cells of the matrix are the findings of the check; passed: suite/matrix.test.ts a model with no instances has a matrix with no columns, and the check is the one of FR-005; passed: suite/matrix.test.ts the matrix is rendered as a Markdown table and as JSON that reads back as the matrix; passed: suite/matrix.test.ts the matrix of the fixture is a row for each annotation and a cell for each dialect

Acceptance scenarios

  1. Given a table with a layer of middle, When it is decoded, Then it is refused, per FR-001.
  2. Given a table with a unit that has instances, When a file under one of its folders is placed, Then it is in that folder's unit, per FR-002.
  3. Given a file with an import in a comment, a dynamic import and a re-export, When it is read, Then the two real imports are found with their lines, per FR-003.
  4. Given a file of Governance that imports Logical by the package's name, When the check runs, Then it reports layers/above, per FR-004.
  5. Given a file of Logical that imports a file of Physical by a relative path, When the check runs, Then it reports layers/relative, per FR-004.
  6. Given a model with an annotation of Governance that nothing accounts for, When it is checked, Then it reports kanon/dropped, and after the annotation is named unexpressed with a reason, nothing, per FR-005.
  7. Given a library whose manifest declares a table and whose tree breaks it, When check runs with an empty baseline, Then it exits 1, and with the finding held it exits 0, and with a held line that no longer occurs it exits 1, per FR-007.
  1. Given a host with two dialects declared by package, When a dialect imports the other, Then it reports instances/sibling, per FR-012.
  2. Given a plugin that imports a plugin it declares no dependency on, When the check runs, Then it reports plugins/undeclared, and with the dependency declared nothing, per FR-012.
  3. Given a model with two dialects and an annotation accounted for in one, When it is checked, Then kanon/dropped names the other dialect, per FR-013.
  4. Given that model, When the matrix is built and rendered, Then a row for each annotation has a cell for each dialect and the Markdown and the JSON say the same, per FR-014.

Out of scope

  • The pattern itself and its vocabulary: commons 0033-kanon of the specifications of commons.
  • Moving the checks that commons/data and commons/headless keep.

Edge cases

  • A surface folder with no row in the table: layers/unclassified, per FR-004.
  • Two instances of one class that import each other: layers/cycle, per FR-004.
  • An exports target given as an object of conditions: the bun or default target is read, per FR-004.

Assumptions

  • A library's .ts files are all under its root and none is outside a unit the table names.

Open questions

OQ-1open question

Whether a conformance level of commons requires a library to declare its table (commons 0033-kanon OQ-1); the check of the manifests has the switch and no level uses it.

Key entities

  • Table - the units of a library, each in a layer, as data in its manifest.
  • Finding - a breach of the table or of the account of annotations, with a key a baseline can hold.
  • LayeredModel - the types-only contract of a Kanon library's model.

Success criteria

SC-001success criterion

A library's layers are held by one check, whatever its units are called.

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

Kanon content checks, Kanon

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