IF Commons GitHub

Repoctl hygiene

0007Active

0007-repoctl-hygiene · owner if · domain commons

Requirements

FR-001checkpassing

The program MUST have the verb hygiene, declared once in the table of verbs as a report of the public tier that only reads and is safe to repeat, with an example of the command and one of --json; the codes E-HYGIENE-GIT, E-HYGIENE-PATH, E-HYGIENE-IMPORT, E-HYGIENE-VENDORED, E-HYGIENE-DUPLICATE and E-HYGIENE-RANGE MUST each be in the closed union of problem codes with an explanation (repoctl explain <code>).

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/hygiene.test.ts: the verb is declared once with its facts and its examples and each code has an explanation

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts the verb is declared once, public and read-only, with its examples, and each code has an e

FR-002checkpassing

The Logical layer MUST give hygiene, a pure function from the facts of a repository (its package.json files, lockfiles, installed copies, relative imports and workspaces, and whether it is the repository of commons) to its findings, each with a level, a code, a path, a message and a fix, in the order of the codes and then of the paths: a dependency by Git on intellectual-frontiers/.github (E-HYGIENE-GIT), a file: or link: dependency into a path with a segment commons that has something after it (E-HYGIENE-PATH), a relative import into such a path (E-HYGIENE-IMPORT), a package of the scope @intellectual-frontiers/ in a folder that is not the root package or a declared workspace (E-HYGIENE-VENDORED), one package of the scope installed at two versions (E-HYGIENE-DUPLICATE) and, as a warning, a dependency of the scope that is not an exact version (E-HYGIENE-RANGE); in the repository of commons the path, import and vendored findings MUST NOT be made.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/hygiene.test.ts: each of the six findings is made from facts, in the order of the codes, and the repository of commons is not reported for its own packages

Proved by: repoctl/suite/hygiene.test.ts

Written in: repoctl/src/logical/hygiene.ts

Tests: passed: suite/hygiene.test.ts each of the six findings is made from facts, in the order of the codes; passed: suite/hygiene.test.ts in the repository of commons the path, import and vendored findings are not made and the o

Cited by: Repoctl, logical/hygiene

FR-003checkpassing

The Logical layer MUST gather the facts only through its ports: it MUST read bun.lock (JSON with comments and trailing commas) and package-lock.json (lockfile versions 2 and 3) as data, the package.json files outside node_modules, the packages installed under node_modules (nested ones and Bun's .bun store included) and the relative imports of the sources; a lockfile that cannot be read MUST be a failing finding of E-ENVIRONMENT and a package.json that declares dependencies with no lockfile MUST be a warning of it (FR-006), never a silent pass.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/hygiene.test.ts: bun.lock and package-lock.json give the same copies, the installed tree is read through the port and a lockfile that cannot be read is a finding

Proved by: repoctl/suite/hygiene.test.ts

Written in: repoctl/src/logical/hygiene-facts.ts

Tests: passed: suite/hygiene.test.ts on a folder: the facts are gathered through the ports, the real command ends in 1 with the; passed: suite/hygiene.test.ts bun.lock and package-lock.json give the same duplicate, comments and trailing commas are r; passed: suite/hygiene.test.ts a repository with no root package.json is judged folder by folder: the lockfile next to ea

Cited by: Repoctl, logical/hygiene-facts, logical/hygiene

FR-004checkpassing

The run MUST end with 0 where no finding fails and with 1 where one does, a warning alone MUST NOT fail it, and --json MUST be one document with the repository's kind, the counts and the findings with their code, level, path, message and fix.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/hygiene.test.ts: the exit status is 1 only for a failure and --json is one document

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts on a folder: the facts are gathered through the ports, the real command ends in 1 with the

FR-005checkpassing

repoctl status MUST read the package a library publishes (its manifest's publishes, else @intellectual-frontiers/<name>) from the registry of npm (commons 0036-distribution FR-009).

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/hygiene.test.ts: status asks npm for the package a library publishes

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts status asks npm for the package a library publishes

FR-006checkpassing

The Logical layer MUST treat every folder that holds a package.json (the root, and nested folders at any depth, never one under node_modules, dist, .git, coverage, .cache, .turbo or .next) as an install of its own: WHEN it gathers the facts it MUST read the bun.lock and package-lock.json next to that package.json and the node_modules of that folder, so that a repository with no root package.json is judged by the lockfiles beside its packages; the duplicate rule (E-HYGIENE-DUPLICATE) MUST be applied to each folder's lockfiles and installed copies separately, never across folders; and IF a package.json declares dependencies in any section and no lockfile is next to it (a lockfile in a folder above it covers it, as the lockfile of a root covers its workspaces), THEN the check MUST warn with E-ENVIRONMENT at that package.json, naming its folder, while a package.json that declares no dependencies MUST NOT be warned about.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/hygiene.test.ts: a repository with no root package.json is judged folder by folder: the lockfile and node_modules next to each package.json are read, two folders are never one install, and a folder with dependencies and no lockfile is named

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts a repository with no root package.json is judged folder by folder: the lockfile next to ea

Acceptance scenarios

  1. Given a repository with a Git dependency on the repository of commons, When hygiene runs, Then it ends with 1 and E-HYGIENE-GIT at the path of the package.json, per FR-002.
  2. Given a link: dependency into ../commons/core, a folder vendor/core with a package named @intellectual-frontiers/core, an import of ../commons/core/src/mod.ts and two versions of one package in a lockfile, When it runs, Then each of the four findings is made at its path, per FR-002.
  3. Given the same two copies in bun.lock and in package-lock.json, When each is read, Then the same duplicate is found, per FR-003.
  4. Given only a range on a package of the scope, When it runs, Then one warning and the status 0, per FR-004.
  5. Given the repository of commons, When it runs, Then its own packages are not findings, per FR-002.
  6. Given a library whose manifest publishes @intellectual-frontiers/arcactl, When status asks npm, Then it asks for that package, per FR-005.
  1. Given no root package.json and three folders each with a package.json and a lockfile of its own, When it runs, Then there is no finding, and a fourth folder with dependencies and no lockfile is one warning that names it, per FR-006.

Out of scope

  • The repair of a finding: each finding says the command, and the program does not edit a package.json.
  • The names of the libraries of commons: the check reads a path, not a registry.

Edge cases

  • A folder named commons that is not ours: the path and the import are findings only where something follows the segment, and the message says what was found, per FR-002.
  • One version of a package under two paths: one copy, no finding, per FR-002.
  • A package.json that is not JSON: left out of the facts, per FR-003.
  • Two folders that install two versions of one package: two installs, not a duplicate, per FR-006.

Assumptions

  • A repository that consumes commons keeps its own packages at its root or in the workspaces its root declares.

Open questions

  • None.

Key entities

  • Facts of a repository - its manifests, lockfiles, installed copies, imports and workspaces.
  • Finding - level, code, path, message and fix.

Success criteria

SC-001success criterion

A repository in order has no finding, and each way of breaking the rule has one.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT)
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Repoctl, logical/hygiene-facts, logical/hygiene, Build policy, findings and never failures

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