@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.
- package/README.md +301 -2
- package/dist/changelog-gen.d.ts +105 -0
- package/dist/changelog-gen.js +498 -0
- package/dist/changelog-text.d.ts +39 -0
- package/dist/changelog-text.js +82 -0
- package/dist/cli-support.d.ts +140 -0
- package/dist/cli-support.js +244 -0
- package/dist/cli-system/app-opts.d.ts +15 -0
- package/dist/cli-system/app-opts.js +13 -0
- package/dist/cli-system/app.d.ts +29 -0
- package/dist/cli-system/app.js +12 -0
- package/dist/cli-system/handlers/completions-setup.d.ts +14 -0
- package/dist/cli-system/handlers/completions-setup.js +139 -0
- package/dist/cli-system/handlers/completions.d.ts +3 -0
- package/dist/cli-system/handlers/completions.js +79 -0
- package/dist/cli-system/handlers/doctor.d.ts +8 -0
- package/dist/cli-system/handlers/doctor.js +146 -0
- package/dist/cli-system/handlers/info.d.ts +3 -0
- package/dist/cli-system/handlers/info.js +69 -0
- package/dist/cli-system/handlers/install.d.ts +8 -0
- package/dist/cli-system/handlers/install.js +137 -0
- package/dist/cli-system/handlers/mod.d.ts +12 -0
- package/dist/cli-system/handlers/mod.js +13 -0
- package/dist/cli-system/handlers/uninstall.d.ts +3 -0
- package/dist/cli-system/handlers/uninstall.js +60 -0
- package/dist/cli-system/handlers/update.d.ts +76 -0
- package/dist/cli-system/handlers/update.js +310 -0
- package/dist/cli-system/handlers/version-check.d.ts +16 -0
- package/dist/cli-system/handlers/version-check.js +176 -0
- package/dist/cli-system/handlers/version.d.ts +3 -0
- package/dist/cli-system/handlers/version.js +45 -0
- package/dist/cli-system/mod.d.ts +19 -0
- package/dist/cli-system/mod.js +52 -0
- package/dist/commitmsg.d.ts +28 -0
- package/dist/commitmsg.js +232 -0
- package/dist/directive-analysis.d.ts +75 -0
- package/dist/directive-analysis.js +223 -0
- package/dist/ffi-client.d.ts +11 -0
- package/dist/ffi-client.js +12 -0
- package/dist/file-tool.d.ts +96 -0
- package/dist/file-tool.js +274 -0
- package/dist/file-tools-shared.d.ts +81 -0
- package/dist/file-tools-shared.js +276 -0
- package/dist/gh-contributors.d.ts +89 -0
- package/dist/gh-contributors.js +205 -0
- package/dist/gh.d.ts +3 -0
- package/dist/gh.js +64 -0
- package/dist/git-listing.d.ts +27 -0
- package/dist/git-listing.js +69 -0
- package/dist/git.d.ts +172 -0
- package/dist/git.js +277 -0
- package/dist/install.d.ts +34 -0
- package/dist/install.js +421 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +14 -0
- package/dist/mod.d.ts +25 -0
- package/dist/mod.js +8 -0
- package/dist/module.d.ts +10 -0
- package/dist/module.js +221 -0
- package/dist/native-functions.d.ts +1088 -0
- package/dist/native-functions.js +2 -0
- package/dist/npm-externals.d.ts +27 -0
- package/dist/npm-externals.js +34 -0
- package/dist/npm-workspace-specifiers.d.ts +6 -0
- package/dist/npm-workspace-specifiers.js +45 -0
- package/dist/package/loader.d.ts +34 -0
- package/dist/package/loader.js +203 -0
- package/dist/package/mod.d.ts +36 -0
- package/dist/package/mod.js +5 -0
- package/dist/package/types.d.ts +142 -0
- package/dist/package/types.js +32 -0
- package/dist/package/workspace.d.ts +33 -0
- package/dist/package/workspace.js +158 -0
- package/dist/package/writer.d.ts +52 -0
- package/dist/package/writer.js +278 -0
- package/dist/package.json +275 -0
- package/dist/release-notes.d.ts +90 -0
- package/dist/release-notes.js +236 -0
- package/dist/release-tag.d.ts +46 -0
- package/dist/release-tag.js +95 -0
- package/dist/release.d.ts +145 -0
- package/dist/release.js +584 -0
- package/dist/source-mask.d.ts +3 -0
- package/dist/source-mask.js +185 -0
- package/dist/validate-bom.d.ts +5 -0
- package/dist/validate-bom.js +43 -0
- package/dist/validate-case-conflict.d.ts +5 -0
- package/dist/validate-case-conflict.js +43 -0
- package/dist/validate-circular-deps.d.ts +11 -0
- package/dist/validate-circular-deps.js +53 -0
- package/dist/validate-code-conventions.d.ts +22 -0
- package/dist/validate-code-conventions.js +166 -0
- package/dist/validate-commit-msg.d.ts +50 -0
- package/dist/validate-commit-msg.js +182 -0
- package/dist/validate-docs.d.ts +20 -0
- package/dist/validate-docs.js +78 -0
- package/dist/validate-eof.d.ts +5 -0
- package/dist/validate-eof.js +61 -0
- package/dist/validate-error-coverage.d.ts +28 -0
- package/dist/validate-error-coverage.js +93 -0
- package/dist/validate-export-names.d.ts +17 -0
- package/dist/validate-export-names.js +56 -0
- package/dist/validate-filenames.d.ts +5 -0
- package/dist/validate-filenames.js +151 -0
- package/dist/validate-json.d.ts +5 -0
- package/dist/validate-json.js +71 -0
- package/dist/validate-large-files.d.ts +5 -0
- package/dist/validate-large-files.js +41 -0
- package/dist/validate-laroux-boundaries.d.ts +19 -0
- package/dist/validate-laroux-boundaries.js +59 -0
- package/dist/validate-licenses.d.ts +5 -0
- package/dist/validate-licenses.js +137 -0
- package/dist/validate-line-endings.d.ts +5 -0
- package/dist/validate-line-endings.js +47 -0
- package/dist/validate-merge-conflict.d.ts +5 -0
- package/dist/validate-merge-conflict.js +46 -0
- package/dist/validate-mod-exports.d.ts +16 -0
- package/dist/validate-mod-exports.js +56 -0
- package/dist/validate-naming-and-todos.d.ts +5 -0
- package/dist/validate-naming-and-todos.js +70 -0
- package/dist/validate-runtime-js-apis.d.ts +5 -0
- package/dist/validate-runtime-js-apis.js +78 -0
- package/dist/validate-secrets.d.ts +5 -0
- package/dist/validate-secrets.js +82 -0
- package/dist/validate-self-imports.d.ts +5 -0
- package/dist/validate-self-imports.js +78 -0
- package/dist/validate-server-loc.d.ts +32 -0
- package/dist/validate-server-loc.js +94 -0
- package/dist/validate-shebangs.d.ts +5 -0
- package/dist/validate-shebangs.js +33 -0
- package/dist/validate-stream.d.ts +25 -0
- package/dist/validate-stream.js +62 -0
- package/dist/validate-submodules.d.ts +5 -0
- package/dist/validate-submodules.js +43 -0
- package/dist/validate-symlinks.d.ts +5 -0
- package/dist/validate-symlinks.js +46 -0
- package/dist/validate-toml.d.ts +5 -0
- package/dist/validate-toml.js +40 -0
- package/dist/validate-trailing-whitespace.d.ts +5 -0
- package/dist/validate-trailing-whitespace.js +49 -0
- package/dist/validate-yaml.d.ts +5 -0
- package/dist/validate-yaml.js +40 -0
- package/dist/validation/config.d.ts +17 -0
- package/dist/validation/config.js +30 -0
- package/dist/validation/mod.d.ts +71 -0
- package/dist/validation/mod.js +479 -0
- package/dist/validation/registry.d.ts +57 -0
- package/dist/validation/registry.js +256 -0
- package/dist/validation/types.d.ts +101 -0
- package/dist/validation/types.js +2 -0
- package/dist/validation/validators/circular-deps.d.ts +7 -0
- package/dist/validation/validators/circular-deps.js +31 -0
- package/dist/validation/validators/docs.d.ts +7 -0
- package/dist/validation/validators/docs.js +38 -0
- package/dist/validation/validators/error-coverage.d.ts +2 -0
- package/dist/validation/validators/error-coverage.js +46 -0
- package/dist/validation/validators/export-names.d.ts +7 -0
- package/dist/validation/validators/export-names.js +31 -0
- package/dist/validation/validators/laroux-boundaries.d.ts +2 -0
- package/dist/validation/validators/laroux-boundaries.js +29 -0
- package/dist/validation/validators/mod-exports.d.ts +7 -0
- package/dist/validation/validators/mod-exports.js +32 -0
- package/dist/validation/validators/mod.d.ts +11 -0
- package/dist/validation/validators/mod.js +12 -0
- package/dist/validation/validators/server-loc.d.ts +2 -0
- package/dist/validation/validators/server-loc.js +48 -0
- package/dist/versions.d.ts +166 -0
- package/dist/versions.js +349 -0
- package/dist/violation-baseline.d.ts +58 -0
- package/dist/violation-baseline.js +144 -0
- package/dist/walk-stream.d.ts +24 -0
- package/dist/walk-stream.js +55 -0
- package/dist/workspace-discovery.d.ts +60 -0
- package/dist/workspace-discovery.js +130 -0
- 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
|
+
};
|