IF Commons GitHub

What a consumer uses of the package

0014Active

0014-repoctl-usage · owner if · domain repoctl

What is read

FR-001checkno test run

repoctl usage MUST read the specifiers of the form @intellectual-frontiers/commons/<library>[/<subpath>] in the code files of the repository it is run on (.ts, .tsx, .mts, .js, .mjs, .cjs, .json5, leaving out node_modules, .git and build), and MUST give for each library the subpaths imported and the number of files that import it; a specifier that names no library of the package (a bare @intellectual-frontiers/commons) MUST be left out.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/usage.test.ts

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

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

FR-002checkno test run

It MUST read the libraries of the installed package from its sources (<package>/<library>/src/**/*.ts and what else a library carries beside them), the package being node_modules/@intellectual-frontiers/commons of the repository or the folder --package names, and MUST derive from them the imports of each library of another library of the package, the files of each and its size in bytes; a repository where the package is not installed MUST end with an environment problem that says where it looked and how to name the folder.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/usage.test.ts

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

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

What is answered

FR-003checkno test run

The answer MUST be pure data of the two inputs (the imports of the consumer and the graph of the package) and MUST list: the libraries the repository imports directly with their subpaths; the libraries it reaches only through the imports of those (each with the library through which it is reached first); the libraries it never touches; and, for the package and for each of the three groups, the number of libraries and the bytes.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/usage.test.ts

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

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

FR-004checkno test run

The answer MUST be the same for the same inputs, in the order of the names of the libraries, and MUST be given as a table and, with --json, as one JSON document; a library the repository imports that the package does not hold MUST be a finding (E-USAGE-UNKNOWN) and MUST NOT be counted.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/usage.test.ts

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

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

FR-005checkno test run

repoctl usage MUST be a verb of the public tier that only reads: it changes no file, and it ends with 0 where it answered.

Enforced (check): .github: cd commons/repoctl && bun run verify — suite/usage.test.ts

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

Written in: repoctl/src/physical/verbs/usage.ts

Out of scope

  • What a consumer uses of a library below its subpath (a function, a type), the size of what an installed package adds of its dependencies, and any consumer repository other than the one it is run on.

Edge cases

  • A library the repository imports by a subpath the library does not export: counted as imported, the subpath is listed as written, per FR-001.
  • A library reached by two paths: the library through which it is first reached, in the order of the names, is the one named, per FR-003.
  • A file that is not text: it counts its bytes and imports nothing, per FR-002.

Assumptions

Open questions

  • None.

Key entities

  • Consumer import: a library of the package and a subpath, and the file that imports it.
  • Graph: each library of the package with the libraries its sources import, its files and its bytes.

Success criteria

  • Run on erga with the package installed, it reproduces the analysis made by hand: the libraries imported directly, those reached through them and those never touched, with their bytes.

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/usage, physical/verbs/usage, Distribution

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