@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,274 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * File tool factory — creates codebase check/fix tools from declarative configs.
4
+ *
5
+ * Each tool is a pure function that receives file data and returns issues or mutations.
6
+ * The factory generates: validator adapter, CLI handler, and library function.
7
+ *
8
+ * Supports two modes:
9
+ * - Per-file (`checkFile`): factory auto-iterates over files
10
+ * - Batch (`checkAll`): tool receives full file list
11
+ *
12
+ * Fixers return Edit-tool-shaped mutations `{path, oldContent, newContent}` —
13
+ * the runner decides whether to apply, preview, or pass to an AI agent.
14
+ *
15
+ * ```
16
+ * Pure logic (Handler) Runner (Adapter) Output (ResponseMapper)
17
+ * ───────────────────── ────────────────── ─────────────────────────
18
+ * checkFile() → issues[] CLI runner Terminal colors + exit code
19
+ * fixFile() → mutation MCP server (IDE tool) JSON tool results
20
+ * AI agent (SDK tool) Structured for LLM
21
+ * ```
22
+ *
23
+ * @module
24
+ */
25
+ import * as primitives from "@eserstack/primitives";
26
+ import * as tui from "@eserstack/shell/tui";
27
+ import * as fileToolsShared from "./file-tools-shared.js";
28
+ import * as cliSupport from "./cli-support.js";
29
+ import * as ffiClient from "./ffi-client.js";
30
+ import * as gitListing from "./git-listing.js";
31
+ // =============================================================================
32
+ // Factory
33
+ // =============================================================================
34
+ /**
35
+ * Reads a CLI flag that may hold several values. `main` collects repeated
36
+ * flags into an array; a `CliEvent` built by another caller may carry one
37
+ * string.
38
+ */
39
+ const toStringList = (value) => {
40
+ if (Array.isArray(value)) {
41
+ return value.filter((item) => typeof item === "string");
42
+ }
43
+ return typeof value === "string" ? [value] : [];
44
+ };
45
+ /**
46
+ * Create a file tool from a declarative config.
47
+ *
48
+ * @param config - Tool configuration
49
+ * @returns A complete file tool with run(), validator, and main()
50
+ */
51
+ export const createFileTool = (config) => {
52
+ // --- Core run function ---
53
+ const run = async (partialOptions) => {
54
+ const options = {
55
+ root: partialOptions?.root ?? ".",
56
+ fix: partialOptions?.fix ?? false,
57
+ exclude: partialOptions?.exclude ?? [],
58
+ ...config.defaults,
59
+ ...partialOptions,
60
+ };
61
+ const changedFiles = partialOptions?.["_changedFiles"];
62
+ const walkOpts = {
63
+ root: options.root,
64
+ extensions: config.extensions,
65
+ exclude: options.exclude,
66
+ includeOnly: changedFiles !== undefined && changedFiles.length > 0
67
+ ? changedFiles
68
+ : undefined,
69
+ };
70
+ const files = await fileToolsShared.walkSourceFiles(walkOpts);
71
+ const allIssues = [];
72
+ const allMutations = [];
73
+ if (config.checkAll !== undefined) {
74
+ // Batch mode
75
+ const issues = await config.checkAll(files, options);
76
+ allIssues.push(...issues);
77
+ }
78
+ else if (config.checkFile !== undefined) {
79
+ // Per-file mode
80
+ for (const file of files) {
81
+ // Files load one at a time: reading thousands at once can exhaust the
82
+ // open file handle limit.
83
+ // oxlint-disable-next-line no-await-in-loop
84
+ const content = await fileToolsShared.loadContent(file);
85
+ const issues = config.checkFile(file, content, options);
86
+ allIssues.push(...issues);
87
+ }
88
+ }
89
+ // Run fixer if fix mode is enabled
90
+ if (options.fix && config.canFix && config.fixFile !== undefined) {
91
+ for (const file of files) {
92
+ // One file at a time, for the same reason as the check loop.
93
+ // oxlint-disable-next-line no-await-in-loop
94
+ const content = await fileToolsShared.loadContent(file);
95
+ if (content === undefined) {
96
+ continue;
97
+ }
98
+ const mutation = config.fixFile(file, content, options);
99
+ if (mutation !== undefined) {
100
+ allMutations.push(mutation);
101
+ }
102
+ }
103
+ }
104
+ return {
105
+ name: config.name,
106
+ issues: allIssues,
107
+ mutations: allMutations,
108
+ filesChecked: files.length,
109
+ };
110
+ };
111
+ // --- Validator adapter ---
112
+ const validator = {
113
+ name: config.name,
114
+ description: config.description,
115
+ requiredStacks: config.stacks,
116
+ async validate(validatorOptions) {
117
+ const fix = validatorOptions.options?.["fix"];
118
+ const configOptions = validatorOptions.options ?? {};
119
+ const result = await run({
120
+ root: validatorOptions.root,
121
+ fix: fix ?? false,
122
+ exclude: [],
123
+ ...configOptions,
124
+ });
125
+ return {
126
+ name: config.name,
127
+ passed: result.issues.length === 0,
128
+ issues: result.issues.map((issue) => ({
129
+ severity: "error",
130
+ message: `${issue.message}${issue.fixed ? " (fixed)" : ""}`,
131
+ file: issue.path,
132
+ line: issue.line,
133
+ })),
134
+ stats: {
135
+ filesChecked: result.filesChecked,
136
+ issuesFound: result.issues.length,
137
+ fixedCount: result.mutations.length,
138
+ },
139
+ };
140
+ },
141
+ };
142
+ // --- CLI adapter ---
143
+ const handleCli = async (event) => {
144
+ const { ctx } = cliSupport.getCliContext();
145
+ const fix = config.canFix && event.flags["fix"] === true;
146
+ const root = event.flags["root"] ?? ".";
147
+ const exclude = toStringList(event.flags["exclude"]);
148
+ // An empty pattern matches every path, so the tool would check nothing
149
+ // and pass.
150
+ if (exclude.includes("")) {
151
+ tui.log.error(ctx, `${config.name}: --exclude needs a pattern, for example --exclude docs/api/`);
152
+ return primitives.results.fail({ exitCode: 1 });
153
+ }
154
+ try {
155
+ const result = await run({ root, fix, exclude });
156
+ if (result.mutations.length > 0) {
157
+ const written = await fileToolsShared.writeMutations(result.mutations);
158
+ tui.log.success(ctx, `Fixed ${written} file(s) for ${config.name}.`);
159
+ }
160
+ if (result.issues.length === 0 && result.mutations.length === 0) {
161
+ tui.log.success(ctx, `${config.name}: ${result.filesChecked} files checked, no issues.`);
162
+ return primitives.results.ok(undefined);
163
+ }
164
+ const unfixed = result.issues.filter((i) => !i.fixed);
165
+ if (unfixed.length > 0) {
166
+ for (const issue of unfixed) {
167
+ const loc = issue.line !== undefined
168
+ ? `${issue.path}:${issue.line}`
169
+ : issue.path;
170
+ tui.log.error(ctx, `${loc}: ${issue.message}`);
171
+ }
172
+ return primitives.results.fail({ exitCode: 1 });
173
+ }
174
+ return primitives.results.ok(undefined);
175
+ }
176
+ catch (error) {
177
+ tui.log.error(ctx, error instanceof Error ? error.message : String(error));
178
+ return primitives.results.fail({ exitCode: 1 });
179
+ }
180
+ };
181
+ // --- CLI main ---
182
+ const main = async (cliArgs) => {
183
+ const event = cliSupport.parseCliEvent(config.name, cliArgs, {
184
+ ...(config.canFix ? { fix: { type: "boolean" } } : {}),
185
+ help: { type: "boolean", short: "h" },
186
+ root: { type: "string" },
187
+ // Each --exclude adds a pattern, the way the manifest lists several.
188
+ exclude: { type: "string", multiple: true, default: [] },
189
+ });
190
+ if (event.flags["help"] === true) {
191
+ const { output: out } = cliSupport.getCliContext();
192
+ out.writeln(`eser codebase ${config.name} — ${config.description}\n`);
193
+ out.writeln(`Usage: eser codebase ${config.name} [options]\n`);
194
+ out.writeln("Options:");
195
+ if (config.canFix) {
196
+ out.writeln(" --fix Auto-fix issues");
197
+ }
198
+ out.writeln(" --root <dir> Root directory (default: .)");
199
+ out.writeln(" --exclude <p> Skip paths matching the regular expression <p>;");
200
+ out.writeln(" repeat the flag to add more patterns");
201
+ out.writeln(" -h, --help Show this help");
202
+ await out.flush();
203
+ return primitives.results.ok(undefined);
204
+ }
205
+ return await handleCli(event);
206
+ };
207
+ return { config, run, validator, main };
208
+ };
209
+ /**
210
+ * Wraps a FileTool so its registry-facing `validator.validate` delegates to Go's
211
+ * built-in file validators when the native FFI library is available.
212
+ *
213
+ * `run` and `main` are left unchanged so that `--fix` mode still works through
214
+ * the TypeScript path (Go validators are check-only).
215
+ *
216
+ * @param tool - The original FileTool created by `createFileTool`
217
+ * @param goValidatorName - The short name used by the Go bridge
218
+ * (`"eof"`, `"bom"`, `"trailing"`, `"line-endings"`, `"merge-conflicts"`, `"secrets"`)
219
+ */
220
+ export const withGoValidator = (tool, goValidatorName) => {
221
+ // Pre-compute dot-prefixed extensions from the tool config (e.g. "ts" → ".ts").
222
+ // Passed to Go so the walker only reads relevant files — saves I/O.
223
+ const goExtensions = tool.config.extensions !== undefined
224
+ ? [...tool.config.extensions.map((e) => `.${e}`)]
225
+ : undefined;
226
+ const goValidator = {
227
+ ...tool.validator,
228
+ validate: async (options) => {
229
+ await ffiClient.ensureLib();
230
+ const lib = ffiClient.getLib();
231
+ if (lib === null) {
232
+ throw new Error(`FFI library unavailable — cannot run validator "${goValidatorName}"`);
233
+ }
234
+ // Excludes go on the request, where the Go walk applies them, so an
235
+ // excluded file is never read on that side either. Regex excludes stay
236
+ // TypeScript-only (the TS tool applies them after the walk); Go gets the
237
+ // string patterns. Validator options are sent FLAT ({root, ...options}):
238
+ // the Go factories read `exclude`, `rules` etc. from the top level of
239
+ // their entry, and the nested `{root, options: {...}}` shape used before
240
+ // left every one of them reading defaults.
241
+ const configOptions = options.options ?? {};
242
+ const rawExclude = configOptions["exclude"];
243
+ const goExcludes = Array.isArray(rawExclude)
244
+ ? rawExclude.filter((e) => typeof e === "string")
245
+ : [];
246
+ const parsed = lib.call("codebaseValidateFiles", {
247
+ dir: options.root,
248
+ validators: [goValidatorName],
249
+ extensions: goExtensions,
250
+ exclude: goExcludes,
251
+ validatorOptions: {
252
+ [goValidatorName]: { root: options.root, ...configOptions },
253
+ },
254
+ ...(await gitListing.bridgeGitOptions(lib, options.root)),
255
+ });
256
+ if (parsed.error) {
257
+ throw new Error(`Go validator "${goValidatorName}" error: ${parsed.error}`);
258
+ }
259
+ if (!parsed.results?.length) {
260
+ throw new Error(`Go validator "${goValidatorName}" returned no results`);
261
+ }
262
+ // Go marshals `issues` with omitempty, so a clean run has no field at
263
+ // all; every consumer maps over it.
264
+ const first = parsed.results[0];
265
+ return {
266
+ ...first,
267
+ issues: first.issues ?? [],
268
+ name: tool.validator.name,
269
+ };
270
+ },
271
+ };
272
+ return { ...tool, validator: goValidator };
273
+ };
274
+ export { loadBytes, loadContent } from "./file-tools-shared.js";
@@ -0,0 +1,81 @@
1
+ /**
2
+ * File metadata entry — returned by the walker.
3
+ * Content is loaded on demand via `loadContent()`.
4
+ */
5
+ export type FileEntry = {
6
+ /** Absolute path to the file */
7
+ readonly path: string;
8
+ /** File name (basename only) */
9
+ readonly name: string;
10
+ /** File size in bytes */
11
+ readonly size: number;
12
+ /** Whether this is a symlink */
13
+ readonly isSymlink: boolean;
14
+ /** Cached text content (populated by loadContent) */
15
+ textContent?: string;
16
+ /** Cached raw bytes (populated by loadBytes) */
17
+ rawBytes?: Uint8Array;
18
+ };
19
+ /**
20
+ * A mutation returned by a fixer tool.
21
+ * Edit-tool-shaped: inspectable, diffable, approvable.
22
+ */
23
+ export type FileMutation = {
24
+ /** Path to the file */
25
+ readonly path: string;
26
+ /** Original content (for diff/preview) */
27
+ readonly oldContent: string;
28
+ /** New content after fix */
29
+ readonly newContent: string;
30
+ };
31
+ /**
32
+ * Options for walking source files.
33
+ */
34
+ export type WalkOptions = {
35
+ /** Root directory (default: ".") */
36
+ readonly root?: string;
37
+ /** File extensions to include (e.g., ["ts", "json"]). Empty = all. */
38
+ readonly extensions?: readonly string[];
39
+ /** Glob/regex patterns to exclude */
40
+ readonly exclude?: readonly (string | RegExp)[];
41
+ /** Include directories in results (default: false) */
42
+ readonly includeDirs?: boolean;
43
+ /** When set, only include files matching these paths (incremental mode). */
44
+ readonly includeOnly?: readonly string[];
45
+ };
46
+ /** Directories always excluded from file tool scanning */
47
+ export declare const DEFAULT_EXCLUDES: readonly RegExp[];
48
+ /**
49
+ * Walk source files in a directory, respecting excludes.
50
+ *
51
+ * @param options - Walk options
52
+ * @returns Array of file entries (metadata only, no content)
53
+ */
54
+ export declare const walkSourceFiles: (options?: WalkOptions) => Promise<FileEntry[]>;
55
+ /**
56
+ * Load text content for a file entry. Caches the result.
57
+ * Returns undefined for binary files.
58
+ */
59
+ export declare const loadContent: (file: FileEntry) => Promise<string | undefined>;
60
+ /**
61
+ * Load raw bytes for a file entry. Caches the result.
62
+ */
63
+ export declare const loadBytes: (file: FileEntry) => Promise<Uint8Array>;
64
+ /**
65
+ * Check if raw bytes represent a binary file.
66
+ * Scans the first 8KB for null bytes.
67
+ */
68
+ export declare const isBinaryBytes: (bytes: Uint8Array) => boolean;
69
+ /**
70
+ * Check if a file path matches any of the given patterns.
71
+ */
72
+ export declare const matchesAnyPattern: (path: string, filePatterns: readonly (string | RegExp)[]) => boolean;
73
+ /**
74
+ * Apply mutations to the in-memory file list.
75
+ * Updates textContent and rawBytes for mutated files.
76
+ */
77
+ export declare const applyMutations: (files: FileEntry[], mutations: readonly FileMutation[]) => void;
78
+ /**
79
+ * Write all accumulated mutations to disk.
80
+ */
81
+ export declare const writeMutations: (mutations: readonly FileMutation[]) => Promise<number>;
@@ -0,0 +1,276 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Shared utilities for file-based codebase tools.
4
+ *
5
+ * Provides file walking, binary detection, content loading, and pattern matching.
6
+ * Used by `createFileTool()` factory and individual tools.
7
+ *
8
+ * @module
9
+ */
10
+ import * as crossRuntime from "@eserstack/standards/cross-runtime";
11
+ import * as patterns from "@eserstack/standards/patterns";
12
+ import * as ffiClient from "./ffi-client.js";
13
+ import * as gitListing from "./git-listing.js";
14
+ // =============================================================================
15
+ // Default excludes
16
+ // =============================================================================
17
+ /** Directories always excluded from file tool scanning */
18
+ export const DEFAULT_EXCLUDES = [
19
+ /node_modules/,
20
+ /\.git\//,
21
+ /\/dist\//,
22
+ /etc\/coverage/,
23
+ /etc\/temp/,
24
+ /\.output\//,
25
+ ];
26
+ // =============================================================================
27
+ // File walking
28
+ // =============================================================================
29
+ /**
30
+ * Walk source files in a directory, respecting excludes.
31
+ *
32
+ * @param options - Walk options
33
+ * @returns Array of file entries (metadata only, no content)
34
+ */
35
+ export const walkSourceFiles = async (options = {}) => {
36
+ const { root = ".", extensions, exclude = [] } = options;
37
+ await ffiClient.ensureLib();
38
+ const lib = ffiClient.getLib();
39
+ if (lib !== null) {
40
+ try {
41
+ // Go expects dot-prefixed extensions (".ts"), TS uses bare ("ts")
42
+ const goExtensions = extensions !== undefined && extensions.length > 0
43
+ ? extensions.map((e) => (e.startsWith(".") ? e : `.${e}`))
44
+ : undefined;
45
+ // Pass only string patterns to Go; regex patterns are applied post-fetch
46
+ const goExcludes = exclude.filter((e) => typeof e === "string");
47
+ const parsed = lib.call("codebaseWalkFiles", {
48
+ dir: root,
49
+ extensions: goExtensions,
50
+ exclude: goExcludes,
51
+ ...(await gitListing.bridgeGitOptions(lib, root)),
52
+ });
53
+ if (!parsed.error && parsed.files !== undefined) {
54
+ const allExcludes = [
55
+ ...DEFAULT_EXCLUDES,
56
+ ...exclude.map((e) => (typeof e === "string" ? new RegExp(e) : e)),
57
+ ];
58
+ let files = parsed.files
59
+ .filter((f) => {
60
+ // Exclude patterns use POSIX "/" separators; normalize the path so
61
+ // they match on Windows (backslash) too. No-op on POSIX runtimes.
62
+ const posixPath = crossRuntime.toPosix(f.path);
63
+ return !allExcludes.some((re) => re.test(posixPath));
64
+ })
65
+ .map((f) => ({
66
+ path: f.path,
67
+ name: f.name,
68
+ size: f.size,
69
+ isSymlink: f.isSymlink,
70
+ }));
71
+ if (options.includeOnly !== undefined &&
72
+ options.includeOnly.length > 0) {
73
+ const allowList = options.includeOnly;
74
+ files = files.filter((file) => allowList.some((entry) => file.path.endsWith(entry) || file.path.includes(entry)));
75
+ }
76
+ return files;
77
+ }
78
+ }
79
+ catch {
80
+ /* fall through to TS */
81
+ }
82
+ }
83
+ const allExcludes = [
84
+ ...DEFAULT_EXCLUDES,
85
+ ...exclude.map((e) => (typeof e === "string" ? new RegExp(e) : e)),
86
+ ];
87
+ const files = [];
88
+ // Git-aware listing first (respects .gitignore); null outside a git
89
+ // repository, and a throw when git cannot run.
90
+ const gitFiles = await gitListing.listGitFiles(root);
91
+ if (gitFiles !== null) {
92
+ // Git-aware path: iterate over git-tracked files
93
+ for (const relativePath of gitFiles) {
94
+ const fullPath = crossRuntime.runtime.path.join(root, relativePath);
95
+ const name = crossRuntime.runtime.path.basename(relativePath);
96
+ // Apply extension filter (bare extensions: "ts", "json", etc.)
97
+ if (extensions !== undefined && extensions.length > 0) {
98
+ if (!patterns.hasExtension(relativePath, extensions)) {
99
+ continue;
100
+ }
101
+ }
102
+ // Apply exclude patterns. Patterns use POSIX "/" separators, so normalize
103
+ // the OS-native fullPath before testing (relativePath from git is already
104
+ // POSIX). No-op on POSIX runtimes.
105
+ const posixFullPath = crossRuntime.toPosix(fullPath);
106
+ if (allExcludes.some((re) => re.test(posixFullPath) || re.test(relativePath))) {
107
+ continue;
108
+ }
109
+ let size = 0;
110
+ let isSymlink = false;
111
+ try {
112
+ // Files are stat'ed one at a time to bound concurrent file system
113
+ // calls on large trees; the Go walker above is the fast path.
114
+ // oxlint-disable-next-line no-await-in-loop
115
+ const stat = await crossRuntime.runtime.fs.lstat(fullPath);
116
+ size = stat.size;
117
+ isSymlink = stat.isSymlink;
118
+ // Skip directories
119
+ if (stat.isDirectory && !(options.includeDirs ?? false)) {
120
+ continue;
121
+ }
122
+ }
123
+ catch {
124
+ continue;
125
+ }
126
+ files.push({ path: fullPath, name, size, isSymlink });
127
+ }
128
+ }
129
+ else {
130
+ // Fallback: filesystem walk (existing behavior)
131
+ for await (const entry of crossRuntime.runtime.fs.walk(root, {
132
+ includeDirs: options.includeDirs ?? false,
133
+ includeFiles: true,
134
+ exts: extensions,
135
+ skip: allExcludes,
136
+ })) {
137
+ if (!entry.isFile && !entry.isSymlink) {
138
+ continue;
139
+ }
140
+ // The walk's `skip` regexes are POSIX-slash based and the walker tests
141
+ // them against OS-native paths, so they silently miss on Windows. Re-apply
142
+ // the excludes here against a POSIX-normalized path to guarantee matches
143
+ // cross-platform. No-op on POSIX runtimes.
144
+ const posixPath = crossRuntime.toPosix(entry.path);
145
+ if (allExcludes.some((re) => re.test(posixPath))) {
146
+ continue;
147
+ }
148
+ let size = 0;
149
+ try {
150
+ const stat = await crossRuntime.runtime.fs.stat(entry.path);
151
+ size = stat.size;
152
+ }
153
+ catch {
154
+ continue;
155
+ }
156
+ files.push({
157
+ path: entry.path,
158
+ name: entry.name,
159
+ size,
160
+ isSymlink: entry.isSymlink,
161
+ });
162
+ }
163
+ }
164
+ // Incremental mode: filter to only changed files when includeOnly is set
165
+ if (options.includeOnly !== undefined && options.includeOnly.length > 0) {
166
+ const allowList = options.includeOnly;
167
+ return files.filter((file) => allowList.some((entry) => file.path.endsWith(entry) || file.path.includes(entry)));
168
+ }
169
+ return files;
170
+ };
171
+ // =============================================================================
172
+ // Content loading (two-phase)
173
+ // =============================================================================
174
+ /**
175
+ * Load text content for a file entry. Caches the result.
176
+ * Returns undefined for binary files.
177
+ */
178
+ export const loadContent = async (file) => {
179
+ if (file.textContent !== undefined) {
180
+ return file.textContent;
181
+ }
182
+ try {
183
+ const bytes = await loadBytes(file);
184
+ if (isBinaryBytes(bytes)) {
185
+ return undefined;
186
+ }
187
+ const text = new TextDecoder().decode(bytes);
188
+ file.textContent = text;
189
+ return text;
190
+ }
191
+ catch {
192
+ return undefined;
193
+ }
194
+ };
195
+ /**
196
+ * Load raw bytes for a file entry. Caches the result.
197
+ */
198
+ export const loadBytes = async (file) => {
199
+ if (file.rawBytes !== undefined) {
200
+ return file.rawBytes;
201
+ }
202
+ const bytes = await crossRuntime.runtime.fs.readFile(file.path);
203
+ file.rawBytes = bytes;
204
+ return bytes;
205
+ };
206
+ // =============================================================================
207
+ // Binary detection
208
+ // =============================================================================
209
+ /**
210
+ * Check if raw bytes represent a binary file.
211
+ * Scans the first 8KB for null bytes.
212
+ */
213
+ export const isBinaryBytes = (bytes) => {
214
+ const scanLength = Math.min(bytes.length, 8192);
215
+ for (let i = 0; i < scanLength; i++) {
216
+ if (bytes[i] === 0) {
217
+ return true;
218
+ }
219
+ }
220
+ return false;
221
+ };
222
+ // =============================================================================
223
+ // Pattern matching
224
+ // =============================================================================
225
+ /**
226
+ * Check if a file path matches any of the given patterns.
227
+ */
228
+ export const matchesAnyPattern = (path, filePatterns) => {
229
+ // Patterns are authored with POSIX "/" separators; normalize the path so they
230
+ // match OS-native (backslash) paths on Windows too. No-op on POSIX runtimes.
231
+ const normalized = crossRuntime.toPosix(path);
232
+ for (const pattern of filePatterns) {
233
+ if (typeof pattern === "string") {
234
+ if (normalized.includes(pattern) || normalized.endsWith(pattern)) {
235
+ return true;
236
+ }
237
+ }
238
+ else if (pattern.test(normalized)) {
239
+ return true;
240
+ }
241
+ }
242
+ return false;
243
+ };
244
+ /**
245
+ * Apply mutations to the in-memory file list.
246
+ * Updates textContent and rawBytes for mutated files.
247
+ */
248
+ export const applyMutations = (files, mutations) => {
249
+ const mutationMap = new Map();
250
+ for (const mutation of mutations) {
251
+ mutationMap.set(mutation.path, mutation);
252
+ }
253
+ for (const file of files) {
254
+ const mutation = mutationMap.get(file.path);
255
+ if (mutation !== undefined) {
256
+ file.textContent = mutation.newContent;
257
+ file.rawBytes = undefined; // invalidate bytes cache
258
+ }
259
+ }
260
+ };
261
+ /**
262
+ * Write all accumulated mutations to disk.
263
+ */
264
+ export const writeMutations = async (mutations) => {
265
+ let written = 0;
266
+ for (const mutation of mutations) {
267
+ if (mutation.oldContent !== mutation.newContent) {
268
+ // Mutations are written in order, so when two of them target the same
269
+ // file the later one wins.
270
+ // oxlint-disable-next-line no-await-in-loop
271
+ await crossRuntime.runtime.fs.writeTextFile(mutation.path, mutation.newContent);
272
+ written++;
273
+ }
274
+ }
275
+ return written;
276
+ };