@intellectual-frontiers/repoctl 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +75 -0
- package/README.md +19 -2
- package/dist/governance/checks.d.ts +23 -0
- package/dist/governance/config.d.ts +233 -0
- package/dist/governance/generators.d.ts +54 -0
- package/dist/governance/identity.d.ts +23 -0
- package/dist/governance/ids.d.ts +46 -0
- package/dist/governance/mod.d.ts +25 -0
- package/dist/governance/mod.js +1063 -0
- package/dist/governance/problems.d.ts +28 -0
- package/dist/governance/proof.d.ts +108 -0
- package/dist/governance/tiers.d.ts +25 -0
- package/dist/governance/verbs.d.ts +43 -0
- package/dist/governance/version.d.ts +14 -0
- package/dist/logical/check.d.ts +33 -0
- package/dist/logical/commit.d.ts +64 -0
- package/dist/logical/constants.d.ts +27 -0
- package/dist/logical/declared.d.ts +32 -0
- package/dist/logical/docs.d.ts +31 -0
- package/dist/logical/doctor.d.ts +42 -0
- package/dist/logical/findings.d.ts +26 -0
- package/dist/logical/glob.d.ts +17 -0
- package/dist/logical/hygiene-facts.d.ts +33 -0
- package/dist/logical/hygiene.d.ts +68 -0
- package/dist/logical/merge.d.ts +46 -0
- package/dist/logical/mod.d.ts +36 -0
- package/dist/logical/mod.js +2553 -0
- package/dist/logical/order.d.ts +24 -0
- package/dist/logical/pool.d.ts +14 -0
- package/dist/logical/ports.d.ts +96 -0
- package/dist/logical/prove.d.ts +118 -0
- package/dist/logical/publish.d.ts +70 -0
- package/dist/logical/scaffold.d.ts +52 -0
- package/dist/logical/select.d.ts +83 -0
- package/dist/logical/semver.d.ts +16 -0
- package/dist/logical/status.d.ts +71 -0
- package/dist/logical/step.d.ts +18 -0
- package/dist/logical/surface.d.ts +73 -0
- package/dist/logical/sync.d.ts +34 -0
- package/dist/mod.d.ts +20 -0
- package/dist/mod.js +12992 -0
- package/dist/physical/adapters.d.ts +25 -0
- package/dist/physical/config-load.d.ts +30 -0
- package/dist/physical/define.d.ts +73 -0
- package/dist/physical/mod.d.ts +26 -0
- package/dist/physical/mod.js +12660 -0
- package/dist/physical/program.d.ts +14 -0
- package/dist/physical/prove-run.d.ts +50 -0
- package/dist/physical/prove.d.ts +76 -0
- package/dist/physical/tests.d.ts +54 -0
- package/dist/physical/verbs/check.d.ts +26 -0
- package/dist/physical/verbs/docs.d.ts +6 -0
- package/dist/physical/verbs/library.d.ts +4 -0
- package/dist/physical/verbs/prove.d.ts +5 -0
- package/dist/physical/verbs/releasing.d.ts +27 -0
- package/dist/physical/verbs/sync.d.ts +12 -0
- package/dist/repoctl.d.ts +16 -0
- package/package.json +70 -4
- package/repoctl.mjs +12693 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The problem codes of Repoctl and what each means (commons repoctl 0002-repoctl-governance FR-004; commons headless 0003-headless-output FR-008): every problem a run can raise is one of a closed union of codes, and each code has an
|
|
3
|
+
* explanation (a title, what happened, the likely cause and the fix) that `repoctl explain <code>` prints and the documentation renders. The registry holds one entry for every code, which the compiler checks.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { CATALOGUE, isProblemCode } from "./problems.js";
|
|
8
|
+
* isProblemCode("E-STALE-GENERATED"); // true
|
|
9
|
+
* CATALOGUE["E-STALE-GENERATED"].fix; // "repoctl sync"
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
/** What `repoctl explain` says of a code: the shape of Headless' explanation, held here so that the governance imports no more than it needs. */
|
|
15
|
+
export type Explained = {
|
|
16
|
+
readonly title: string;
|
|
17
|
+
readonly what: string;
|
|
18
|
+
readonly why: string;
|
|
19
|
+
readonly fix: string;
|
|
20
|
+
};
|
|
21
|
+
/** The code of every problem: a closed union. */
|
|
22
|
+
export type ProblemCode = "E-USAGE" | "E-ENVIRONMENT" | "E-STALE-GENERATED" | "E-GENERATOR-FAILED" | "E-SPEC-KIT" | "E-MIZAN-RULE" | "E-VERSIONS" | "E-TYPES" | "E-VERSION-CONSTANT" | "E-UNDECLARED-DEPENDENCY" | "E-LIBRARY-CHECK" | "E-MERGE-FAILED" | "E-MERGE-CONFLICT" | "E-REGENERATE-FAILED" | "E-NPM-UNREACHABLE" | "E-RELEASE-RECORD" | "E-RELEASE-FAILED" | "E-PUBLISH-REFUSED" | "E-NO-TOKEN" | "E-NO-TARBALL" | "E-PUBLISH-FAILED" | "E-COMMIT-SUBJECT" | "E-COMMIT-REFS" | "E-COMMIT-SESSION" | "E-COMMIT-FORBIDDEN" | "E-COMMIT-NOTHING" | "E-COMMIT-FAILED" | "E-LIBRARY-NAME" | "E-LIBRARY-RESERVED" | "E-LIBRARY-EXISTS" | "E-DOCTOR-INSTALL" | "E-DOCTOR-LINKS" | "E-DOCTOR-NODE" | "E-DOCTOR-BUN" | "E-DOCTOR-GIT" | "E-HYGIENE-GIT" | "E-HYGIENE-PATH" | "E-HYGIENE-IMPORT" | "E-HYGIENE-VENDORED" | "E-HYGIENE-DUPLICATE" | "E-HYGIENE-RANGE" | "E-PROVE-FAILED" | "E-PROVE-QUARANTINE" | "E-CHECK-FAILED" | "E-CONFIG-MISSING" | "E-CONFIG-LOAD" | "E-CONFIG-INVALID" | "E-DOCS-GENERATOR-MISSING" | "E-DOCS-FAILED";
|
|
23
|
+
/** Every code, in the order the explanations are listed. */
|
|
24
|
+
export declare const PROBLEM_CODES: readonly ProblemCode[];
|
|
25
|
+
/** Whether a text is one of the codes. */
|
|
26
|
+
export declare function isProblemCode(text: string): text is ProblemCode;
|
|
27
|
+
/** The explanation of every code: a registry the compiler holds complete. */
|
|
28
|
+
export declare const CATALOGUE: Readonly<Record<ProblemCode, Explained>>;
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The facts of proof proportional to blast radius (commons repoctl 0008-repoctl-prove FR-002 to FR-005, FR-009): the seven tiers of proof with their budgets, the change classes with the proofs each one needs, the proofs
|
|
3
|
+
* as a closed union (each belongs to exactly one tier by an exhaustive function), the reasons a proof is left out, the foundation libraries and the files whose change is every proof's change. The planner of the Logical layer
|
|
4
|
+
* reads these tables and decides nothing of its own that is not here.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { CLASS_RULES, tierOfProof } from "./proof.js";
|
|
9
|
+
* CLASS_RULES.prose.tiers; // ["T0"]
|
|
10
|
+
* tierOfProof({ kind: "sync-check" }); // "T0"
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
16
|
+
import type { LibraryName } from "./ids.js";
|
|
17
|
+
/** The seven tiers of proof, cheapest first: a closed union. */
|
|
18
|
+
export type ProofTier = "T0" | "T1" | "T2" | "T3" | "T4" | "T5" | "T6";
|
|
19
|
+
/** Every tier of proof, cheapest first. */
|
|
20
|
+
export declare const PROOF_TIER_IDS: readonly ProofTier[];
|
|
21
|
+
/** When a tier runs. */
|
|
22
|
+
export type Occasion = "edit" | "push" | "main" | "nightly" | "release";
|
|
23
|
+
/** What a tier is: its name, what it proves, its budget in seconds and the occasions it runs on. */
|
|
24
|
+
export type TierFacts = {
|
|
25
|
+
readonly id: ProofTier;
|
|
26
|
+
readonly name: string;
|
|
27
|
+
readonly proves: string;
|
|
28
|
+
readonly budgetSeconds: number;
|
|
29
|
+
readonly runsOn: readonly Occasion[];
|
|
30
|
+
};
|
|
31
|
+
/** The tiers of proof by their words. */
|
|
32
|
+
export declare const PROOF_TIERS: Readonly<Record<ProofTier, TierFacts>>;
|
|
33
|
+
/** A tier from `3` or `T3`, or why the text is none. */
|
|
34
|
+
export declare function parseProofTier(text: string): Result<ProofTier, string>;
|
|
35
|
+
/** What a changed file is: a closed union. */
|
|
36
|
+
export type ChangeClass = "prose" | "spec" | "spec-requirements" | "generated" | "version" | "test" | "source" | "packaging" | "planner" | "outside";
|
|
37
|
+
/** Every class, in the order the table and the plan list them. */
|
|
38
|
+
export declare const CHANGE_CLASSES: readonly ChangeClass[];
|
|
39
|
+
/** What a class is and what it needs: one row for each class. */
|
|
40
|
+
export type ClassRule = {
|
|
41
|
+
readonly class: ChangeClass;
|
|
42
|
+
readonly means: string;
|
|
43
|
+
readonly proofs: string;
|
|
44
|
+
readonly tiers: readonly ProofTier[];
|
|
45
|
+
};
|
|
46
|
+
/** The class rules: the one table the planner, the documentation and the tests read. */
|
|
47
|
+
export declare const CLASS_RULES: Readonly<Record<ChangeClass, ClassRule>>;
|
|
48
|
+
/** What a scope of the specification check is: one library's kit or the repository's. */
|
|
49
|
+
export type SpecScope = LibraryName | "repository";
|
|
50
|
+
/** A proof: one check or run, for a library where it has one. A closed union, so that every proof has its tier, its command and its sentence by an exhaustive match. */
|
|
51
|
+
export type Proof = {
|
|
52
|
+
readonly kind: "docs-check";
|
|
53
|
+
} | {
|
|
54
|
+
readonly kind: "spec-check";
|
|
55
|
+
readonly scope: SpecScope;
|
|
56
|
+
} | {
|
|
57
|
+
readonly kind: "trace-check";
|
|
58
|
+
readonly library: LibraryName;
|
|
59
|
+
} | {
|
|
60
|
+
readonly kind: "types";
|
|
61
|
+
readonly library: LibraryName;
|
|
62
|
+
} | {
|
|
63
|
+
readonly kind: "sync-check";
|
|
64
|
+
} | {
|
|
65
|
+
readonly kind: "versions-check";
|
|
66
|
+
} | {
|
|
67
|
+
readonly kind: "suite";
|
|
68
|
+
readonly library: LibraryName;
|
|
69
|
+
} | {
|
|
70
|
+
readonly kind: "smoke";
|
|
71
|
+
readonly library: LibraryName;
|
|
72
|
+
} | {
|
|
73
|
+
readonly kind: "seam";
|
|
74
|
+
readonly provider: LibraryName;
|
|
75
|
+
readonly consumer: LibraryName;
|
|
76
|
+
} | {
|
|
77
|
+
readonly kind: "pack";
|
|
78
|
+
readonly library: LibraryName;
|
|
79
|
+
} | {
|
|
80
|
+
readonly kind: "end-to-end";
|
|
81
|
+
} | {
|
|
82
|
+
readonly kind: "platform";
|
|
83
|
+
readonly library: LibraryName;
|
|
84
|
+
readonly system: "windows" | "macos";
|
|
85
|
+
} | {
|
|
86
|
+
readonly kind: "release-gate";
|
|
87
|
+
};
|
|
88
|
+
/** The tier a proof belongs to: every proof is in exactly one. */
|
|
89
|
+
export declare function tierOfProof(p: Proof): ProofTier;
|
|
90
|
+
/** The proof as one stable key: the same proof has the same key, so a plan holds each once. */
|
|
91
|
+
export declare function proofKey(p: Proof): string;
|
|
92
|
+
/** Why a proof is left out: a closed union, each with one sentence in the plan. */
|
|
93
|
+
export type SkipReason = "class-needs-none" | "surface-unchanged" | "symbols-unused" | "tests-unaffected" | "cache-hit" | "tier-scheduled" | "quarantined";
|
|
94
|
+
/** Every reason, in the order of the documentation. */
|
|
95
|
+
export declare const SKIP_REASONS: readonly SkipReason[];
|
|
96
|
+
/** The foundation libraries: what the rest of commons stands on, so a change of their behaviour runs a smoke gate before anything wider. */
|
|
97
|
+
export declare const FOUNDATION: readonly string[];
|
|
98
|
+
/** The paths whose change is the change of every proof: the planner, the generators, the workflow definitions and the tier rules (globs; `*` is one segment, `**` any number). */
|
|
99
|
+
export declare const PLANNER_GLOBS: readonly string[];
|
|
100
|
+
/** A quarantined test: named by its path from the repository's root, with the person who owns getting it fixed, the day it must be fixed by (it runs again after) and why. */
|
|
101
|
+
export type QuarantineEntry = {
|
|
102
|
+
readonly test: string;
|
|
103
|
+
readonly owner: string;
|
|
104
|
+
readonly expires: string;
|
|
105
|
+
readonly reason: string;
|
|
106
|
+
};
|
|
107
|
+
/** The quarantine record from its JSON text, or why it is not one: a list of entries, each with a test, an owner, an expiry day (`YYYY-MM-DD`) and a reason. */
|
|
108
|
+
export declare function parseQuarantine(text: string): Result<readonly QuarantineEntry[], string>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The audience tiers of Repoctl (commons repoctl 0002-repoctl-governance FR-003; commons headless 0010-audience-tiers): three, lowest first. `public` sees what only reads (the checks, the status, the plan of a
|
|
3
|
+
* release); `contributor` also sees what changes a checkout (the generated files, the merge, the commit, a new library, the making of a release); `releaser` also sees the publication. The tier is a fact of the host that
|
|
4
|
+
* runs the program (the variable `REPOCTL_TIER`, the key of a tool server), never a word of a message.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { LADDER, tierOf } from "./tiers.js";
|
|
9
|
+
* LADDER.ladder.length; // 3
|
|
10
|
+
* tierOf("releaser");
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import { type TierLadder, type TierName } from "@intellectual-frontiers/headless/governance";
|
|
16
|
+
/** The names of the tiers, lowest first: a closed union. */
|
|
17
|
+
export type TierId = "public" | "contributor" | "releaser";
|
|
18
|
+
/** Every tier, lowest first. */
|
|
19
|
+
export declare const TIER_IDS: readonly TierId[];
|
|
20
|
+
/** The three tiers as headless' tier names. */
|
|
21
|
+
export declare const TIERS: Readonly<Record<TierId, TierName>>;
|
|
22
|
+
/** The ladder of the program: the tier of a caller who says nothing is `contributor`, the person at their own checkout. */
|
|
23
|
+
export declare const LADDER: TierLadder;
|
|
24
|
+
/** The tier named by a word, or undefined where the word is none of the three. */
|
|
25
|
+
export declare function tierOf(word: string): TierName | undefined;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The verbs of Repoctl as facts (commons repoctl 0002-repoctl-governance FR-002, FR-003; commons headless 0002-headless-governance, 0005-reach-and-targets): each verb is declared once, with what it is (a report or an action), what it may
|
|
3
|
+
* do (`read`, `mutate`, `destructive`), whether repeating it is safe, whether it previews and checks, the tier that may see it and the reach policy that says through which channels it comes and how a destruction is confirmed. The
|
|
4
|
+
* command line, the tool server and the documentation read this one table; a test holds that its facts do not contradict each other.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { VERBS, verbIds } from "./verbs.js";
|
|
9
|
+
* VERBS["release publish"].effect; // "destructive"
|
|
10
|
+
* verbIds().includes("sync"); // true
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import type { Channel, ConfirmationClass, Effect, Kind } from "@intellectual-frontiers/headless/governance";
|
|
16
|
+
import type { TierId } from "./tiers.js";
|
|
17
|
+
/** The words of every verb, as a person types them: a closed union. */
|
|
18
|
+
export type VerbId = "sync" | "merge" | "check" | "status" | "hygiene" | "release plan" | "release apply" | "release publish" | "new library" | "commit" | "doctor" | "prove" | "docs build" | "docs serve" | "docs check" | "mcp";
|
|
19
|
+
/** What a verb is. */
|
|
20
|
+
export type VerbFacts = {
|
|
21
|
+
readonly id: VerbId;
|
|
22
|
+
readonly summary: string;
|
|
23
|
+
readonly kind: Kind;
|
|
24
|
+
readonly effect: Effect;
|
|
25
|
+
/** Whether running it again with the same input changes nothing more. */
|
|
26
|
+
readonly idempotent: boolean;
|
|
27
|
+
/** Whether `--dry-run` previews what it would change. */
|
|
28
|
+
readonly dryRun: boolean;
|
|
29
|
+
/** Whether `--check` ends with findings where it would change something. */
|
|
30
|
+
readonly check: boolean;
|
|
31
|
+
/** The lowest tier that sees it. */
|
|
32
|
+
readonly tier: TierId;
|
|
33
|
+
/** The channels it comes through. */
|
|
34
|
+
readonly channels: readonly Channel[];
|
|
35
|
+
/** How it is confirmed: a destruction by a person (and, from a tool server, only as a preview). */
|
|
36
|
+
readonly confirmation: ConfirmationClass;
|
|
37
|
+
/** The options only a person may give. */
|
|
38
|
+
readonly humanOnly: readonly string[];
|
|
39
|
+
};
|
|
40
|
+
/** Every verb, by its words: a registry the compiler holds complete. */
|
|
41
|
+
export declare const VERBS: Readonly<Record<VerbId, VerbFacts>>;
|
|
42
|
+
/** The words of every verb, in the order the help lists them. */
|
|
43
|
+
export declare function verbIds(): readonly VerbId[];
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The version of Repoctl, as the program says it (`repoctl --version`). The manifest names this constant in `versionConstants`, so that the release writes the new version here with the manifest and the package, and the check
|
|
3
|
+
* finds it where it disagrees.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { REPOCTL_VERSION } from "./version.js";
|
|
8
|
+
* REPOCTL_VERSION; // "0.1.0"
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
/** The version of the library, which the manifest, the package and the release record say as well. */
|
|
14
|
+
export declare const REPOCTL_VERSION = "0.1.0";
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `repoctl check` (commons repoctl 0003-repoctl-sync FR-007, FR-008): every check of the repository in one report. A section is one check (a generator's, the specification kit of commons, the rules of Mizan, the versions, the
|
|
3
|
+
* specification kit of each library, the constants that say a version) with its findings, each a code of the closed union that `repoctl explain` explains and the command that fixes it. Nothing is written.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { sectionOk } from "./check.js";
|
|
8
|
+
* sectionOk({ id: "specs", title: "The specification kit of commons", findings: [] }); // true
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { type Config } from "@intellectual-frontiers/repoctl/governance";
|
|
14
|
+
import { type Finding } from "./findings.js";
|
|
15
|
+
import type { Run, World } from "./ports.js";
|
|
16
|
+
/** One check and what it found. */
|
|
17
|
+
export type Section = {
|
|
18
|
+
readonly id: string;
|
|
19
|
+
readonly title: string;
|
|
20
|
+
readonly findings: readonly Finding[];
|
|
21
|
+
};
|
|
22
|
+
/** Every section, in the order they are reported. */
|
|
23
|
+
export type CheckReport = {
|
|
24
|
+
readonly sections: readonly Section[];
|
|
25
|
+
};
|
|
26
|
+
/** Whether a section found nothing that fails. */
|
|
27
|
+
export declare function sectionOk(s: Section): boolean;
|
|
28
|
+
/** Whether a whole report found nothing that fails. */
|
|
29
|
+
export declare function reportOk(r: CheckReport): boolean;
|
|
30
|
+
/** What a check program's end is as findings: none where it ended with 0, one for each line it said where it ended with 1, and a warning that it did not run for any other status. */
|
|
31
|
+
export declare function findingsOfProgram(run: Run, code: Finding["code"], fix: string): readonly Finding[];
|
|
32
|
+
/** Runs every check of the configuration: the generators', its named checks, and, where it has libraries, the specification kit of each and the constants that say a version. */
|
|
33
|
+
export declare function runCheck(w: World, config: Pick<Config, "generators" | "checks" | "libraries">): Promise<CheckReport>;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `repoctl commit` (commons repoctl 0005-repoctl-library-commit-doctor FR-004 to FR-007): the commit of this repository, made one way. The author and the committer are the identity of the repository's configuration, the message is the subject and then the trailers the configuration lists (the reference to an issue,
|
|
3
|
+
* the line that credits the agent, the session) on their own lines, files that must not be committed (the local folder of an agent, installed packages, files that look like secrets) are refused by their paths and by what they say,
|
|
4
|
+
* and the generated files are checked first (before anything is staged), so that no commit leaves one stale. Pure where it can be: the message and the refusals are functions of their inputs.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { DEFAULT_ALLOWED_PATHS, DEFAULT_FORBIDDEN_PATHS } from "@intellectual-frontiers/repoctl/governance";
|
|
9
|
+
* import { forbidden, messageOf } from "./commit.js";
|
|
10
|
+
* forbidden({ paths: DEFAULT_FORBIDDEN_PATHS, allow: DEFAULT_ALLOWED_PATHS, secrets: [] }, ".claude/settings.json"); // "the local folder of an agent (.claude/)"
|
|
11
|
+
* messageOf({ issue: { prefix: "Refs #", required: false }, trailers: ["issue"] }, { subject: "Add", refs: "10", coAuthor: undefined, session: undefined }).trailers; // ["Refs #10"]
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
import { type CommitPolicy, type CommitSubject, type Generator, type IssueNumber, type SessionUrl } from "@intellectual-frontiers/repoctl/governance";
|
|
17
|
+
import { type Finding } from "./findings.js";
|
|
18
|
+
import type { World } from "./ports.js";
|
|
19
|
+
/** What a commit is made of. */
|
|
20
|
+
export type CommitInput = {
|
|
21
|
+
readonly subject: CommitSubject;
|
|
22
|
+
readonly refs: IssueNumber | undefined;
|
|
23
|
+
/** The address of the session, where the policy has the trailer. */
|
|
24
|
+
readonly session: SessionUrl | undefined;
|
|
25
|
+
/** The line that credits the agent, where the policy has the trailer. */
|
|
26
|
+
readonly coAuthor: string | undefined;
|
|
27
|
+
/** Paths to stage first (the files already staged are committed in any case). */
|
|
28
|
+
readonly paths: readonly string[];
|
|
29
|
+
readonly dryRun: boolean;
|
|
30
|
+
};
|
|
31
|
+
/** The message of a commit: the subject, and the trailers, each a line. */
|
|
32
|
+
export type Message = {
|
|
33
|
+
readonly subject: string;
|
|
34
|
+
readonly trailers: readonly string[];
|
|
35
|
+
};
|
|
36
|
+
/** The message: the subject, then the trailers the policy lists, in its order, each a line: the reference to an issue (the policy's prefix and the number), the line that credits the agent, and `Claude-Session`. A trailer whose value is not given is left out. */
|
|
37
|
+
export declare function messageOf(policy: Pick<CommitPolicy, "issue" | "trailers">, input: {
|
|
38
|
+
readonly subject: string;
|
|
39
|
+
readonly refs: string | undefined;
|
|
40
|
+
readonly coAuthor: string | undefined;
|
|
41
|
+
readonly session: string | undefined;
|
|
42
|
+
}): Message;
|
|
43
|
+
/** The message as Git is given it: the subject, a blank line, and the trailers on lines of their own. */
|
|
44
|
+
export declare function messageText(m: Message): string;
|
|
45
|
+
/** Why a path must not be committed under the policy, or undefined where it may be: a forbidden glob matches it and no allowed glob does. */
|
|
46
|
+
export declare function forbidden(policy: CommitPolicy["forbidden"], path: string): string | undefined;
|
|
47
|
+
/** What a text holds that looks like a secret under the policy, or undefined where it holds none. */
|
|
48
|
+
export declare function secretLike(policy: CommitPolicy["forbidden"], text: string): string | undefined;
|
|
49
|
+
/** What a commit came to. */
|
|
50
|
+
export type CommitReport = {
|
|
51
|
+
readonly kind: "refused";
|
|
52
|
+
readonly findings: readonly Finding[];
|
|
53
|
+
} | {
|
|
54
|
+
readonly kind: "preview";
|
|
55
|
+
readonly message: string;
|
|
56
|
+
readonly files: readonly string[];
|
|
57
|
+
} | {
|
|
58
|
+
readonly kind: "committed";
|
|
59
|
+
readonly message: string;
|
|
60
|
+
readonly files: readonly string[];
|
|
61
|
+
readonly sha: string;
|
|
62
|
+
};
|
|
63
|
+
/** Makes the commit: stages the paths, refuses what must not be committed, checks the generated files, and commits as the repository's identity. */
|
|
64
|
+
export declare function runCommit(w: Pick<World, "process" | "repo" | "files">, input: CommitInput, order: readonly Generator[], policy: CommitPolicy): Promise<CommitReport>;
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { type Finding } from "./findings.js";
|
|
2
|
+
import type { LibraryInfo } from "./ports.js";
|
|
3
|
+
/** A constant of a library's sources that holds its version: the file from the library's folder and the constant's name. */
|
|
4
|
+
export type VersionConstant = {
|
|
5
|
+
readonly file: string;
|
|
6
|
+
readonly name: string;
|
|
7
|
+
};
|
|
8
|
+
/** A source file: its path from the repository's root and its text. */
|
|
9
|
+
export type Source = {
|
|
10
|
+
readonly path: string;
|
|
11
|
+
readonly text: string;
|
|
12
|
+
};
|
|
13
|
+
/** One `NAME_VERSION = "text"` found in a source, and the line it is on. */
|
|
14
|
+
export type Found = {
|
|
15
|
+
readonly path: string;
|
|
16
|
+
readonly name: string;
|
|
17
|
+
readonly value: string;
|
|
18
|
+
readonly line: number;
|
|
19
|
+
};
|
|
20
|
+
/** Every constant of a source that ends in `_VERSION` and is a text. */
|
|
21
|
+
export declare function constantsIn(source: Source): readonly Found[];
|
|
22
|
+
/** The name a library's own version constant has by convention: its name in capitals, hyphens as underscores, and `_VERSION`. */
|
|
23
|
+
export declare function conventionName(library: string): string;
|
|
24
|
+
/** The sources of a library that are read for constants: the TypeScript under its `src/`, and the files its manifest names. */
|
|
25
|
+
export declare function isRead(library: LibraryInfo, path: string): boolean;
|
|
26
|
+
/** What is wrong with the constants of the libraries' sources: one that disagrees with its library's version, one the manifest names that is not there, one that is not a version. */
|
|
27
|
+
export declare function constantFindings(libraries: readonly LibraryInfo[], sources: readonly Source[]): readonly Finding[];
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The packages a library imports and does not declare (commons repoctl 0003-repoctl-sync FR-010): a library job of CI installs only its own folder, so a package that a source, a test or a tool of the library imports by name
|
|
3
|
+
* (and `node:` imports, which need `@types/node`) must be in its `dependencies` or `devDependencies`, or the job fails where a checkout with the whole repository installed passes. Pure: it reads the texts it is given.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { undeclaredFindings } from "./declared.js";
|
|
8
|
+
* const lib = { name: "a", folder: "commons/a", manifest: '{"devDependencies":{}}', sources: [{ path: "commons/a/suite/x.test.ts", text: 'import { x } from "left-pad";' }] };
|
|
9
|
+
* undeclaredFindings([lib]).length; // 1
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { type Finding } from "./findings.js";
|
|
15
|
+
import type { Source } from "./constants.js";
|
|
16
|
+
/** A library as this check reads it: its folder, the text of its `package.json` and the TypeScript of its sources, suite and tools. */
|
|
17
|
+
export type DeclaredInput = {
|
|
18
|
+
readonly name: string;
|
|
19
|
+
readonly folder: string;
|
|
20
|
+
readonly manifest: string;
|
|
21
|
+
readonly sources: readonly Source[];
|
|
22
|
+
};
|
|
23
|
+
/** The package a specifier names, `node:` for a built-in of Node, or undefined for a relative path, a path, a template and a built-in of Bun. */
|
|
24
|
+
export declare function importedPackageOf(specifier: string): string | undefined;
|
|
25
|
+
/** The text of a source without its block comments, whose examples import what the library does not. */
|
|
26
|
+
export declare function withoutBlockComments(text: string): string;
|
|
27
|
+
/** The packages a source imports, each with the first line that does. */
|
|
28
|
+
export declare function importedPackages(source: Source): ReadonlyMap<string, number>;
|
|
29
|
+
/** The names a manifest declares under dependencies, devDependencies, peerDependencies and optionalDependencies; none where it cannot be read. */
|
|
30
|
+
export declare function declaredNames(manifest: string): ReadonlySet<string>;
|
|
31
|
+
/** A finding for each package a library imports and does not declare, naming the first file and line that imports it. */
|
|
32
|
+
export declare function undeclaredFindings(libraries: readonly DeclaredInput[]): readonly Finding[];
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The documentation verbs' reasoning (commons repoctl 0011-repoctl-docs FR-001 to FR-004): what `repoctl docs build`, `serve` and `check` ask of the documentation generator `ifc-docs` of `@intellectual-frontiers/docs`, as arguments of its command
|
|
3
|
+
* line, and what a missing generator or a failed run is as a finding. The generator is not carried by repoctl: the Physical layer loads it by its package name where it is installed, through the port below, and a test fills the port with its own.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { docsArguments } from "./docs.js";
|
|
8
|
+
* docsArguments("build", { config: "docs.config.ts", out: "_site", generator: undefined }, "/r"); // ["build", "--out", "/r/_site", "--config", "/r/docs.config.ts"]
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import type { Result } from "@intellectual-frontiers/core";
|
|
14
|
+
import type { DocsSettings } from "@intellectual-frontiers/repoctl/governance";
|
|
15
|
+
import { type Finding } from "./findings.js";
|
|
16
|
+
/** The command line of the generator `ifc-docs` is the program's `main`: its arguments and the folder it runs from to the status it ends with. */
|
|
17
|
+
export type DocsGenerator = {
|
|
18
|
+
readonly main: (argv: readonly string[], cwd: string) => Promise<number>;
|
|
19
|
+
};
|
|
20
|
+
/** The port that loads the generator from the repository's own dependencies (or from the module the settings name), or says why it cannot. */
|
|
21
|
+
export type DocsPort = {
|
|
22
|
+
readonly load: (repo: string, generator: string | undefined) => Promise<Result<DocsGenerator, string>>;
|
|
23
|
+
};
|
|
24
|
+
/** What the generator is asked: build into a folder, or check. */
|
|
25
|
+
export type DocsAsk = "build" | "check";
|
|
26
|
+
/** The arguments of the generator for a request: `build` writes into the folder given (the settings' by default), `check` writes nothing; both read the settings' configuration file. Paths are made absolute from the repository's root. */
|
|
27
|
+
export declare function docsArguments(ask: DocsAsk, settings: DocsSettings, repo: string, out?: string): readonly string[];
|
|
28
|
+
/** The finding of a generator that is not installed. */
|
|
29
|
+
export declare function missingGenerator(why: string): Finding;
|
|
30
|
+
/** The finding of a generator that ended with a status other than 0. */
|
|
31
|
+
export declare function failedGenerator(ask: DocsAsk | "serve", status: number): Finding;
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `repoctl doctor` (commons repoctl 0005-repoctl-library-commit-doctor FR-008): what is wrong with this checkout and what to do about it, in the order a person would fix it: Git and the checkout, the installed dependencies, the links of the libraries,
|
|
3
|
+
* Node at the configured least version, the version of Bun the repository pins, and the generated files that are stale. The facts are gathered through the ports; the diagnosis is a function of the facts.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { diagnose } from "./doctor.js";
|
|
8
|
+
* const policy = { minNode: 26, bunPin: undefined, links: undefined, install: "bun install" };
|
|
9
|
+
* diagnose({ git: { works: true, inside: true, origin: true }, installed: true, unlinked: [], node: "v26.13.1", bun: "1.4.4", pinnedBun: "1.4.4", stale: [] }, policy); // []
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import type { DoctorPolicy, Generator } from "@intellectual-frontiers/repoctl/governance";
|
|
15
|
+
import { type Finding } from "./findings.js";
|
|
16
|
+
import type { World } from "./ports.js";
|
|
17
|
+
/** What is found of the checkout and the tools. */
|
|
18
|
+
export type Facts = {
|
|
19
|
+
readonly git: {
|
|
20
|
+
readonly works: boolean;
|
|
21
|
+
readonly inside: boolean;
|
|
22
|
+
readonly origin: boolean;
|
|
23
|
+
};
|
|
24
|
+
/** Whether the root has its `node_modules`. */
|
|
25
|
+
readonly installed: boolean;
|
|
26
|
+
/** The libraries that are not linked under the policy's folder of links (none where the policy has none). */
|
|
27
|
+
readonly unlinked: readonly string[];
|
|
28
|
+
/** What `node --version` says, or undefined where Node does not run. */
|
|
29
|
+
readonly node: string | undefined;
|
|
30
|
+
/** What `bun --version` says. */
|
|
31
|
+
readonly bun: string | undefined;
|
|
32
|
+
/** The version of Bun the policy's pin file names. */
|
|
33
|
+
readonly pinnedBun: string | undefined;
|
|
34
|
+
/** The generated files that are stale. */
|
|
35
|
+
readonly stale: readonly Finding[];
|
|
36
|
+
};
|
|
37
|
+
/** The major number of a version such as `v26.13.1`, or undefined. */
|
|
38
|
+
export declare function majorOf(version: string | undefined): number | undefined;
|
|
39
|
+
/** Everything wrong, in the order to fix it. */
|
|
40
|
+
export declare function diagnose(f: Facts, policy: DoctorPolicy): readonly Finding[];
|
|
41
|
+
/** Gathers the facts through the ports. */
|
|
42
|
+
export declare function gatherFacts(w: World, order: readonly Generator[], policy: DoctorPolicy): Promise<Facts>;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a verb finds, as values (commons repoctl 0002-repoctl-governance FR-004): a finding has a level, a code of the closed union, a sentence that names its subject, and the command that fixes it. The Physical layer turns
|
|
3
|
+
* a finding into Headless' problem; nothing here knows how it is drawn.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { finding } from "./findings.js";
|
|
8
|
+
* finding("fail", "E-STALE-GENERATED", "readme: README.md is stale", "bun commons/libraries/src/readme.ts").code; // "E-STALE-GENERATED"
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import type { ProblemCode } from "@intellectual-frontiers/repoctl/governance";
|
|
14
|
+
/** How serious a finding is: a failure fails the run, a warning does not. */
|
|
15
|
+
export type Level = "fail" | "warn";
|
|
16
|
+
/** A finding: its level, its code, what is wrong and what to run. */
|
|
17
|
+
export type Finding = {
|
|
18
|
+
readonly level: Level;
|
|
19
|
+
readonly code: ProblemCode;
|
|
20
|
+
readonly message: string;
|
|
21
|
+
readonly fix: string;
|
|
22
|
+
};
|
|
23
|
+
/** A finding of the given level and code. */
|
|
24
|
+
export declare function finding(level: Level, code: ProblemCode, message: string, fix: string): Finding;
|
|
25
|
+
/** The lines of a program's output that say something, without the blank ones and trimmed, at most `n` of them from the end. */
|
|
26
|
+
export declare function tailLines(text: string, n: number): readonly string[];
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Globs of paths, as the tables of the generators write them (commons repoctl 0003-repoctl-sync FR-001): `*` is the characters of one segment and `**` any number of segments. A path matches a glob, and two globs overlap where some
|
|
3
|
+
* path could match both, which is what makes one generator come after another: it reads what the other writes.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { matches, overlap } from "./glob.js";
|
|
8
|
+
* matches("commons/*\/LICENSE", "commons/core/LICENSE"); // true
|
|
9
|
+
* overlap("commons/**\/suite/**", "commons/core/suite/a.test.ts"); // true
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
/** Whether a path (from the repository's root, with `/`) matches a glob. */
|
|
15
|
+
export declare function matches(glob: string, path: string): boolean;
|
|
16
|
+
/** Whether some path could match both globs. */
|
|
17
|
+
export declare function overlap(a: string, b: string): boolean;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The facts of a repository for the hygiene check, gathered through the ports (commons repoctl 0007-repoctl-hygiene FR-003; commons 0036-distribution FR-011): the lockfiles read as data (`bun.lock` is JSON with comments and trailing commas,
|
|
3
|
+
* `package-lock.json` is JSON of lockfile versions 2 and 3), the `package.json` files outside `node_modules`, the packages installed under `node_modules` (a folder of the scope, nested ones and Bun's `.bun` store) and the relative imports of the sources.
|
|
4
|
+
* The parsers are pure; only `gatherHygieneFacts` of this module reads, and only through `Files`.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { parseNpmLock } from "./hygiene-facts.js";
|
|
9
|
+
* const r = parseNpmLock('{ "packages": { "node_modules/@intellectual-frontiers/core": { "version": "0.1.5" } } }', "package-lock.json");
|
|
10
|
+
* r.kind; // "read"
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
16
|
+
import type { HygieneFacts, LockFacts, PackageFacts } from "./hygiene.js";
|
|
17
|
+
import type { HygienePolicy } from "@intellectual-frontiers/repoctl/governance";
|
|
18
|
+
import type { World } from "./ports.js";
|
|
19
|
+
/** The text of a JSON with comments and trailing commas as JSON: comments and the commas before `}` and `]` are removed, and strings are left as they are. */
|
|
20
|
+
export declare function stripJsonc(text: string): string;
|
|
21
|
+
/** The copies of the packages of commons a `bun.lock` holds: each entry of `packages` is `[ "name@version", ... ]` under a key that says where it is nested. */
|
|
22
|
+
export declare function parseBunLock(source: string, file: string, scope: string): LockFacts;
|
|
23
|
+
/** The copies of the packages of commons a `package-lock.json` (versions 2 and 3: `packages` keyed by path) holds. */
|
|
24
|
+
export declare function parseNpmLock(source: string, file: string, scope: string): LockFacts;
|
|
25
|
+
/** The facts of one `package.json`'s text: its name and its dependencies of every section; the workspaces it declares are the second part. */
|
|
26
|
+
export declare function parsePackage(source: string, path: string): Result<{
|
|
27
|
+
readonly facts: PackageFacts;
|
|
28
|
+
readonly workspaces: readonly string[];
|
|
29
|
+
}, string>;
|
|
30
|
+
/** The relative specifiers a source imports, with the specifier as written. */
|
|
31
|
+
export declare function relativeImports(source: string): readonly string[];
|
|
32
|
+
/** Gathers the facts of the repository of a world: the only reads of the check. */
|
|
33
|
+
export declare function gatherHygieneFacts(w: Pick<World, "files" | "repo">, policy: HygienePolicy): Promise<HygieneFacts>;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { HygienePolicy } from "@intellectual-frontiers/repoctl/governance";
|
|
2
|
+
import type { Finding } from "./findings.js";
|
|
3
|
+
/** A dependency a `package.json` declares: its name and what it asks for. */
|
|
4
|
+
export type Dependency = {
|
|
5
|
+
readonly name: string;
|
|
6
|
+
readonly spec: string;
|
|
7
|
+
};
|
|
8
|
+
/** A `package.json` of the repository: its path from the root, its name and its dependencies (of every section). */
|
|
9
|
+
export type PackageFacts = {
|
|
10
|
+
readonly path: string;
|
|
11
|
+
readonly name: string | undefined;
|
|
12
|
+
readonly dependencies: readonly Dependency[];
|
|
13
|
+
};
|
|
14
|
+
/** One installed copy of a package: its version and where it is (a path from the root, or a key of the lockfile). */
|
|
15
|
+
export type Copy = {
|
|
16
|
+
readonly version: string;
|
|
17
|
+
readonly where: string;
|
|
18
|
+
};
|
|
19
|
+
/** What reading a lockfile gave: the copies of each package of commons it holds, or why it could not be read. */
|
|
20
|
+
export type LockFacts = {
|
|
21
|
+
readonly kind: "read";
|
|
22
|
+
readonly file: string;
|
|
23
|
+
readonly copies: ReadonlyMap<string, readonly Copy[]>;
|
|
24
|
+
} | {
|
|
25
|
+
readonly kind: "unreadable";
|
|
26
|
+
readonly file: string;
|
|
27
|
+
readonly why: string;
|
|
28
|
+
};
|
|
29
|
+
/** A relative import of a source: the file and the specifier as written. */
|
|
30
|
+
export type ImportFact = {
|
|
31
|
+
readonly file: string;
|
|
32
|
+
readonly specifier: string;
|
|
33
|
+
};
|
|
34
|
+
/** Whose repository it is: the repository the family's packages are made in (the policy's source marker is there), or a repository that consumes them. */
|
|
35
|
+
export type Repository = "source" | "consumer";
|
|
36
|
+
/** Everything the check reads of a repository. */
|
|
37
|
+
export type HygieneFacts = {
|
|
38
|
+
readonly repository: Repository;
|
|
39
|
+
readonly packages: readonly PackageFacts[];
|
|
40
|
+
/** One entry for each lockfile found (`bun.lock`, `package-lock.json`); none where there is none. */
|
|
41
|
+
readonly locks: readonly LockFacts[];
|
|
42
|
+
/** The copies found in `node_modules`, by package. */
|
|
43
|
+
readonly installed: ReadonlyMap<string, readonly Copy[]>;
|
|
44
|
+
readonly imports: readonly ImportFact[];
|
|
45
|
+
/** The globs of the workspaces the root `package.json` declares: the packages of the repository itself. */
|
|
46
|
+
readonly workspaces: readonly string[];
|
|
47
|
+
};
|
|
48
|
+
/** A finding of the check, with the path it was found at. */
|
|
49
|
+
export type HygieneFinding = Finding & {
|
|
50
|
+
readonly path: string;
|
|
51
|
+
};
|
|
52
|
+
/** Whether a version specifier is an exact version. */
|
|
53
|
+
export declare function isExactVersion(spec: string): boolean;
|
|
54
|
+
/** Whether a dependency specifier is a dependency by Git on the family's own repository (a fragment of the policy's `gitSources` is in it). */
|
|
55
|
+
export declare function isGitOfFamily(policy: HygienePolicy, spec: string): boolean;
|
|
56
|
+
/** The kind of a path dependency: `file:` or `link:` and the path, or nothing where the specifier is none. */
|
|
57
|
+
export declare function pathOf(spec: string): string | undefined;
|
|
58
|
+
/** Whether a path goes through the policy's folder name and the folder holds something: the name is a segment and is not the last. A policy with no folder name has no such path. */
|
|
59
|
+
export declare function intoFamily(policy: HygienePolicy, path: string): boolean;
|
|
60
|
+
/** The findings of a repository, in the order of the codes and then of the paths. */
|
|
61
|
+
export declare function hygiene(facts: HygieneFacts, policy: HygienePolicy): readonly HygieneFinding[];
|
|
62
|
+
/** Whether any finding fails the run: a warning alone does not. */
|
|
63
|
+
export declare function hygieneFails(findings: readonly Finding[]): boolean;
|
|
64
|
+
/** The counts of a run: failures and warnings. */
|
|
65
|
+
export declare function countsOf(findings: readonly Finding[]): {
|
|
66
|
+
readonly failures: number;
|
|
67
|
+
readonly warnings: number;
|
|
68
|
+
};
|