module-kit

module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0

README

module-kit

CI Release CodeQL Latest release Go version Coverage OpenSSF Scorecard License

Code Smells Reliability Rating Security Rating Maintainability Rating Vulnerabilities

The NovaTrail module format in code: the one Go library that holds the format's semantics, and the authors' CLI on top of it. It reads an author's module and checks it — the schema, a skill graph without cycles, references, the shared taxonomy, keys by solver and fallback texts by leak check — builds the module package and the module index, and compares a new version of a module with every published one by the format's rules of versions. It also fills seeded task templates and runs their solvers in a Starlark sandbox, and for the platform's service it builds the open view of a task, joins two readings of a learner's work into one observation and runs the check kinds on it, admits a verdict only by the provenance of its key and trusts a package by the chain of digests from a pinned index; signatures it leaves to spec's release-verify. It never calls an AI model: the library makes no network calls, the CLI only reads and writes a module's files, and neither holds learners' data.

A component of NovaTrail, a universal open platform for adaptive learning, interactive lessons and AI tutoring. It belongs to stage 1, Format and core, with spec, modules, learner-model, engine and sim; together with modules it tries the module format v0 on two unlike subjects at once.

Status

Detailing is done. The documents came first: the first epic of RUN.md, now archived in docs/plan/E1.md, decided what the component's card left open, and the code follows in the order RUN.md sets. The code began with the skeleton of the CLI, module-kit --version, which the author had written ahead of the format so that the shared Go checks of .github have code to be tried on (R04), and the library's packages, each saying what it will hold (R20). The first code of the format is the reader of YAML: it reads a module's file into its JSON value and refuses one that breaks a rule yaml.*, on go-yaml v4 with passes of its own around it wherever go-yaml reads otherwise than YAML 1.2.2 (R21). On it stands the check of a module: its folder as the format lays it out, the rules module.*, and the format version its manifest names, which the check reads before anything else and refuses outside 0.3 (R22). Each file of a part is checked against the JSON Schema 2020-12 schema of its part, by santhosh-tekuri/jsonschema over a copy of the format's schemas that a test holds to spec's, and a breach of a schema names its keyword and its place as the format's examples do (R23). From the marks x-open in the same schemas the library builds the open view of each part, what the learner's app receives, into the types of spec's formatv0/open (R24). On the files that their schemas accept, the check runs the rules of the manifest, the skill graph and the catalogs, and the library computes the tiers of the skills that the package will hold (R25); it runs the rules of a task and of a lesson too, those that need no check kind, no leak check and no template (R26). The library gives the verdict of an answer slot and of an item on the values read in them, by the check kinds number, fraction and choice and their normalization, with the trap of a wrong value, and the check of a module reads by those verdicts the rules of a task that a check sees itself (R27). The normalization follows Unicode 17.0.0, which a release names in verdict.UnicodeVersion and on the second line of module-kit --version. A predicate runs in the Starlark sandbox, on go.starlark.net at the version the format names, in the format's one dialect, with its limit of steps and module-kit's clock, and the check of a module holds that its expression names nothing but value and the dialect's built-in names (R28). The package observation holds what module-kit does with spec's observation, novatrail.observation.v1: which one is valid, how the readings of two readers join into one answer slot by answer slot, and the verdict on the joined one with the options tapped beside it, or how an essay's submission ends; an observation that is not valid is no observation, and every answer slot that AI reads gets unchecked (R29). The leak check finds the keys and the leak phrases of a task in a text: in the tutor's words before api sends them, and in the texts of a module that a learner sees before solving, which the check of a module holds by task.no-leaks and lesson.no-leaks. It normalizes a text as the verdict normalizes a value, by code that has moved into a package of its own for both (R30). The generator of the format is module-kit's own code, written from the constants of the format's text, with an error on an argument outside a function's domain and Go's math/rand/v2 and hash/fnv as its reference in the tests alone; by it the library picks which instance of a template an attempt gets from the attempt's seed (R31). The library counts the instances of a template, its expressions read as the format's narrow subset of Starlark and evaluated in the sandbox, and fills an instance with its numbers in a single pass, as api will with the numbers a package carries; the check of a module holds a template to the rules of templates and every instance of it to the schema and the rules of a task, the leak check among them (R32). A template's solver runs once, on a thread of the sandbox of its own, and its solve on every instance in turn with the numbers that the open fields show, within one budget of steps and one clock for the template; its results join the numbers of each instance, and the check of a module reads the instances with them (R33). The library builds the package of a module that passed its check — its canonical view, with the tiers of the skill graph and the numbers of every instance, the listing of its device part and its inventory — writing each text by its own function of the canonical text, which refuses a value the format cannot hold, and reads a package as files by the chain of digests from the digest of the package, each file held to its digest, its schema and its canonical text; it gives the digest of the open view of a task and of an instance too (R34). From the packages of a release, the index of the release before and the release's withdrawals, the library builds the module index, refusing a build that breaks a rule module-index.*; it reads an index of any version of the format by the places every version keeps, and picks the version of a module that a new attempt takes: the newest by semver that is not withdrawn and lies in the format's window (R35). The library compares a new version of a module with the newest published one, each published package read by the chain of digests without its device part: it finds the part of the version that the change asks for by the table of the format, reports each change at its place in the package, and gives the next versions after the newest published one by the rule of 0.y.z (R36). It holds the eight rules module-version.* too, each refusal named by its rule, and reads a published package of an earlier version of the format by the places every version keeps, so that the rules hold through a move of the format, which is a major change while the format is v0; every test vector of the format now passes (R37). The CLI now checks a module and builds its package: module-kit check <module> reports each breach with its place and the ID of its rule, and module-kit build <module> <folder> writes the package as files into a folder that does not exist yet or is empty. Both exit with 0 when the format accepts the module, 1 when it refuses it, and 2 when the command could not do its work. The solvers of a module's templates run one on each CPU, each once for the check and the package together, and a release carries the license and notice of every module the binary is built from (R38). check warns, too, of a PNG or WebP picture with a pixel that is not fully opaque, which may vanish on a dark sheet, and of one it could not check; a warning refuses nothing and changes no exit status (R39). module-kit index builds the module index of a release of modules from the previous index or --first, the release's packages, its tag and its withdrawals or --no-withdrawals, each "none" said by a flag of its own; module-kit diff compares a new version of a module, a folder or a package, with the packages of every version that the index names, and reports the part of the version and each change, or the rule module-version.* that refuses it (R40). A test walks every example and test vector of the format and of the observation, which the code takes from spec's Go modules at the submodule's tag (R20), and module-kit passes every one: the test skips none, so no release comes out that fails one (R42). The code of the format came in the second epic, E2, now archived in docs/plan/E2.md, on the module format 0.3 that spec defines in its format/. Its releases from v0.2.0 on, the line 0.2, are the ones others take — the CLI as a release binary that spec's release-verify accepts, the library as a Go module at the tag; the releases of the line 0.1 before them were steps of the epic, and nobody takes them (R16; R42). module-kit open writes the open views of a release of modules for the samples page of canvas: of each module the version a new attempt would take, with the withdrawals that the index of the newest release marks; open-views.json with the open view of its manifest and of each task beside its digest, a template's instance for each seed given; and the files of its device part (R43).

Releases

A release comes out by itself once the checks pass on main: the next patch of the current line, tagged vX.Y.Z with the release, and nobody tags by hand. The releases of the line 0.1 were steps of the code's first epic, and nobody takes them; the line 0.2, from v0.2.0, is the one others take (R16, R42). Releases are immutable, so a tag stays on its commit and no file changes once it is out.

  • The CLI is one binary for each of linux, darwin and windows, on amd64 and arm64, module-kit_<version>_<os>_<arch>, beside the licenses of the modules it is built from and SHA256SUMS. Each file is signed with cosign by NovaTrail's shared release workflow, its bundle <file>.sigstore.json beside it. Take a binary at an exact tag, and check it before its first run with spec's just -f spec/justfile release-verify module-kit <tag> <file>, which checks the signature against Sigstore's trust root and everything its certificate names (R77 spec). module-kit with no arguments prints how to call each command, and module-kit --version its release.
  • The library is the Go module github.com/altnovatrail/module-kit, at the tag of a release: go get github.com/altnovatrail/module-kit@v0.2.1. Its packages are documented by their doc comments: pkg.go.dev.

Contributing

Report a bug or propose a change in an issue, in English or Russian, and open one before a pull request unless the pull request fixes a typo or a broken link. How a change comes in, with every commit signed off, and what every change keeps to are in the organization's CONTRIBUTING.md; the rules every NovaTrail repository shares are in spec's RULES.md: code comes with its tests. Report a vulnerability privately, as the security policy says, never in a public issue.

Work in the devcontainer: open the repository in VS Code and choose "Reopen in Container". It holds every tool at the version the repository pins. The checks are recipes of the justfile, and just --list names each with its arguments:

  • just ci-lint — gofmt and go vet, and that the pinned versions agree: gopls with its lock file, spec's Go modules with the submodule, and the licenses a release carries with the modules the binary is built from;
  • just ci-test — every test, with the race detector, among them the test of every example and test vector of the module format, which skips none; it writes the coverage to coverage/go.out;
  • just ci-vuln — govulncheck; just ci-licenses — go-licenses, with the list of allowed licenses in ALLOWED_LICENSES;
  • just build — the CLI into bin/; just release-files <version> — the files of a release into dist/.

A check exits with a non-zero status when it finds a problem. CI runs them all on every pull request and on main, runs each binary of a release on a runner of its own system, and a pull request merges only when they pass. Documents are checked by just -f spec/justfile docs-check-repo.

Documents

The documents are in Russian.

  • docs/architecture.md — the component: what it does and does not do, its data and links, and what is still to decide.
  • docs/decisions.md — the decision log: what was decided, why, and what was rejected.
  • RUN.md — the work plan, in epics.

The working rules, for people and coding agents alike, are in CLAUDE.md and AGENTS.md. The platform's shared vocabulary, formats, contracts and decisions are in spec, checked out here as a git submodule at v0.9.2: clone this repository with git clone --recurse-submodules.

License

Apache-2.0.

Directories

Path Synopsis
cmd
module-kit command
Command module-kit is the authors' CLI of NovaTrail's module format (architecture 3.7 in spec; architecture 3.6): check checks a module, and warns of a picture that is not opaque; build builds its package as files; index builds the module index of a release of modules; diff compares a new version of a module with the published ones; and open writes the open views of a release of modules for the page of samples of canvas, all by the library of this module.
Command module-kit is the authors' CLI of NovaTrail's module format (architecture 3.7 in spec; architecture 3.6): check checks a module, and warns of a picture that is not opaque; build builds its package as files; index builds the module index of a release of modules; diff compares a new version of a module with the published ones; and open writes the open views of a release of modules for the page of samples of canvas, all by the library of this module.
internal
canonical
Package canonical writes the canonical text of a JSON value — of a package, a module index and an open view — and stops with an error on a value the format cannot hold (format/README.md, section 25; R09).
Package canonical writes the canonical text of a JSON value — of a package, a module index and an open view — and stops with an error on a value the format cannot hold (format/README.md, section 25; R09).
normal
Package normal normalizes a text as the check kinds of the module format and its leak check do, and reads a number in the notation that a kind takes (format/README.md, sections 15 and 20): the steps 1 to 7 of a number and the units of step 6, the normal form of a choice, and a number in notation as an exact rational.
Package normal normalizes a text as the check kinds of the module format and its leak check do, and reads a number in the notation that a kind takes (format/README.md, sections 15 and 20): the steps 1 to 7 of a number and the units of step 6, the normal form of a choice, and a number in notation as an exact rational.
random
Package random is the generator of the format and its places of randomness, written from the constants of the format's text rather than taken from math/rand/v2, with an error on an argument outside a function's domain (format/README.md, section 22; R59 spec; R10).
Package random is the generator of the format and its places of randomness, written from the constants of the format's text rather than taken from math/rand/v2, with an error on an argument outside a function's domain (format/README.md, section 22; R59 spec; R10).
sandbox
Package sandbox runs the Starlark of the format — the predicate of a check, the expressions of a template and its solver — in go.starlark.net at the version the format names, in its one dialect, with the format's limits of steps and module-kit's clocks, on the caller's goroutine and with its context (format/README.md, sections 15, 23 and 24; R88 spec; R11; architecture 3.4).
Package sandbox runs the Starlark of the format — the predicate of a check, the expressions of a template and its solver — in go.starlark.net at the version the format names, in its one dialect, with the format's limits of steps and module-kit's clocks, on the caller's goroutine and with its context (format/README.md, sections 15, 23 and 24; R88 spec; R11; architecture 3.4).
schema
Package schema checks a value against the JSON Schema 2020-12 schemas of the format version the library reads, reporting every keyword that fails with its place (format/README.md, sections 5 and 8), and builds the open view of a value from the marks x-open in the same schemas (section 6).
Package schema checks a value against the JSON Schema 2020-12 schemas of the format version the library reads, reporting every keyword that fails with its place (format/README.md, sections 5 and 8), and builds the open view of a value from the marks x-open in the same schemas (section 6).
semver
Package semver reads a version of a module, X.Y.Z, and orders two of them by Semantic Versioning 2.0.0, as the format writes a version: three decimal numerals with no leading zero, and no pre-release and no build metadata (format/README.md, sections 26 and 27; R46 spec).
Package semver reads a version of a module, X.Y.Z, and orders two of them by Semantic Versioning 2.0.0, as the format writes a version: three decimal numerals with no leading zero, and no pre-release and no build metadata (format/README.md, sections 26 and 27; R46 spec).
vectors
Package vectors runs every example and test vector of the module format — spec.Format, at the version go.mod requires — and the vectors of the observation, observation/v1/ of contracts.Vectors, against module-kit: an implementation that does not pass them does not conform (format/README.md, sections 1, 8 and 9; contracts/README.md, section 10).
Package vectors runs every example and test vector of the module format — spec.Format, at the version go.mod requires — and the vectors of the observation, observation/v1/ of contracts.Vectors, against module-kit: an implementation that does not pass them does not conform (format/README.md, sections 1, 8 and 9; contracts/README.md, section 10).
yaml
Package yaml reads a file of a module, YAML 1.2.2 under its Core schema, into a JSON value, and refuses a file that breaks a rule yaml.*, naming the rule and its place, or that is not YAML 1.2.2 at all (format/README.md, section 4; R45 spec).
Package yaml reads a file of a module, YAML 1.2.2 under its Core schema, into a JSON value, and refuses a file that breaks a rule yaml.*, naming the rule and its place, or that is not YAML 1.2.2 at all (format/README.md, section 4; R45 spec).
Package leak finds the keys and the leak phrases of a task in a text: in the tutor's words before they reach the device, for api, and in the texts of a module that a learner sees before solving, for the check of a module, which holds task.no-leaks and lesson.no-leaks by it (format/README.md, section 20; R54 spec, R57 spec; R30).
Package leak finds the keys and the leak phrases of a task in a text: in the tutor's words before they reach the device, for api, and in the texts of a module that a learner sees before solving, for the check of a module, which holds task.no-leaks and lesson.no-leaks by it (format/README.md, section 20; R54 spec, R57 spec; R30).
Package module reads an author's module and checks it as the module format says: its layout and the version of the format it names, each file against the schema of its part, and the format rules of each part, between parts and of the whole module — the tiers of the skill graph, the templates with every instance and solver, and the leak check of the texts a learner sees before solving among them (format/README.md, sections 2 and 4–24).
Package module reads an author's module and checks it as the module format says: its layout and the version of the format it names, each file against the schema of its part, and the format rules of each part, between parts and of the whole module — the tiers of the skill graph, the templates with every instance and solver, and the leak check of the texts a learner sees before solving among them (format/README.md, sections 2 and 4–24).
Package moduleindex builds the module index of a release from the previous index, the release's packages, its tag and its withdrawals, refusing by the rules module-index.*; reads an index of any version of the format by the places every version keeps; and picks the version of a module for a new attempt: the newest by semver that is not withdrawn and lies in the format's window (format/README.md, sections 2 and 26; R63 spec; R16).
Package moduleindex builds the module index of a release from the previous index, the release's packages, its tag and its withdrawals, refusing by the rules module-index.*; reads an index of any version of the format by the places every version keeps; and picks the version of a module for a new attempt: the newest by semver that is not withdrawn and lies in the format's window (format/README.md, sections 2 and 26; R63 spec; R16).
Package modulepackage builds the package of a checked module — its canonical view, the listing of its device part and its inventory, with their digests — and reads a package as files by the chain of digests from the digest an index gives: inventory, then parts, then files (format/README.md, section 25; R62 spec).
Package modulepackage builds the package of a checked module — its canonical view, the listing of its device part and its inventory, with their digests — and reads a package as files by the chain of digests from the digest an index gives: inventory, then parts, then files (format/README.md, section 25; R62 spec).
Package moduleversion compares a new version of a module with its published ones: it finds the part of the version that the change asks for, by the table of format/README.md, section 27, and reports every change at its place (R89 spec, R101 spec; R13, R36).
Package moduleversion compares a new version of a module with its published ones: it finds the part of the version that the change asks for, by the table of format/README.md, section 27, and reports every change at its place (R89 spec, R101 spec; R13, R36).
Package observation holds what module-kit does with an observation, novatrail.observation.v1: which one is valid, how the observations of two readers join into one, answer slot by answer slot, which verdict the observation gives with the options tapped beside it, and how the submission of an essay ends (contracts/README.md, section 10; R86 spec; R29).
Package observation holds what module-kit does with an observation, novatrail.observation.v1: which one is valid, how the observations of two readers join into one, answer slot by answer slot, which verdict the observation gives with the options tapped beside it, and how the submission of an essay ends (contracts/README.md, section 10; R86 spec; R29).
Package openview builds the open view of a part of a module and of an instance of a template — what the learner's app receives: the part without its closed fields — from the marks x-open in the schemas of the format, and the digest of the open view of a task and of an instance (format/README.md, section 6; R05 spec; R93 spec).
Package openview builds the open view of a part of a module and of an instance of a template — what the learner's app receives: the part without its closed fields — from the marks x-open in the schemas of the format, and the digest of the open view of a task and of an instance (format/README.md, section 6; R05 spec; R93 spec).
Package picture reads the pictures of a module for what the format asks of them but does not refuse: a picture SHOULD have an opaque background, and module-kit warns of one with a pixel that is not fully opaque (format/README.md, section 14; the second amendment of 2026-11-01 to R51 in spec).
Package picture reads the pictures of a module for what the format asks of them but does not refuse: a picture SHOULD have an opaque background, and module-kit warns of one with a pixel that is not fully opaque (format/README.md, section 14; the second amendment of 2026-11-01 to R51 in spec).
Package template fills the templates of tasks: it counts the instances of a template, runs its solver on them, builds each one with its numbers, and picks the instance of an attempt from the attempt's seed (format/README.md, sections 22–24; R60 spec, R61 spec).
Package template fills the templates of tasks: it counts the instances of a template, runs its solver on them, builds each one with its numbers, and picks the instance of an attempt from the attempt's seed (format/README.md, sections 22–24; R60 spec, R61 spec).
Package verdict gives the verdict of an answer slot and of an item on the values read in them, by the check kinds of the module format and their normalization, with the reason of a value that cannot be read and the trap of a wrong one (format/README.md, section 15).
Package verdict gives the verdict of an answer slot and of an item on the values read in them, by the check kinds of the module format and their normalization, with the reason of a value that cannot be read and the trap of a wrong one (format/README.md, section 15).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL