@eserstack/codebase 0.0.0-bootstrap.0 → 5.0.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 (175) hide show
  1. package/README.md +302 -0
  2. package/dist/changelog-gen.d.ts +105 -0
  3. package/dist/changelog-gen.js +498 -0
  4. package/dist/changelog-text.d.ts +39 -0
  5. package/dist/changelog-text.js +82 -0
  6. package/dist/cli-support.d.ts +140 -0
  7. package/dist/cli-support.js +244 -0
  8. package/dist/cli-system/app-opts.d.ts +15 -0
  9. package/dist/cli-system/app-opts.js +13 -0
  10. package/dist/cli-system/app.d.ts +29 -0
  11. package/dist/cli-system/app.js +12 -0
  12. package/dist/cli-system/handlers/completions-setup.d.ts +14 -0
  13. package/dist/cli-system/handlers/completions-setup.js +139 -0
  14. package/dist/cli-system/handlers/completions.d.ts +3 -0
  15. package/dist/cli-system/handlers/completions.js +79 -0
  16. package/dist/cli-system/handlers/doctor.d.ts +8 -0
  17. package/dist/cli-system/handlers/doctor.js +146 -0
  18. package/dist/cli-system/handlers/info.d.ts +3 -0
  19. package/dist/cli-system/handlers/info.js +69 -0
  20. package/dist/cli-system/handlers/install.d.ts +8 -0
  21. package/dist/cli-system/handlers/install.js +137 -0
  22. package/dist/cli-system/handlers/mod.d.ts +12 -0
  23. package/dist/cli-system/handlers/mod.js +13 -0
  24. package/dist/cli-system/handlers/uninstall.d.ts +3 -0
  25. package/dist/cli-system/handlers/uninstall.js +60 -0
  26. package/dist/cli-system/handlers/update.d.ts +76 -0
  27. package/dist/cli-system/handlers/update.js +310 -0
  28. package/dist/cli-system/handlers/version-check.d.ts +16 -0
  29. package/dist/cli-system/handlers/version-check.js +176 -0
  30. package/dist/cli-system/handlers/version.d.ts +3 -0
  31. package/dist/cli-system/handlers/version.js +45 -0
  32. package/dist/cli-system/mod.d.ts +19 -0
  33. package/dist/cli-system/mod.js +52 -0
  34. package/dist/commitmsg.d.ts +28 -0
  35. package/dist/commitmsg.js +232 -0
  36. package/dist/directive-analysis.d.ts +75 -0
  37. package/dist/directive-analysis.js +223 -0
  38. package/dist/ffi-client.d.ts +11 -0
  39. package/dist/ffi-client.js +12 -0
  40. package/dist/file-tool.d.ts +96 -0
  41. package/dist/file-tool.js +274 -0
  42. package/dist/file-tools-shared.d.ts +81 -0
  43. package/dist/file-tools-shared.js +276 -0
  44. package/dist/gh-contributors.d.ts +89 -0
  45. package/dist/gh-contributors.js +205 -0
  46. package/dist/gh.d.ts +3 -0
  47. package/dist/gh.js +64 -0
  48. package/dist/git-listing.d.ts +27 -0
  49. package/dist/git-listing.js +69 -0
  50. package/dist/git.d.ts +172 -0
  51. package/dist/git.js +277 -0
  52. package/dist/install.d.ts +34 -0
  53. package/dist/install.js +421 -0
  54. package/dist/main.d.ts +22 -0
  55. package/dist/main.js +14 -0
  56. package/dist/mod.d.ts +25 -0
  57. package/dist/mod.js +8 -0
  58. package/dist/module.d.ts +10 -0
  59. package/dist/module.js +221 -0
  60. package/dist/native-functions.d.ts +1088 -0
  61. package/dist/native-functions.js +2 -0
  62. package/dist/npm-externals.d.ts +27 -0
  63. package/dist/npm-externals.js +34 -0
  64. package/dist/npm-workspace-specifiers.d.ts +6 -0
  65. package/dist/npm-workspace-specifiers.js +45 -0
  66. package/dist/package/loader.d.ts +34 -0
  67. package/dist/package/loader.js +203 -0
  68. package/dist/package/mod.d.ts +36 -0
  69. package/dist/package/mod.js +5 -0
  70. package/dist/package/types.d.ts +142 -0
  71. package/dist/package/types.js +32 -0
  72. package/dist/package/workspace.d.ts +33 -0
  73. package/dist/package/workspace.js +158 -0
  74. package/dist/package/writer.d.ts +52 -0
  75. package/dist/package/writer.js +278 -0
  76. package/dist/package.json +275 -0
  77. package/dist/release-notes.d.ts +90 -0
  78. package/dist/release-notes.js +236 -0
  79. package/dist/release-tag.d.ts +46 -0
  80. package/dist/release-tag.js +95 -0
  81. package/dist/release.d.ts +145 -0
  82. package/dist/release.js +584 -0
  83. package/dist/source-mask.d.ts +3 -0
  84. package/dist/source-mask.js +185 -0
  85. package/dist/validate-bom.d.ts +5 -0
  86. package/dist/validate-bom.js +43 -0
  87. package/dist/validate-case-conflict.d.ts +5 -0
  88. package/dist/validate-case-conflict.js +43 -0
  89. package/dist/validate-circular-deps.d.ts +11 -0
  90. package/dist/validate-circular-deps.js +53 -0
  91. package/dist/validate-code-conventions.d.ts +22 -0
  92. package/dist/validate-code-conventions.js +166 -0
  93. package/dist/validate-commit-msg.d.ts +50 -0
  94. package/dist/validate-commit-msg.js +182 -0
  95. package/dist/validate-docs.d.ts +20 -0
  96. package/dist/validate-docs.js +78 -0
  97. package/dist/validate-eof.d.ts +5 -0
  98. package/dist/validate-eof.js +61 -0
  99. package/dist/validate-error-coverage.d.ts +28 -0
  100. package/dist/validate-error-coverage.js +93 -0
  101. package/dist/validate-export-names.d.ts +17 -0
  102. package/dist/validate-export-names.js +56 -0
  103. package/dist/validate-filenames.d.ts +5 -0
  104. package/dist/validate-filenames.js +151 -0
  105. package/dist/validate-json.d.ts +5 -0
  106. package/dist/validate-json.js +71 -0
  107. package/dist/validate-large-files.d.ts +5 -0
  108. package/dist/validate-large-files.js +41 -0
  109. package/dist/validate-laroux-boundaries.d.ts +19 -0
  110. package/dist/validate-laroux-boundaries.js +59 -0
  111. package/dist/validate-licenses.d.ts +5 -0
  112. package/dist/validate-licenses.js +137 -0
  113. package/dist/validate-line-endings.d.ts +5 -0
  114. package/dist/validate-line-endings.js +47 -0
  115. package/dist/validate-merge-conflict.d.ts +5 -0
  116. package/dist/validate-merge-conflict.js +46 -0
  117. package/dist/validate-mod-exports.d.ts +16 -0
  118. package/dist/validate-mod-exports.js +56 -0
  119. package/dist/validate-naming-and-todos.d.ts +5 -0
  120. package/dist/validate-naming-and-todos.js +70 -0
  121. package/dist/validate-runtime-js-apis.d.ts +5 -0
  122. package/dist/validate-runtime-js-apis.js +78 -0
  123. package/dist/validate-secrets.d.ts +5 -0
  124. package/dist/validate-secrets.js +82 -0
  125. package/dist/validate-self-imports.d.ts +5 -0
  126. package/dist/validate-self-imports.js +78 -0
  127. package/dist/validate-server-loc.d.ts +32 -0
  128. package/dist/validate-server-loc.js +94 -0
  129. package/dist/validate-shebangs.d.ts +5 -0
  130. package/dist/validate-shebangs.js +33 -0
  131. package/dist/validate-stream.d.ts +25 -0
  132. package/dist/validate-stream.js +62 -0
  133. package/dist/validate-submodules.d.ts +5 -0
  134. package/dist/validate-submodules.js +43 -0
  135. package/dist/validate-symlinks.d.ts +5 -0
  136. package/dist/validate-symlinks.js +46 -0
  137. package/dist/validate-toml.d.ts +5 -0
  138. package/dist/validate-toml.js +40 -0
  139. package/dist/validate-trailing-whitespace.d.ts +5 -0
  140. package/dist/validate-trailing-whitespace.js +49 -0
  141. package/dist/validate-yaml.d.ts +5 -0
  142. package/dist/validate-yaml.js +40 -0
  143. package/dist/validation/config.d.ts +17 -0
  144. package/dist/validation/config.js +30 -0
  145. package/dist/validation/mod.d.ts +71 -0
  146. package/dist/validation/mod.js +479 -0
  147. package/dist/validation/registry.d.ts +57 -0
  148. package/dist/validation/registry.js +256 -0
  149. package/dist/validation/types.d.ts +101 -0
  150. package/dist/validation/types.js +2 -0
  151. package/dist/validation/validators/circular-deps.d.ts +7 -0
  152. package/dist/validation/validators/circular-deps.js +31 -0
  153. package/dist/validation/validators/docs.d.ts +7 -0
  154. package/dist/validation/validators/docs.js +38 -0
  155. package/dist/validation/validators/error-coverage.d.ts +2 -0
  156. package/dist/validation/validators/error-coverage.js +46 -0
  157. package/dist/validation/validators/export-names.d.ts +7 -0
  158. package/dist/validation/validators/export-names.js +31 -0
  159. package/dist/validation/validators/laroux-boundaries.d.ts +2 -0
  160. package/dist/validation/validators/laroux-boundaries.js +29 -0
  161. package/dist/validation/validators/mod-exports.d.ts +7 -0
  162. package/dist/validation/validators/mod-exports.js +32 -0
  163. package/dist/validation/validators/mod.d.ts +11 -0
  164. package/dist/validation/validators/mod.js +12 -0
  165. package/dist/validation/validators/server-loc.d.ts +2 -0
  166. package/dist/validation/validators/server-loc.js +48 -0
  167. package/dist/versions.d.ts +166 -0
  168. package/dist/versions.js +349 -0
  169. package/dist/violation-baseline.d.ts +58 -0
  170. package/dist/violation-baseline.js +144 -0
  171. package/dist/walk-stream.d.ts +24 -0
  172. package/dist/walk-stream.js +55 -0
  173. package/dist/workspace-discovery.d.ts +60 -0
  174. package/dist/workspace-discovery.js +130 -0
  175. package/package.json +225 -1
@@ -0,0 +1,95 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Release tag management — reads VERSION file, creates and pushes git tags.
4
+ *
5
+ * Can be used as a library or as a standalone script.
6
+ *
7
+ * Library usage:
8
+ * ```typescript
9
+ * import * as releaseTag from "@eserstack/codebase/release-tag";
10
+ *
11
+ * const result = await releaseTag.pushReleaseTag({ dryRun: true });
12
+ * console.log(result.tag); // "v4.0.43"
13
+ * ```
14
+ *
15
+ * CLI usage:
16
+ * node ./release-tag.ts [--dry-run]
17
+ *
18
+ * @module
19
+ */
20
+ import * as primitives from "@eserstack/primitives";
21
+ import * as standards from "@eserstack/standards";
22
+ import * as functions from "@eserstack/functions";
23
+ import * as tui from "@eserstack/shell/tui";
24
+ import * as git from "./git.js";
25
+ import * as versions from "./versions.js";
26
+ import * as cliSupport from "./cli-support.js";
27
+ /**
28
+ * Reads the VERSION file, creates an annotated git tag, and pushes it.
29
+ *
30
+ * @param options - Options for the operation
31
+ * @returns Result describing the tag that was created
32
+ * @throws If the VERSION file is missing or contains an invalid version
33
+ */
34
+ export const pushReleaseTag = async (options = {}) => {
35
+ const { root = ".", remote = "origin", tagPrefix = "v", messageTemplate = "Release {tag}", dryRun = false, } = options;
36
+ const version = await versions.readVersionFile({ root });
37
+ if (version === undefined || !/^\d+\.\d+\.\d+$/.test(version)) {
38
+ throw new Error(`Invalid or missing version in VERSION file: "${version}"`);
39
+ }
40
+ const tag = `${tagPrefix}${version}`;
41
+ const message = messageTemplate
42
+ .replace("{tag}", tag)
43
+ .replace("{version}", version);
44
+ if (!dryRun) {
45
+ await git.createTag(tag, message);
46
+ await git.pushTag(remote, tag);
47
+ }
48
+ return { version, tag, remote, dryRun };
49
+ };
50
+ // --- Handler ---
51
+ /** Handler: wraps pushReleaseTag as a Task via fromPromise. */
52
+ export const pushReleaseTagHandler = (input) => functions.task.fromPromise(() => pushReleaseTag(input));
53
+ // --- CLI Adapter ---
54
+ /** Adapter: functions.triggers.CliEvent → PushReleaseTagOptions (extracts --dry-run flag). */
55
+ const cliAdapter = (event) => primitives.results.ok({ dryRun: event.flags["dry-run"] === true });
56
+ // --- CLI ResponseMapper ---
57
+ /** ResponseMapper: formats PushReleaseTagResult for CLI output. */
58
+ const cliResponseMapper = (result) => {
59
+ const { ctx } = cliSupport.getCliContext();
60
+ if (primitives.results.isFail(result)) {
61
+ const message = result.error instanceof Error
62
+ ? result.error.message
63
+ : String(result.error);
64
+ tui.log.error(ctx, message);
65
+ return primitives.results.fail({ exitCode: 1 });
66
+ }
67
+ const { value } = result;
68
+ if (value.dryRun) {
69
+ tui.log.warn(ctx, `[DRY RUN] Would create and push tag ${value.tag}`);
70
+ }
71
+ else {
72
+ tui.log.success(ctx, `Created tag ${value.tag}`);
73
+ tui.log.info(ctx, `Pushed tag ${value.tag} to ${value.remote}`);
74
+ }
75
+ return primitives.results.ok(undefined);
76
+ };
77
+ // --- CLI Trigger ---
78
+ /** Runnable CLI trigger for release-tag. */
79
+ export const handleCli = functions.handler.createTrigger({
80
+ handler: pushReleaseTagHandler,
81
+ adaptInput: cliAdapter,
82
+ adaptOutput: cliResponseMapper,
83
+ });
84
+ /** Parse the release-tag arguments: `--dry-run` (`-n`). */
85
+ export const parseCliArgs = (cliArgs) => cliSupport.parseCliEvent("release-tag", cliArgs, {
86
+ "dry-run": { type: "boolean", short: "n" },
87
+ });
88
+ /** CLI entry point for dispatcher compatibility. */
89
+ export const main = async (cliArgs) => await handleCli(parseCliArgs(cliArgs));
90
+ if (import.meta.main) {
91
+ // Entry point: the await only runs when this file is executed directly.
92
+ // oxlint-disable-next-line node/no-top-level-await
93
+ const result = await main(standards.crossRuntime.runtime.process.args);
94
+ cliSupport.runCliMain(result, cliSupport.getCliContext().output);
95
+ }
@@ -0,0 +1,145 @@
1
+ import * as functions from "@eserstack/functions";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ import type * as changelogGen from "./changelog-gen.ts";
4
+ /**
5
+ * Options for the release command.
6
+ */
7
+ export type ReleaseOptions = {
8
+ /** Version bump type: patch, minor, major, or same (no bump). */
9
+ readonly type: "patch" | "minor" | "major" | "same";
10
+ /** Preview changes without executing (default: false). */
11
+ readonly dryRun?: boolean;
12
+ /** Skip confirmation prompt (default: false). */
13
+ readonly yes?: boolean;
14
+ };
15
+ /**
16
+ * What the release flow calls out to, replaceable in tests.
17
+ */
18
+ export type ReleaseDeps = {
19
+ /** Writes the changelog section, or previews it under dryRun. */
20
+ readonly generateChangelog: (options: changelogGen.GenerateChangelogOptions) => Promise<changelogGen.GenerateChangelogResult>;
21
+ };
22
+ /**
23
+ * Result of the release command.
24
+ */
25
+ export type ReleaseResult = {
26
+ /** The new version after bumping. */
27
+ readonly version: string;
28
+ /** The previous version before bumping. */
29
+ readonly previousVersion: string;
30
+ /** The release tag for the new version (e.g. "v4.3.1"). */
31
+ readonly tag: string;
32
+ /** Whether the commits since the last tag gave the changelog any entry. */
33
+ readonly changelogGenerated: boolean;
34
+ /** Whether changes were committed. */
35
+ readonly committed: boolean;
36
+ /** Whether the commit was pushed. */
37
+ readonly pushed: boolean;
38
+ /** Whether the tag was pushed (this is what starts the pipeline). */
39
+ readonly tagPushed: boolean;
40
+ /** Whether this was a dry run. */
41
+ readonly dryRun: boolean;
42
+ };
43
+ /**
44
+ * Options for the rerelease command.
45
+ */
46
+ export type RereleaseOptions = {
47
+ /** Preview changes without executing (default: false). */
48
+ readonly dryRun?: boolean;
49
+ /** Skip confirmation prompt (default: false). */
50
+ readonly yes?: boolean;
51
+ };
52
+ /**
53
+ * Result of the rerelease command.
54
+ */
55
+ export type RereleaseResult = {
56
+ /** The current version. */
57
+ readonly version: string;
58
+ /** The tag that was recreated. */
59
+ readonly tag: string;
60
+ /** Whether this was a dry run. */
61
+ readonly dryRun: boolean;
62
+ };
63
+ /**
64
+ * Options for the unrelease command.
65
+ */
66
+ export type UnreleaseOptions = {
67
+ /** Skip confirmation prompt (default: false). */
68
+ readonly yes?: boolean;
69
+ };
70
+ /**
71
+ * Result of the unrelease command.
72
+ */
73
+ export type UnreleaseResult = {
74
+ /** The current version. */
75
+ readonly version: string;
76
+ /** The tag that was deleted. */
77
+ readonly tag: string;
78
+ /** Whether the tag was deleted. */
79
+ readonly deleted: boolean;
80
+ /** Whether the matching GitHub Release was deleted (best-effort). */
81
+ readonly releaseDeleted: boolean;
82
+ };
83
+ /**
84
+ * Perform a full release: bump version, generate changelog, commit, push, and
85
+ * push the `v<version>` tag that starts the release pipeline.
86
+ *
87
+ * The tag push is the last step and the only one CI reacts to, so a release
88
+ * that stops before it publishes nothing — both push failures below name the
89
+ * command that finishes the job.
90
+ *
91
+ * @param options - Release options
92
+ * @returns Result describing what happened
93
+ * @throws If working tree is dirty, or unpushed commits exist (without --yes)
94
+ */
95
+ export declare const release: (options: ReleaseOptions, deps?: ReleaseDeps) => Promise<ReleaseResult>;
96
+ /**
97
+ * Delete the current version tag and re-push it at HEAD, re-firing the release
98
+ * pipeline for a version that is already committed.
99
+ *
100
+ * This is the repair path for a release whose tag push failed or whose pipeline
101
+ * run needs repeating; it adds no commit and changes no version.
102
+ *
103
+ * Pre-checks: tree must be clean, no unpushed commits.
104
+ *
105
+ * @param options - Rerelease options
106
+ * @returns Result describing what happened
107
+ * @throws If working tree is dirty or unpushed commits exist
108
+ */
109
+ export declare const rerelease: (options?: RereleaseOptions) => Promise<RereleaseResult>;
110
+ /**
111
+ * Delete the current version tag (local + remote) and its GitHub Release.
112
+ *
113
+ * The version-bump commit is deliberately left in history — rewriting a pushed
114
+ * commit is not something a cleanup command should do behind the operator's
115
+ * back. `eser codebase rerelease` re-pushes the tag afterwards, which is the
116
+ * command for "the version is already committed, the tag needs to exist again".
117
+ *
118
+ * @param options - Unrelease options
119
+ * @returns Result describing what happened
120
+ */
121
+ export declare const unrelease: (options?: UnreleaseOptions) => Promise<UnreleaseResult>;
122
+ /** Handler: wraps release as a Task via fromPromise. */
123
+ export declare const releaseHandler: functions.handler.Handler<ReleaseOptions, ReleaseResult, Error>;
124
+ /** Handler: wraps rerelease as a Task via fromPromise. */
125
+ export declare const rereleaseHandler: functions.handler.Handler<RereleaseOptions, RereleaseResult, Error>;
126
+ /** Handler: wraps unrelease as a Task via fromPromise. */
127
+ export declare const unreleaseHandler: functions.handler.Handler<UnreleaseOptions, UnreleaseResult, Error>;
128
+ /** Runnable CLI trigger for release. */
129
+ export declare const handleReleaseCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
130
+ /** Runnable CLI trigger for rerelease. */
131
+ export declare const handleRereleaseCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
132
+ /** Runnable CLI trigger for unrelease. */
133
+ export declare const handleUnreleaseCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
134
+ /** Parse the release arguments: the bump type, `--dry-run` (`-n`), `--yes` (`-y`). */
135
+ export declare const parseReleaseArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
136
+ /** Parse the rerelease arguments: `--dry-run` (`-n`), `--yes` (`-y`). */
137
+ export declare const parseRereleaseArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
138
+ /** Parse the unrelease arguments: `--yes` (`-y`). */
139
+ export declare const parseUnreleaseArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
140
+ /** CLI entry point for release (default export via main). */
141
+ export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;
142
+ /** CLI entry point for rerelease. */
143
+ export declare const rereleaseMain: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;
144
+ /** CLI entry point for unrelease. */
145
+ export declare const unreleaseMain: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;