@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,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The order of the generators (commons repoctl 0003-repoctl-sync FR-001): a generator comes after every generator it declares in `after` and every generator that writes something it reads, which the globs of the table say, and where the facts do not order two of them the
|
|
3
|
+
* table's own order stands. A table in which generators wait for one another is refused with the ones that do. Pure: the same table gives the same order.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { GENERATORS } from "@intellectual-frontiers/repoctl/governance";
|
|
8
|
+
* import { orderGenerators } from "./order.js";
|
|
9
|
+
* const r = orderGenerators(GENERATORS);
|
|
10
|
+
* r.kind === "ok" && r.value[0]?.id; // "libraries"
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
16
|
+
import { type Generator, type StepId } from "@intellectual-frontiers/repoctl/governance";
|
|
17
|
+
/** Whether `later` comes after `earlier`: it declares it in `after`, or it reads something that `earlier` writes. */
|
|
18
|
+
export declare function reads(later: Generator, earlier: Generator): boolean;
|
|
19
|
+
/** The generators in the order they are run, or the ids of those that wait for one another. */
|
|
20
|
+
export declare function orderGenerators(table: readonly Generator[]): Result<readonly Generator[], readonly StepId[]>;
|
|
21
|
+
/** The generator that writes a path (from the repository's root, with `/`), the first of the table where two globs match it; none where no generator writes it. */
|
|
22
|
+
export declare function generatorOf(table: readonly Generator[], path: string): Generator | undefined;
|
|
23
|
+
/** The command that fixes a stale generator, as a person types it. */
|
|
24
|
+
export declare function fixOf(g: Generator): string;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Jobs run a few at a time (commons repoctl 0003-repoctl-sync FR-007): the checks of the libraries are independent reads, so they run in a pool of a fixed width, and their results are in the order of the jobs, whatever order they
|
|
3
|
+
* finished in. A pure function of the jobs it is given.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { pool } from "./pool.js";
|
|
8
|
+
* await pool([3, 1, 2], 2, (n) => Promise.resolve(n * 2)); // [6, 2, 4]
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
/** Runs `job` on each item, at most `width` at a time, and gives the results in the order of the items. */
|
|
14
|
+
export declare function pool<T, R>(items: readonly T[], width: number, job: (item: T) => Promise<R>): Promise<readonly R[]>;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ports of Repoctl (commons repoctl 0001-repoctl-layers FR-006): everything a verb needs of the world, as records of functions that the Physical layer fills and a test fills with its own. A program is run through `Process`
|
|
3
|
+
* (the same shape as Headless' executor, with the output as text), a file is read and written through `Files`, the registry of npm is asked through `Registry`, and a credential is taken through `Credentials` and never
|
|
4
|
+
* through the environment of a verb. Nothing in Governance or Logical reads a file, runs a program or reaches the network except through these.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import type { Process } from "@intellectual-frontiers/repoctl/logical";
|
|
9
|
+
* const none: Process = { run: () => Promise.resolve({ code: 0, stdout: "", stderr: "" }) };
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import type { Result } from "@intellectual-frontiers/core";
|
|
15
|
+
import type { Secret } from "@intellectual-frontiers/headless/logical";
|
|
16
|
+
import type { VersionConstant } from "./constants.js";
|
|
17
|
+
import type { DocsPort } from "./docs.js";
|
|
18
|
+
/** How a program ended, with its output as text. */
|
|
19
|
+
export type Run = {
|
|
20
|
+
readonly code: number;
|
|
21
|
+
readonly stdout: string;
|
|
22
|
+
readonly stderr: string;
|
|
23
|
+
};
|
|
24
|
+
/** How to run a program: where, and with which variables added to its environment. */
|
|
25
|
+
export type RunOptions = {
|
|
26
|
+
readonly cwd?: string;
|
|
27
|
+
readonly env?: Readonly<Record<string, string>>;
|
|
28
|
+
};
|
|
29
|
+
/** The port that runs a program by its argument vector, with no shell between. */
|
|
30
|
+
export type Process = {
|
|
31
|
+
readonly run: (argv: readonly string[], options?: RunOptions) => Promise<Run>;
|
|
32
|
+
};
|
|
33
|
+
/** The port of files. Paths are absolute; a folder's entries are names. */
|
|
34
|
+
export type Files = {
|
|
35
|
+
/** The text of a file, or undefined where it is not there. */
|
|
36
|
+
readonly read: (path: string) => Promise<string | undefined>;
|
|
37
|
+
/** Writes a text (making the folder), with the mode where one is given. */
|
|
38
|
+
readonly write: (path: string, text: string, mode?: number) => Promise<void>;
|
|
39
|
+
/** Removes a file; nothing where it is not there. */
|
|
40
|
+
readonly remove: (path: string) => Promise<void>;
|
|
41
|
+
/** Whether a file or a folder is there. */
|
|
42
|
+
readonly exists: (path: string) => Promise<boolean>;
|
|
43
|
+
/** The names in a folder, files and folders, sorted; none where it is not there. */
|
|
44
|
+
readonly list: (dir: string) => Promise<readonly string[]>;
|
|
45
|
+
/** Every file under a folder, as paths from the folder, sorted, leaving out `node_modules`; none where it is not there. */
|
|
46
|
+
readonly walk: (dir: string) => Promise<readonly string[]>;
|
|
47
|
+
/** Makes a private folder outside the repository and gives its path. */
|
|
48
|
+
readonly makeTemp: (prefix: string) => Promise<string>;
|
|
49
|
+
/** Removes a folder and what is in it. */
|
|
50
|
+
readonly removeTree: (path: string) => Promise<void>;
|
|
51
|
+
};
|
|
52
|
+
/** What npm shows of a package. */
|
|
53
|
+
export type NpmView = {
|
|
54
|
+
readonly latest: string | undefined;
|
|
55
|
+
readonly versions: readonly string[];
|
|
56
|
+
};
|
|
57
|
+
/** The port of the registry of npm: what it shows of a package, or `absent` where it has none, or why it could not be asked. */
|
|
58
|
+
export type Registry = {
|
|
59
|
+
readonly view: (name: string) => Promise<Result<NpmView | "absent", string>>;
|
|
60
|
+
};
|
|
61
|
+
/** The port of credentials: the token for npm is held by whoever publishes and is read from where the host keeps it, never from a verb's own options. */
|
|
62
|
+
export type Credentials = {
|
|
63
|
+
readonly npmToken: () => Secret | undefined;
|
|
64
|
+
};
|
|
65
|
+
/** What a library says of itself, read from its manifest. */
|
|
66
|
+
export type LibraryInfo = {
|
|
67
|
+
readonly name: string;
|
|
68
|
+
/** The package it publishes: its scope and name, or the one its manifest names in `publishes`. */
|
|
69
|
+
readonly package: string;
|
|
70
|
+
/** Its folder from the repository's root. */
|
|
71
|
+
readonly folder: string;
|
|
72
|
+
readonly version: string;
|
|
73
|
+
readonly level: string;
|
|
74
|
+
/** Its spec kit from its folder, where it has one. */
|
|
75
|
+
readonly specKit: string | undefined;
|
|
76
|
+
readonly npm: boolean;
|
|
77
|
+
/** Why the library is held out of the release, where it is: it has no tag, no registry and no set. */
|
|
78
|
+
readonly held: string | undefined;
|
|
79
|
+
readonly versionConstants: readonly VersionConstant[];
|
|
80
|
+
};
|
|
81
|
+
/** The port of the manifests: every library of the repository, or why they cannot be read. */
|
|
82
|
+
export type Libraries = {
|
|
83
|
+
readonly list: () => Promise<Result<readonly LibraryInfo[], string>>;
|
|
84
|
+
};
|
|
85
|
+
/** The world a verb runs in: the repository's root and every port. */
|
|
86
|
+
export type World = {
|
|
87
|
+
/** The absolute path of the repository's root. */
|
|
88
|
+
readonly repo: string;
|
|
89
|
+
readonly process: Process;
|
|
90
|
+
readonly files: Files;
|
|
91
|
+
readonly registry: Registry;
|
|
92
|
+
readonly credentials: Credentials;
|
|
93
|
+
readonly libraries: Libraries;
|
|
94
|
+
/** The documentation generator, loaded from the repository's own dependencies. */
|
|
95
|
+
readonly docs: DocsPort;
|
|
96
|
+
};
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import { type ChangeClass, type LibraryName, type Proof, type ProofTier, type SkipReason } from "@intellectual-frontiers/repoctl/governance";
|
|
2
|
+
import { type Mention, type SurfaceDelta, type Usage } from "./surface.js";
|
|
3
|
+
/** A file that changed: its path and its text at the base and now (none where it was not there). */
|
|
4
|
+
export type ChangedFile = {
|
|
5
|
+
readonly path: string;
|
|
6
|
+
readonly before: string | undefined;
|
|
7
|
+
readonly after: string | undefined;
|
|
8
|
+
};
|
|
9
|
+
/** A changed file with its class and the library whose folder holds it, where one does. */
|
|
10
|
+
export type ClassifiedFile = {
|
|
11
|
+
readonly path: string;
|
|
12
|
+
readonly class: ChangeClass;
|
|
13
|
+
readonly library: LibraryName | undefined;
|
|
14
|
+
};
|
|
15
|
+
/** What one library imports from another. */
|
|
16
|
+
export type Use = {
|
|
17
|
+
readonly provider: LibraryName;
|
|
18
|
+
readonly usage: Usage;
|
|
19
|
+
};
|
|
20
|
+
/** A library as the planner reads it: its place, what it imports from other libraries, whether it is foundation, and the systems it has code of its own for. */
|
|
21
|
+
export type LibraryNode = {
|
|
22
|
+
readonly name: LibraryName;
|
|
23
|
+
readonly package: string;
|
|
24
|
+
readonly folder: string;
|
|
25
|
+
readonly foundation: boolean;
|
|
26
|
+
readonly uses: readonly Use[];
|
|
27
|
+
readonly systems: readonly ("windows" | "macos")[];
|
|
28
|
+
};
|
|
29
|
+
/** The surface of one library as the planner needs it: how it differs from the base, and for each exported name the identifiers its declaration mentions. */
|
|
30
|
+
export type LibrarySurface = {
|
|
31
|
+
readonly delta: SurfaceDelta;
|
|
32
|
+
readonly mentions: readonly Mention[];
|
|
33
|
+
};
|
|
34
|
+
/** Everything the planner reads. */
|
|
35
|
+
export type ProofInput = {
|
|
36
|
+
readonly base: string;
|
|
37
|
+
/** Whether Git said what changed; where it did not, the plan is everything. */
|
|
38
|
+
readonly gitKnown: boolean;
|
|
39
|
+
/** Plan everything (`--all`). */
|
|
40
|
+
readonly all: boolean;
|
|
41
|
+
readonly changed: readonly ChangedFile[];
|
|
42
|
+
readonly libraries: readonly LibraryNode[];
|
|
43
|
+
readonly surfaces: ReadonlyMap<LibraryName, LibrarySurface>;
|
|
44
|
+
/** The libraries that read the files that no library holds. */
|
|
45
|
+
readonly outsideReaders: readonly LibraryName[];
|
|
46
|
+
};
|
|
47
|
+
/** Why a proof is in the plan. */
|
|
48
|
+
export type Why = {
|
|
49
|
+
readonly kind: "class";
|
|
50
|
+
readonly class: ChangeClass;
|
|
51
|
+
readonly files: number;
|
|
52
|
+
} | {
|
|
53
|
+
readonly kind: "surface";
|
|
54
|
+
readonly provider: LibraryName;
|
|
55
|
+
readonly symbols: readonly string[];
|
|
56
|
+
} | {
|
|
57
|
+
readonly kind: "surface-unknown";
|
|
58
|
+
readonly provider: LibraryName;
|
|
59
|
+
readonly why: string;
|
|
60
|
+
} | {
|
|
61
|
+
readonly kind: "foundation";
|
|
62
|
+
readonly library: LibraryName;
|
|
63
|
+
} | {
|
|
64
|
+
readonly kind: "everything";
|
|
65
|
+
readonly because: string;
|
|
66
|
+
};
|
|
67
|
+
/** A proof of the plan with its tier and why. */
|
|
68
|
+
export type PlannedProof = {
|
|
69
|
+
readonly proof: Proof;
|
|
70
|
+
readonly tier: ProofTier;
|
|
71
|
+
readonly why: Why;
|
|
72
|
+
};
|
|
73
|
+
/** A proof left out, the tier it would have been in, what it would have proved, the reason and the sentence that says why leaving it out is safe. */
|
|
74
|
+
export type SkippedProof = {
|
|
75
|
+
readonly tier: ProofTier;
|
|
76
|
+
readonly subject: string;
|
|
77
|
+
readonly reason: SkipReason;
|
|
78
|
+
readonly because: string;
|
|
79
|
+
};
|
|
80
|
+
/** The proof plan of a change. */
|
|
81
|
+
export type ProofPlan = {
|
|
82
|
+
readonly base: string;
|
|
83
|
+
readonly files: readonly ClassifiedFile[];
|
|
84
|
+
readonly classes: readonly ChangeClass[];
|
|
85
|
+
readonly proofs: readonly PlannedProof[];
|
|
86
|
+
readonly skipped: readonly SkippedProof[];
|
|
87
|
+
readonly libraries: {
|
|
88
|
+
readonly total: number;
|
|
89
|
+
readonly proven: readonly LibraryName[];
|
|
90
|
+
};
|
|
91
|
+
};
|
|
92
|
+
/** The planner's answer: the plan, or the libraries whose surface it needs first. */
|
|
93
|
+
export type PlanStep = {
|
|
94
|
+
readonly kind: "plan";
|
|
95
|
+
readonly plan: ProofPlan;
|
|
96
|
+
} | {
|
|
97
|
+
readonly kind: "needs";
|
|
98
|
+
readonly libraries: readonly LibraryName[];
|
|
99
|
+
};
|
|
100
|
+
/** The class of a changed file, by its path and its content at the base and now; `libraryOf` says which library's folder holds a path. */
|
|
101
|
+
export declare function classifyFile(change: ChangedFile, libraryOf: (path: string) => LibraryName | undefined): ClassifiedFile;
|
|
102
|
+
/** The classes of the files, in the order of the table, each once. */
|
|
103
|
+
export declare function classesOf(files: readonly ClassifiedFile[]): readonly ChangeClass[];
|
|
104
|
+
/** The library whose folder holds a path of the repository, among these. */
|
|
105
|
+
export declare function libraryOfPath(libraries: readonly {
|
|
106
|
+
readonly name: LibraryName;
|
|
107
|
+
readonly folder: string;
|
|
108
|
+
}[]): (path: string) => LibraryName | undefined;
|
|
109
|
+
/** The proofs of every tier for these libraries: what a change to the planner, `--all` and the release plan. */
|
|
110
|
+
export declare function everything(libraries: readonly LibraryNode[], why: Why): readonly PlannedProof[];
|
|
111
|
+
/** The sentence that says why a proof is in the plan. */
|
|
112
|
+
export declare function whySentence(w: Why): string;
|
|
113
|
+
/** The sentence that says why leaving a proof out is safe. */
|
|
114
|
+
export declare function skipSentence(s: SkippedProof): string;
|
|
115
|
+
/** A name of the proof for a person. */
|
|
116
|
+
export declare function proofLabel(p: Proof): string;
|
|
117
|
+
/** The plan of a change, or the libraries whose surface it needs to be given first. */
|
|
118
|
+
export declare function planProof(input: ProofInput): PlanStep;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { type Secret } from "@intellectual-frontiers/headless/logical";
|
|
2
|
+
import { type Finding } from "./findings.js";
|
|
3
|
+
import type { World } from "./ports.js";
|
|
4
|
+
/** One release of the record: a library, its version, its folder and its tag, and whether it goes to npm. */
|
|
5
|
+
export type ReleaseEntry = {
|
|
6
|
+
readonly slug: string;
|
|
7
|
+
readonly package: string;
|
|
8
|
+
readonly version: string;
|
|
9
|
+
readonly folder: string;
|
|
10
|
+
readonly tag: string;
|
|
11
|
+
readonly publish: boolean;
|
|
12
|
+
};
|
|
13
|
+
/** What is to happen to one release. */
|
|
14
|
+
export type Item = {
|
|
15
|
+
readonly kind: "ready";
|
|
16
|
+
readonly entry: ReleaseEntry;
|
|
17
|
+
readonly tarball: string;
|
|
18
|
+
} | {
|
|
19
|
+
readonly kind: "present";
|
|
20
|
+
readonly entry: ReleaseEntry;
|
|
21
|
+
} | {
|
|
22
|
+
readonly kind: "no-tarball";
|
|
23
|
+
readonly entry: ReleaseEntry;
|
|
24
|
+
readonly tarball: string;
|
|
25
|
+
} | {
|
|
26
|
+
readonly kind: "unknown";
|
|
27
|
+
readonly entry: ReleaseEntry;
|
|
28
|
+
readonly why: string;
|
|
29
|
+
};
|
|
30
|
+
/** The plan of a publication: what each release comes to, and the phrase that confirms it. */
|
|
31
|
+
export type PublishPlan = {
|
|
32
|
+
readonly items: readonly Item[];
|
|
33
|
+
readonly phrase: string;
|
|
34
|
+
};
|
|
35
|
+
/** What happened to one release. */
|
|
36
|
+
export type Published = {
|
|
37
|
+
readonly kind: "published";
|
|
38
|
+
readonly entry: ReleaseEntry;
|
|
39
|
+
} | {
|
|
40
|
+
readonly kind: "present";
|
|
41
|
+
readonly entry: ReleaseEntry;
|
|
42
|
+
} | {
|
|
43
|
+
readonly kind: "failed";
|
|
44
|
+
readonly entry: ReleaseEntry;
|
|
45
|
+
readonly detail: readonly string[];
|
|
46
|
+
} | {
|
|
47
|
+
readonly kind: "not-run";
|
|
48
|
+
readonly entry: ReleaseEntry;
|
|
49
|
+
readonly why: string;
|
|
50
|
+
};
|
|
51
|
+
/** The absolute path of the tarball the packer makes for a release: `dist/<scope>-<package>-<version>.tgz` in the library's folder. */
|
|
52
|
+
export declare function tarballPath(repo: string, e: ReleaseEntry): string;
|
|
53
|
+
/** The phrase that confirms a publication: the word, how many packages go, and the start of a digest of which (`publish 3 1a2b3c4d`), so that what was reviewed is what is sent. */
|
|
54
|
+
export declare function confirmationPhrase(entries: readonly ReleaseEntry[]): string;
|
|
55
|
+
/** The releases of the record that are not tagged yet and go to npm, as the plan: each with its tarball, or why it cannot be sent. */
|
|
56
|
+
export declare function planPublish(w: Pick<World, "files" | "registry" | "repo">, entries: readonly ReleaseEntry[], tagged: ReadonlySet<string>): Promise<PublishPlan>;
|
|
57
|
+
/** Whether the publication may go on: the token is there and the typed phrase is the plan's. The reasons otherwise. */
|
|
58
|
+
export declare function gate(input: {
|
|
59
|
+
readonly token: Secret | undefined;
|
|
60
|
+
readonly typed: string | undefined;
|
|
61
|
+
readonly phrase: string;
|
|
62
|
+
}): readonly Finding[];
|
|
63
|
+
/** The text of the private npmrc: the one line that gives npm the credential for the registry. It is written only to a file of mode 0600 in a folder that is removed. */
|
|
64
|
+
export declare function npmrcText(token: Secret): string;
|
|
65
|
+
/** Publishes what the plan says is ready, one release at a time, and gives what happened to each. Nothing it reports holds the token. */
|
|
66
|
+
export declare function runPublish(w: Pick<World, "files" | "process" | "repo">, plan: PublishPlan, token: Secret): Promise<readonly Published[]>;
|
|
67
|
+
/** The findings of a publication: a release that failed or could not be tried. */
|
|
68
|
+
export declare function findingsOfPublish(done: readonly Published[]): readonly Finding[];
|
|
69
|
+
/** What is said of the versions that were sent: npm stages a hand publish for about an hour, so `status` may not list it at once; nothing says it is live. */
|
|
70
|
+
export declare const STAGED_NOTE = "npm stages a version published by hand for about an hour: `repoctl status` lists it once npm shows it, and the release workflow makes the tags";
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `repoctl new library <name>` (commons repoctl 0005-repoctl-library-commit-doctor FR-001 to FR-003): the files of a new library of commons, as data. A library is a folder with a manifest that declares the table of its layers (Kanon), a
|
|
3
|
+
* package, a typed `about.ts`, a specification kit with its first specification and the enforcement of it, a test that proves it, the tools `verify` runs, a TypeScript configuration and, made by the license program, its `LICENSE`.
|
|
4
|
+
* The name must be one the register accepts and one that no family holds. Pure: the same name, role and summary give the same files.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { filesOf } from "./scaffold.js";
|
|
9
|
+
* filesOf({ name: "widget", summary: "Widgets, made by the book." }).map((f) => f.path).includes("commons/widget/library.ts"); // true
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
15
|
+
import { type LibraryName } from "@intellectual-frontiers/repoctl/governance";
|
|
16
|
+
/** The roles a library is classified in, for the table of the README. */
|
|
17
|
+
export type Role = "foundation" | "pattern" | "program" | "standard";
|
|
18
|
+
/** Every role. */
|
|
19
|
+
export declare const ROLES: readonly Role[];
|
|
20
|
+
/** A name held for a family: the exact name or the prefix, and the host it is held for. */
|
|
21
|
+
export type Held = {
|
|
22
|
+
readonly match: {
|
|
23
|
+
readonly kind: "exact";
|
|
24
|
+
readonly name: string;
|
|
25
|
+
} | {
|
|
26
|
+
readonly kind: "prefix";
|
|
27
|
+
readonly prefix: string;
|
|
28
|
+
};
|
|
29
|
+
readonly host: string;
|
|
30
|
+
};
|
|
31
|
+
/** What a new library is given. */
|
|
32
|
+
export type NewLibrary = {
|
|
33
|
+
readonly name: string;
|
|
34
|
+
readonly summary: string; /** The folder (from the repository's root) the libraries are in. */
|
|
35
|
+
readonly folder: string;
|
|
36
|
+
};
|
|
37
|
+
/** A file to write: its path from the repository's root and its text. */
|
|
38
|
+
export type NewFile = {
|
|
39
|
+
readonly path: string;
|
|
40
|
+
readonly text: string;
|
|
41
|
+
};
|
|
42
|
+
/** The name, once it is one that is valid, not held for a family and not in use; or why not. */
|
|
43
|
+
export declare function acceptName(text: string, held: readonly Held[], existing: readonly string[], folder: string): Result<LibraryName, {
|
|
44
|
+
readonly code: "E-LIBRARY-NAME" | "E-LIBRARY-RESERVED" | "E-LIBRARY-EXISTS";
|
|
45
|
+
readonly message: string;
|
|
46
|
+
}>;
|
|
47
|
+
/** The title of a library from its name: `my-lib` is `My Lib`. */
|
|
48
|
+
export declare function titleOf(name: string): string;
|
|
49
|
+
/** The files of a new library. */
|
|
50
|
+
export declare function filesOf(l: NewLibrary): readonly NewFile[];
|
|
51
|
+
/** The README's map of the roles with a line added for the new library: after the last library of its role, or at the end of the map; the source unchanged where the library is there already. */
|
|
52
|
+
export declare function withRole(source: string, name: string, role: Role): Result<string, string>;
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which tests a change must run, and which it may leave out (commons repoctl 0008-repoctl-prove FR-011, FR-012, FR-014): a test runs when anything it transitively imports changed (the selector by imports), when a requirement named by
|
|
3
|
+
* a changed file's `// Spec:` line is proved by it (the selector by the trace register), or, for a seam, when its library imports a changed symbol of the provider; a test of a suite that reads the tree is never left out (a seam is about symbols, so it runs the tests that import them); a quarantined test is
|
|
4
|
+
* reported and not run until its expiry; and the key of a result in the cache is a hash of everything that decides it.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* The functions are pure: the Physical layer reads the files, resolves the imports and runs the tests, and these decide. A test leaves out only what it cannot reach, so the selectors only ever add a test to the run.
|
|
8
|
+
*
|
|
9
|
+
* @limits
|
|
10
|
+
* A test that reads a file by a path it builds at run time is found only where it names the checkout (`CHECKOUT`, `import.meta`, `process.cwd`): it is then `environmental` and runs whenever its library is proved.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* import { specIdsOf } from "./select.js";
|
|
15
|
+
* specIdsOf("// Spec: 0003-repoctl-sync FR-002, FR-003\n"); // ["0003-repoctl-sync FR-002", "0003-repoctl-sync FR-003"]
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
18
|
+
* @module
|
|
19
|
+
*/
|
|
20
|
+
import type { LibraryName, QuarantineEntry } from "@intellectual-frontiers/repoctl/governance";
|
|
21
|
+
import { type SurfaceDelta, type Usage } from "./surface.js";
|
|
22
|
+
/** A test file as the selectors read it: where it is, what it reaches, whether it reads the tree, which requirements it proves and what its library imports of other libraries through it. */
|
|
23
|
+
export type TestReach = {
|
|
24
|
+
readonly library: LibraryName;
|
|
25
|
+
/** The path from the repository's root. */
|
|
26
|
+
readonly path: string;
|
|
27
|
+
/** What it transitively imports: files, and folders (ending with `/`) where an import could not be resolved to a file. */
|
|
28
|
+
readonly depends: readonly string[];
|
|
29
|
+
/** Whether it reads the checkout, so that no change can be shown not to reach it. */
|
|
30
|
+
readonly environmental: boolean;
|
|
31
|
+
/** The requirements it proves, as `<spec> FR-nnn`. */
|
|
32
|
+
readonly proves: readonly string[];
|
|
33
|
+
/** What the files of its own library that it reaches import of each other library. */
|
|
34
|
+
readonly uses: readonly {
|
|
35
|
+
readonly provider: LibraryName;
|
|
36
|
+
readonly usage: Usage;
|
|
37
|
+
}[];
|
|
38
|
+
};
|
|
39
|
+
/** Why a test is in the run. */
|
|
40
|
+
export type Selector = "import" | "trace" | "symbol" | "environmental" | "everything";
|
|
41
|
+
/** The tests that run, each with why, and those left out. */
|
|
42
|
+
export type Selection = {
|
|
43
|
+
readonly run: readonly {
|
|
44
|
+
readonly test: TestReach;
|
|
45
|
+
readonly by: Selector;
|
|
46
|
+
}[];
|
|
47
|
+
readonly left: readonly TestReach[];
|
|
48
|
+
};
|
|
49
|
+
/** The requirements a text names on its `Spec:` lines, as `<spec> FR-nnn`, the list after a spec expanded. */
|
|
50
|
+
export declare function specIdsOf(text: string): readonly string[];
|
|
51
|
+
/** The requirements a test proves: the identifiers in its `proves([...])` calls. */
|
|
52
|
+
export declare function provesOf(text: string): readonly string[];
|
|
53
|
+
/** The specification a path of a specification's own folder names (`.../specs/0008-repoctl-prove/spec.md`), where it is one. */
|
|
54
|
+
export declare function specOfPath(path: string): string | undefined;
|
|
55
|
+
/** Whether a text reads the checkout: the tests that do are never left out. */
|
|
56
|
+
export declare function readsTheTree(text: string): boolean;
|
|
57
|
+
/** The tests of a suite that a change must run: by imports, by the trace register, and the ones that read the tree; the others are left out. `everything` runs them all (the plan is every proof). */
|
|
58
|
+
export declare function selectTests(tests: readonly TestReach[], changed: readonly {
|
|
59
|
+
readonly path: string;
|
|
60
|
+
readonly text: string;
|
|
61
|
+
}[], everything: boolean): Selection;
|
|
62
|
+
/** The tests of a consumer that a change of the symbols of a provider must run: those whose library files import one of them (or everything from the provider). */
|
|
63
|
+
export declare function selectSeam(tests: readonly TestReach[], provider: LibraryName, delta: SurfaceDelta): Selection;
|
|
64
|
+
/** The tests of a run split by the quarantine record on a day (`YYYY-MM-DD`): those that run, those held back with their entry, and the entries that have expired (their tests run again). */
|
|
65
|
+
export declare function applyQuarantine<T extends {
|
|
66
|
+
readonly test: TestReach;
|
|
67
|
+
}>(selected: readonly T[], entries: readonly QuarantineEntry[], today: string): {
|
|
68
|
+
readonly run: readonly T[];
|
|
69
|
+
readonly held: readonly {
|
|
70
|
+
readonly item: T;
|
|
71
|
+
readonly entry: QuarantineEntry;
|
|
72
|
+
}[];
|
|
73
|
+
readonly expired: readonly QuarantineEntry[];
|
|
74
|
+
};
|
|
75
|
+
/** The seeds and counterexamples a failing property test printed, so that a failure says how to reproduce it. */
|
|
76
|
+
export declare function seedsOf(output: string): readonly string[];
|
|
77
|
+
/** The key of a result: the same text for the same test, the same sources it imports and the same runtime, so that a cache holds a result by it. The hashes are given: one for the test, one for each source it imports. */
|
|
78
|
+
export declare function cacheKeyOf(parts: {
|
|
79
|
+
readonly runtime: string;
|
|
80
|
+
readonly library: LibraryName;
|
|
81
|
+
readonly test: string;
|
|
82
|
+
readonly hashes: readonly (readonly [string, string])[];
|
|
83
|
+
}): string;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The order of versions (commons repoctl 0004-repoctl-status-release FR-001): the greatest of some versions of Semantic Versioning, by their numbers, a pre-release coming before the same numbers without one. Pure.
|
|
3
|
+
*
|
|
4
|
+
* @example
|
|
5
|
+
* ```ts
|
|
6
|
+
* import { compareSemver, greatest } from "./semver.js";
|
|
7
|
+
* compareSemver("0.10.0", "0.9.9"); // 1
|
|
8
|
+
* greatest(["1.0.0-rc.1", "1.0.0", "0.9.0"]); // "1.0.0"
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
/** -1, 0 or 1 as `a` is before, the same as, or after `b`; a text that is not a version is before every version. */
|
|
14
|
+
export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
|
|
15
|
+
/** The greatest of some versions, or undefined where there are none. */
|
|
16
|
+
export declare function greatest(versions: readonly string[]): string | undefined;
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `repoctl status` (commons repoctl 0004-repoctl-status-release FR-001 to FR-003): for each library of the repository, its version in the repository, the version npm shows and the version of its greatest tag, as rows (a table
|
|
3
|
+
* for a person, JSON for a program). What npm shows is reported as it shows it: a version that was published a short while ago may not be listed yet, and nothing here guesses that it is on its way. `--offline` asks no network:
|
|
4
|
+
* npm is not asked and the tags are those of the local clone.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { tagsOf } from "./status.js";
|
|
9
|
+
* tagsOf("abc\trefs/tags/core-v0.1.0\nabc\trefs/tags/core-v0.1.0^{}\n").get("core"); // ["0.1.0"]
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import type { Result } from "@intellectual-frontiers/core";
|
|
15
|
+
import { type Finding } from "./findings.js";
|
|
16
|
+
import type { LibraryInfo, World } from "./ports.js";
|
|
17
|
+
/** What npm shows of a library's package. */
|
|
18
|
+
export type NpmCell = {
|
|
19
|
+
readonly kind: "skipped";
|
|
20
|
+
} | {
|
|
21
|
+
readonly kind: "not-published";
|
|
22
|
+
} | {
|
|
23
|
+
readonly kind: "absent";
|
|
24
|
+
} | {
|
|
25
|
+
readonly kind: "unreachable";
|
|
26
|
+
readonly why: string;
|
|
27
|
+
} | {
|
|
28
|
+
readonly kind: "found";
|
|
29
|
+
readonly latest: string | undefined;
|
|
30
|
+
readonly hasRepoVersion: boolean;
|
|
31
|
+
};
|
|
32
|
+
/** What the tags show of a library. */
|
|
33
|
+
export type TagCell = {
|
|
34
|
+
readonly kind: "unreachable";
|
|
35
|
+
readonly why: string;
|
|
36
|
+
} | {
|
|
37
|
+
readonly kind: "none";
|
|
38
|
+
readonly source: "remote" | "local";
|
|
39
|
+
} | {
|
|
40
|
+
readonly kind: "found";
|
|
41
|
+
readonly latest: string;
|
|
42
|
+
readonly hasRepoVersion: boolean;
|
|
43
|
+
readonly source: "remote" | "local";
|
|
44
|
+
};
|
|
45
|
+
/** Where a library stands, from the three versions. */
|
|
46
|
+
export type State = "released" | "unpublished" | "untagged" | "unknown" | "held";
|
|
47
|
+
/** One row of the status. */
|
|
48
|
+
export type Row = {
|
|
49
|
+
readonly library: string;
|
|
50
|
+
readonly repo: string;
|
|
51
|
+
readonly npm: NpmCell;
|
|
52
|
+
readonly tag: TagCell;
|
|
53
|
+
readonly state: State;
|
|
54
|
+
};
|
|
55
|
+
/** The status: its rows, in the order of the libraries' names. */
|
|
56
|
+
export type StatusReport = {
|
|
57
|
+
readonly offline: boolean;
|
|
58
|
+
readonly rows: readonly Row[];
|
|
59
|
+
};
|
|
60
|
+
/** The versions each library is tagged at, from the lines of `git ls-remote --tags` (a sha, a tab, the reference) or of `git tag --list` (the name alone). */
|
|
61
|
+
export declare function tagsOf(text: string): ReadonlyMap<string, readonly string[]>;
|
|
62
|
+
/** Where a library stands: it is released when npm holds its repository version (or it is not on npm) and its tag is made; what is not known is unknown. */
|
|
63
|
+
export declare function stateOf(lib: Pick<LibraryInfo, "npm" | "held">, npm: NpmCell, tag: TagCell): State;
|
|
64
|
+
/** Reads the status of every library. The error is why the libraries or the tags could not be read at all. */
|
|
65
|
+
export declare function runStatus(w: World, options: {
|
|
66
|
+
readonly offline: boolean;
|
|
67
|
+
}): Promise<Result<StatusReport, string>>;
|
|
68
|
+
/** The findings of a status: a registry or a tag list that could not be read, as warnings. */
|
|
69
|
+
export declare function findingsOfStatus(r: StatusReport): readonly Finding[];
|
|
70
|
+
/** The table of a status for a person: one line for each library, columns aligned. */
|
|
71
|
+
export declare function tableOf(r: StatusReport): string;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a step of a configuration is run (commons repoctl 0003-repoctl-sync FR-002; 0009-repoctl-config FR-003): a program goes through the port that runs programs, from the repository's root; a typed function is called with the root. A function that throws is
|
|
3
|
+
* a run that could not be made (status 2 with the message), never a throw of the verb.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { runStep } from "./step.js";
|
|
8
|
+
* const world = { repo: "/r", process: { run: () => Promise.resolve({ code: 0, stdout: "", stderr: "" }) } };
|
|
9
|
+
* const r = await runStep(world, { kind: "function", label: "f", call: () => Promise.resolve({ code: 1, stdout: "", stderr: "x" }) });
|
|
10
|
+
* r.code; // 1
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import type { Step } from "@intellectual-frontiers/repoctl/governance";
|
|
16
|
+
import type { Run, World } from "./ports.js";
|
|
17
|
+
/** Runs a step in the world: the program from the repository's root, or the function with it. */
|
|
18
|
+
export declare function runStep(w: Pick<World, "process" | "repo">, step: Step): Promise<Run>;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The public type surface of a library as values (commons repoctl 0008-repoctl-prove FR-006 to FR-008): the declarations a compiler emitted for its sources, read statement by statement, each exported one with the declarations local to
|
|
3
|
+
* its file that it can mention; the fingerprint of the surface (a hash of each declaration, by name); the names that changed between two fingerprints; and what a source imports from a package, by name. The functions are pure: the
|
|
4
|
+
* Physical layer emits the declarations and hashes the texts, and these decide what changed and who uses it.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* A declaration file is regular enough to be cut by depth: a statement ends at a semicolon outside every bracket, or at the brace that closes a block declaration (`interface`, `class`, `namespace`, `enum`) when a new statement
|
|
8
|
+
* follows. Comments are removed by the compiler; the scanner also skips them and strings, so a comment that holds a brace changes nothing.
|
|
9
|
+
*
|
|
10
|
+
* @limits
|
|
11
|
+
* A name is the key of a declaration, so two declarations of one name in two files of a library are one entry with both texts; an overload is one entry. A change that only moves a declaration to another file leaves its entry as it was.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```ts
|
|
15
|
+
* import { declarationsOf, importsOf } from "./surface.js";
|
|
16
|
+
* declarationsOf("a.d.ts", "export declare function f(x: number): string;\n").map((d) => d.name); // ["f"]
|
|
17
|
+
* importsOf('import { a, type B } from "@x/y/z";', "@x/y"); // { all: false, names: ["a", "B"] }
|
|
18
|
+
* ```
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
/** One exported declaration: the file it is in, its name, and its text with the declarations local to the file that it can mention. */
|
|
23
|
+
export type Declaration = {
|
|
24
|
+
readonly file: string;
|
|
25
|
+
readonly name: string;
|
|
26
|
+
readonly text: string;
|
|
27
|
+
};
|
|
28
|
+
/** What a source imports from a package: every name (a namespace import, a re-export of everything, a dynamic import) or these names. */
|
|
29
|
+
export type Usage = {
|
|
30
|
+
readonly all: boolean;
|
|
31
|
+
readonly names: readonly string[];
|
|
32
|
+
};
|
|
33
|
+
/** The fingerprint of a surface: each exported name with the hash of its declarations. */
|
|
34
|
+
export type Fingerprint = ReadonlyMap<string, string>;
|
|
35
|
+
/** How a library's surface differs between two states: not at all, in these names, or in a way that cannot be told. */
|
|
36
|
+
export type SurfaceDelta = {
|
|
37
|
+
readonly kind: "same";
|
|
38
|
+
} | {
|
|
39
|
+
readonly kind: "changed";
|
|
40
|
+
readonly symbols: readonly string[];
|
|
41
|
+
} | {
|
|
42
|
+
readonly kind: "unknown";
|
|
43
|
+
readonly why: string;
|
|
44
|
+
};
|
|
45
|
+
/** The text of TypeScript or JavaScript without its comments, the strings, templates and regular expressions kept as they are. */
|
|
46
|
+
export declare function stripComments(text: string): string;
|
|
47
|
+
/** The code of a text with its comments removed and its white space made one space: two texts that differ only in comments or layout are the same. */
|
|
48
|
+
export declare function codeOf(text: string): string;
|
|
49
|
+
/** The statements of a declaration file, each as its text. */
|
|
50
|
+
export declare function statementsOf(text: string): readonly string[];
|
|
51
|
+
/** The names a statement exports; none where it exports nothing. */
|
|
52
|
+
export declare function exportedNames(statement: string): readonly string[];
|
|
53
|
+
/** The exported declarations of one declaration file, each with the file's local declarations that it can mention. */
|
|
54
|
+
export declare function declarationsOf(file: string, text: string): readonly Declaration[];
|
|
55
|
+
/** The fingerprint of declarations: each name with the hash of its texts, sorted and joined, so that moving a declaration to another file changes nothing and the order of files changes nothing. */
|
|
56
|
+
export declare function fingerprintOf(declarations: readonly Declaration[], hash: (text: string) => string): Fingerprint;
|
|
57
|
+
/** The names whose hash differs, that appeared or that went away between two fingerprints, sorted. */
|
|
58
|
+
export declare function surfaceDelta(base: Fingerprint, now: Fingerprint): SurfaceDelta;
|
|
59
|
+
/** An exported name and the identifiers its declaration mentions (with the declarations local to its file). */
|
|
60
|
+
export type Mention = {
|
|
61
|
+
readonly name: string;
|
|
62
|
+
readonly mentions: readonly string[];
|
|
63
|
+
};
|
|
64
|
+
/** For each exported name, the identifiers its declarations mention: what a changed name could reach through a library's own surface. */
|
|
65
|
+
export declare function mentionsOf(declarations: readonly Declaration[]): readonly Mention[];
|
|
66
|
+
/** The package a specifier names: `@scope/name` or `name`, without the subpath; none for a relative path. */
|
|
67
|
+
export declare function packageOf(specifier: string): string | undefined;
|
|
68
|
+
/** What a source imports from each package it imports (the subpaths of one package together): the names, or all of them where the import cannot say which. */
|
|
69
|
+
export declare function usagesOf(text: string): ReadonlyMap<string, Usage>;
|
|
70
|
+
/** What a source imports from a package (the package name, or any subpath of it). */
|
|
71
|
+
export declare function importsOf(text: string, pkg: string): Usage;
|
|
72
|
+
/** The union of usages. */
|
|
73
|
+
export declare function joinUsage(a: Usage, b: Usage): Usage;
|