@git.zone/cli 8.3.2 → 8.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.
Files changed (29) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +14 -0
  3. package/dist_ts/helpers.workflow.js +29 -1
  4. package/dist_ts/mod_config/index.js +42 -1
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
  6. package/dist_ts/mod_release/classes.releasejournal.js +95 -9
  7. package/dist_ts/mod_release/helpers.npmartifact.d.ts +68 -7
  8. package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
  9. package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
  10. package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
  11. package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
  12. package/dist_ts/mod_release/helpers.releaseline.js +129 -0
  13. package/dist_ts/mod_release/helpers.releasepublication.d.ts +2 -0
  14. package/dist_ts/mod_release/helpers.releasepublication.js +86 -19
  15. package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
  16. package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
  17. package/dist_ts/mod_release/index.js +130 -40
  18. package/package.json +3 -3
  19. package/readme.md +123 -7
  20. package/ts/00_commitinfo_data.ts +1 -1
  21. package/ts/helpers.workflow.ts +54 -0
  22. package/ts/mod_config/index.ts +47 -0
  23. package/ts/mod_release/classes.releasejournal.ts +149 -10
  24. package/ts/mod_release/helpers.npmartifact.ts +302 -22
  25. package/ts/mod_release/helpers.releasebranch.ts +120 -45
  26. package/ts/mod_release/helpers.releaseline.ts +214 -0
  27. package/ts/mod_release/helpers.releasepublication.ts +168 -16
  28. package/ts/mod_release/helpers.releaseversion.ts +5 -1
  29. package/ts/mod_release/index.ts +177 -26
@@ -29,8 +29,14 @@ import {
29
29
  import {
30
30
  compareReleaseVersions,
31
31
  isCanonicalReleaseVersion,
32
+ releaseVersionMajor,
32
33
  type IReleaseVersionFloorRecord,
33
34
  } from "./helpers.releaseversion.js";
35
+ import {
36
+ getReleaseDistTag,
37
+ parseReleaseLine,
38
+ type IReleaseLine,
39
+ } from "./helpers.releaseline.js";
34
40
 
35
41
  export const releaseJournalStorageVersion = 1 as const;
36
42
  export const legacyReleaseJournalSchemaVersion = 1 as const;
@@ -66,7 +72,8 @@ export type TReleaseErrorCode =
66
72
  | "artifact-conflict"
67
73
  | "already-published"
68
74
  | "destination-conflict"
69
- | "attempt-recovery-required";
75
+ | "attempt-recovery-required"
76
+ | "dist-tag-conflict";
70
77
 
71
78
  export interface IReleaseAttempt {
72
79
  id: string;
@@ -95,21 +102,34 @@ export interface IReleaseArtifact {
95
102
  export interface IReleaseGitJournal extends IReleaseTargetStatus {
96
103
  remote: string | null;
97
104
  destinationHash: string | null;
105
+ /**
106
+ * The release branch's commit at the destination that the push leases:
107
+ * `main`, or the branch of the journaled release line. The name predates
108
+ * release lines and is kept so that every journal keeps parsing.
109
+ */
98
110
  expectedRemoteMainOid: string | null;
99
111
  }
100
112
 
101
113
  export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
102
114
  registry: string;
103
115
  packageName?: string;
116
+ /**
117
+ * A release line records the `latest` version it found when it claimed the
118
+ * publication, so a line that took `latest` names the exact restore command.
119
+ */
120
+ previousLatest?: string;
104
121
  }
105
122
 
106
123
  export interface IReleaseIdentity {
107
124
  version: string;
108
125
  tag: string;
126
+ /** The release commit, on `main` or on the branch of `line`. */
109
127
  mainOid: string;
110
128
  tagOid: string;
111
129
  /** Present only when release.versionFloor raised the version above the inferred one. */
112
130
  versionFloor?: IReleaseVersionFloorRecord;
131
+ /** Present only for a maintenance line release; absent means `main` and `latest`. */
132
+ line?: IReleaseLine;
113
133
  }
114
134
 
115
135
  export interface IReleaseJournalV1 {
@@ -121,7 +141,8 @@ export interface IReleaseJournalV1 {
121
141
  git: IReleaseGitJournal;
122
142
  npm: {
123
143
  access: TReleaseNpmAccess;
124
- tag: "latest";
144
+ /** `latest`, or the dist-tag of the journaled release line. */
145
+ tag: string;
125
146
  alreadyPublished: "success" | "error";
126
147
  registries: IReleaseNpmRegistryJournal[];
127
148
  };
@@ -163,7 +184,8 @@ export interface IReleaseJournalV2 {
163
184
  git: IReleaseGitJournal;
164
185
  npm: {
165
186
  access: TReleaseNpmAccess;
166
- tag: "latest";
187
+ /** `latest`, or the dist-tag of the journaled release line. */
188
+ tag: string;
167
189
  alreadyPublished: "success" | "error";
168
190
  registries: IReleaseNpmRegistryJournal[];
169
191
  };
@@ -274,6 +296,7 @@ const errorCodes: TReleaseErrorCode[] = [
274
296
  "already-published",
275
297
  "destination-conflict",
276
298
  "attempt-recovery-required",
299
+ "dist-tag-conflict",
277
300
  ];
278
301
 
279
302
  const isPlainObject = (
@@ -606,18 +629,75 @@ const assertVersionFloorRecord = (
606
629
  }
607
630
  };
608
631
 
632
+ const assertReleaseLineRecord = (valueArg: unknown): IReleaseLine => {
633
+ if (!isPlainObject(valueArg)) {
634
+ throw new Error("Release journal release line must be an object.");
635
+ }
636
+ assertExactKeys(
637
+ valueArg,
638
+ ["branch", "distTag"],
639
+ "Release journal release line",
640
+ );
641
+ const line = parseReleaseLine(valueArg, "Release journal release line");
642
+ if (!line) throw new Error("Release journal release line is missing.");
643
+ return line;
644
+ };
645
+
646
+ /**
647
+ * Only a line release claims a publication with the `latest` version it found,
648
+ * and the guard admitted it only with a higher major than the release. The
649
+ * record exists once the publication was claimed.
650
+ */
651
+ const assertPreviousLatest = (
652
+ registryArg: Record<string, unknown>,
653
+ releaseArg: IReleaseIdentity,
654
+ contextArg: string,
655
+ ): void => {
656
+ const previousLatest = registryArg.previousLatest;
657
+ if (
658
+ !releaseArg.line ||
659
+ typeof previousLatest !== "string" ||
660
+ !isCanonicalReleaseVersion(previousLatest) ||
661
+ releaseVersionMajor(previousLatest) <=
662
+ releaseVersionMajor(releaseArg.version) ||
663
+ registryArg.attempts === 0
664
+ ) {
665
+ throw new Error(
666
+ `${contextArg}.previousLatest must record the higher-major latest version a release line found when it claimed the publication.`,
667
+ );
668
+ }
669
+ };
670
+
671
+ /**
672
+ * A release line publishes only to Git and npm: Docker aliases and Gitea's
673
+ * latest release follow their own rules, which a line must not move.
674
+ */
675
+ const assertNoReleaseLine = (
676
+ valueArg: Record<string, unknown>,
677
+ schemaArg: number,
678
+ ): void => {
679
+ if (isPlainObject(valueArg.release) && Object.hasOwn(valueArg.release, "line"))
680
+ throw new Error(
681
+ `Release journal schema ${schemaArg} cannot carry a release line.`,
682
+ );
683
+ };
684
+
609
685
  const assertReleaseIdentity = (valueArg: unknown): IReleaseIdentity => {
610
686
  if (!isPlainObject(valueArg)) {
611
687
  throw new Error("Release journal release identity is missing.");
612
688
  }
613
689
  const hasVersionFloor = Object.hasOwn(valueArg, "versionFloor");
690
+ const hasLine = Object.hasOwn(valueArg, "line");
614
691
  assertExactKeys(
615
692
  valueArg,
616
- hasVersionFloor
617
- ? [...releaseIdentityKeys, "versionFloor"]
618
- : releaseIdentityKeys,
693
+ [
694
+ ...releaseIdentityKeys,
695
+ ...(hasVersionFloor ? ["versionFloor"] : []),
696
+ ...(hasLine ? ["line"] : []),
697
+ ],
619
698
  "Release journal release",
620
699
  );
700
+ if (hasLine) assertReleaseLineRecord(valueArg.line);
621
701
  if (
622
702
  typeof valueArg.version !== "string" ||
623
703
  normalizeReleaseVersion(valueArg.version) !== valueArg.version ||
@@ -722,7 +802,7 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
722
802
  );
723
803
  if (
724
804
  (valueArg.npm.access !== "public" && valueArg.npm.access !== "private") ||
725
- valueArg.npm.tag !== "latest" ||
805
+ valueArg.npm.tag !== getReleaseDistTag(release.line) ||
726
806
  (valueArg.npm.alreadyPublished !== "success" &&
727
807
  valueArg.npm.alreadyPublished !== "error") ||
728
808
  !Array.isArray(valueArg.npm.registries)
@@ -738,10 +818,26 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
738
818
  }
739
819
  assertExactKeys(
740
820
  rawRegistry,
741
- ["state", "attempts", "attempt", "error", "registry"],
821
+ [
822
+ "state",
823
+ "attempts",
824
+ "attempt",
825
+ "error",
826
+ "registry",
827
+ ...(Object.hasOwn(rawRegistry, "previousLatest")
828
+ ? ["previousLatest"]
829
+ : []),
830
+ ],
742
831
  `Release journal npm registry ${index}`,
743
832
  );
744
833
  assertTargetStatus(rawRegistry, `Release journal npm registry ${index}`);
834
+ if (Object.hasOwn(rawRegistry, "previousLatest")) {
835
+ assertPreviousLatest(
836
+ rawRegistry,
837
+ release,
838
+ `Release journal npm registry ${index}`,
839
+ );
840
+ }
745
841
  if (
746
842
  typeof rawRegistry.registry !== "string" ||
747
843
  !isCanonicalRegistryUrl(rawRegistry.registry) ||
@@ -1029,6 +1125,7 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1029
1125
  if (!isPlainObject(valueArg)) {
1030
1126
  throw new Error("Release journal root must be a JSON object.");
1031
1127
  }
1128
+ assertNoReleaseLine(valueArg, 2);
1032
1129
  const hasPackages = Object.hasOwn(valueArg, "packages");
1033
1130
  assertExactKeys(
1034
1131
  valueArg,
@@ -1160,7 +1257,17 @@ const assertReleaseJournalV3 = (
1160
1257
  const target = targets[targetOffset++];
1161
1258
  assertExactKeys(
1162
1259
  target,
1163
- ["state", "attempts", "attempt", "error", "registry", "packageName"],
1260
+ [
1261
+ "state",
1262
+ "attempts",
1263
+ "attempt",
1264
+ "error",
1265
+ "registry",
1266
+ "packageName",
1267
+ ...(Object.hasOwn(target, "previousLatest")
1268
+ ? ["previousLatest"]
1269
+ : []),
1270
+ ],
1164
1271
  "Release package target",
1165
1272
  );
1166
1273
  const { packageName, ...registry } = target;
@@ -1249,6 +1356,7 @@ const assertReleaseJournalV3 = (
1249
1356
  const assertReleaseJournalV4 = (
1250
1357
  valueArg: Record<string, unknown>,
1251
1358
  ): IReleaseJournalV4 => {
1359
+ assertNoReleaseLine(valueArg, 4);
1252
1360
  assertExactKeys(
1253
1361
  valueArg,
1254
1362
  [
@@ -1736,6 +1844,28 @@ const assertSchema4AppendOnlyTransition = (
1736
1844
  }
1737
1845
  };
1738
1846
 
1847
+ /**
1848
+ * The `latest` a line found is recorded when it claims a publication and is
1849
+ * never rewritten afterwards, except by the next claim of a failed attempt.
1850
+ */
1851
+ const assertPreviousLatestTransition = (
1852
+ currentArg: TReleaseJournal,
1853
+ nextArg: TReleaseJournal,
1854
+ ): void => {
1855
+ for (const [index, before] of currentArg.npm.registries.entries()) {
1856
+ const after = nextArg.npm.registries[index];
1857
+ if (before.previousLatest === after?.previousLatest) continue;
1858
+ const claims =
1859
+ (before.state === "pending" || before.state === "failed") &&
1860
+ after?.state === "publishing";
1861
+ if (!claims || after.previousLatest === undefined) {
1862
+ throw new Error(
1863
+ "A release line records the latest version it found only when it claims a publication.",
1864
+ );
1865
+ }
1866
+ }
1867
+ };
1868
+
1739
1869
  /** The Git destination state a recorded release leases when it publishes. */
1740
1870
  export interface IReleaseIntentGit {
1741
1871
  remote: string;
@@ -1824,9 +1954,17 @@ export const assertReleaseIntent = (valueArg: unknown): IReleaseIntent => {
1824
1954
  if (valueArg.kind !== releaseIntentKind) {
1825
1955
  throw new Error("Release intent kind is invalid.");
1826
1956
  }
1827
- assertReleaseIdentity(valueArg.release);
1957
+ const release = assertReleaseIdentity(valueArg.release);
1828
1958
  const plan = assertReleaseIntentPlan(valueArg.plan);
1829
1959
  const git = assertReleaseIntentGit(valueArg.git);
1960
+ if (
1961
+ release.line &&
1962
+ (plan.targets.includes("docker") || plan.targets.includes("giteaAssets"))
1963
+ ) {
1964
+ throw new Error(
1965
+ "A release line publishes only to Git and npm; its intent cannot name Docker or Gitea assets.",
1966
+ );
1967
+ }
1830
1968
  if (plan.targets.includes("git") !== (git !== null)) {
1831
1969
  throw new Error(
1832
1970
  "A release intent records a Git destination exactly when Git is a target.",
@@ -2247,6 +2385,7 @@ export class ReleaseJournalStore {
2247
2385
  }
2248
2386
  if (current.schemaVersion === 4 && next.schemaVersion === 4)
2249
2387
  assertSchema4AppendOnlyTransition(current, next);
2388
+ assertPreviousLatestTransition(current, next);
2250
2389
  await this.writeAtomic(version, next);
2251
2390
  return next;
2252
2391
  });