IF Commons GitHub

Toolchain ontology adapter

0004Active

0004-toolchain-ontology · owner if · domain commons

Requirements

FR-001checkpassing

pinSourceFromOntology MUST give a source of pins that, for a pin and a platform the ontology states, gives the version, the address, the SHA-256, the format and the folder of its download as a Download.

Enforced (check): .github: cd commons/toolchain && bun run verify — suite/ontology.test.ts: a download for a pinned program on a platform

Proved by: toolchain/suite/ontology.test.ts

Written in: toolchain/src/physical/ontology/ontology.ts

Tests: passed: suite/ontology.test.ts a pinned program on a platform gives its version, address, SHA-256, format and folder; passed: suite/ontology.test.ts a tool that is pinned in the ontology resolves at the version of its pin

FR-002checkpassing

Where the ontology gives no download, the source MUST give the reason in the ontology's own words and naming the pin and the platform: a pin or a platform it does not state, a pin it does not pin on the platform, a platform that is unpinned with its reason, and a checksum that is not 64 lower-case hexadecimal digits.

Enforced (check): .github: cd commons/toolchain && bun run verify — suite/ontology.test.ts: the ontology's reason for an unknown, unpinned or not pinned download

Proved by: toolchain/suite/ontology.test.ts

Written in: toolchain/src/physical/ontology/ontology.ts

Tests: passed: suite/ontology.test.ts where the ontology gives no download the reason names the pin and the platform

FR-003checkpassing

Every download the source gives MUST pass defineDownload (an https address with no credentials, a SHA-256, a format and a folder inside the unpacked folder), and one that does not MUST be given as a reason and never as a download.

Enforced (check): .github: cd commons/toolchain && bun run verify — suite/ontology.test.ts: every download given is valid under defineDownload

Proved by: toolchain/suite/ontology.test.ts

Written in: toolchain/src/physical/ontology/ontology.ts

Tests: passed: suite/ontology.test.ts every download the source gives is valid under defineDownload

FR-004checkpassing

The adapter MUST hold no version, address or hash of its own: every one it gives is the ontology's, and no source of this library MUST contain one.

Enforced (check): .github: cd commons/toolchain && bun run verify — suite/ontology.test.ts: no version, address or hash in the sources

Proved by: toolchain/suite/ontology.test.ts

Written in: toolchain/src/physical/ontology/ontology.ts

Tests: passed: suite/ontology.test.ts no source of this library holds a version, an address or a hash of a pin

Acceptance scenarios

  1. Given the pin bun and the platform linux-x64, When the source is asked, Then it gives a download with an https address, a SHA-256, a format and a folder, per FR-001.
  2. Given a pin the ontology does not state, When the source is asked, Then it gives a reason that names the pin, per FR-002.
  3. Given a pin that is unpinned on a platform, When the source is asked, Then it gives a reason that names the pin and the platform and says why, per FR-002.
  4. Given the tool bun with a pin binding and the dialect of downloads, When it is resolved with this source, Then it is resolved at the version of the ontology's pin, per FR-001.

Out of scope

  • Writing or reviewing a pin: the ontology and its owner; this adapter only reads.
  • Fetching what an address gives: the dialect of downloads.

Edge cases

  • A pin that is pinned on some platforms only: the source gives a download for those and a reason for the others, per FR-002.
  • A platform name the ontology does not state: a reason, per FR-002.

Assumptions

  • The ontology's own check (its generator) holds a pin well formed; this adapter checks the form again, because it is the last place before a download is made.

Open questions

  • None.

Key entities

  • Adapter - the Physical unit that makes a source of pins from the ontology.

Success criteria

SC-001success criterion

A version and a hash are read from the ontology each time and are written nowhere in this library.

SC-002success criterion

A tool that is pinned in the ontology resolves without a line of this library naming its version.

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

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