@intellectual-frontiers/libraries 0.2.1 → 0.4.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.
@@ -0,0 +1,176 @@
1
+ import { type Result } from "@intellectual-frontiers/core";
2
+ import { type Look } from "@intellectual-frontiers/system/tty";
3
+ import { type Slug } from "@intellectual-frontiers/mizan/versions/record";
4
+ import { type Impact } from "@intellectual-frontiers/mizan/versions/scheme";
5
+ /** The record of the release, from the repository's root. */
6
+ export declare const RECORD_PATH = "commons/generated/release.auto.json";
7
+ /** What the plan knows of a library: its version, what it imports, the last tag of it, whether its files changed since, and the impact the commits since state. */
8
+ export type Facts = {
9
+ readonly slug: Slug;
10
+ readonly folder: string;
11
+ readonly version: string;
12
+ /** The libraries (by slug) whose package its own sources import. */
13
+ readonly imports: readonly Slug[];
14
+ /** The greatest tag of the library by Semantic Version precedence, where it has one. */
15
+ readonly last: {
16
+ readonly version: string;
17
+ readonly tag: string;
18
+ } | undefined;
19
+ /** Whether a file of the library changed since `last`; false where there is none. */
20
+ readonly changed: boolean;
21
+ /** The greatest impact the commits since `last` state, a patch where none does. */
22
+ readonly impact: Impact;
23
+ /** Whether the release sends it to a registry: a library that names npm. */
24
+ readonly publish: boolean;
25
+ /** For a version that is not tagged or is ahead of its tag: what npm holds of this version, compared with the files of the library. */
26
+ readonly registry: Drift;
27
+ /** Whether a file of the library changed since the last commit that raised its version, and the impact the commits since state (a patch where none does): the fallback where npm cannot be compared. */
28
+ readonly sinceVersion: {
29
+ readonly changed: boolean;
30
+ readonly impact: Impact;
31
+ };
32
+ };
33
+ /** What npm holds of a version, against the files of the library: not there, there and the same, there and different, or not known (offline, or the registry did not say). */
34
+ export type Drift = "absent" | "same" | "differs" | "unknown";
35
+ /** Why a library is raised. */
36
+ export type Why = "changed" | "differs-from-npm" | "changed-since-version" | "manual";
37
+ /** What the release does to one library. */
38
+ export type Decision = {
39
+ readonly kind: "unchanged";
40
+ } | {
41
+ readonly kind: "as-is";
42
+ readonly why: "no-tag" | "ahead-of-tag";
43
+ readonly npm: Drift;
44
+ } | {
45
+ readonly kind: "raised";
46
+ readonly to: string;
47
+ readonly impact: Impact;
48
+ readonly why: Why;
49
+ } | {
50
+ readonly kind: "dependent";
51
+ readonly to: string;
52
+ readonly because: readonly Slug[];
53
+ };
54
+ /** One step of a release: a library, its version before and after, and what is done to it. */
55
+ export type Step = {
56
+ readonly slug: Slug;
57
+ readonly folder: string;
58
+ readonly from: string;
59
+ readonly to: string;
60
+ readonly tag: string;
61
+ readonly publish: boolean;
62
+ readonly decision: Exclude<Decision, {
63
+ readonly kind: "unchanged";
64
+ }>;
65
+ };
66
+ /** The plan: every step in the order of the imports, and the libraries that are left alone. */
67
+ export type Plan = {
68
+ readonly steps: readonly Step[];
69
+ readonly unchanged: readonly Slug[];
70
+ };
71
+ /** The text of a decision, in a sentence. */
72
+ export declare function describe(d: Decision, from: string): string;
73
+ /**
74
+ * The plan of a release from the facts of the libraries (FR-013): a library with no tag, or ahead of its last tag, is released as it is; one that is tagged at its version and changed is raised by its impact; one that is tagged,
75
+ * unchanged and imports a library that is raised, directly or through another, is raised by a patch; the rest are left alone. A library whose version is below its last tag is an error, and so is a cycle of imports.
76
+ */
77
+ export declare function planRelease(facts: readonly Facts[], raise?: ReadonlyMap<string, Impact | undefined>): Result<Plan, string>;
78
+ /** The record the workflow reads, as the bytes of its file: the steps that publish or tag, in order. */
79
+ export declare function recordText(plan: Plan): string;
80
+ /** One entry of the record, as the workflow reads it. */
81
+ export type Entry = {
82
+ readonly slug: string;
83
+ readonly version: string;
84
+ readonly folder: string;
85
+ readonly tag: string;
86
+ readonly publish: boolean;
87
+ };
88
+ /** The entries of a record's text, or why it is not one. */
89
+ export declare function readRecord(text: string): Result<readonly Entry[], string>;
90
+ /** What the workflow builds and publishes: the entries whose tag is not there yet, as the cells of a matrix and the sequence to publish in, as the outputs of a step. */
91
+ export declare function matrixOutputs(entries: readonly Entry[], tagged: ReadonlySet<string>): string;
92
+ /** Writes a library's new version into its record, its manifest and its package, each where it says the version; the problem where one does not. */
93
+ export declare function writeVersion(repo: string, step: Step): Result<readonly string[], string>;
94
+ /** What a tarball holds that the comparison reads: the SHA-256 of each file by its path (without the folder `package/`), and the text of its `package.json`. */
95
+ export type Tarball = {
96
+ readonly hashes: ReadonlyMap<string, string>;
97
+ readonly packageJson: string;
98
+ };
99
+ /** The files of a gzipped tar, as a registry serves it: each regular file's path and SHA-256. A header it cannot read ends the list there. */
100
+ export declare function tarballOf(gz: Uint8Array): Tarball;
101
+ /**
102
+ * Whether the files of a library are those of the version npm holds (FR-013): the sources the package carries (`src/`, each by its SHA-256 against the library's own file) and the keys of its `exports` (the packer rewrites the rest of
103
+ * `package.json`, and the compiled files are the compiler's). A source that is missing here, or other, or an entry of `exports` that was added or removed, is a difference.
104
+ */
105
+ export declare function driftOf(published: Tarball, local: {
106
+ readonly hash: (path: string) => string | undefined;
107
+ readonly packageJson: string;
108
+ }): "same" | "differs";
109
+ /** Compares a library's version with what npm holds of it. */
110
+ export type Registry = (slug: string, version: string, folder: string) => Promise<Drift>;
111
+ /** The registry of npm itself, read over HTTPS: the metadata of the version, its tarball, and the library's files under `repo`; anything that goes wrong is `unknown`, never a guess. */
112
+ export declare function realRegistry(repo: string): Registry;
113
+ /** What the host gives the plan: the facts of the libraries from the tags and the tree. */
114
+ export declare function factsOf(repo: string, registry?: Registry): Promise<Result<readonly Facts[], string>>;
115
+ /** The commands that make the generated files, in the order they are made: the section of the libraries first, the register last. Each is run once, by `apply`. */
116
+ export declare const GENERATORS: readonly (readonly string[])[];
117
+ /** The tests that pack every library, install it into a consumer and type-check against it (the heavy proof a release asks for and a push does not). */
118
+ export declare const PACKAGE_TESTS: readonly string[];
119
+ /** What `apply` runs besides the planner: the generators and the tests, which a test of this module replaces. */
120
+ export type Host = {
121
+ readonly generate: (repo: string, command: readonly string[]) => Promise<Result<void, string>>;
122
+ readonly prove: (repo: string) => Promise<Result<void, string>>;
123
+ };
124
+ /** The real host: each command run with Bun from the repository's root. */
125
+ export declare const REAL: Host;
126
+ /** What `apply` did: the files written, in order. */
127
+ export type Applied = {
128
+ readonly plan: Plan;
129
+ readonly written: readonly string[];
130
+ };
131
+ /** Makes the release (FR-014): raises the versions of the plan, makes the generated files once, runs the tests that pack unless asked not to, and writes the record. */
132
+ export declare function applyRelease(repo: string, host: Host, options: {
133
+ readonly tests: boolean;
134
+ readonly raise?: ReadonlyMap<string, Impact | undefined>;
135
+ readonly registry?: Registry;
136
+ }): Promise<Result<Applied, string>>;
137
+ /** The lines the plan prints: one for each library that is released, and the libraries left alone. */
138
+ export declare function planLines(look: Look, plan: Plan): readonly string[];
139
+ /** What the publication needs from the world, so that its order and its rules are a pure function of what these say. */
140
+ export type Tools = {
141
+ /** Whether the version is on npm (asked again after a pause where it is not, because a version put there by hand may take a while to show). */
142
+ readonly onNpm: (name: string, version: string) => Promise<boolean>;
143
+ /** Sends the package to npm; the reason where it cannot (no trusted publisher and no token, or npm refused). */
144
+ readonly npm: (e: Entry) => Promise<Result<void, string>>;
145
+ /** Sends the package to the GitHub package registry, unless it is there. */
146
+ readonly github: (e: Entry) => Promise<Result<void, string>>;
147
+ /** Makes the tag at the commit that runs, or finds it there. */
148
+ readonly tag: (tag: string) => Promise<Result<"made" | "there", string>>;
149
+ };
150
+ /** What happened to one release: the state of its publication, and of its tag. */
151
+ export type Outcome = {
152
+ readonly slug: string;
153
+ readonly tag: string;
154
+ readonly npm: "present" | "published" | "failed" | "not-published";
155
+ readonly registry: "done" | "failed" | "not-published";
156
+ readonly tagged: "made" | "there" | "withheld" | "failed";
157
+ readonly reasons: readonly string[];
158
+ };
159
+ /**
160
+ * Publishes and tags the releases in order (FR-015), each by itself: a version that is on npm is not sent again and is tagged; one that is not is sent, and where nothing can send it (no trusted publisher, no token) it is
161
+ * reported and its tag withheld, and the others go on; a release that is only tagged (a library that names no npm) is tagged. A tag that is there is kept. The failures are in the outcomes, never thrown.
162
+ */
163
+ export declare function publishAll(entries: readonly Entry[], tools: Tools): Promise<readonly Outcome[]>;
164
+ /** The lines that say how each release went, and whether the run is a failure: one failure anywhere fails it, after every release was tried. */
165
+ export declare function outcomeLines(outcomes: readonly Outcome[]): {
166
+ readonly lines: readonly string[];
167
+ readonly failed: boolean;
168
+ };
169
+ /** The tools of a run of the release workflow: npm and the GitHub CLI, the tarballs under `dir` (one folder for each library, `package-<slug>`), and the environment's credentials. */
170
+ export declare function realTools(dir: string): Tools;
171
+ /** What `--raise` says: each library by its name, with the impact after an `=` where one is given. */
172
+ export declare function raiseOf(words: readonly string[]): Result<ReadonlyMap<string, Impact | undefined>, string>;
173
+ /** The registry that is not asked (`--offline`). */
174
+ export declare const offlineRegistry: Registry;
175
+ /** The command line. Returns the exit status: 0, 1 where a plan or a step failed, 2 for a command line that does not fit. */
176
+ export declare function main(argv: readonly string[], host?: Host): Promise<number>;