IF Commons GitHub

Rules

0004Draft

0004-rules · owner if · domain commons

The rules

FR-001checkpassing

A rule MUST be a pm:Rule in the ontology (commons/ontology/supply-chain/packaging/rules.ts, amended 2026-11-16: it was Turtle) with a set, a pattern (an ECMAScript regular expression), a short name and the reason it is not allowed. The sets are shell-portability (a construct only GNU tools have), ci-forbidden-program (a program a CI step must not run), ci-forbidden-action (a CI construct that installs or containerizes), host-program (a program a command must take from its toolchain, never from the host) and installer (a package manager code must not call directly).

Enforced (check): .github: bun test ./tests/ — Rules: the set, the generator's refusals, the portability tool and its use on the installer script

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Rules: every rule is in a set, with a pattern, a name and a reason

Cited by: supply-chain/packaging/packaging

FR-002checkpassing

The generator MUST write every rule to commons/generated/rules.auto.toml (schema = 1, the hash of the ontology, one [[rules]] table each), and MUST refuse, naming it, a rule with no set from the list, no pattern, name or reason, a pattern that is not a regular expression and a name used twice.

Enforced (check): .github: bun test ./tests/ — Rules: the set, the generator's refusals, the portability tool and its use on the installer script

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Rules: every rule is in a set, with a pattern, a name and a reason; passed: tests/commons-packaging.test.ts Record: a bad rule or field is refused

Cited by: The ontology in TypeScript

FR-003checkpassing

commons/tools/shell-portability-check.ts MUST report every line of the shell scripts it is given that matches a shell-portability rule, as file:line: uses X (reason), skipping comment lines and trailing comments and a line that holds text the caller excuses, and MUST exit 1 where it reports one. It runs on Bun or Node 26 and needs only the TOML reader of the library formats (@intellectual-frontiers/formats/toml) (amended 2026-11-15: it was Python, with its standard library alone).

Enforced (check): .github: bun test ./tests/ — Rules: the set, the generator's refusals, the portability tool and its use on the installer script

Proved by: tests/commons-packaging.test.ts

Tests: passed: tests/commons-packaging.test.ts Rules: the portability tool needs the kernel's TOML reader and the tools' core alone; passed: tests/commons-packaging.test.ts Rules: the portability tool reports a GNU-only line and skips comments and excused lines

FR-004checkno test run

A harness MUST take these sets from the generated file and MUST NOT keep its own copy of a pattern; what a harness adds (where the rules apply, which of its own paths are excused) is its own.

Enforced (check): .github: bun test ./tests/ — Rules: the set, the generator's refusals, the portability tool and its use on the installer script

Out of scope

  • Where a harness applies a rule: its paths, and the requirement that excuses an exception, are the harness's.

Edge cases

  • A script that names sed -i in a trailing comment to say it avoids it: it is not reported, per FR-003.
  • A line that picks shasum or sha256sum by what the computer has: the caller excuses it by the text it holds, per FR-003.
  • A pattern with a typo: the generator names the rule and writes nothing, per FR-002.
  • A rule whose set is spelled wrongly: the generator names it, per FR-002.

Assumptions

  • A pattern is an ECMAScript regular expression (JavaScript's RegExp, with no flags), which every harness of the company runs, their tools being TypeScript (amended 2026-11-15: it was Python's syntax; every rule kept is written alike in both).

Open questions

OQ-1open question

Whether the rules for a second language (the Rust crate, JavaScript) join these sets or form their own.

Key entities

  • Rule - a pattern, a set and a reason (pm:Rule).

Success criteria

SC-001success criterion

bin/agora-install.sh has no line the tool reports.

SC-002success criterion

A harness's toolchain checks read these sets and keep no pattern of their own.

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

Ontology, supply-chain/packaging/mod, supply-chain/packaging/packaging, supply-chain/packaging/rules, The harness of Mizan, The ontology in TypeScript

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