@intellectual-frontiers/ergonex 0.2.6 → 0.3.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/README.md +2 -0
- package/dist/desired.d.ts +27 -0
- package/dist/diff.d.ts +12 -0
- package/dist/doctor.d.ts +79 -0
- package/dist/findings.d.ts +85 -0
- package/dist/layout.d.ts +83 -0
- package/dist/manifest.d.ts +84 -0
- package/dist/mod.d.ts +29 -0
- package/dist/mod.js +4219 -0
- package/dist/modules/external.d.ts +31 -0
- package/dist/modules/mod.d.ts +10 -0
- package/dist/modules/name.d.ts +32 -0
- package/dist/modules/registry.d.ts +51 -0
- package/dist/modules/types.d.ts +178 -0
- package/dist/places.d.ts +35 -0
- package/dist/plan.d.ts +176 -0
- package/dist/platform/k-args.d.ts +28 -0
- package/dist/policy.d.ts +39 -0
- package/dist/portable.d.ts +111 -0
- package/dist/render.d.ts +95 -0
- package/dist/setup/evidence.d.ts +58 -0
- package/dist/shell/block.d.ts +45 -0
- package/dist/shell/mod.d.ts +8 -0
- package/dist/shell/snippet.d.ts +43 -0
- package/dist/state-record.d.ts +59 -0
- package/dist/state.d.ts +64 -0
- package/dist/templates/data.d.ts +25 -0
- package/dist/templates/hooks.d.ts +13 -0
- package/dist/templates/mod.d.ts +16 -0
- package/dist/tools/catalog.d.ts +70 -0
- package/dist/types.d.ts +51 -0
- package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
- package/dist/vendor/ts/githost/git.d.ts +16 -0
- package/dist/vendor/ts/githost/github.d.ts +15 -0
- package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
- package/dist/vendor/ts/githost/mod.d.ts +29 -0
- package/dist/vendor/ts/githost/remote.d.ts +59 -0
- package/dist/vendor/ts/githost/types.d.ts +101 -0
- package/dist/vendor/ts/kernel/archive.d.ts +147 -0
- package/dist/vendor/ts/kernel/args.d.ts +240 -0
- package/dist/vendor/ts/kernel/assess.d.ts +247 -0
- package/dist/vendor/ts/kernel/attest.d.ts +164 -0
- package/dist/vendor/ts/kernel/base64.d.ts +24 -0
- package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
- package/dist/vendor/ts/kernel/cms.d.ts +106 -0
- package/dist/vendor/ts/kernel/commands.d.ts +103 -0
- package/dist/vendor/ts/kernel/cose.d.ts +34 -0
- package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
- package/dist/vendor/ts/kernel/csv.d.ts +38 -0
- package/dist/vendor/ts/kernel/der.d.ts +67 -0
- package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
- package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
- package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
- package/dist/vendor/ts/kernel/glob.d.ts +64 -0
- package/dist/vendor/ts/kernel/grc.d.ts +356 -0
- package/dist/vendor/ts/kernel/http.d.ts +46 -0
- package/dist/vendor/ts/kernel/json5.d.ts +46 -0
- package/dist/vendor/ts/kernel/layers.d.ts +35 -0
- package/dist/vendor/ts/kernel/md5.d.ts +19 -0
- package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
- package/dist/vendor/ts/kernel/mod.d.ts +95 -0
- package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
- package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
- package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
- package/dist/vendor/ts/kernel/otel.d.ts +365 -0
- package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
- package/dist/vendor/ts/kernel/palette.d.ts +44 -0
- package/dist/vendor/ts/kernel/png.d.ts +124 -0
- package/dist/vendor/ts/kernel/rdf-schema.d.ts +190 -0
- package/dist/vendor/ts/kernel/rdf-term.d.ts +162 -0
- package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +148 -0
- package/dist/vendor/ts/kernel/rdf-write.d.ts +25 -0
- package/dist/vendor/ts/kernel/rdf.d.ts +35 -0
- package/dist/vendor/ts/kernel/render.d.ts +111 -0
- package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
- package/dist/vendor/ts/kernel/semver.d.ts +94 -0
- package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
- package/dist/vendor/ts/kernel/signals.d.ts +371 -0
- package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
- package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
- package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
- package/dist/vendor/ts/kernel/toml.d.ts +51 -0
- package/dist/vendor/ts/kernel/trace.d.ts +169 -0
- package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
- package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
- package/dist/vendor/ts/kernel/vt.d.ts +78 -0
- package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
- package/dist/vendor/ts/kernel/width.d.ts +63 -0
- package/dist/vendor/ts/kernel/xml.d.ts +73 -0
- package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
- package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
- package/ergonex.mjs +137 -138
- package/package.json +17 -5
package/README.md
CHANGED
|
@@ -8,4 +8,6 @@ bunx @intellectual-frontiers/ergonex init # with Bun; with Node 26: npx @int
|
|
|
8
8
|
|
|
9
9
|
It makes the workspace folder, puts `ergonex` on your path and says what to do next. `ergonex doctor` checks the workspace and says what to fix.
|
|
10
10
|
|
|
11
|
+
The package is also a library: `import { ... } from "@intellectual-frontiers/ergonex"` gives the plan, the manifest, the layout and the host, with their types.
|
|
12
|
+
|
|
11
13
|
The sources and the specifications are in https://github.com/intellectual-frontiers/.github/tree/main/commons/ergonex
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the manifest wants, as the plan reads it (commons 0002-workspace-model FR-021, 0003-host FR-013): the repositories with the settings of their own local Git configuration, the worktrees,
|
|
3
|
+
* and the generated files with the SHA-256 of their bytes. The target state of the source state.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* The settings are only ever those of a repository's local configuration, never the global or the system's: `core.hooksPath` (the absolute path of `<home>/.ergonex/hooks`, with `/` between
|
|
7
|
+
* segments), the commit signing the policy requires (`commit.gpgsign`, `gpg.format`, `user.signingkey`), `user.name` and `user.email` where the manifest names them, and on Windows `core.longpaths`.
|
|
8
|
+
* Pure: the root and the platform are arguments.
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { type Sha256 } from "./vendor/ts/kernel/mod.js";
|
|
13
|
+
import type { Manifest } from "./manifest.js";
|
|
14
|
+
import type { Desired } from "./plan.js";
|
|
15
|
+
import { type GeneratedFile } from "./render.js";
|
|
16
|
+
/** What the settings depend on besides the manifest. */
|
|
17
|
+
export type DesiredFacts = {
|
|
18
|
+
/** The root, as an absolute path with `/` between segments (`C:/Users/a/workspaces` on Windows). */
|
|
19
|
+
readonly homePosix: string;
|
|
20
|
+
readonly windows: boolean;
|
|
21
|
+
};
|
|
22
|
+
/** The settings of every managed repository's local configuration, key to value. */
|
|
23
|
+
export declare function settingsOf(manifest: Manifest, facts: DesiredFacts): Readonly<Record<string, string>>;
|
|
24
|
+
/** What the manifest and its generated files want. */
|
|
25
|
+
export declare function desiredOf(manifest: Manifest, files: readonly GeneratedFile[], facts: DesiredFacts): Promise<Desired>;
|
|
26
|
+
/** The digest of a set of files by path, which `verify` and `render` compare with the disk and the record. */
|
|
27
|
+
export declare function digestsOf(files: readonly GeneratedFile[]): Promise<ReadonlyMap<string, Sha256>>;
|
package/dist/diff.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A unified diff of two texts (commons 0003-host FR-012, FR-019): what `ergonex render --diff` shows of a generated file that would change, and what `ergonex shell --install` shows of the one
|
|
3
|
+
* block it would write, so that a person sees the exact change before it is made.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* The lines are compared by a longest common subsequence, which is exact and, for the files of a workspace (a few hundred lines), small. The hunks carry three lines of context, as `diff -u` does,
|
|
7
|
+
* and a text with no difference gives no hunk and an empty string. Line endings are LF here; a caller normalizes first.
|
|
8
|
+
*
|
|
9
|
+
* @module
|
|
10
|
+
*/
|
|
11
|
+
/** The unified diff from `before` to `after`, headed by `--- a/<name>` and `+++ b/<name>`; an empty string where the texts are equal. */
|
|
12
|
+
export declare function unifiedDiff(name: string, before: string, after: string): string;
|
package/dist/doctor.d.ts
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import type { Finding, Severity } from "./findings.js";
|
|
2
|
+
import type { RepoPath } from "./types.js";
|
|
3
|
+
/** What a check came to: the four words of `ergonex doctor`. */
|
|
4
|
+
export type Level = "ok" | "suggest" | "warn" | "error";
|
|
5
|
+
/** One check and what it found. */
|
|
6
|
+
export type Check = {
|
|
7
|
+
/** The rule, such as `ergonex/path-too-long`. */
|
|
8
|
+
readonly id: string;
|
|
9
|
+
readonly level: Level;
|
|
10
|
+
/** What it is about: a path, a tool, a repository. */
|
|
11
|
+
readonly subject: string;
|
|
12
|
+
/** What is wrong and what to do about it, or, for `ok`, what was found. */
|
|
13
|
+
readonly message: string;
|
|
14
|
+
};
|
|
15
|
+
/** The severity a level becomes; `ok` is none. */
|
|
16
|
+
export declare function severityOf(level: Level): Severity | undefined;
|
|
17
|
+
/** The findings of a list of checks, each first seen `today`. */
|
|
18
|
+
export declare function findingsOf(checks: readonly Check[], today: string): readonly Finding[];
|
|
19
|
+
/** What a probe of the root's file system found, or why it was not made. */
|
|
20
|
+
export type FsProbe = {
|
|
21
|
+
readonly kind: "found";
|
|
22
|
+
readonly type: string;
|
|
23
|
+
readonly wsl: boolean;
|
|
24
|
+
} | {
|
|
25
|
+
readonly kind: "not-run";
|
|
26
|
+
readonly reason: string;
|
|
27
|
+
};
|
|
28
|
+
/** The kinds of file system the workspace warns about. */
|
|
29
|
+
export type FsKind = "ok" | "fat" | "exfat" | "network" | "wsl-windows-drive";
|
|
30
|
+
/** The kind of a file system by the type a probe reported (`vfat`, `exfat`, `nfs`, `9p`), and whether the system is WSL. */
|
|
31
|
+
export declare function classifyFs(type: string, wsl: boolean): FsKind;
|
|
32
|
+
/** The check of the file system of the root. */
|
|
33
|
+
export declare function fsCheck(probe: FsProbe, home: string): Check;
|
|
34
|
+
/** What is known of the version of a tool. */
|
|
35
|
+
export type ToolProbe = {
|
|
36
|
+
readonly name: string;
|
|
37
|
+
readonly version: string | undefined;
|
|
38
|
+
};
|
|
39
|
+
/** The oldest Node `ergonex` runs on (Node 26 is the backup runtime). */
|
|
40
|
+
export declare const MIN_NODE_MAJOR = 26;
|
|
41
|
+
/** The checks of the runtime and of the tools: git must be there; the runtime must be Bun, or Node 26 or later; the other runtime, where it is missing, is a suggestion. */
|
|
42
|
+
export declare function runtimeChecks(runtime: {
|
|
43
|
+
readonly name: "bun" | "node";
|
|
44
|
+
readonly version: string;
|
|
45
|
+
}, tools: readonly ToolProbe[]): readonly Check[];
|
|
46
|
+
/** What the long-path setting of Windows is. */
|
|
47
|
+
export type LongPaths = "enabled" | "disabled" | "unknown";
|
|
48
|
+
/** What the path checks are given. */
|
|
49
|
+
export type PathFacts = {
|
|
50
|
+
readonly home: string;
|
|
51
|
+
readonly windows: boolean;
|
|
52
|
+
readonly longPaths: LongPaths;
|
|
53
|
+
/** Every path of the workspace the manifest and the templates name: repositories, worktrees, generated files. */
|
|
54
|
+
readonly paths: readonly RepoPath[];
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* The checks of path length (0002-workspace-model FR-012, FR-036): on Windows while long paths are off, a path longer than 259 characters is an error naming it and saying that `ergonex setup` can turn
|
|
58
|
+
* long paths on; and that long paths are not enabled is informational while no path exceeds the limit. Elsewhere the limit does not apply.
|
|
59
|
+
*/
|
|
60
|
+
export declare function pathChecks(f: PathFacts): readonly Check[];
|
|
61
|
+
/**
|
|
62
|
+
* The checks of the length of each repository's own path (0002-workspace-model FR-048), on every system: over 150 characters is informational (it leaves little room for the files inside the repository),
|
|
63
|
+
* over 259 an error whether or not long paths are enabled. A repository whose path fits has no check of its own.
|
|
64
|
+
*/
|
|
65
|
+
export declare function repoPathChecks(f: {
|
|
66
|
+
readonly home: string;
|
|
67
|
+
readonly windows: boolean;
|
|
68
|
+
readonly repositories: readonly RepoPath[];
|
|
69
|
+
}): readonly Check[];
|
|
70
|
+
/** What is known of a repository's hooks. */
|
|
71
|
+
export type HookFacts = {
|
|
72
|
+
readonly repo: RepoPath;
|
|
73
|
+
/** The repository is on disk (its state is not `Missing`). */
|
|
74
|
+
readonly present: boolean;
|
|
75
|
+
/** The repository's local `core.hooksPath`, if it sets one. */
|
|
76
|
+
readonly hooksPath: string | undefined;
|
|
77
|
+
};
|
|
78
|
+
/** The checks of the hooks: a repository on disk whose local `core.hooksPath` is not the workspace's is a warning that says to run `ergonex apply`. */
|
|
79
|
+
export declare function hookChecks(facts: readonly HookFacts[], wantedHooksPath: string): readonly Check[];
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a check of the workspace reports (commons 0002-workspace-model FR-033, FR-035): a finding has a rule, a severity (`ergonex:Informational`, `ergonex:Warning`, `ergonex:Error`), a message, what it is
|
|
3
|
+
* about and the day it was first seen; it is written as a SARIF 2.1.0 log whose results have the level of the severity; and a finding about something outside the catalog grows from informational
|
|
4
|
+
* to a warning once it is more than the grace days old, counted from the day first seen and never restarted by a later run.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Days are `YYYY-MM-DD` texts, and every function takes the day it needs as an argument: nothing here reads a clock. A finding's message says what is wrong and what to do, and holds no secret:
|
|
8
|
+
* the caller gives the file and the line, never the line's text.
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
13
|
+
/** The severities of a finding, the keys of the code list `ergonex:Severity`. */
|
|
14
|
+
export type Severity = "Informational" | "Warning" | "Error";
|
|
15
|
+
/** All the severities, least serious first. */
|
|
16
|
+
export declare const SEVERITIES: readonly Severity[];
|
|
17
|
+
/** What a check reports. */
|
|
18
|
+
export type Finding = {
|
|
19
|
+
/** The rule that found it, such as `ergonex/path-too-long`. */
|
|
20
|
+
readonly ruleId: string;
|
|
21
|
+
readonly severity: Severity;
|
|
22
|
+
/** What is wrong and what to do about it. */
|
|
23
|
+
readonly message: string;
|
|
24
|
+
/** What it is about: a path, a repository, a tool. */
|
|
25
|
+
readonly subject: string;
|
|
26
|
+
/** The day it was first seen, `YYYY-MM-DD`. */
|
|
27
|
+
readonly firstSeen: string;
|
|
28
|
+
};
|
|
29
|
+
/** The SARIF level of a severity, the `ergonex:sarifLevel` of the code list. */
|
|
30
|
+
export declare function sarifLevel(severity: Severity): "note" | "warning" | "error";
|
|
31
|
+
/** The most serious severity of a list, or undefined for none. */
|
|
32
|
+
export declare function worst(findings: readonly Finding[]): Severity | undefined;
|
|
33
|
+
/** The exit status of a run with these findings: `Findings` where one is a warning or an error, `Ok` where there is none or all are informational (0001-ergonex FR-010). */
|
|
34
|
+
export declare function exitStatusOf(findings: readonly Finding[]): "Ok" | "Findings";
|
|
35
|
+
/** A day as the number of days since 1970-01-01, or undefined where the text is not a real day. */
|
|
36
|
+
export declare function dayNumber(day: string): number | undefined;
|
|
37
|
+
/** The whole days from one day to another (negative where `to` is before `from`), or an error naming the text that is not a day. */
|
|
38
|
+
export declare function daysBetween(from: string, to: string): Result<number, string>;
|
|
39
|
+
/** The grace period of a tool or module outside the catalog, in days (`ergonex:unapprovedGraceDays`). */
|
|
40
|
+
export declare const UNAPPROVED_GRACE_DAYS = 90;
|
|
41
|
+
/**
|
|
42
|
+
* The severity of a tool or module outside the catalog first seen on `firstSeen`, judged on `today`: informational from the day it is first seen, a warning once it is more than `graceDays` old
|
|
43
|
+
* (FR-033). The 90th day is still informational and the 91st is a warning. A day that is not a day, or is in the future, is informational (a clock set wrong must not fail a run).
|
|
44
|
+
*/
|
|
45
|
+
export declare function unapprovedSeverity(firstSeen: string, today: string, graceDays?: number): Severity;
|
|
46
|
+
/**
|
|
47
|
+
* The day to record for something seen `today`: the day it was recorded before where there is one, so that a later run never restarts the clock (FR-033), else today. `previous` is the state
|
|
48
|
+
* record's days by key.
|
|
49
|
+
*/
|
|
50
|
+
export declare function firstSeenOf(previous: Readonly<Record<string, string>>, key: string, today: string): string;
|
|
51
|
+
/** A SARIF 2.1.0 log of findings: one run, the rules that found them, one result each at the level of its severity. */
|
|
52
|
+
export type SarifLog = {
|
|
53
|
+
readonly $schema: string;
|
|
54
|
+
readonly version: "2.1.0";
|
|
55
|
+
readonly runs: readonly [
|
|
56
|
+
{
|
|
57
|
+
readonly tool: {
|
|
58
|
+
readonly driver: {
|
|
59
|
+
readonly name: string;
|
|
60
|
+
readonly informationUri: string;
|
|
61
|
+
readonly rules: readonly {
|
|
62
|
+
readonly id: string;
|
|
63
|
+
}[];
|
|
64
|
+
};
|
|
65
|
+
};
|
|
66
|
+
readonly results: readonly {
|
|
67
|
+
readonly ruleId: string;
|
|
68
|
+
readonly level: "note" | "warning" | "error";
|
|
69
|
+
readonly message: {
|
|
70
|
+
readonly text: string;
|
|
71
|
+
};
|
|
72
|
+
readonly locations: readonly {
|
|
73
|
+
readonly logicalLocations: readonly {
|
|
74
|
+
readonly name: string;
|
|
75
|
+
}[];
|
|
76
|
+
}[];
|
|
77
|
+
readonly properties: {
|
|
78
|
+
readonly firstSeen: string;
|
|
79
|
+
};
|
|
80
|
+
}[];
|
|
81
|
+
}
|
|
82
|
+
];
|
|
83
|
+
};
|
|
84
|
+
/** The findings as a SARIF 2.1.0 log (FR-035); `tool` is the name of the command that made them. */
|
|
85
|
+
export declare function toSarif(findings: readonly Finding[], tool?: string): SarifLog;
|
package/dist/layout.d.ts
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where things are in the workspace (commons 0002-workspace-model FR-001, FR-006 to FR-008, FR-019, FR-020): a repository is at `<home>/<git-host>/<path...>/<repo>`, which mirrors its remote; a
|
|
3
|
+
* worktree is at `<home>/.worktrees/<git-host>/<path...>/<repo>/<branch-slug>`; the path of a remote and the remote of a path are each made from the other; and a name or a depth that would not
|
|
4
|
+
* be valid is refused naming it.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Pure: the root is a value the caller gives (`homeOf` reads the variable from an environment it is handed, never its own). A host or a segment of a remote named like a folder of the workspace
|
|
8
|
+
* (`.worktrees`, `.ergonex`, `.git`, in any case) is refused (FR-008). A path deeper than two segments below a host without `NestedGroups` (GitHub, plain Git) is refused with the manager and the path named (FR-020).
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
13
|
+
import { type HostKinds } from "./vendor/ts/githost/mod.js";
|
|
14
|
+
import type { HostKind, RepoRef } from "./vendor/ts/githost/mod.js";
|
|
15
|
+
import { type PortableError } from "./portable.js";
|
|
16
|
+
import { type BrandError, type BranchName, type GitHost, type PortableSegment, type RepoPath } from "./types.js";
|
|
17
|
+
/** The folders that belong to the workspace itself, which no host and no segment of a remote may be named like. */
|
|
18
|
+
export declare const WORKSPACE_FOLDERS: readonly string[];
|
|
19
|
+
/** Why a reference or a branch has no place in the workspace. */
|
|
20
|
+
export type LayoutError = {
|
|
21
|
+
readonly kind: "portable";
|
|
22
|
+
readonly cause: PortableError;
|
|
23
|
+
} | {
|
|
24
|
+
readonly kind: "host";
|
|
25
|
+
readonly cause: BrandError;
|
|
26
|
+
} | {
|
|
27
|
+
readonly kind: "workspace-folder";
|
|
28
|
+
readonly segment: string;
|
|
29
|
+
} | {
|
|
30
|
+
readonly kind: "too-deep";
|
|
31
|
+
readonly manager: HostKind;
|
|
32
|
+
readonly path: readonly string[];
|
|
33
|
+
readonly limit: number;
|
|
34
|
+
} | {
|
|
35
|
+
readonly kind: "too-shallow";
|
|
36
|
+
readonly path: readonly string[];
|
|
37
|
+
} | {
|
|
38
|
+
readonly kind: "not-in-layout";
|
|
39
|
+
readonly path: string;
|
|
40
|
+
};
|
|
41
|
+
/** A refusal as one sentence that names the manager, the path or the name. */
|
|
42
|
+
export declare function describeLayoutError(e: LayoutError): string;
|
|
43
|
+
/** The Git host of a reference as the first folder of its path: lower case, portable, and not named like a folder of the workspace. */
|
|
44
|
+
export declare function gitHostOf(ref: RepoRef): Result<GitHost, LayoutError>;
|
|
45
|
+
/** The path of a repository: `<git-host>/<path...>/<repo>` (FR-006). */
|
|
46
|
+
export declare function repoPathOf(ref: RepoRef): Result<RepoPath, LayoutError>;
|
|
47
|
+
/**
|
|
48
|
+
* A branch as one path segment for its worktree: each character Windows would refuse, and `/`, becomes `-`, repeated `-` become one, a trailing dot or space and the dashes at either end are
|
|
49
|
+
* dropped, and a device name gets an underscore after it. `feature/x.` is `feature-x` and `a:b` is `a-b`; a name that has nothing left is refused.
|
|
50
|
+
*/
|
|
51
|
+
export declare function slugOf(text: string): Result<PortableSegment, PortableError>;
|
|
52
|
+
/** The path of a worktree of a repository for a branch: `.worktrees/<git-host>/<path...>/<repo>/<branch-slug>` (FR-007). */
|
|
53
|
+
export declare function worktreePathOf(ref: RepoRef, branch: BranchName | string): Result<RepoPath, LayoutError>;
|
|
54
|
+
/**
|
|
55
|
+
* The reference a path of the workspace mirrors, the reverse of `repoPathOf`: its first segment is the host and the kind of host is the manifest's (`hostKinds`), GitHub for `github.com` and
|
|
56
|
+
* GitLab for `gitlab.com`. A path under `.worktrees` or `.ergonex`, or of fewer than three segments, is not a repository's.
|
|
57
|
+
*/
|
|
58
|
+
export declare function refOfPath(path: RepoPath, hostKinds?: HostKinds): Result<RepoRef, LayoutError>;
|
|
59
|
+
/** What the environment gives of where the workspace is. */
|
|
60
|
+
export type HomeFacts = {
|
|
61
|
+
/** `ERGONEX_HOME`, if set. */
|
|
62
|
+
readonly workspacesHome?: string | undefined;
|
|
63
|
+
/** `HOME` on Linux and macOS, `USERPROFILE` on Windows. */
|
|
64
|
+
readonly home?: string | undefined;
|
|
65
|
+
readonly windows: boolean;
|
|
66
|
+
/** `--home` of this run. */
|
|
67
|
+
readonly override?: string | undefined;
|
|
68
|
+
};
|
|
69
|
+
/** Why no root could be found. */
|
|
70
|
+
export type HomeError = {
|
|
71
|
+
readonly kind: "no-home";
|
|
72
|
+
};
|
|
73
|
+
/** The root of the workspace: `--home`, else `$ERGONEX_HOME`, else `$HOME/workspaces` (`%USERPROFILE%\workspaces` on Windows) (FR-001). */
|
|
74
|
+
export declare function homeOf(facts: HomeFacts): Result<string, HomeError>;
|
|
75
|
+
/** What is known of a repository's checkout when a worktree is asked for. */
|
|
76
|
+
export type WorktreeFacts = {
|
|
77
|
+
/** The checkout has uncommitted changes (work that a branch change would disturb). */
|
|
78
|
+
readonly uncommittedWork: boolean;
|
|
79
|
+
/** Another person or agent is working in the repository (its own checkout, or another worktree, is in use). */
|
|
80
|
+
readonly otherWorker: boolean;
|
|
81
|
+
};
|
|
82
|
+
/** Whether a worktree is to be made: only where another person or agent, or uncommitted work, is on the repository; otherwise the repository's own checkout is the place to work (FR-007). */
|
|
83
|
+
export declare function worktreeWanted(facts: WorktreeFacts): boolean;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The workspace's manifest, the source state (commons 0003-host FR-001, 0002-workspace-model FR-006, FR-011, FR-019, FR-020): the repositories it names, the self-managed GitLab hosts, the
|
|
3
|
+
* policy and the identity, decoded once at the boundary by the kernel's decoder and then checked as a whole, so that every field that is wrong is reported with its place and none is guessed.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* Two stages. The shape is the kernel decoder's: the first field that is not what is expected stops that stage, named by its path. The meaning is this module's and reports all it finds: a remote that
|
|
7
|
+
* is not a remote of a host, a path that is not portable or is named like a folder of the workspace, a path deeper than the host's manager offers, two repositories or worktrees whose paths
|
|
8
|
+
* are one after Unicode normalization and case folding (both are named, on every file system), a branch that is not a branch name, and a repository on a host the policy does not allow.
|
|
9
|
+
* An issue is a finding of severity `Error` (`issueFinding`); a manifest with one is not used.
|
|
10
|
+
*
|
|
11
|
+
* @limits It does not read the file: `workspace.ts` is a TypeScript module the host layer loads and hands over as a value. The tool catalog is decoded by `tools/catalog.ts` (0002-workspace-model FR-037).
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
16
|
+
import { type HostKinds } from "./vendor/ts/githost/mod.js";
|
|
17
|
+
import type { RepoRef } from "./vendor/ts/githost/mod.js";
|
|
18
|
+
import type { Finding } from "./findings.js";
|
|
19
|
+
import { type ToolCatalog } from "./tools/catalog.js";
|
|
20
|
+
import { type Policy } from "./policy.js";
|
|
21
|
+
import { type BranchName, type RepoPath } from "./types.js";
|
|
22
|
+
/** A worktree the manifest asks for. */
|
|
23
|
+
export type ManifestWorktree = {
|
|
24
|
+
readonly branch: BranchName;
|
|
25
|
+
readonly path: RepoPath;
|
|
26
|
+
};
|
|
27
|
+
/** A repository the manifest names, with where it goes. */
|
|
28
|
+
export type ManifestRepo = {
|
|
29
|
+
/** The remote as the manifest wrote it, normalized to the HTTPS URL it is cloned from. */
|
|
30
|
+
readonly cloneUrl: string;
|
|
31
|
+
readonly ref: RepoRef;
|
|
32
|
+
readonly path: RepoPath;
|
|
33
|
+
readonly branch?: BranchName | undefined;
|
|
34
|
+
/** The group of repositories it belongs to (one `<group>.auto.code-workspace` file each). */
|
|
35
|
+
readonly group?: string | undefined;
|
|
36
|
+
readonly worktrees: readonly ManifestWorktree[];
|
|
37
|
+
};
|
|
38
|
+
/** A module the workspace registers (0001-ergonex FR-011): its name, the program that runs it and, where given, the SHA-256 that program must have. */
|
|
39
|
+
export type ManifestModule = {
|
|
40
|
+
readonly name: string;
|
|
41
|
+
readonly program: string;
|
|
42
|
+
readonly sha256?: string | undefined;
|
|
43
|
+
readonly summary?: string | undefined;
|
|
44
|
+
};
|
|
45
|
+
/** How commits are signed in a managed repository (0003-host FR-013): `openpgp` or `ssh`, and the key the manifest names, if it names one. */
|
|
46
|
+
export type ManifestSigning = {
|
|
47
|
+
readonly format: "openpgp" | "ssh";
|
|
48
|
+
readonly key?: string | undefined;
|
|
49
|
+
};
|
|
50
|
+
/** The decoded manifest. */
|
|
51
|
+
export type Manifest = {
|
|
52
|
+
readonly repositories: readonly ManifestRepo[];
|
|
53
|
+
/** The hosts that are not plain Git, by name: the self-managed GitLab hosts the manifest names (and never one guessed from a URL). */
|
|
54
|
+
readonly hostKinds: HostKinds;
|
|
55
|
+
readonly policy: Policy;
|
|
56
|
+
readonly identity?: {
|
|
57
|
+
readonly name: string;
|
|
58
|
+
readonly email: string;
|
|
59
|
+
} | undefined;
|
|
60
|
+
/** The signing the policy requires, where the manifest names a format. */
|
|
61
|
+
readonly signing?: ManifestSigning | undefined;
|
|
62
|
+
/** Whether `direnv` is wanted (0003-host FR-023): `.envrc.auto` is generated only where it is wanted and a probe finds it. */
|
|
63
|
+
readonly direnv: boolean;
|
|
64
|
+
/** The modules the workspace registers, written to `modules.auto.json`. */
|
|
65
|
+
readonly modules: readonly ManifestModule[];
|
|
66
|
+
/** The tool catalog (0002-workspace-model FR-037): empty where the manifest names none. */
|
|
67
|
+
readonly catalog: ToolCatalog;
|
|
68
|
+
};
|
|
69
|
+
/** One thing wrong in the manifest, with where. */
|
|
70
|
+
export type ManifestIssue = {
|
|
71
|
+
/** The rule that found it: `ergonex/manifest-shape`, `ergonex/manifest-remote`, `ergonex/manifest-path`, `ergonex/manifest-branch`, `ergonex/manifest-host`, `ergonex/manifest-signing`, `ergonex/manifest-module`, `ergonex/catalog-shape`, `ergonex/catalog-tool`, `ergonex/path-collision`, `ergonex/host-not-allowed`. */
|
|
72
|
+
readonly rule: string;
|
|
73
|
+
/** The field, as `$.repositories[2].remote`. */
|
|
74
|
+
readonly path: string;
|
|
75
|
+
readonly message: string;
|
|
76
|
+
};
|
|
77
|
+
/** An issue as a finding of the severity `Error`, first seen `today`. */
|
|
78
|
+
export declare function issueFinding(issue: ManifestIssue, today: string): Finding;
|
|
79
|
+
/** The manifest from a value of unknown shape, or every issue found in it. Pure: nothing is read, and nothing in the value is kept that is not decoded. */
|
|
80
|
+
export declare function decodeManifest(input: unknown, options?: {
|
|
81
|
+
readonly loopbackHttp?: boolean;
|
|
82
|
+
}): Result<Manifest, readonly ManifestIssue[]>;
|
|
83
|
+
/** The kind of host of a name under a manifest: GitHub for `github.com`, GitLab for `gitlab.com` and the hosts it names, plain Git for the rest (0002-workspace-model FR-019). */
|
|
84
|
+
export declare function hostKindIn(manifest: Manifest, host: string): "Github" | "Gitlab" | "Git";
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IF Workspaces, the pure core (commons 0002-workspace-model, 0003-host): the managed place on a computer where the repositories of Intellectual Frontiers live. This module is rung 10 of the
|
|
3
|
+
* ladder, the environment the other rungs are worked in (0016-ladder), and no rung below it imports it. Built here: the branded types (`GitHost`, `RepoPath`, `PortableSegment`, `BranchName`, `Sha`,
|
|
4
|
+
* `Version`), the layout from a remote to a path and back, the portability of a path on Linux, macOS and Windows, the typed manifest, the state of a repository and its classification, the plan
|
|
5
|
+
* as a pure function, the findings with their severities and SARIF, and the policy; the typed templates and the generated files, the state record, the module contract and its discovery, the shell
|
|
6
|
+
* snippet and its one block, a unified diff and the checks of the doctor. The three Git host adapters are in `../githost/`. The command `ergonex` is `ergonex.ts`, its modules are in `commands/`, and what it does
|
|
7
|
+
* with `git` and the files is in `host/`; the tools and the policy scans are another milestone's work.
|
|
8
|
+
*
|
|
9
|
+
* @remarks
|
|
10
|
+
* Everything here but `host/`, `commands/` and `ergonex.ts` is pure: no file, no process, no clock, no environment; each takes what it needs as an argument. `host/` runs `git` and reads and writes files, `commands/` are the typed modules of the command, and `ergonex.ts` is the controller; `host/observe.ts` only reads.
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
export { unifiedDiff } from "./diff.js";
|
|
15
|
+
export { digestsOf, type DesiredFacts, desiredOf, settingsOf } from "./desired.js";
|
|
16
|
+
export { type Check, classifyFs, findingsOf, fsCheck, type FsKind, type FsProbe, hookChecks, type HookFacts, type Level, type LongPaths, MIN_NODE_MAJOR, type PathFacts, pathChecks, repoPathChecks, runtimeChecks, severityOf, type ToolProbe, } from "./doctor.js";
|
|
17
|
+
export { checkFiles, describeGenerateError, type FileBody, type FileMode, fileDigest, type GeneratedFile, generated, generatedPath, type GenerateError, HOOKS_FOLDER, headerText, isAutoName, normalizeText, } from "./render.js";
|
|
18
|
+
export { decodeStateRecord, EMPTY_RECORD, encodeStateRecord, type FileFacts, ERGONEX_VERSION, type RecordedFile, STATE_RECORD_PATH, type StateRecord, verifyFindings, withFile, withoutFile, } from "./state-record.js";
|
|
19
|
+
export { type Candidates, decodeExternalManifest, decodeRegistered, defineCommand, describeNameError, dispatch, EXIT_STATUSES, type ExitStatus, exitCodeOf, externalManifestSchema, findModule, type Found, GLOBAL_OPTIONS, hiddenFindings, type ErgonexModule, MODULE_SOURCES, type ModuleName, type ModuleSource, moduleName, nearestNames, precedenceOf, type Report, resolveAll, type Failure, type Command, type Context, } from "./modules/mod.js";
|
|
20
|
+
export { renderAll, type Template, type TemplateData, TEMPLATES } from "./templates/mod.js";
|
|
21
|
+
export { BEGIN, END, installBlock, removeBlock, rcFileFor, SHELLS, type Shell, snippetFor } from "./shell/mod.js";
|
|
22
|
+
export { type Action, type ActionKind, type Desired, type DesiredFile, type DesiredRepo, type DesiredWorktree, describeAction, describeRefusal, describeSkip, type HostChange, isDestructive, isHostChange, isSettled, mayRemove, type Observed, type ObservedFile, type ObservedRepo, plan, type Plan, planDigest, type PlanOptions, type RefuseWhy, type SkipWhy, } from "./plan.js";
|
|
23
|
+
export { checkPathLength, child, type Collision, collisions, describePortableError, foldKey, MAX_SEGMENT_BYTES, nativePath, type PathTooLong, type PortableError, REPO_PATH_ROOM, repoPath, type RepoPathLength, repoPathLength, segment, segmentsOf, WINDOWS_PATH_LIMIT, } from "./portable.js";
|
|
24
|
+
export { describeLayoutError, gitHostOf, homeOf, type HomeError, type HomeFacts, type LayoutError, refOfPath, repoPathOf, slugOf, WORKSPACE_FOLDERS, worktreePathOf, worktreeWanted, type WorktreeFacts, } from "./layout.js";
|
|
25
|
+
export { decodeManifest, hostKindIn, issueFinding, type Manifest, type ManifestIssue, type ManifestRepo, type ManifestWorktree, } from "./manifest.js";
|
|
26
|
+
export { classify, defaultActionOf, describeRemote, fastForwardable, holdsLocalWork, isExpectedRemote, REPO_STATE_KINDS, type RepoFacts, type RepoState, type RepoStateKind, } from "./state.js";
|
|
27
|
+
export { daysBetween, dayNumber, exitStatusOf, type Finding, firstSeenOf, sarifLevel, type SarifLog, type Severity, SEVERITIES, toSarif, UNAPPROVED_GRACE_DAYS, unapprovedSeverity, worst, } from "./findings.js";
|
|
28
|
+
export { hookFailsWhenUnableToCheck, hostAllowed, isRegulated, type Policy, policyOf, type PolicyInput, unsignedCommitSeverity, } from "./policy.js";
|
|
29
|
+
export { type BranchName, branchName, type BrandError, describeBrandError, type GitHost, gitHost, type PortableSegment, type RepoPath, type Sha, sha, type Version, version, } from "./types.js";
|