IF Commons GitHub

Repoctl sync, merge and check

0003Active

0003-repoctl-sync · owner if · domain commons

Requirements

FR-001checkpassing

sync MUST run the generators in an order where each comes after every generator that writes something it reads, as the globs of the table say, the order of the table standing where they do not order two; a table whose generators wait for one another MUST be refused with the ones that do.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/sync.test.ts: the order puts a reader after its writer and refuses generators that wait for each other

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

Written in: repoctl/src/logical/glob.ts, repoctl/src/logical/order.ts

Tests: passed: suite/sync.test.ts a glob matches a path by segments, and two globs overlap where one path could match both; passed: suite/sync.test.ts the order puts a reader after its writer, keeps the table's order where the globs do not o

Cited by: Repoctl, logical/glob, logical/order

FR-002checkpassing

sync MUST ask each generator's own check first and run the generator only where its check ends with 1, then check it again; a generator whose check ends with another status, or that is still not as it makes after it ran, MUST be reported as a failure of that generator (E-GENERATOR-FAILED) and the others MUST still be tried.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/sync.test.ts: only a stale generator is run, it is checked again, and a failure of one does not stop the others

Proved by: repoctl/suite/prove-select.test.ts, repoctl/suite/sync.test.ts

Written in: repoctl/src/logical/step.ts, repoctl/src/logical/sync.ts, repoctl/src/physical/verbs/sync.ts

Tests: passed: suite/sync.test.ts over real generators only the stale one is run and checked again, --check writes nothing a; passed: suite/sync.test.ts a generator that cannot be made is a failure of that generator and the others are still tr; passed: suite/sync.test.ts a generator's status is read as it ends: 0 fresh, 1 stale, anything else failed

Cited by: Repoctl, logical/step, logical/sync, physical/verbs/sync

FR-003checkpassing

sync --check MUST write nothing and MUST end with the status 1 where any generator is stale, naming each stale generator (E-STALE-GENERATED) with the command that makes its files, and MUST end with 0 where none is; --dry-run MUST say which generators would be run and end with 0.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/sync.test.ts: --check writes nothing and names the stale generator with its command; the real repository passes

Proved by: repoctl/suite/prove-select.test.ts, repoctl/suite/sync.test.ts

Tests: passed: suite/sync.test.ts over real generators only the stale one is run and checked again, --check writes nothing a; passed: suite/sync.test.ts the real repository is in step: sync --check ends with 0, --dry-run says what it would do,

FR-004checkpassing

sync MUST give the same bytes for the same sources: running it a second time MUST change no file, and --only MUST run only the generators it names and MUST refuse an id that is not one.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/sync.test.ts: a second run changes no file, and --only runs only what it names

Proved by: repoctl/suite/prove-select.test.ts, repoctl/suite/sync.test.ts

Tests: passed: suite/sync.test.ts over real generators only the stale one is run and checked again, --check writes nothing a; passed: suite/sync.test.ts the real repository is in step: sync --check ends with 0, --dry-run says what it would do,

Cited by: Repoctl, logical/sync

FR-005checkpassing

merge <ref> MUST run Git's merge; where files conflict, it MUST make the conflicting generated files again by their generators (taking one side to clear the markers, running sync and staging what then is as its generator makes it) and MUST NOT resolve a generated file by hand, and MUST report every conflict in a file that no generator writes (E-MERGE-CONFLICT), leaving that file as Git left it; a generated file that also holds text a person wrote (the table of the README, the register of the libraries) MUST keep the lines of both sides where they conflict before its generated part is made again, and merge MUST say so.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/merge.test.ts: in a real repository a conflict in a generated file is made again, one in a file that holds written text keeps the lines of both sides, and a conflict in a written file is left as Git left it

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

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

Tests: passed: suite/merge.test.ts a conflict in a file a person wrote is named and left as Git left it, and the merge is not; passed: suite/merge.test.ts a generated file that conflicts is made again, staged and committed as the identity, with ; passed: suite/merge.test.ts a generated file that a person also writes keeps the lines of both sides and has its gener; passed: suite/merge.test.ts the conflicted paths are split into the ones a generator writes and the ones a person wrot

Cited by: Repoctl, logical/merge

FR-006checkpassing

merge MUST make the merge commit only where no conflict is left, MUST end with the status 1 where any is, and where Git merges with no conflict MUST report the generated files that are stale (E-STALE-GENERATED) and write nothing; a merge that Git refuses for another reason MUST be reported as E-MERGE-FAILED with Git's words.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/merge.test.ts: the merge commit is made only where no conflict is left, and a refusal of Git is E-MERGE-FAILED

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

Tests: passed: suite/merge.test.ts a conflict in a file a person wrote is named and left as Git left it, and the merge is not; passed: suite/merge.test.ts a generated file that conflicts is made again, staged and committed as the identity, with ; passed: suite/merge.test.ts a clean merge reports the generated files that are stale, and a refusal of Git is E-MERGE-

Cited by: Repoctl, logical/merge, physical/verbs/sync

FR-007checkpassing

check MUST run the check of every generator, the format check of the specification kit of commons, the rules of Mizan, the versions, the format check and the rules of the specification kit of each library at its level, and the check of the constants that say a version, MUST write nothing, and MUST give one report in which each finding has a code of ProblemCode and the command that fixes it, ending with 1 where any finding fails and 0 where none does.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/check.test.ts: one report with a code and a fix for each finding, the real repository passes, nothing is written

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

Written in: repoctl/src/logical/check.ts, repoctl/src/logical/pool.ts, repoctl/src/physical/verbs/check.ts

Tests: passed: suite/check.test.ts one report over the real repository writes nothing, ends with 0 and has a section for ever; passed: suite/check.test.ts a check program's end is findings: none for 0, a finding for each line it said for 1 (with

Cited by: Repoctl, logical/check, logical/pool, physical/verbs/check

FR-008checkpassing

check MUST find every constant of the sources of a library that is named <LIBRARY>_VERSION (the library's name in capitals, a hyphen as an underscore) or named by the manifest in versionConstants, whose text is not the version of the library (E-VERSION-CONSTANT), and MUST find a constant the manifest names that is not in its file.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/check.test.ts: a constant that disagrees with its library's version is found, and so is one the manifest names that is missing

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

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

Tests: passed: suite/check.test.ts one report over the real repository writes nothing, ends with 0 and has a section for ever; passed: suite/check.test.ts a constant named for its library or by its manifest that disagrees with the library's vers

Cited by: Repoctl, logical/check, logical/constants

FR-009checkpassing

explain <code> MUST say, for every code of the program, its title, what happened, the likely cause and the fix, and for a text that is no code MUST say so and name the nearest.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/check.test.ts: every code is explained and a text that is no code names the nearest

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

Tests: passed: suite/check.test.ts every code is explained, and a text that is no code names the nearest

Cited by: Repoctl, physical/verbs/check

FR-010checkpassing

Where the configuration's libraries.declaredDependencies is on, check MUST find every package that a TypeScript file of a library's src/, suite/, tools/ or its about.ts imports by name, and every node: import (which needs @types/node), that the library's package.json declares in none of dependencies, devDependencies, peerDependencies and optionalDependencies (E-UNDECLARED-DEPENDENCY), naming the file, the line and the line to add; the package of the library itself, relative and bun: imports and imports inside a block comment are not findings. A library job installs only its own folder, so what its checkout finds by the install of the whole repository is missing there.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/declared.test.ts: a package or a node: import that the manifest does not declare is found with its file and line; the library itself, relative and bun: imports and block comments are not; the real repository declares every import

Proved by: repoctl/suite/check.test.ts, repoctl/suite/declared.test.ts

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

Tests: passed: suite/check.test.ts one report over the real repository writes nothing, ends with 0 and has a section for ever; passed: suite/declared.test.ts a package or a node: import that the manifest does not declare is found with its file and

Cited by: Repoctl, logical/declared

Acceptance scenarios

  1. Given a table in which a generator reads what another writes, When it is ordered, Then the reader comes after the writer, per FR-001.
  2. Given a table in which two generators read what the other writes, When it is ordered, Then it is refused naming both, per FR-001.
  3. Given a generator whose check ends with 1 and whose run makes it end with 0, When sync runs, Then it is made once and reported as made, and a fresh generator is not run, per FR-002.
  4. Given a generator that still ends with 1 after it ran, When sync runs, Then it is a failure of that generator and the next generator is still tried, per FR-002.
  5. Given a stale generator, When sync --check runs, Then nothing is written, the status is 1 and the generator and its command are named, per FR-003.
  6. Given the real repository, When sync --check runs, Then it ends with 0, per FR-003 and FR-004.
  7. Given two branches that changed the README table and a manifest differently, When merge runs, Then the README is made again and staged, the merge is committed, and no marker is left, per FR-005 and FR-006.
  8. Given two branches that each wrote a line of the README and changed the sources of its table, When merge runs, Then both lines are in the README and its table is made again, per FR-005.
  9. Given two branches that changed one line of a source differently, When merge runs, Then the file is named and left with Git's markers, the merge is not committed and the status is 1, per FR-005 and FR-006.
  10. Given a library whose version is 0.4.7 and a constant that says 0.4.6, When check runs, Then the constant is a finding with the file and the line, per FR-008.
  11. Given explain E-STALE-GENERATED, When it runs, Then it says the title, the cause and repoctl sync, per FR-009.
  12. Given a library whose test imports node:fs and whose manifest has no @types/node, When check runs, Then E-UNDECLARED-DEPENDENCY names the file, the line and the devDependency to add, per FR-010.

Out of scope

  • The logic of each generator: the generators' own specifications.
  • The check of the tests and the types of each library: bun run dev:check and each library's verify.

Edge cases

  • A generator that is not installed or whose source is broken ends with a status that is neither 0 nor 1: it is a failure of the generator, per FR-002.
  • A generated file that conflicts while the source of its generator also conflicts: its generator cannot make it, so it stays unresolved (E-REGENERATE-FAILED), per FR-005.
  • A repository with no origin/main: the check of the versions cannot run and is a warning, not a failure, per FR-007.

Assumptions

  • The libraries of commons that Repoctl calls (libraries, the tools of commons) are on the branch that holds it, and git, bun and node are installed.

Open questions

  • None.

Key entities

  • Generator - a program that makes files from sources and checks them.
  • Section - one check of check and what it found.

Success criteria

SC-001success criterion

After sync, sync --check ends with 0, and after a merge of generated files nothing is hand-edited.

SC-002success criterion

A version constant left behind by a release is found before the push.

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

Repoctl, logical/check, logical/constants, logical/declared, logical/glob, logical/merge, logical/mod, logical/order, logical/pool, logical/step, logical/sync, physical/verbs/check, physical/verbs/sync

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