@eserstack/codebase 0.0.0-stage → 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 +301 -2
  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 +222 -3
@@ -0,0 +1,89 @@
1
+ import * as functions from "@eserstack/functions";
2
+ import type * as shellArgs from "@eserstack/shell/args";
3
+ /**
4
+ * A GitHub contributor returned by the API. The snake_case keys are the
5
+ * GitHub REST API's field names.
6
+ */
7
+ export type Contributor = {
8
+ readonly login: string;
9
+ readonly avatar_url: string;
10
+ readonly html_url: string;
11
+ readonly contributions: number;
12
+ };
13
+ /**
14
+ * Options for updating the contributor list.
15
+ */
16
+ export type UpdateContributorsOptions = {
17
+ /** Path to README.md (default: "README.md") */
18
+ readonly readmePath?: string;
19
+ /** Number of columns per row in the table (default: 8) */
20
+ readonly columnsPerRow?: number;
21
+ /** Auto-commit and push changes (default: false) */
22
+ readonly commit?: boolean;
23
+ };
24
+ /**
25
+ * Result of updating the contributor list.
26
+ */
27
+ export type UpdateContributorsResult = {
28
+ /** Number of contributors found */
29
+ readonly contributorCount: number;
30
+ /** Path to the README that was updated */
31
+ readonly readmePath: string;
32
+ /** Whether the README was modified */
33
+ readonly updated: boolean;
34
+ /** Whether changes were committed */
35
+ readonly committed: boolean;
36
+ };
37
+ /**
38
+ * Gets the current repository owner and name via `gh repo view`.
39
+ *
40
+ * @returns Object with owner and name fields
41
+ * @throws If not in a GitHub repository or gh CLI is unavailable
42
+ */
43
+ export declare const getRepoInfo: () => Promise<{
44
+ readonly owner: string;
45
+ readonly name: string;
46
+ }>;
47
+ /**
48
+ * Fetches all contributors for a repository via the GitHub API.
49
+ *
50
+ * @param owner - Repository owner
51
+ * @param repo - Repository name
52
+ * @returns Array of contributors sorted by contribution count
53
+ */
54
+ export declare const fetchContributors: (owner: string, repo: string) => Promise<Contributor[]>;
55
+ /**
56
+ * Generates an HTML table of contributors.
57
+ *
58
+ * @param contributors - Array of contributors
59
+ * @param columnsPerRow - Number of columns per row (default: 8)
60
+ * @returns HTML table string
61
+ */
62
+ export declare const generateContributorMarkdown: (contributors: readonly Contributor[], columnsPerRow?: number) => string;
63
+ /**
64
+ * Replaces the contributor section in a README string.
65
+ *
66
+ * @param readmeContent - Current README content
67
+ * @param markdown - New contributor markdown to insert
68
+ * @returns Object with updated content and whether it changed
69
+ * @throws If contributor markers are not found in the README
70
+ */
71
+ export declare const replaceContributorSection: (readmeContent: string, markdown: string) => {
72
+ readonly content: string;
73
+ readonly changed: boolean;
74
+ };
75
+ /**
76
+ * Updates the contributor list in the README.
77
+ *
78
+ * @param options - Options for the operation
79
+ * @returns Result describing what was done
80
+ */
81
+ export declare const updateContributors: (options?: UpdateContributorsOptions) => Promise<UpdateContributorsResult>;
82
+ /** Handler: wraps updateContributors as a Task via fromPromise. */
83
+ export declare const updateContributorsHandler: functions.handler.Handler<UpdateContributorsOptions, UpdateContributorsResult, Error>;
84
+ /** Runnable CLI trigger for gh-contributors. */
85
+ export declare const handleCli: (event: functions.triggers.CliEvent) => Promise<shellArgs.CliResult<void>>;
86
+ /** Parse the gh contributors arguments: `--columns`, `--readme`, `--commit`, `--help`. */
87
+ export declare const parseCliArgs: (cliArgs?: readonly string[]) => functions.triggers.CliEvent;
88
+ /** CLI entry point for dispatcher compatibility. */
89
+ export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;
@@ -0,0 +1,205 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Update contributor list in README.md using the GitHub API.
4
+ *
5
+ * Fetches contributors via `gh api`, generates an HTML table, and replaces the
6
+ * content between `<!-- CONTRIBUTORS:START -->` and `<!-- CONTRIBUTORS:END -->`
7
+ * markers in the README.
8
+ *
9
+ * Can be used as a library or as a standalone script.
10
+ *
11
+ * Library usage:
12
+ * ```typescript
13
+ * import * as ghContributors from "@eserstack/codebase/gh-contributors";
14
+ *
15
+ * const result = await ghContributors.updateContributors({ columnsPerRow: 8 });
16
+ * console.log(result.contributorCount); // 12
17
+ * ```
18
+ *
19
+ * CLI usage:
20
+ * eser codebase gh contributors [--columns <n>] [--readme <path>] [--commit]
21
+ *
22
+ * @module
23
+ */
24
+ import * as primitives from "@eserstack/primitives";
25
+ import * as standards from "@eserstack/standards";
26
+ import * as functions from "@eserstack/functions";
27
+ import * as shell from "@eserstack/shell";
28
+ import * as tui from "@eserstack/shell/tui";
29
+ import * as cliSupport from "./cli-support.js";
30
+ // --- Pure logic ---
31
+ const START_MARKER = "<!-- CONTRIBUTORS:START -->";
32
+ const END_MARKER = "<!-- CONTRIBUTORS:END -->";
33
+ /**
34
+ * Gets the current repository owner and name via `gh repo view`.
35
+ *
36
+ * @returns Object with owner and name fields
37
+ * @throws If not in a GitHub repository or gh CLI is unavailable
38
+ */
39
+ export const getRepoInfo = async () => {
40
+ const json = await shell.exec.exec `gh repo view --json owner,name`.text();
41
+ const parsed = JSON.parse(json);
42
+ return { owner: parsed.owner.login, name: parsed.name };
43
+ };
44
+ /**
45
+ * Fetches all contributors for a repository via the GitHub API.
46
+ *
47
+ * @param owner - Repository owner
48
+ * @param repo - Repository name
49
+ * @returns Array of contributors sorted by contribution count
50
+ */
51
+ export const fetchContributors = async (owner, repo) => {
52
+ const json = await shell.exec
53
+ .exec `gh api repos/${owner}/${repo}/contributors --paginate`.text();
54
+ const contributors = JSON.parse(json);
55
+ return contributors.filter((c) => !c.login.includes("[bot]"));
56
+ };
57
+ /**
58
+ * Generates an HTML table of contributors.
59
+ *
60
+ * @param contributors - Array of contributors
61
+ * @param columnsPerRow - Number of columns per row (default: 8)
62
+ * @returns HTML table string
63
+ */
64
+ export const generateContributorMarkdown = (contributors, columnsPerRow = 8) => {
65
+ if (contributors.length === 0) {
66
+ return `${START_MARKER}\n${END_MARKER}`;
67
+ }
68
+ const rows = [];
69
+ for (let i = 0; i < contributors.length; i += columnsPerRow) {
70
+ const chunk = contributors.slice(i, i + columnsPerRow);
71
+ const cells = chunk.map((c) => ` <td align="center"><a href="${c.html_url}"><img src="${c.avatar_url}?s=80" width="80" /><br /><sub>${c.login}</sub></a></td>`);
72
+ rows.push(` <tr>\n${cells.join("\n")}\n </tr>`);
73
+ }
74
+ return `${START_MARKER}\n<table>\n${rows.join("\n")}\n</table>\n${END_MARKER}`;
75
+ };
76
+ /**
77
+ * Replaces the contributor section in a README string.
78
+ *
79
+ * @param readmeContent - Current README content
80
+ * @param markdown - New contributor markdown to insert
81
+ * @returns Object with updated content and whether it changed
82
+ * @throws If contributor markers are not found in the README
83
+ */
84
+ export const replaceContributorSection = (readmeContent, markdown) => {
85
+ const startIdx = readmeContent.indexOf(START_MARKER);
86
+ const endIdx = readmeContent.indexOf(END_MARKER);
87
+ if (startIdx === -1 || endIdx === -1) {
88
+ throw new Error(`Could not find contributor markers in README. ` +
89
+ `Add '${START_MARKER}' and '${END_MARKER}' markers to the file.`);
90
+ }
91
+ const before = readmeContent.slice(0, startIdx);
92
+ const after = readmeContent.slice(endIdx + END_MARKER.length);
93
+ const newContent = `${before}${markdown}${after}`;
94
+ return { content: newContent, changed: newContent !== readmeContent };
95
+ };
96
+ // --- Main function ---
97
+ /**
98
+ * Updates the contributor list in the README.
99
+ *
100
+ * @param options - Options for the operation
101
+ * @returns Result describing what was done
102
+ */
103
+ export const updateContributors = async (options = {}) => {
104
+ const { readmePath = "README.md", columnsPerRow = 8, commit: shouldCommit = false, } = options;
105
+ const resolvedPath = standards.crossRuntime.runtime.path.resolve(readmePath);
106
+ // Get repo info
107
+ const repoInfo = await getRepoInfo();
108
+ // Fetch contributors
109
+ const contributors = await fetchContributors(repoInfo.owner, repoInfo.name);
110
+ // Generate markdown
111
+ const markdown = generateContributorMarkdown(contributors, columnsPerRow);
112
+ // Read README and replace section
113
+ const currentContent = await standards.crossRuntime.runtime.fs.readTextFile(resolvedPath);
114
+ const { content: newContent, changed } = replaceContributorSection(currentContent, markdown);
115
+ let committed = false;
116
+ if (changed) {
117
+ await standards.crossRuntime.runtime.fs.writeTextFile(resolvedPath, newContent);
118
+ if (shouldCommit) {
119
+ await shell.exec.exec `git add ${resolvedPath}`.spawn();
120
+ await shell.exec
121
+ .exec `git -c user.name=${"github-actions[bot]"} -c user.email=${"github-actions[bot]@users.noreply.github.com"} commit -m ${"docs: update contributors list"}`.spawn();
122
+ await shell.exec.exec `git push`.spawn();
123
+ committed = true;
124
+ }
125
+ }
126
+ return {
127
+ contributorCount: contributors.length,
128
+ readmePath: resolvedPath,
129
+ updated: changed,
130
+ committed,
131
+ };
132
+ };
133
+ // --- Handler ---
134
+ /** Handler: wraps updateContributors as a Task via fromPromise. */
135
+ export const updateContributorsHandler = (input) => functions.task.fromPromise(() => updateContributors(input));
136
+ // --- CLI Adapter ---
137
+ /** Adapter: functions.triggers.CliEvent -> UpdateContributorsOptions. */
138
+ const cliAdapter = (event) => {
139
+ const columnsRaw = event.flags["columns"];
140
+ const columns = columnsRaw !== undefined ? Number(columnsRaw) : undefined;
141
+ return primitives.results.ok({
142
+ readmePath: event.flags["readme"] ?? undefined,
143
+ columnsPerRow: columns,
144
+ commit: event.flags["commit"] === true,
145
+ });
146
+ };
147
+ // --- CLI ResponseMapper ---
148
+ /** ResponseMapper: formats UpdateContributorsResult for CLI output. */
149
+ const cliResponseMapper = (result) => {
150
+ const { ctx } = cliSupport.getCliContext();
151
+ if (primitives.results.isFail(result)) {
152
+ const err = result.error;
153
+ const message = err instanceof Error
154
+ ? err.message
155
+ : (err.message ?? String(err));
156
+ tui.log.error(ctx, message);
157
+ return primitives.results.fail({ exitCode: 1 });
158
+ }
159
+ const { value } = result;
160
+ if (!value.updated) {
161
+ tui.log.info(ctx, `No changes — ${value.contributorCount} contributors already up to date.`);
162
+ }
163
+ else if (value.committed) {
164
+ tui.log.success(ctx, `Updated ${value.contributorCount} contributors and committed changes.`);
165
+ }
166
+ else {
167
+ tui.log.success(ctx, `Updated ${value.contributorCount} contributors in ${value.readmePath}.`);
168
+ }
169
+ return primitives.results.ok(undefined);
170
+ };
171
+ // --- CLI Trigger ---
172
+ /** Runnable CLI trigger for gh-contributors. */
173
+ export const handleCli = functions.handler.createTrigger({
174
+ handler: updateContributorsHandler,
175
+ adaptInput: cliAdapter,
176
+ adaptOutput: cliResponseMapper,
177
+ });
178
+ /** Parse the gh contributors arguments: `--columns`, `--readme`, `--commit`, `--help`. */
179
+ export const parseCliArgs = (cliArgs) => cliSupport.parseCliEvent("gh-contributors", cliArgs, {
180
+ columns: { type: "string" },
181
+ readme: { type: "string" },
182
+ commit: { type: "boolean" },
183
+ help: { type: "boolean", short: "h" },
184
+ });
185
+ /** CLI entry point for dispatcher compatibility. */
186
+ export const main = async (cliArgs) => {
187
+ const event = parseCliArgs(cliArgs);
188
+ if (event.flags["help"] === true) {
189
+ const { output: out } = cliSupport.getCliContext();
190
+ out.writeln("eser codebase gh contributors — Update contributor list\n");
191
+ out.writeln("Options:");
192
+ out.writeln(" --columns <n> Number of columns per row (default: 8)");
193
+ out.writeln(" --readme <path> Path to README.md (default: README.md)");
194
+ out.writeln(" --commit Auto-commit and push changes");
195
+ out.writeln(" --help, -h Show this help");
196
+ return primitives.results.ok(undefined);
197
+ }
198
+ return await handleCli(event);
199
+ };
200
+ if (import.meta.main) {
201
+ // Entry point: the await only runs when this file is executed directly.
202
+ // oxlint-disable-next-line node/no-top-level-await
203
+ const result = await main(standards.crossRuntime.runtime.process.args);
204
+ cliSupport.runCliMain(result, cliSupport.getCliContext().output);
205
+ }
package/dist/gh.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type * as shellArgs from "@eserstack/shell/args";
2
+ /** CLI entry point for dispatcher compatibility. */
3
+ export declare const main: (cliArgs?: readonly string[]) => Promise<shellArgs.CliResult<void>>;
package/dist/gh.js ADDED
@@ -0,0 +1,64 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Sub-dispatcher for GitHub operations.
4
+ *
5
+ * Routes `eser codebase gh <subcommand>` to the correct handler module.
6
+ *
7
+ * CLI usage:
8
+ * eser codebase gh contributors — Update contributor list in README.md
9
+ * eser codebase gh release-notes — Sync CHANGELOG to GitHub Releases
10
+ * eser codebase gh release-tag — Create and push release git tags
11
+ *
12
+ * @module
13
+ */
14
+ import * as primitives from "@eserstack/primitives";
15
+ import * as standards from "@eserstack/standards";
16
+ import * as tui from "@eserstack/shell/tui";
17
+ import * as cliSupport from "./cli-support.js";
18
+ const showGhHelp = () => {
19
+ const { ctx, output: out } = cliSupport.getCliContext();
20
+ tui.log.info(ctx, "eser codebase gh — GitHub operations\n");
21
+ out.writeln("Subcommands:");
22
+ out.writeln(" contributors Update contributor list in README.md");
23
+ out.writeln(" release-notes Sync CHANGELOG to GitHub Releases");
24
+ out.writeln(" release-tag Create and push release git tags");
25
+ out.writeln("\nRun 'eser codebase gh <subcommand> --help' for details.");
26
+ };
27
+ /** CLI entry point for dispatcher compatibility. */
28
+ export const main = async (cliArgs) => {
29
+ const args = (cliArgs ?? []);
30
+ const subcommand = args[0];
31
+ const remaining = args.slice(1);
32
+ if (subcommand === undefined ||
33
+ subcommand === "--help" ||
34
+ subcommand === "-h") {
35
+ showGhHelp();
36
+ return primitives.results.ok(undefined);
37
+ }
38
+ switch (subcommand) {
39
+ case "contributors": {
40
+ const mod = await import("./gh-contributors.js");
41
+ return await mod.main(remaining);
42
+ }
43
+ case "release-notes": {
44
+ const mod = await import("./release-notes.js");
45
+ return await mod.main(remaining);
46
+ }
47
+ case "release-tag": {
48
+ const mod = await import("./release-tag.js");
49
+ return await mod.main(remaining);
50
+ }
51
+ default: {
52
+ const { ctx } = cliSupport.getCliContext();
53
+ tui.log.error(ctx, `Unknown gh subcommand: ${subcommand}`);
54
+ showGhHelp();
55
+ return primitives.results.fail({ exitCode: 1 });
56
+ }
57
+ }
58
+ };
59
+ if (import.meta.main) {
60
+ // Entry point: the await only runs when this file is executed directly.
61
+ // oxlint-disable-next-line node/no-top-level-await
62
+ const result = await main(standards.crossRuntime.runtime.process.args);
63
+ cliSupport.runCliMain(result, cliSupport.getCliContext().output);
64
+ }
@@ -0,0 +1,27 @@
1
+ import type * as ffiTypes from "@eserstack/ajan/ffi";
2
+ /**
3
+ * List the files git tracks or would track under `root`, relative to it:
4
+ * `git ls-files --cached --others --exclude-standard`, so .gitignore holds.
5
+ *
6
+ * @returns The paths, or `null` when `root` is not inside a git repository
7
+ * @throws {Error} When git cannot run or fails for another reason; walking the
8
+ * filesystem instead would list the gitignored files too
9
+ */
10
+ export declare const listGitFiles: (root: string) => Promise<string[] | null>;
11
+ /** The git fields of a codebase walk or validate request. */
12
+ export type BridgeGitOptions = {
13
+ readonly gitAware: boolean;
14
+ readonly gitFiles?: readonly string[];
15
+ };
16
+ /**
17
+ * The git fields for a bridge request that walks `root`.
18
+ *
19
+ * On the native library this is `{ gitAware }`: Go runs git. On the WASM build
20
+ * the listing comes from {@link listGitFiles}; outside a git repository the
21
+ * walk goes without git, as the native walk does there.
22
+ *
23
+ * @param lib - The loaded bridge
24
+ * @param root - The directory the request walks (default ".")
25
+ * @param gitAware - Whether the request asks for a git-aware walk
26
+ */
27
+ export declare const bridgeGitOptions: (lib: ffiTypes.FFILibrary, root: string | undefined, gitAware?: boolean) => Promise<BridgeGitOptions>;
@@ -0,0 +1,69 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * The git listing behind every git-aware walk of this package.
4
+ *
5
+ * The native library runs `git ls-files` itself. The WASM build cannot start a
6
+ * process, and its git-aware walk fails without a listing (TASK-366), so on
7
+ * that backend the listing is made here, on the host, and sent with the
8
+ * request as `gitFiles`.
9
+ *
10
+ * @module
11
+ */
12
+ import * as shellExec from "@eserstack/shell/exec";
13
+ // `git ls-files` returns in well under a second; the bound keeps a hung git (a
14
+ // held index lock) from stalling a validator.
15
+ const GIT_LS_FILES_TIMEOUT_MS = 30_000;
16
+ const decoder = new TextDecoder();
17
+ /**
18
+ * List the files git tracks or would track under `root`, relative to it:
19
+ * `git ls-files --cached --others --exclude-standard`, so .gitignore holds.
20
+ *
21
+ * @returns The paths, or `null` when `root` is not inside a git repository
22
+ * @throws {Error} When git cannot run or fails for another reason; walking the
23
+ * filesystem instead would list the gitignored files too
24
+ */
25
+ export const listGitFiles = async (root) => {
26
+ let result;
27
+ try {
28
+ result =
29
+ await shellExec.exec `git ls-files -z --cached --others --exclude-standard`
30
+ .cwd(root)
31
+ .timeout(GIT_LS_FILES_TIMEOUT_MS)
32
+ .noThrow()
33
+ .spawn();
34
+ }
35
+ catch (error) {
36
+ throw new Error(`list the files of ${root} with git: git cannot run, so .gitignore ` +
37
+ `cannot be honoured; install git or put it on PATH`, { cause: error });
38
+ }
39
+ if (!result.success) {
40
+ const stderr = decoder.decode(result.stderr).trim();
41
+ if (stderr.includes("not a git repository")) {
42
+ return null;
43
+ }
44
+ throw new Error(`list the files of ${root} with git: git ls-files exited with ` +
45
+ `${result.code}: ${stderr}`);
46
+ }
47
+ return decoder
48
+ .decode(result.stdout)
49
+ .split("\0")
50
+ .filter((path) => path !== "");
51
+ };
52
+ /**
53
+ * The git fields for a bridge request that walks `root`.
54
+ *
55
+ * On the native library this is `{ gitAware }`: Go runs git. On the WASM build
56
+ * the listing comes from {@link listGitFiles}; outside a git repository the
57
+ * walk goes without git, as the native walk does there.
58
+ *
59
+ * @param lib - The loaded bridge
60
+ * @param root - The directory the request walks (default ".")
61
+ * @param gitAware - Whether the request asks for a git-aware walk
62
+ */
63
+ export const bridgeGitOptions = async (lib, root, gitAware = true) => {
64
+ if (!gitAware || lib.backend === "native") {
65
+ return { gitAware };
66
+ }
67
+ const gitFiles = await listGitFiles(root ?? ".");
68
+ return gitFiles === null ? { gitAware: false } : { gitAware, gitFiles };
69
+ };
package/dist/git.d.ts ADDED
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Represents a git commit with its metadata.
3
+ */
4
+ export type Commit = {
5
+ /** The commit subject (first line of commit message) */
6
+ subject: string;
7
+ /** The commit body (rest of the commit message), empty when there is none */
8
+ body: string;
9
+ /** The full commit hash (40 characters) */
10
+ hash: string;
11
+ };
12
+ /**
13
+ * Represents a git user for commit authorship.
14
+ */
15
+ export type CommitUser = {
16
+ /** The user's name */
17
+ name: string;
18
+ /** The user's email address */
19
+ email: string;
20
+ };
21
+ /**
22
+ * Gets the latest tag in the current branch.
23
+ *
24
+ * @returns The latest tag name
25
+ * @throws If no tags are found or git command fails
26
+ *
27
+ * @example
28
+ * ```typescript
29
+ * const tag = await getLatestTag();
30
+ * console.log(tag); // "v1.0.0"
31
+ * ```
32
+ */
33
+ export declare const getLatestTag: () => Promise<string>;
34
+ /**
35
+ * Gets the name of the current git branch.
36
+ *
37
+ * @returns The current branch name
38
+ * @throws If not in a git repository or in detached HEAD state
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * const branch = await getCurrentBranch();
43
+ * console.log(branch); // "main"
44
+ * ```
45
+ */
46
+ export declare const getCurrentBranch: () => Promise<string>;
47
+ /**
48
+ * Checks out a specific git reference (branch, tag, or commit).
49
+ *
50
+ * @param ref - The reference to checkout (branch name, tag, or commit hash)
51
+ *
52
+ * @example
53
+ * ```typescript
54
+ * await checkout("main");
55
+ * await checkout("v1.0.0");
56
+ * await checkout("abc123");
57
+ * ```
58
+ */
59
+ export declare const checkout: (ref: string) => Promise<void>;
60
+ /**
61
+ * Checks out the previous git reference (equivalent to `git checkout -`).
62
+ *
63
+ * @example
64
+ * ```typescript
65
+ * await checkout("feature-branch");
66
+ * // do some work
67
+ * await checkoutPrevious(); // goes back to previous branch
68
+ * ```
69
+ */
70
+ export declare const checkoutPrevious: () => Promise<void>;
71
+ /**
72
+ * Creates a new branch and checks it out.
73
+ *
74
+ * @param name - The name of the new branch
75
+ *
76
+ * @example
77
+ * ```typescript
78
+ * await createAndCheckoutBranch("feature/new-feature");
79
+ * ```
80
+ */
81
+ export declare const createAndCheckoutBranch: (name: string) => Promise<void>;
82
+ /**
83
+ * Gets all commits between two git references.
84
+ *
85
+ * @param start - The starting reference (exclusive)
86
+ * @param end - The ending reference (inclusive)
87
+ * @returns Array of commits with hash, subject, and body
88
+ *
89
+ * @example
90
+ * ```typescript
91
+ * const commits = await getCommitsBetween("v1.0.0", "main");
92
+ * for (const commit of commits) {
93
+ * console.log(`${commit.hash}: ${commit.subject}`);
94
+ * }
95
+ * ```
96
+ */
97
+ export declare const getCommitsBetween: (start: string, end: string) => Promise<Commit[]>;
98
+ /**
99
+ * Gets all commits since a specific date.
100
+ *
101
+ * @param date - The date in YYYY.MM.DD or YYYY-MM-DD format
102
+ * @returns Array of commits with hash, subject, and body
103
+ *
104
+ * @example
105
+ * ```typescript
106
+ * const commits = await getCommitsSinceDate("2024.07.16");
107
+ * for (const commit of commits) {
108
+ * console.log(`${commit.hash}: ${commit.subject}`);
109
+ * }
110
+ * ```
111
+ */
112
+ export declare const getCommitsSinceDate: (date: string) => Promise<Commit[]>;
113
+ /**
114
+ * Stages all changes in the working directory.
115
+ *
116
+ * @example
117
+ * ```typescript
118
+ * await stageAll();
119
+ * ```
120
+ */
121
+ export declare const stageAll: () => Promise<void>;
122
+ /**
123
+ * Creates a commit with the specified message and user.
124
+ *
125
+ * @param message - The commit message
126
+ * @param user - The commit author (name and email)
127
+ *
128
+ * @example
129
+ * ```typescript
130
+ * await commit("feat: add new feature", {
131
+ * name: "John Doe",
132
+ * email: "john@example.com"
133
+ * });
134
+ * ```
135
+ */
136
+ export declare const commit: (message: string, user: CommitUser) => Promise<void>;
137
+ /**
138
+ * Pushes a branch to a remote repository.
139
+ *
140
+ * @param remote - The remote name (e.g., "origin")
141
+ * @param branch - The branch name to push
142
+ *
143
+ * @example
144
+ * ```typescript
145
+ * await push("origin", "feature-branch");
146
+ * ```
147
+ */
148
+ export declare const push: (remote: string, branch: string) => Promise<void>;
149
+ /**
150
+ * Creates an annotated git tag.
151
+ *
152
+ * @param tag - The tag name (e.g., "v1.0.0")
153
+ * @param message - The tag annotation message
154
+ *
155
+ * @example
156
+ * ```typescript
157
+ * await createTag("v1.0.0", "Release v1.0.0");
158
+ * ```
159
+ */
160
+ export declare const createTag: (tag: string, message: string) => Promise<void>;
161
+ /**
162
+ * Pushes a tag to a remote repository.
163
+ *
164
+ * @param remote - The remote name (e.g., "origin")
165
+ * @param tag - The tag name to push
166
+ *
167
+ * @example
168
+ * ```typescript
169
+ * await pushTag("origin", "v1.0.0");
170
+ * ```
171
+ */
172
+ export declare const pushTag: (remote: string, tag: string) => Promise<void>;