@git.zone/cli 6.13.2 → 6.15.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,139 @@
1
+ import * as plugins from "./plugins.js";
2
+
3
+ /**
4
+ * Resolve the project's own tstest binary. The CLI deliberately does not
5
+ * depend on tstest at runtime: a project that tests already has it, and a
6
+ * project that does not should simply skip the cleanup.
7
+ */
8
+ export const getProjectTstestBinPath = (
9
+ projectRootArg: string,
10
+ platformArg: NodeJS.Platform = process.platform,
11
+ ): string => {
12
+ return plugins.path.join(
13
+ projectRootArg,
14
+ "node_modules",
15
+ ".bin",
16
+ platformArg === "win32" ? "tstest.CMD" : "tstest",
17
+ );
18
+ };
19
+
20
+ export const hasInstalledProjectTstestBinary = async (
21
+ projectRootArg: string,
22
+ platformArg: NodeJS.Platform = process.platform,
23
+ ): Promise<boolean> => {
24
+ try {
25
+ await plugins.fs.access(getProjectTstestBinPath(projectRootArg, platformArg));
26
+ return true;
27
+ } catch {
28
+ return false;
29
+ }
30
+ };
31
+
32
+ /**
33
+ * Whether the project wants its test artifacts removed as part of a release.
34
+ * Defaults to true; a project opts out with
35
+ * `{"@git.zone/tstest": {"cleanup": {"onRelease": false}}}`.
36
+ */
37
+ export const readTstestCleanupOnRelease = (projectRootArg: string): boolean => {
38
+ try {
39
+ const smartconfigInstance = new plugins.smartconfig.Smartconfig(
40
+ projectRootArg,
41
+ );
42
+ const tstestConfig = smartconfigInstance.dataFor<{
43
+ cleanup?: { onRelease?: boolean };
44
+ }>("@git.zone/tstest", {});
45
+ return tstestConfig?.cleanup?.onRelease !== false;
46
+ } catch {
47
+ return true;
48
+ }
49
+ };
50
+
51
+ /** First tstest version that understands the `clean` subcommand. */
52
+ export const MINIMUM_TSTEST_CLEAN_VERSION = "6.1.0";
53
+
54
+ const parseVersion = (versionArg: string): number[] =>
55
+ versionArg
56
+ .split("-")[0]
57
+ .split(".")
58
+ .map((part) => Number.parseInt(part, 10) || 0);
59
+
60
+ export const satisfiesMinimumCleanVersion = (versionArg: string): boolean => {
61
+ const actual = parseVersion(versionArg);
62
+ const required = parseVersion(MINIMUM_TSTEST_CLEAN_VERSION);
63
+ for (let index = 0; index < required.length; index++) {
64
+ const actualPart = actual[index] ?? 0;
65
+ if (actualPart > required[index]) return true;
66
+ if (actualPart < required[index]) return false;
67
+ }
68
+ return true;
69
+ };
70
+
71
+ /**
72
+ * Version of tstest installed in the project, or null when it cannot be read.
73
+ */
74
+ export const readProjectTstestVersion = async (
75
+ projectRootArg: string,
76
+ ): Promise<string | null> => {
77
+ try {
78
+ const packageJsonPath = plugins.path.join(
79
+ projectRootArg,
80
+ "node_modules",
81
+ "@git.zone",
82
+ "tstest",
83
+ "package.json",
84
+ );
85
+ const contents = await plugins.fs.readFile(packageJsonPath, "utf8");
86
+ const parsed = JSON.parse(contents) as { version?: string };
87
+ return parsed.version ?? null;
88
+ } catch {
89
+ return null;
90
+ }
91
+ };
92
+
93
+ /**
94
+ * True when a release should run `tstest clean` for this project: tstest is
95
+ * installed at a version that understands the subcommand, and the project has
96
+ * not opted out. An older tstest would treat `clean` as a test path, so it is
97
+ * deliberately skipped rather than invoked.
98
+ */
99
+ export const shouldCleanTestArtifactsOnRelease = async (
100
+ projectRootArg: string,
101
+ ): Promise<boolean> => {
102
+ if (!readTstestCleanupOnRelease(projectRootArg)) {
103
+ return false;
104
+ }
105
+ if (!(await hasInstalledProjectTstestBinary(projectRootArg))) {
106
+ return false;
107
+ }
108
+ const version = await readProjectTstestVersion(projectRootArg);
109
+ return version ? satisfiesMinimumCleanVersion(version) : false;
110
+ };
111
+
112
+ /** Single-quote a value for safe interpolation into a shell command. */
113
+ export const shellQuote = (valueArg: string): string =>
114
+ `'${valueArg.replaceAll("'", `'\\''`)}'`;
115
+
116
+ /**
117
+ * Run the project's `tstest clean`. Cleanup is housekeeping, so a failure is
118
+ * reported and swallowed rather than failing an otherwise complete release.
119
+ */
120
+ export const runTstestCleanup = async (
121
+ smartshellArg: plugins.smartshell.Smartshell,
122
+ projectRootArg: string,
123
+ ): Promise<void> => {
124
+ const binPath = getProjectTstestBinPath(projectRootArg);
125
+ console.log("cleaning test artifacts");
126
+ try {
127
+ // Quoted: a project path may contain spaces or shell metacharacters.
128
+ const execResult = await smartshellArg.exec(
129
+ `cd ${shellQuote(projectRootArg)} && ${shellQuote(binPath)} clean`,
130
+ );
131
+ if (execResult.exitCode !== 0) {
132
+ console.error(
133
+ `tstest clean exited with ${execResult.exitCode}; leaving test artifacts in place`,
134
+ );
135
+ }
136
+ } catch (error) {
137
+ console.error(`tstest clean failed: ${error}`);
138
+ }
139
+ };
@@ -1,5 +1,7 @@
1
1
  import { getCliConfigValue } from "./helpers.smartconfig.js";
2
2
  import { getProcessUserArgv } from "./helpers.climode.js";
3
+ import { shouldCleanTestArtifactsOnRelease } from "./helpers.tstest.js";
4
+ import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
3
5
 
4
6
  export type TConfirmationMode = "prompt" | "auto" | "plan";
5
7
 
@@ -155,6 +157,8 @@ export interface IReleaseWorkflowConfig {
155
157
  strategy?: "semver";
156
158
  source?: "pendingChangelog" | "manual";
157
159
  };
160
+ /** Canonical x.y.z minimum for the next release version. */
161
+ versionFloor?: string;
158
162
  preflight?: {
159
163
  test?: boolean;
160
164
  build?: boolean;
@@ -189,11 +193,14 @@ export interface IResolvedReleaseWorkflow {
189
193
  targets: TReleaseTarget[];
190
194
  runTests: boolean;
191
195
  runBuild: boolean;
196
+ /** Remove tstest's artifacts once the release has published. */
197
+ cleanTestArtifacts: boolean;
192
198
  testCommand: string;
193
199
  buildCommand: string;
194
200
  changelogFile: "changelog.md";
195
201
  changelogPendingSection: "Pending";
196
202
  changelogVersionHeading: "## {{date}} - {{version}}";
203
+ versionFloor?: string;
197
204
  gitEnabled: boolean;
198
205
  gitRemote: string;
199
206
  pushBranch: boolean;
@@ -623,6 +630,7 @@ const buildReleasePlan = (options: {
623
630
  runTests: boolean;
624
631
  runBuild: boolean;
625
632
  targets: TReleaseTarget[];
633
+ cleanTestArtifacts: boolean;
626
634
  }): string[] => {
627
635
  const plan: string[] = ["preflight.branch", "preflight.cleanTree"];
628
636
  if (options.runTests) plan.push("preflight.test");
@@ -646,6 +654,10 @@ const buildReleasePlan = (options: {
646
654
  if (options.targets.includes("docker")) {
647
655
  plan.push("target.docker.cleanup");
648
656
  }
657
+ // Runs last: a failed release keeps its test logs for diagnosis.
658
+ if (options.cleanTestArtifacts) {
659
+ plan.push("core.cleanTestArtifacts");
660
+ }
649
661
  return plan;
650
662
  };
651
663
 
@@ -743,6 +755,7 @@ export const resolveReleaseWorkflow = async (
743
755
  ): Promise<IResolvedReleaseWorkflow> => {
744
756
  const cliConfig = await readCliWorkflowConfig();
745
757
  const releaseConfig = cliConfig.release || {};
758
+ const versionFloor = parseReleaseVersionFloor(releaseConfig.versionFloor);
746
759
  const targetConfig = releaseConfig.targets || {};
747
760
  const gitConfig = targetConfig.git || {};
748
761
  const npmConfig = targetConfig.npm || {};
@@ -862,17 +875,29 @@ export const resolveReleaseWorkflow = async (
862
875
  dockerNoBuild: false,
863
876
  };
864
877
 
878
+ const cleanTestArtifacts = await shouldCleanTestArtifactsOnRelease(
879
+ process.cwd(),
880
+ );
881
+
865
882
  return {
866
883
  confirmation,
867
- plan: buildReleasePlan({ mergeRequested, runTests, runBuild, targets }),
884
+ plan: buildReleasePlan({
885
+ mergeRequested,
886
+ runTests,
887
+ runBuild,
888
+ targets,
889
+ cleanTestArtifacts,
890
+ }),
868
891
  targets,
869
892
  runTests,
870
893
  runBuild,
894
+ cleanTestArtifacts,
871
895
  testCommand: releaseConfig.preflight?.testCommand || "pnpm test",
872
896
  buildCommand: releaseConfig.preflight?.buildCommand || "pnpm build",
873
897
  changelogFile: "changelog.md",
874
898
  changelogPendingSection: "Pending",
875
899
  changelogVersionHeading: "## {{date}} - {{version}}",
900
+ ...(versionFloor ? { versionFloor } : {}),
876
901
  gitEnabled,
877
902
  gitRemote: gitConfig.remote || "origin",
878
903
  pushBranch,
@@ -25,6 +25,10 @@ import {
25
25
  } from "../helpers.workflow.js";
26
26
  import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
27
27
  import { TsdockerReleaseClient } from "../mod_release/helpers.tsdockerprotocol.js";
28
+ import {
29
+ ReleaseVersionError,
30
+ parseReleaseVersionFloor,
31
+ } from "../mod_release/helpers.releaseversion.js";
28
32
  import { getSealedReleaseConfigError } from "../helpers.sealedrelease.js";
29
33
 
30
34
  export { ReleaseConfig, CommitConfig };
@@ -298,6 +302,7 @@ async function handleShow(mode: ICliMode): Promise<void> {
298
302
  const targets = release.targets || {};
299
303
  printConfigSection("Release Workflow", [
300
304
  ["confirmation", formatValue(release.confirmation)],
305
+ ["version floor", formatValue(release.versionFloor)],
301
306
  ["clean tree", "required"],
302
307
  ["run tests", formatValue(release.preflight?.test)],
303
308
  ["run build", formatValue(release.preflight?.build)],
@@ -1776,6 +1781,8 @@ async function validateReleaseConfig(
1776
1781
  });
1777
1782
  }
1778
1783
 
1784
+ findings.push(validateReleaseVersionFloor(releaseConfig.versionFloor));
1785
+
1779
1786
  if (
1780
1787
  releaseConfig.registries ||
1781
1788
  releaseConfig.accessLevel ||
@@ -1842,6 +1849,25 @@ async function validateReleaseConfig(
1842
1849
  await validateDockerTarget(targets.docker || {}, smartconfigData, findings);
1843
1850
  }
1844
1851
 
1852
+ function validateReleaseVersionFloor(valueArg: unknown): IDoctorFinding {
1853
+ try {
1854
+ const versionFloor = parseReleaseVersionFloor(valueArg);
1855
+ return {
1856
+ level: "ok",
1857
+ message: versionFloor
1858
+ ? `Release version floor ${versionFloor} is a canonical version`
1859
+ : "Release version floor is not configured",
1860
+ };
1861
+ } catch (error) {
1862
+ if (!(error instanceof ReleaseVersionError)) throw error;
1863
+ return {
1864
+ level: "error",
1865
+ message: error.message,
1866
+ fix: "Set release.versionFloor to a canonical x.y.z version or remove it.",
1867
+ };
1868
+ }
1869
+ }
1870
+
1845
1871
  async function validateAssetsConfig(
1846
1872
  rawAssetsConfig: unknown,
1847
1873
  smartconfigData: Record<string, any>,
@@ -21,6 +21,11 @@ import {
21
21
  type IReleaseQualificationResult,
22
22
  type TReleasePromotionEvidence,
23
23
  } from "./helpers.tsdockerprotocol.js";
24
+ import {
25
+ compareReleaseVersions,
26
+ isCanonicalReleaseVersion,
27
+ type IReleaseVersionFloorRecord,
28
+ } from "./helpers.releaseversion.js";
24
29
 
25
30
  export const releaseJournalStorageVersion = 1 as const;
26
31
  export const legacyReleaseJournalSchemaVersion = 1 as const;
@@ -74,16 +79,20 @@ export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
74
79
  packageName?: string;
75
80
  }
76
81
 
82
+ export interface IReleaseIdentity {
83
+ version: string;
84
+ tag: string;
85
+ mainOid: string;
86
+ tagOid: string;
87
+ /** Present only when release.versionFloor raised the version above the inferred one. */
88
+ versionFloor?: IReleaseVersionFloorRecord;
89
+ }
90
+
77
91
  export interface IReleaseJournalV1 {
78
92
  kind: "gitzone-release-journal";
79
93
  schemaVersion: typeof legacyReleaseJournalSchemaVersion;
80
94
  revision: number;
81
- release: {
82
- version: string;
83
- tag: string;
84
- mainOid: string;
85
- tagOid: string;
86
- };
95
+ release: IReleaseIdentity;
87
96
  artifact: IReleaseArtifact | null;
88
97
  git: IReleaseGitJournal;
89
98
  npm: {
@@ -123,12 +132,7 @@ export interface IReleaseJournalV2 {
123
132
  kind: "gitzone-release-journal";
124
133
  schemaVersion: typeof releaseJournalSchemaVersion;
125
134
  revision: number;
126
- release: {
127
- version: string;
128
- tag: string;
129
- mainOid: string;
130
- tagOid: string;
131
- };
135
+ release: IReleaseIdentity;
132
136
  artifact: IReleaseArtifact | null;
133
137
  git: IReleaseGitJournal;
134
138
  npm: {
@@ -213,7 +217,6 @@ export const getReleaseNpmArtifact = (
213
217
  return artifact;
214
218
  };
215
219
 
216
- const releaseVersionRegex = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
217
220
  const gitOidRegex = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
218
221
  const attemptIdRegex = /^[0-9a-f]{32}$/;
219
222
  const sha1Regex = /^[0-9a-f]{40}$/;
@@ -292,7 +295,7 @@ const assertIsoTimestamp = (valueArg: unknown, contextArg: string): string => {
292
295
 
293
296
  export const normalizeReleaseVersion = (valueArg: string): string => {
294
297
  const version = valueArg.startsWith("v") ? valueArg.slice(1) : valueArg;
295
- if (!releaseVersionRegex.test(version)) {
298
+ if (!isCanonicalReleaseVersion(version)) {
296
299
  throw new Error(
297
300
  "Release journal versions must use canonical x.y.z semver.",
298
301
  );
@@ -494,6 +497,69 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
494
497
  : undefined,
495
498
  });
496
499
 
500
+ const releaseIdentityKeys = ["version", "tag", "mainOid", "tagOid"] as const;
501
+
502
+ const assertVersionFloorRecord = (
503
+ valueArg: unknown,
504
+ versionArg: string,
505
+ ): void => {
506
+ if (!isPlainObject(valueArg)) {
507
+ throw new Error("Release journal version floor must be an object.");
508
+ }
509
+ assertExactKeys(
510
+ valueArg,
511
+ ["floor", "inferredVersion"],
512
+ "Release journal version floor",
513
+ );
514
+ if (
515
+ typeof valueArg.floor !== "string" ||
516
+ typeof valueArg.inferredVersion !== "string" ||
517
+ !isCanonicalReleaseVersion(valueArg.floor) ||
518
+ !isCanonicalReleaseVersion(valueArg.inferredVersion)
519
+ ) {
520
+ throw new Error(
521
+ "Release journal version floor must record canonical x.y.z versions.",
522
+ );
523
+ }
524
+ if (
525
+ valueArg.floor !== versionArg ||
526
+ compareReleaseVersions(valueArg.inferredVersion, valueArg.floor) >= 0
527
+ ) {
528
+ throw new Error(
529
+ "Release journal version floor must equal the release version and exceed the inferred version.",
530
+ );
531
+ }
532
+ };
533
+
534
+ const assertReleaseIdentity = (valueArg: unknown): IReleaseIdentity => {
535
+ if (!isPlainObject(valueArg)) {
536
+ throw new Error("Release journal release identity is missing.");
537
+ }
538
+ const hasVersionFloor = Object.hasOwn(valueArg, "versionFloor");
539
+ assertExactKeys(
540
+ valueArg,
541
+ hasVersionFloor
542
+ ? [...releaseIdentityKeys, "versionFloor"]
543
+ : releaseIdentityKeys,
544
+ "Release journal release",
545
+ );
546
+ if (
547
+ typeof valueArg.version !== "string" ||
548
+ normalizeReleaseVersion(valueArg.version) !== valueArg.version ||
549
+ valueArg.tag !== `v${valueArg.version}` ||
550
+ typeof valueArg.mainOid !== "string" ||
551
+ !gitOidRegex.test(valueArg.mainOid) ||
552
+ typeof valueArg.tagOid !== "string" ||
553
+ !gitOidRegex.test(valueArg.tagOid)
554
+ ) {
555
+ throw new Error("Release journal Git identity is invalid.");
556
+ }
557
+ if (hasVersionFloor) {
558
+ assertVersionFloorRecord(valueArg.versionFloor, valueArg.version);
559
+ }
560
+ return valueArg as unknown as IReleaseIdentity;
561
+ };
562
+
497
563
  const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
498
564
  if (!isPlainObject(valueArg)) {
499
565
  throw new Error("Release journal root must be a JSON object.");
@@ -523,29 +589,10 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
523
589
  throw new Error("Release journal header is invalid or unsupported.");
524
590
  }
525
591
 
526
- if (!isPlainObject(valueArg.release)) {
527
- throw new Error("Release journal release identity is missing.");
528
- }
529
- assertExactKeys(
530
- valueArg.release,
531
- ["version", "tag", "mainOid", "tagOid"],
532
- "Release journal release",
533
- );
534
- if (
535
- typeof valueArg.release.version !== "string" ||
536
- normalizeReleaseVersion(valueArg.release.version) !==
537
- valueArg.release.version ||
538
- valueArg.release.tag !== `v${valueArg.release.version}` ||
539
- typeof valueArg.release.mainOid !== "string" ||
540
- !gitOidRegex.test(valueArg.release.mainOid) ||
541
- typeof valueArg.release.tagOid !== "string" ||
542
- !gitOidRegex.test(valueArg.release.tagOid)
543
- ) {
544
- throw new Error("Release journal Git identity is invalid.");
545
- }
592
+ const release = assertReleaseIdentity(valueArg.release);
546
593
 
547
594
  const artifact = assertArtifact(valueArg.artifact);
548
- if (artifact && artifact.version !== valueArg.release.version) {
595
+ if (artifact && artifact.version !== release.version) {
549
596
  throw new Error(
550
597
  "Release journal artifact version does not match the release.",
551
598
  );
@@ -717,7 +764,7 @@ export const getReleaseDockerPromotionContext = (
717
764
 
718
765
  const assertDockerJournal = (
719
766
  valueArg: unknown,
720
- releaseArg: IReleaseJournalV2["release"],
767
+ releaseArg: IReleaseIdentity,
721
768
  ): IReleaseDockerJournal => {
722
769
  if (!isPlainObject(valueArg)) {
723
770
  throw new Error("Release journal Docker target is missing.");
@@ -932,28 +979,9 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
932
979
  ) {
933
980
  throw new Error("Release journal header is invalid or unsupported.");
934
981
  }
935
- if (!isPlainObject(valueArg.release)) {
936
- throw new Error("Release journal release identity is missing.");
937
- }
938
- assertExactKeys(
939
- valueArg.release,
940
- ["version", "tag", "mainOid", "tagOid"],
941
- "Release journal release",
942
- );
943
- if (
944
- typeof valueArg.release.version !== "string" ||
945
- normalizeReleaseVersion(valueArg.release.version) !==
946
- valueArg.release.version ||
947
- valueArg.release.tag !== `v${valueArg.release.version}` ||
948
- typeof valueArg.release.mainOid !== "string" ||
949
- !gitOidRegex.test(valueArg.release.mainOid) ||
950
- typeof valueArg.release.tagOid !== "string" ||
951
- !gitOidRegex.test(valueArg.release.tagOid)
952
- ) {
953
- throw new Error("Release journal Git identity is invalid.");
954
- }
982
+ const release = assertReleaseIdentity(valueArg.release);
955
983
  const artifact = assertArtifact(valueArg.artifact);
956
- if (artifact && artifact.version !== valueArg.release.version) {
984
+ if (artifact && artifact.version !== release.version) {
957
985
  throw new Error(
958
986
  "Release journal artifact version does not match the release.",
959
987
  );
@@ -1043,10 +1071,7 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1043
1071
  "Release journal npm targets and artifact must exist together.",
1044
1072
  );
1045
1073
  }
1046
- const docker = assertDockerJournal(
1047
- valueArg.docker,
1048
- valueArg.release as unknown as IReleaseJournalV2["release"],
1049
- );
1074
+ const docker = assertDockerJournal(valueArg.docker, release);
1050
1075
  const activePublishers = [
1051
1076
  valueArg.git as unknown as IReleaseTargetStatus,
1052
1077
  ...(valueArg.npm.registries as unknown as IReleaseTargetStatus[]),