code-guardian-ai 0.0.0-stage → 0.3.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 (70) hide show
  1. package/.env.example +24 -0
  2. package/LICENSE +21 -0
  3. package/README.md +774 -2
  4. package/bin/cli.js +2 -0
  5. package/dist/build-manifest.json +136 -0
  6. package/dist/cli/commands/check.js +56 -0
  7. package/dist/cli/commands/doctor.js +55 -0
  8. package/dist/cli/commands/find.js +31 -0
  9. package/dist/cli/commands/init-files.js +13 -0
  10. package/dist/cli/commands/init.js +50 -0
  11. package/dist/cli/commands/optimize.js +53 -0
  12. package/dist/cli/commands/scan.js +47 -0
  13. package/dist/cli/index.js +62 -0
  14. package/dist/cli/output.js +4 -0
  15. package/dist/context.js +11 -0
  16. package/dist/core/ast/analysis.js +455 -0
  17. package/dist/core/ast/cached-info.js +46 -0
  18. package/dist/core/ast/discovery.js +485 -0
  19. package/dist/core/ast/extract-js.js +531 -0
  20. package/dist/core/ast/extract-py.js +298 -0
  21. package/dist/core/ast/graph.js +92 -0
  22. package/dist/core/ast/health.js +338 -0
  23. package/dist/core/ast/indexer.js +286 -0
  24. package/dist/core/ast/packages.js +343 -0
  25. package/dist/core/ast/parser.js +91 -0
  26. package/dist/core/ast/report.js +154 -0
  27. package/dist/core/ast/resolver.js +392 -0
  28. package/dist/core/ast/rules.js +37 -0
  29. package/dist/core/ast/scope-js.js +191 -0
  30. package/dist/core/ast/shared-index.js +131 -0
  31. package/dist/core/ast/tsconfig.js +301 -0
  32. package/dist/core/ast/types.js +1 -0
  33. package/dist/core/ast/util.js +156 -0
  34. package/dist/core/git/git.js +430 -0
  35. package/dist/core/llm/policy.js +35 -0
  36. package/dist/core/llm/provider.js +199 -0
  37. package/dist/core/prompt/compressor.js +118 -0
  38. package/dist/core/prompt/criteria.js +36 -0
  39. package/dist/core/prompt/find.js +47 -0
  40. package/dist/core/prompt/guidelines.js +22 -0
  41. package/dist/core/prompt/model-output.js +178 -0
  42. package/dist/core/prompt/refiner.js +194 -0
  43. package/dist/core/prompt/relevance.js +265 -0
  44. package/dist/core/prompt/untrusted.js +57 -0
  45. package/dist/core/security/masker.js +330 -0
  46. package/dist/core/security/outbound.js +40 -0
  47. package/dist/core/security/safe-file.js +396 -0
  48. package/dist/core/security/sandbox.js +181 -0
  49. package/dist/core/validation/baseline.js +121 -0
  50. package/dist/core/validation/delta.js +243 -0
  51. package/dist/core/validation/policy.js +123 -0
  52. package/dist/db/cache-key.js +221 -0
  53. package/dist/db/client.js +563 -0
  54. package/dist/db/schema-check.js +149 -0
  55. package/dist/db/schema.js +36 -0
  56. package/dist/db/windows-acl.js +150 -0
  57. package/dist/index.js +55 -0
  58. package/dist/mcp/server.js +20 -0
  59. package/dist/mcp/tools/find-reusable.js +22 -0
  60. package/dist/mcp/tools/get-context.js +39 -0
  61. package/dist/mcp/tools/optimize-prompt.js +31 -0
  62. package/dist/mcp/tools/result.js +31 -0
  63. package/dist/mcp/tools/validate-rules.js +28 -0
  64. package/dist/utils/config.js +117 -0
  65. package/dist/utils/errors.js +9 -0
  66. package/dist/utils/logger.js +19 -0
  67. package/dist/utils/pace.js +19 -0
  68. package/dist/utils/text.js +22 -0
  69. package/dist/utils/tokens.js +14 -0
  70. package/package.json +69 -4
@@ -0,0 +1,131 @@
1
+ import { indexProject } from './indexer.js';
2
+ // One shared entry point for MCP requests that need an index. Each request used to run its own indexProject, so a client that
3
+ // sent N requests at once started N scans of the same workspace. Now:
4
+ //
5
+ // - Coalescing. Requests for the same context share one scan. A request only joins a scan that has NOT started reading the
6
+ // workspace yet; one that arrives while a scan is running waits for the next scan, which starts when the current one ends. So
7
+ // every request gets a result from a scan that began after it arrived (never one that predates a file change it may be
8
+ // reporting on), and there is at most one running and one waiting scan per context.
9
+ // - A global bound. At most MAX_CONCURRENT_INDEXES scans run at once across all workspaces; the rest queue.
10
+ // - Cancellation is per request. A request that is cancelled leaves immediately with its signal's reason; the scan itself is only
11
+ // aborted once no request is waiting for it, so one client cancelling never cancels work another one still needs. (An aborted
12
+ // scan keeps what it already cached, exactly as before.)
13
+ // - Nothing is shared mutably: the first caller gets the Project the scan built, every other caller a structured clone of it.
14
+ // - Every slot is released in a finally, and a failed scan is forgotten as soon as it ends, so a failure never blocks later requests.
15
+ export const MAX_CONCURRENT_INDEXES = 2;
16
+ class Gate {
17
+ limit;
18
+ active = 0;
19
+ waiting = [];
20
+ constructor(limit) {
21
+ this.limit = limit;
22
+ }
23
+ // Resolves with a release function once a slot is free; rejects (and leaves the queue) when the signal aborts first.
24
+ acquire(signal) {
25
+ signal.throwIfAborted();
26
+ return new Promise((resolve, reject) => {
27
+ const grant = () => {
28
+ signal.removeEventListener('abort', onAbort);
29
+ this.active++;
30
+ let released = false;
31
+ resolve(() => {
32
+ if (released)
33
+ return;
34
+ released = true;
35
+ this.active--;
36
+ this.waiting.shift()?.();
37
+ });
38
+ };
39
+ const onAbort = () => {
40
+ const at = this.waiting.indexOf(grant);
41
+ if (at >= 0)
42
+ this.waiting.splice(at, 1);
43
+ reject(signal.reason);
44
+ };
45
+ if (this.active < this.limit)
46
+ return grant();
47
+ this.waiting.push(grant);
48
+ signal.addEventListener('abort', onAbort, { once: true });
49
+ });
50
+ }
51
+ }
52
+ export function createIndexCoordinator(options = {}) {
53
+ const gate = new Gate(Math.max(1, options.maxConcurrent ?? MAX_CONCURRENT_INDEXES));
54
+ const index = options.index ?? indexProject;
55
+ const slots = new WeakMap();
56
+ function start(ctx, slot) {
57
+ const controller = new AbortController();
58
+ const prior = slot.running;
59
+ const run = { controller, waiters: 0, started: false, handedOut: false };
60
+ run.promise = (async () => {
61
+ // The next scan of a context starts only when the previous one is over, so two scans of one workspace never overlap.
62
+ if (prior)
63
+ await prior.settled;
64
+ const release = await gate.acquire(controller.signal);
65
+ try {
66
+ controller.signal.throwIfAborted();
67
+ run.started = true;
68
+ if (slot.queued === run)
69
+ slot.queued = undefined;
70
+ slot.running = run;
71
+ return await index(ctx, { signal: controller.signal });
72
+ }
73
+ finally {
74
+ release();
75
+ if (slot.running === run)
76
+ slot.running = undefined;
77
+ if (slot.queued === run)
78
+ slot.queued = undefined;
79
+ }
80
+ })();
81
+ run.settled = run.promise.then(() => undefined, () => undefined);
82
+ return run;
83
+ }
84
+ return (ctx, signal) => {
85
+ // Always a promise, even for a request that was cancelled before it arrived.
86
+ if (signal?.aborted)
87
+ return Promise.reject(signal.reason);
88
+ let slot = slots.get(ctx);
89
+ if (!slot)
90
+ slots.set(ctx, (slot = {}));
91
+ const state = slot;
92
+ const run = state.queued ?? (state.queued = start(ctx, state));
93
+ return new Promise((resolve, reject) => {
94
+ run.waiters++;
95
+ let done = false;
96
+ const finish = () => {
97
+ if (done)
98
+ return false;
99
+ done = true;
100
+ signal?.removeEventListener('abort', onAbort);
101
+ return true;
102
+ };
103
+ const onAbort = () => {
104
+ if (!finish())
105
+ return;
106
+ if (--run.waiters === 0) {
107
+ // Nobody needs this scan any more. A scan that has not started must also stop being joinable at once.
108
+ if (state.queued === run)
109
+ state.queued = undefined;
110
+ run.controller.abort(signal?.reason);
111
+ }
112
+ reject(signal?.reason);
113
+ };
114
+ signal?.addEventListener('abort', onAbort, { once: true });
115
+ run.promise.then((project) => {
116
+ if (!finish())
117
+ return;
118
+ run.waiters--;
119
+ const own = !run.handedOut;
120
+ run.handedOut = true;
121
+ resolve(own ? project : structuredClone(project));
122
+ }, (err) => {
123
+ if (!finish())
124
+ return;
125
+ run.waiters--;
126
+ reject(err);
127
+ });
128
+ });
129
+ };
130
+ }
131
+ export const indexShared = createIndexCoordinator();
@@ -0,0 +1,301 @@
1
+ import path from 'node:path';
2
+ import { log } from '../../utils/logger.js';
3
+ import { errorMessage } from '../../utils/errors.js';
4
+ import { readInside } from '../security/sandbox.js';
5
+ export const TSCONFIG_NAME = /^(?:tsconfig|jsconfig)(?:\.[\w.-]+)?\.json$/;
6
+ const MAX_CONFIG_BYTES = 256 * 1024;
7
+ const MAX_EXTENDS_DEPTH = 8;
8
+ export function diskReader(root) {
9
+ return (rel) => {
10
+ try {
11
+ return readInside(root, rel, MAX_CONFIG_BYTES).toString('utf8');
12
+ }
13
+ catch {
14
+ return null;
15
+ }
16
+ };
17
+ }
18
+ function isTrailingComma(src, index) {
19
+ const closing = /\s*[}\]]/y;
20
+ closing.lastIndex = index + 1;
21
+ return closing.test(src);
22
+ }
23
+ export function parseJsonc(input) {
24
+ const src = input.replace(/^\uFEFF/, '');
25
+ let stripped = '';
26
+ let i = 0;
27
+ while (i < src.length) {
28
+ const ch = src[i];
29
+ if (ch === '"') {
30
+ let j = i + 1;
31
+ while (j < src.length && src[j] !== '"')
32
+ j += src[j] === '\\' ? 2 : 1;
33
+ stripped += src.slice(i, j + 1);
34
+ i = j + 1;
35
+ }
36
+ else if (ch === '/' && src[i + 1] === '/') {
37
+ while (i < src.length && src[i] !== '\n')
38
+ i++;
39
+ }
40
+ else if (ch === '/' && src[i + 1] === '*') {
41
+ const end = src.indexOf('*/', i + 2);
42
+ i = end === -1 ? src.length : end + 2;
43
+ }
44
+ else {
45
+ stripped += ch;
46
+ i++;
47
+ }
48
+ }
49
+ let clean = '';
50
+ i = 0;
51
+ while (i < stripped.length) {
52
+ const ch = stripped[i];
53
+ if (ch === '"') {
54
+ let j = i + 1;
55
+ while (j < stripped.length && stripped[j] !== '"')
56
+ j += stripped[j] === '\\' ? 2 : 1;
57
+ clean += stripped.slice(i, j + 1);
58
+ i = j + 1;
59
+ }
60
+ else if (ch === ',' && isTrailingComma(stripped, i)) {
61
+ i++;
62
+ }
63
+ else {
64
+ clean += ch;
65
+ i++;
66
+ }
67
+ }
68
+ return JSON.parse(clean);
69
+ }
70
+ const asObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
71
+ const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : undefined;
72
+ function toWorkspacePath(dir, relative) {
73
+ const joined = path.posix.normalize(path.posix.join(dir || '.', relative));
74
+ if (joined === '..' || joined.startsWith('../') || path.posix.isAbsolute(joined))
75
+ return undefined;
76
+ return joined === '.' ? '' : joined;
77
+ }
78
+ const dirOf = (file) => (path.posix.dirname(file) === '.' ? '' : path.posix.dirname(file));
79
+ // A package.json read from node_modules is not trusted, so the condition tree is searched depth-first (default, require, import)
80
+ // with an explicit stack and a hard cap on depth and visited nodes, instead of recursing as deep as the file nests.
81
+ const MAX_EXPORTS_DEPTH = 16;
82
+ const MAX_EXPORTS_VISITED = 256;
83
+ function exportsTarget(value) {
84
+ const pending = [{ value, depth: 0 }];
85
+ let visited = 0;
86
+ for (let entry = pending.pop(); entry; entry = pending.pop()) {
87
+ if (++visited > MAX_EXPORTS_VISITED)
88
+ return undefined;
89
+ if (typeof entry.value === 'string') {
90
+ if (entry.value)
91
+ return entry.value;
92
+ continue;
93
+ }
94
+ const object = asObject(entry.value);
95
+ if (!object || entry.depth >= MAX_EXPORTS_DEPTH)
96
+ continue;
97
+ for (const key of ['import', 'require', 'default'])
98
+ pending.push({ value: object[key], depth: entry.depth + 1 });
99
+ }
100
+ return undefined;
101
+ }
102
+ // `extends: "@tsconfig/node20/tsconfig.json"`, `extends: "@acme/tsconfig"` and workspace packages linked into node_modules.
103
+ function packageConfig(read, fromDir, spec) {
104
+ for (let dir = fromDir;; dir = dirOf(dir)) {
105
+ const base = path.posix.join(dir || '.', 'node_modules', spec);
106
+ const normalized = path.posix.normalize(base);
107
+ const direct = spec.endsWith('.json') ? [normalized] : [`${normalized}.json`, `${normalized}/tsconfig.json`];
108
+ for (const candidate of direct)
109
+ if (read(candidate) !== null)
110
+ return candidate;
111
+ const manifest = read(`${normalized}/package.json`);
112
+ if (manifest) {
113
+ try {
114
+ const pkg = asObject(JSON.parse(manifest)) ?? {};
115
+ const exportsMap = asObject(pkg.exports);
116
+ const named = typeof pkg.tsconfig === 'string' ? pkg.tsconfig : exportsTarget(exportsMap ? (exportsMap['.'] ?? exportsMap) : pkg.exports);
117
+ if (named) {
118
+ const resolved = toWorkspacePath(normalized, named);
119
+ if (resolved && read(resolved) !== null)
120
+ return resolved;
121
+ }
122
+ }
123
+ catch {
124
+ // an unreadable manifest just means this candidate does not apply
125
+ }
126
+ }
127
+ if (dir === '')
128
+ return undefined;
129
+ }
130
+ }
131
+ function parentChain(read, dir, extendsValue, depth, seen) {
132
+ const entries = (Array.isArray(extendsValue) ? extendsValue : [extendsValue]).filter((v) => typeof v === 'string');
133
+ let merged = {};
134
+ for (const entry of entries) {
135
+ let candidates = [];
136
+ if (entry.startsWith('.')) {
137
+ const base = toWorkspacePath(dir, entry);
138
+ if (base !== undefined)
139
+ candidates = base.endsWith('.json') ? [base] : [`${base}.json`, `${base}/tsconfig.json`];
140
+ }
141
+ else {
142
+ const found = packageConfig(read, dir, entry);
143
+ if (found)
144
+ candidates = [found];
145
+ }
146
+ let found = false;
147
+ for (const candidate of candidates) {
148
+ const loaded = load(read, candidate, depth + 1, seen);
149
+ if (loaded) {
150
+ merged = { ...merged, ...loaded };
151
+ found = true;
152
+ break;
153
+ }
154
+ }
155
+ // A package-based extends lives in node_modules, which a checkout may not have; a relative one is part of the repository.
156
+ if (!found && entry.startsWith('.'))
157
+ merged.incomplete = true;
158
+ }
159
+ return merged;
160
+ }
161
+ function load(read, file, depth, seen) {
162
+ if (depth > MAX_EXTENDS_DEPTH || seen.has(file))
163
+ return null;
164
+ const content = read(file);
165
+ if (content === null)
166
+ return null;
167
+ let parsed;
168
+ try {
169
+ parsed = asObject(parseJsonc(content));
170
+ }
171
+ catch (err) {
172
+ log.debug(`Ignoring ${file}: ${errorMessage(err)}`);
173
+ return null;
174
+ }
175
+ if (!parsed)
176
+ return null;
177
+ const dir = dirOf(file);
178
+ const inherited = parentChain(read, dir, parsed.extends, depth, new Set([...seen, file]));
179
+ const options = asObject(parsed.compilerOptions) ?? {};
180
+ const result = { ...inherited };
181
+ if (typeof options.baseUrl === 'string') {
182
+ const resolved = toWorkspacePath(dir, options.baseUrl);
183
+ if (resolved !== undefined)
184
+ result.baseUrl = resolved;
185
+ }
186
+ for (const key of ['outDir', 'rootDir']) {
187
+ const value = options[key];
188
+ if (typeof value === 'string') {
189
+ const resolved = toWorkspacePath(dir, value);
190
+ if (resolved !== undefined)
191
+ result[key] = resolved;
192
+ }
193
+ }
194
+ const rawPaths = asObject(options.paths);
195
+ if (rawPaths) {
196
+ result.paths = Object.entries(rawPaths)
197
+ .map(([pattern, targets]) => ({ pattern, targets: Array.isArray(targets) ? targets.filter((t) => typeof t === 'string') : [] }))
198
+ .filter((mapping) => mapping.targets.length > 0);
199
+ result.pathsDir = dir;
200
+ }
201
+ // include, exclude and files are inherited, and patterns stay relative to the config that wrote them.
202
+ for (const key of ['include', 'exclude', 'files']) {
203
+ const own = strings(parsed[key]);
204
+ if (own)
205
+ result[key] = own.map((p) => toWorkspacePath(dir, p)).filter((p) => p !== undefined);
206
+ }
207
+ const references = (Array.isArray(parsed.references) ? parsed.references : [])
208
+ .map((ref) => asObject(ref)?.path)
209
+ .filter((p) => typeof p === 'string')
210
+ .map((p) => toWorkspacePath(dir, p))
211
+ .filter((p) => p !== undefined)
212
+ .map((p) => (p.endsWith('.json') ? p : p ? `${p}/tsconfig.json` : 'tsconfig.json'));
213
+ return { ...result, references };
214
+ }
215
+ export function loadTsConfigs(source, files) {
216
+ const read = typeof source === 'string' ? diskReader(source) : source;
217
+ const configs = [];
218
+ const done = new Set();
219
+ const queue = [...new Set(files)].sort();
220
+ while (queue.length > 0) {
221
+ const file = queue.shift();
222
+ if (done.has(file))
223
+ continue;
224
+ done.add(file);
225
+ const resolved = load(read, file, 0, new Set());
226
+ if (!resolved)
227
+ continue;
228
+ const dir = dirOf(file);
229
+ configs.push({
230
+ file,
231
+ dir,
232
+ baseUrl: resolved.baseUrl,
233
+ pathsBase: resolved.baseUrl ?? resolved.pathsDir ?? dir,
234
+ paths: resolved.paths ?? [],
235
+ include: resolved.include,
236
+ exclude: resolved.exclude,
237
+ files: resolved.files,
238
+ references: resolved.references,
239
+ outDir: resolved.outDir,
240
+ rootDir: resolved.rootDir,
241
+ ...(resolved.incomplete ? { incomplete: true } : {}),
242
+ });
243
+ for (const reference of resolved.references)
244
+ if (!done.has(reference))
245
+ queue.push(reference);
246
+ }
247
+ return configs.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
248
+ }
249
+ function escapeRegExp(value) {
250
+ return value.replace(/[.+^${}()|[\]\\]/g, '\\$&');
251
+ }
252
+ // TypeScript's include/exclude globs: `*` and `?` stay inside a segment, `**/` spans directories.
253
+ // A pattern with no extension and no wildcard names a directory.
254
+ export function globToRegExp(pattern) {
255
+ const normalized = pattern.replace(/\/+$/, '');
256
+ const hasWildcard = /[*?]/.test(normalized);
257
+ const base = !hasWildcard && !path.posix.extname(normalized) ? `${normalized}/**/*` : normalized;
258
+ let source = '';
259
+ for (let i = 0; i < base.length; i++) {
260
+ const ch = base[i];
261
+ if (ch === '*' && base[i + 1] === '*') {
262
+ if (base[i + 2] === '/') {
263
+ source += '(?:.*/)?';
264
+ i += 2;
265
+ }
266
+ else {
267
+ source += '.*';
268
+ i += 1;
269
+ }
270
+ }
271
+ else if (ch === '*') {
272
+ source += '[^/]*';
273
+ }
274
+ else if (ch === '?') {
275
+ source += '[^/]';
276
+ }
277
+ else {
278
+ source += escapeRegExp(ch);
279
+ }
280
+ }
281
+ return new RegExp(`^${source}$`);
282
+ }
283
+ const DEFAULT_EXCLUDE = ['node_modules', 'bower_components', 'jspm_packages'];
284
+ const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
285
+ // Whether a tsconfig's include/exclude/files would put this file in the project.
286
+ export function configCovers(config, file) {
287
+ const inside = config.dir === '' || file === config.dir || file.startsWith(`${config.dir}/`);
288
+ if (!inside)
289
+ return false;
290
+ if (!SOURCE_FILE.test(file))
291
+ return false;
292
+ const excludes = (config.exclude ?? DEFAULT_EXCLUDE.map((e) => (config.dir ? `${config.dir}/${e}` : e))).map(globToRegExp);
293
+ if (excludes.some((re) => re.test(file)))
294
+ return false;
295
+ if (config.files?.includes(file))
296
+ return true;
297
+ if (config.include)
298
+ return config.include.map(globToRegExp).some((re) => re.test(file));
299
+ // `files` without `include` means exactly those files; a config with neither covers everything under its directory.
300
+ return config.files === undefined;
301
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,156 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { hasParseError } from './health.js';
3
+ export function kids(node) {
4
+ return node ? node.namedChildren.filter((c) => c !== null) : [];
5
+ }
6
+ export const text = (node) => node?.text ?? '';
7
+ // The source text of `node` up to `end`, with comments removed. Signatures are built from this so that a comment
8
+ // inside a parameter list or type never becomes part of what is displayed or sent to an external model.
9
+ export function codeText(node, source, end) {
10
+ if (!node)
11
+ return '';
12
+ const stop = end ?? node.endIndex;
13
+ const cuts = [];
14
+ // Explicit stack (children pushed in reverse so comments are collected in source order): the tree can be far deeper than the call stack.
15
+ const pending = [node];
16
+ for (let n = pending.pop(); n; n = pending.pop()) {
17
+ if (n.startIndex >= stop)
18
+ continue;
19
+ if (n.type === 'comment') {
20
+ cuts.push([n.startIndex, n.endIndex]);
21
+ continue;
22
+ }
23
+ const children = n.children;
24
+ for (let i = children.length - 1; i >= 0; i--) {
25
+ const child = children[i];
26
+ if (child)
27
+ pending.push(child);
28
+ }
29
+ }
30
+ let out = '';
31
+ let pos = node.startIndex;
32
+ for (const [from, to] of cuts) {
33
+ out += `${source.slice(pos, from)} `;
34
+ pos = to;
35
+ }
36
+ return out + source.slice(pos, stop);
37
+ }
38
+ export const rangeOf = (node) => [node.startIndex, node.endIndex];
39
+ export const within = (index, ranges) => ranges.some(([start, end]) => index >= start && index < end);
40
+ export const lineOf = (node) => node.startPosition.row + 1;
41
+ export function oneLine(value, max = 160) {
42
+ const flat = value.replace(/\s+/g, ' ').trim();
43
+ return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
44
+ }
45
+ const MIN_BODY_CHARS = 120;
46
+ export function bodyHash(body) {
47
+ // A body that contains a syntax error was cut short or repaired by the parser: equal hashes would prove nothing.
48
+ if (!body || hasParseError(body))
49
+ return undefined;
50
+ const normalized = body.text.replace(/\s+/g, ' ').trim();
51
+ if (normalized.length < MIN_BODY_CHARS)
52
+ return undefined;
53
+ return createHash('sha1').update(normalized).digest('hex').slice(0, 12);
54
+ }
55
+ export function summarizeNames(names, limit = 10) {
56
+ const shown = names.slice(0, limit).join(', ');
57
+ return names.length > limit ? `${shown}, …` : shown;
58
+ }
59
+ const MIN_STRUCT_TOKENS = 40;
60
+ const LITERAL_TOKENS = {
61
+ string: 'S', template_string: 'S', number: 'N', integer: 'N', float: 'N', regex: 'R', concatenated_string: 'S',
62
+ };
63
+ const SKIPPED = new Set(['comment', 'type_annotation', 'type_parameters', 'return_type', 'decorator']);
64
+ // Hash of a function's parameters and body (not its name or keyword form) where names declared inside the function (parameters, locals) are replaced by their
65
+ // order of appearance, free names, property names and operators are kept, and literals keep only their kind.
66
+ // Two functions that differ only in local naming, literal values or type annotations hash the same; anything
67
+ // that changes the shape of the code does not. This compares syntax, never behaviour.
68
+ export function structuralHash(parts, isDeclared) {
69
+ if (parts.some((part) => hasParseError(part)))
70
+ return undefined;
71
+ const rename = new Map();
72
+ const tokens = [];
73
+ const CLOSE = Symbol('close');
74
+ // Explicit stack: a node is followed by a CLOSE marker so the closing token lands after its last descendant, exactly where
75
+ // a recursive walk would emit it. Children are pushed in reverse to keep source order.
76
+ const pending = [];
77
+ for (let i = parts.length - 1; i >= 0; i--) {
78
+ const part = parts[i];
79
+ if (part)
80
+ pending.push(part);
81
+ }
82
+ for (let item = pending.pop(); item !== undefined; item = pending.pop()) {
83
+ if (item === CLOSE) {
84
+ tokens.push(')');
85
+ continue;
86
+ }
87
+ const node = item;
88
+ if (SKIPPED.has(node.type))
89
+ continue;
90
+ const literal = LITERAL_TOKENS[node.type];
91
+ if (literal) {
92
+ tokens.push(literal);
93
+ continue;
94
+ }
95
+ if (node.childCount === 0) {
96
+ if (node.type === 'identifier' || node.type === 'shorthand_property_identifier' || node.type === 'shorthand_property_identifier_pattern') {
97
+ const name = node.text;
98
+ if (isDeclared(node) || rename.has(name)) {
99
+ if (!rename.has(name))
100
+ rename.set(name, rename.size);
101
+ tokens.push(`#${rename.get(name)}`);
102
+ }
103
+ else {
104
+ tokens.push(`id:${name}`);
105
+ }
106
+ }
107
+ else if (node.isNamed) {
108
+ tokens.push(`${node.type}:${node.text}`);
109
+ }
110
+ else {
111
+ tokens.push(node.type);
112
+ }
113
+ continue;
114
+ }
115
+ tokens.push(`(${node.type}`);
116
+ pending.push(CLOSE);
117
+ const children = node.children;
118
+ for (let i = children.length - 1; i >= 0; i--) {
119
+ const child = children[i];
120
+ if (child)
121
+ pending.push(child);
122
+ }
123
+ }
124
+ if (tokens.length < MIN_STRUCT_TOKENS)
125
+ return undefined;
126
+ return createHash('sha1').update(tokens.join(' ')).digest('hex').slice(0, 12);
127
+ }
128
+ const cleanDoc = (raw) => {
129
+ const lines = raw
130
+ .replace(/^\s*(?:\/\*+|\/\/+|#+|"""|\'\'\')/, '')
131
+ .replace(/(?:\*+\/|"""|\'\'\')\s*$/, '')
132
+ .split('\n')
133
+ .map((l) => l.replace(/^\s*(?:\*+|\/\/+|#+)\s?/, '').trim())
134
+ .filter((l) => l && !l.startsWith('@') && !/^eslint|^prettier|^ts-|^istanbul/i.test(l));
135
+ const first = lines.join(' ').match(/^.*?(?:[.!?](?=\s|$)|$)/)?.[0] ?? '';
136
+ const doc = oneLine(first.trim(), 160);
137
+ return doc.length >= 8 ? doc : undefined;
138
+ };
139
+ // The comment that sits directly above a declaration (or above its `export` wrapper): a JSDoc block or `//` line.
140
+ export function leadingComment(node) {
141
+ const target = node.parent?.type === 'export_statement' ? node.parent : node;
142
+ const prev = target.previousSibling;
143
+ if (prev?.type !== 'comment' || prev.endPosition.row < target.startPosition.row - 1)
144
+ return undefined;
145
+ if (/^\/\/\s*(?:@ts-|eslint|prettier|istanbul|#region|#endregion)/.test(prev.text))
146
+ return undefined;
147
+ return cleanDoc(prev.text);
148
+ }
149
+ // A Python docstring: the first statement of a function or class body when it is a bare string.
150
+ export function docstring(def) {
151
+ const first = def.childForFieldName('body')?.namedChildren[0];
152
+ if (first?.type !== 'expression_statement')
153
+ return undefined;
154
+ const str = first.namedChildren[0];
155
+ return str?.type === 'string' ? cleanDoc(str.text) : undefined;
156
+ }