@aryam/fixmap-core 0.9.0 → 0.9.2

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 (194) hide show
  1. package/README.md +51 -1
  2. package/dist/annotation-store.d.ts +5 -0
  3. package/dist/annotation-store.js +117 -0
  4. package/dist/annotation-store.js.map +1 -0
  5. package/dist/annotations.d.ts +57 -0
  6. package/dist/annotations.js +221 -0
  7. package/dist/annotations.js.map +1 -0
  8. package/dist/architecture-history.d.ts +33 -0
  9. package/dist/architecture-history.js +234 -0
  10. package/dist/architecture-history.js.map +1 -0
  11. package/dist/architecture.d.ts +124 -0
  12. package/dist/architecture.js +348 -0
  13. package/dist/architecture.js.map +1 -0
  14. package/dist/artifacts.d.ts +9 -0
  15. package/dist/artifacts.js +82 -0
  16. package/dist/artifacts.js.map +1 -0
  17. package/dist/ask.d.ts +48 -0
  18. package/dist/ask.js +182 -0
  19. package/dist/ask.js.map +1 -0
  20. package/dist/browser.d.ts +66 -3
  21. package/dist/browser.js +34 -2
  22. package/dist/browser.js.map +1 -1
  23. package/dist/capabilities.d.ts +39 -0
  24. package/dist/capabilities.js +172 -0
  25. package/dist/capabilities.js.map +1 -0
  26. package/dist/capability-history.d.ts +49 -0
  27. package/dist/capability-history.js +176 -0
  28. package/dist/capability-history.js.map +1 -0
  29. package/dist/change-conflicts.d.ts +34 -0
  30. package/dist/change-conflicts.js +140 -0
  31. package/dist/change-conflicts.js.map +1 -0
  32. package/dist/change-scope.d.ts +81 -0
  33. package/dist/change-scope.js +316 -0
  34. package/dist/change-scope.js.map +1 -0
  35. package/dist/characterization.d.ts +61 -0
  36. package/dist/characterization.js +169 -0
  37. package/dist/characterization.js.map +1 -0
  38. package/dist/ci-matrix.d.ts +53 -0
  39. package/dist/ci-matrix.js +170 -0
  40. package/dist/ci-matrix.js.map +1 -0
  41. package/dist/compare.js +2 -2
  42. package/dist/compare.js.map +1 -1
  43. package/dist/composer-projects.d.ts +32 -0
  44. package/dist/composer-projects.js +246 -0
  45. package/dist/composer-projects.js.map +1 -0
  46. package/dist/context.d.ts +1 -1
  47. package/dist/context.js +26 -4
  48. package/dist/context.js.map +1 -1
  49. package/dist/contracts.d.ts +75 -0
  50. package/dist/contracts.js +526 -0
  51. package/dist/contracts.js.map +1 -0
  52. package/dist/custom-language-context.d.ts +43 -0
  53. package/dist/custom-language-context.js +89 -0
  54. package/dist/custom-language-context.js.map +1 -0
  55. package/dist/decisions.d.ts +64 -0
  56. package/dist/decisions.js +338 -0
  57. package/dist/decisions.js.map +1 -0
  58. package/dist/dossier.d.ts +63 -0
  59. package/dist/dossier.js +176 -0
  60. package/dist/dossier.js.map +1 -0
  61. package/dist/dotnet-projects.d.ts +26 -0
  62. package/dist/dotnet-projects.js +171 -0
  63. package/dist/dotnet-projects.js.map +1 -0
  64. package/dist/editor-loader.d.ts +9 -0
  65. package/dist/editor-loader.js +18 -0
  66. package/dist/editor-loader.js.map +1 -0
  67. package/dist/editor-protocol.d.ts +35 -0
  68. package/dist/editor-protocol.js +200 -0
  69. package/dist/editor-protocol.js.map +1 -0
  70. package/dist/editor-session.d.ts +15 -0
  71. package/dist/editor-session.js +27 -0
  72. package/dist/editor-session.js.map +1 -0
  73. package/dist/editor-transport.d.ts +10 -0
  74. package/dist/editor-transport.js +75 -0
  75. package/dist/editor-transport.js.map +1 -0
  76. package/dist/enterprise-policy.d.ts +82 -0
  77. package/dist/enterprise-policy.js +170 -0
  78. package/dist/enterprise-policy.js.map +1 -0
  79. package/dist/evidence-bundle.d.ts +13 -0
  80. package/dist/evidence-bundle.js +105 -0
  81. package/dist/evidence-bundle.js.map +1 -0
  82. package/dist/evidence.d.ts +125 -0
  83. package/dist/evidence.js +252 -0
  84. package/dist/evidence.js.map +1 -0
  85. package/dist/explain.js +7 -0
  86. package/dist/explain.js.map +1 -1
  87. package/dist/go-projects.d.ts +22 -0
  88. package/dist/go-projects.js +146 -0
  89. package/dist/go-projects.js.map +1 -0
  90. package/dist/graph.js +9 -0
  91. package/dist/graph.js.map +1 -1
  92. package/dist/grounding.d.ts +4 -1
  93. package/dist/grounding.js +70 -13
  94. package/dist/grounding.js.map +1 -1
  95. package/dist/identity-graph.d.ts +106 -0
  96. package/dist/identity-graph.js +353 -0
  97. package/dist/identity-graph.js.map +1 -0
  98. package/dist/impact.d.ts +2 -1
  99. package/dist/impact.js +12 -4
  100. package/dist/impact.js.map +1 -1
  101. package/dist/import-graph.d.ts +7 -1
  102. package/dist/import-graph.js +616 -34
  103. package/dist/import-graph.js.map +1 -1
  104. package/dist/incident.d.ts +74 -0
  105. package/dist/incident.js +212 -0
  106. package/dist/incident.js.map +1 -0
  107. package/dist/index.d.ts +91 -4
  108. package/dist/index.js +47 -3
  109. package/dist/index.js.map +1 -1
  110. package/dist/language-adapters.d.ts +33 -0
  111. package/dist/language-adapters.js +390 -0
  112. package/dist/language-adapters.js.map +1 -0
  113. package/dist/language-registry.d.ts +26 -0
  114. package/dist/language-registry.js +57 -0
  115. package/dist/language-registry.js.map +1 -0
  116. package/dist/languages.d.ts +20 -5
  117. package/dist/languages.js +197 -19
  118. package/dist/languages.js.map +1 -1
  119. package/dist/markdown.d.ts +1 -0
  120. package/dist/markdown.js +7 -1
  121. package/dist/markdown.js.map +1 -1
  122. package/dist/migration.d.ts +56 -0
  123. package/dist/migration.js +154 -0
  124. package/dist/migration.js.map +1 -0
  125. package/dist/outcomes.d.ts +57 -0
  126. package/dist/outcomes.js +146 -0
  127. package/dist/outcomes.js.map +1 -0
  128. package/dist/ownership.d.ts +29 -0
  129. package/dist/ownership.js +189 -0
  130. package/dist/ownership.js.map +1 -0
  131. package/dist/plan-alternatives.d.ts +74 -0
  132. package/dist/plan-alternatives.js +205 -0
  133. package/dist/plan-alternatives.js.map +1 -0
  134. package/dist/plan.d.ts +7 -0
  135. package/dist/plan.js +41 -8
  136. package/dist/plan.js.map +1 -1
  137. package/dist/rank.d.ts +64 -1
  138. package/dist/rank.js +278 -26
  139. package/dist/rank.js.map +1 -1
  140. package/dist/repo-scan.d.ts +8 -1
  141. package/dist/repo-scan.js +341 -97
  142. package/dist/repo-scan.js.map +1 -1
  143. package/dist/report.d.ts +16 -0
  144. package/dist/report.js +298 -33
  145. package/dist/report.js.map +1 -1
  146. package/dist/retrieval.d.ts +37 -0
  147. package/dist/retrieval.js +150 -21
  148. package/dist/retrieval.js.map +1 -1
  149. package/dist/reverse-docs.d.ts +46 -0
  150. package/dist/reverse-docs.js +179 -0
  151. package/dist/reverse-docs.js.map +1 -0
  152. package/dist/ruby-projects.d.ts +20 -0
  153. package/dist/ruby-projects.js +114 -0
  154. package/dist/ruby-projects.js.map +1 -0
  155. package/dist/runtime-evidence.d.ts +90 -0
  156. package/dist/runtime-evidence.js +186 -0
  157. package/dist/runtime-evidence.js.map +1 -0
  158. package/dist/rust-projects.d.ts +17 -0
  159. package/dist/rust-projects.js +125 -0
  160. package/dist/rust-projects.js.map +1 -0
  161. package/dist/sandbox.d.ts +59 -0
  162. package/dist/sandbox.js +202 -0
  163. package/dist/sandbox.js.map +1 -0
  164. package/dist/semantic-cache.d.ts +8 -0
  165. package/dist/semantic-cache.js +149 -0
  166. package/dist/semantic-cache.js.map +1 -0
  167. package/dist/semantic.d.ts +78 -0
  168. package/dist/semantic.js +237 -0
  169. package/dist/semantic.js.map +1 -0
  170. package/dist/sensitive-data.d.ts +8 -0
  171. package/dist/sensitive-data.js +157 -0
  172. package/dist/sensitive-data.js.map +1 -0
  173. package/dist/signals.js +1 -1
  174. package/dist/signals.js.map +1 -1
  175. package/dist/supply-chain.d.ts +38 -0
  176. package/dist/supply-chain.js +206 -0
  177. package/dist/supply-chain.js.map +1 -0
  178. package/dist/test-reliability.d.ts +56 -0
  179. package/dist/test-reliability.js +191 -0
  180. package/dist/test-reliability.js.map +1 -0
  181. package/dist/text.js +8 -1
  182. package/dist/text.js.map +1 -1
  183. package/dist/transformers-embedding.d.ts +16 -0
  184. package/dist/transformers-embedding.js +127 -0
  185. package/dist/transformers-embedding.js.map +1 -0
  186. package/dist/types.d.ts +79 -2
  187. package/dist/validate.js +172 -0
  188. package/dist/validate.js.map +1 -1
  189. package/dist/verify.js +136 -2
  190. package/dist/verify.js.map +1 -1
  191. package/dist/workspace.d.ts +86 -0
  192. package/dist/workspace.js +557 -0
  193. package/dist/workspace.js.map +1 -0
  194. package/package.json +2 -2
@@ -0,0 +1,202 @@
1
+ import { execFile, spawn } from "node:child_process";
2
+ import { isAbsolute, resolve } from "node:path";
3
+ import { promisify } from "node:util";
4
+ const exec = promisify(execFile);
5
+ const EXECUTION_ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
6
+ const PINNED_IMAGE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,399}@sha256:[a-f0-9]{64}$/i;
7
+ const DEFAULT_LIMITS = {
8
+ timeoutMs: 5 * 60_000,
9
+ outputBytes: 1_000_000,
10
+ cpus: 1,
11
+ memoryMb: 1_024,
12
+ pids: 256,
13
+ tmpfsMb: 256
14
+ };
15
+ export function buildSandboxInvocation(request) {
16
+ if (!request || !EXECUTION_ID.test(request.executionId) || request.consent !== "execute-declared-command") {
17
+ throw new Error("Sandbox execution requires a valid ID and explicit execute-declared-command consent.");
18
+ }
19
+ if (!isAbsolute(request.repoRoot) || /[\0\r\n,]/.test(request.repoRoot)) {
20
+ throw new Error("Sandbox repository root must be an absolute path without control characters or commas.");
21
+ }
22
+ if (!PINNED_IMAGE.test(request.image))
23
+ throw new Error("Sandbox image must be pinned by sha256 digest.");
24
+ if (!validCommand(request.command) || !Array.isArray(request.declaredCommands) || request.declaredCommands.length > 100 ||
25
+ !request.declaredCommands.every(validCommand) || !request.declaredCommands.includes(request.command)) {
26
+ throw new Error("Sandbox command must exactly match a bounded declared command.");
27
+ }
28
+ const networkEnabled = request.network?.enabled === true;
29
+ if (networkEnabled && request.network?.consent !== "allow-sandbox-network") {
30
+ throw new Error("Sandbox network access requires separate allow-sandbox-network consent.");
31
+ }
32
+ const limits = validateLimits(request.limits);
33
+ const repoRoot = resolve(request.repoRoot);
34
+ const containerName = `fixmap-${request.executionId}-${stableHash(`${repoRoot}\0${request.command}`).slice(0, 10)}`;
35
+ const network = networkEnabled ? "bridge" : "none";
36
+ const args = [
37
+ "--context", "default",
38
+ "run", "--rm", "--name", containerName,
39
+ "--pull", "never",
40
+ "--network", network,
41
+ "--read-only",
42
+ "--cap-drop", "ALL",
43
+ "--security-opt", "no-new-privileges:true",
44
+ "--user", "65534:65534",
45
+ "--pids-limit", String(limits.pids),
46
+ "--cpus", String(limits.cpus),
47
+ "--memory", `${limits.memoryMb}m`,
48
+ "--ipc", "none",
49
+ "--ulimit", "nofile=1024:1024",
50
+ "--tmpfs", `/tmp:rw,noexec,nosuid,nodev,size=${limits.tmpfsMb}m`,
51
+ "--mount", `type=bind,source=${repoRoot},target=/workspace,readonly`,
52
+ "--workdir", "/workspace",
53
+ "--entrypoint", "/bin/sh",
54
+ request.image,
55
+ "-lc", request.command
56
+ ];
57
+ return {
58
+ executable: "docker",
59
+ args,
60
+ containerName,
61
+ policy: {
62
+ sourceReadOnly: true,
63
+ rootFilesystemReadOnly: true,
64
+ network,
65
+ inheritedContainerEnvironment: false,
66
+ capabilitiesDropped: "ALL",
67
+ noNewPrivileges: true,
68
+ user: "65534:65534",
69
+ pull: "never"
70
+ },
71
+ limits
72
+ };
73
+ }
74
+ export async function runSandbox(request, adapter = runDockerProcess) {
75
+ const invocation = buildSandboxInvocation(request);
76
+ let raw;
77
+ try {
78
+ raw = await adapter(invocation);
79
+ }
80
+ catch (error) {
81
+ raw = { reason: "unavailable", exitCode: null, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
82
+ }
83
+ const stdout = truncateUtf8(raw.stdout, invocation.limits.outputBytes);
84
+ const stderrBudget = Math.max(0, invocation.limits.outputBytes - Buffer.byteLength(stdout.value));
85
+ const stderr = truncateUtf8(raw.stderr, stderrBudget);
86
+ const status = raw.reason === "timeout" ? "timeout"
87
+ : raw.reason === "unavailable" ? "unavailable"
88
+ : raw.reason === "output-limit" ? "crashed"
89
+ : raw.exitCode === 125 ? "unavailable"
90
+ : raw.exitCode === 0 ? "passed" : raw.exitCode === null ? "crashed" : "failed";
91
+ return {
92
+ sandboxResultVersion: 1,
93
+ executionId: request.executionId,
94
+ image: request.image,
95
+ command: request.command,
96
+ status,
97
+ exitCode: raw.exitCode,
98
+ stdout: stdout.value,
99
+ stderr: stderr.value,
100
+ outputTruncated: raw.reason === "output-limit" || stdout.truncated || stderr.truncated,
101
+ policy: invocation.policy,
102
+ limits: invocation.limits
103
+ };
104
+ }
105
+ async function runDockerProcess(invocation) {
106
+ return new Promise((resolveResult) => {
107
+ const child = spawn(invocation.executable, invocation.args, {
108
+ stdio: ["ignore", "pipe", "pipe"],
109
+ windowsHide: true,
110
+ env: minimalDockerEnvironment()
111
+ });
112
+ const stdout = [];
113
+ const stderr = [];
114
+ let bytes = 0;
115
+ let reason = "exit";
116
+ let settled = false;
117
+ const finish = async (exitCode) => {
118
+ if (settled)
119
+ return;
120
+ settled = true;
121
+ clearTimeout(timer);
122
+ if (reason !== "exit")
123
+ await cleanupContainer(invocation.containerName);
124
+ resolveResult({ reason, exitCode, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8") });
125
+ };
126
+ const capture = (target) => (chunk) => {
127
+ const remaining = invocation.limits.outputBytes - bytes;
128
+ if (remaining > 0)
129
+ target.push(chunk.subarray(0, remaining));
130
+ bytes += chunk.length;
131
+ if (bytes > invocation.limits.outputBytes && reason === "exit") {
132
+ reason = "output-limit";
133
+ child.kill();
134
+ void finish(null);
135
+ }
136
+ };
137
+ child.stdout.on("data", capture(stdout));
138
+ child.stderr.on("data", capture(stderr));
139
+ child.once("error", (error) => {
140
+ reason = "unavailable";
141
+ stderr.push(Buffer.from(error.message));
142
+ void finish(null);
143
+ });
144
+ child.once("close", (code) => { void finish(code); });
145
+ const timer = setTimeout(() => {
146
+ reason = "timeout";
147
+ child.kill();
148
+ void finish(null);
149
+ }, invocation.limits.timeoutMs);
150
+ });
151
+ }
152
+ async function cleanupContainer(name) {
153
+ try {
154
+ await exec("docker", ["--context", "default", "rm", "--force", name], { windowsHide: true, timeout: 15_000, env: minimalDockerEnvironment() });
155
+ }
156
+ catch {
157
+ // Best effort: the attached `docker run --rm` normally removes the container itself.
158
+ }
159
+ }
160
+ function minimalDockerEnvironment() {
161
+ const environment = {};
162
+ for (const key of ["PATH", "Path", "PATHEXT", "SYSTEMROOT", "SystemRoot", "TEMP", "TMP", "DOCKER_CONFIG"]) {
163
+ if (process.env[key] !== undefined)
164
+ environment[key] = process.env[key];
165
+ }
166
+ return environment;
167
+ }
168
+ function validateLimits(input) {
169
+ const limits = { ...DEFAULT_LIMITS, ...(input ?? {}) };
170
+ if (!integerBetween(limits.timeoutMs, 1_000, 10 * 60_000) || !integerBetween(limits.outputBytes, 1_024, 10_000_000) ||
171
+ typeof limits.cpus !== "number" || !Number.isFinite(limits.cpus) || limits.cpus < 0.1 || limits.cpus > 8 ||
172
+ !integerBetween(limits.memoryMb, 64, 16_384) || !integerBetween(limits.pids, 16, 1_024) || !integerBetween(limits.tmpfsMb, 16, 4_096)) {
173
+ throw new Error("Sandbox resource limits are outside supported bounds.");
174
+ }
175
+ return limits;
176
+ }
177
+ function validCommand(value) { return typeof value === "string" && value.trim().length > 0 && value.length <= 2_000 && !/[\0\r\n]/.test(value); }
178
+ function integerBetween(value, minimum, maximum) { return Number.isSafeInteger(value) && value >= minimum && value <= maximum; }
179
+ function truncateUtf8(value, maximum) {
180
+ const bytes = Buffer.from(value);
181
+ if (bytes.length <= maximum)
182
+ return { value, truncated: false };
183
+ const decoder = new TextDecoder("utf-8", { fatal: true });
184
+ for (let end = maximum; end >= Math.max(0, maximum - 4); end -= 1) {
185
+ try {
186
+ return { value: decoder.decode(bytes.subarray(0, end)), truncated: true };
187
+ }
188
+ catch {
189
+ // Try the previous UTF-8 boundary.
190
+ }
191
+ }
192
+ return { value: "", truncated: true };
193
+ }
194
+ function stableHash(value) {
195
+ let hash = 0xcbf29ce484222325n;
196
+ for (const byte of new TextEncoder().encode(value)) {
197
+ hash ^= BigInt(byte);
198
+ hash = BigInt.asUintN(64, hash * 0x100000001b3n);
199
+ }
200
+ return hash.toString(16).padStart(16, "0");
201
+ }
202
+ //# sourceMappingURL=sandbox.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ import type { EmbeddingProvider } from "./semantic.js";
2
+ export type PersistentEmbeddingCacheOptions = {
3
+ repositoryRoot: string;
4
+ cacheRoot?: string;
5
+ maxEntries?: number;
6
+ };
7
+ /** Wraps an embedding provider with an atomic, model-isolated, local persistent cache. */
8
+ export declare function withPersistentEmbeddingCache(provider: EmbeddingProvider, options: PersistentEmbeddingCacheOptions): Promise<EmbeddingProvider>;
@@ -0,0 +1,149 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import { mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
3
+ import { homedir } from "node:os";
4
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
5
+ const CACHE_VERSION = 1;
6
+ const DEFAULT_MAX_ENTRIES = 50_000;
7
+ /** Wraps an embedding provider with an atomic, model-isolated, local persistent cache. */
8
+ export async function withPersistentEmbeddingCache(provider, options) {
9
+ const requestedRepositoryRoot = resolve(options.repositoryRoot);
10
+ const requestedCacheRoot = resolve(options.cacheRoot ?? configuredSemanticCacheRoot());
11
+ if (samePath(requestedRepositoryRoot, requestedCacheRoot) || isContained(requestedRepositoryRoot, requestedCacheRoot)) {
12
+ throw new Error("Semantic cache must be outside the scanned repository so derived vectors cannot enter ranking or version control.");
13
+ }
14
+ const repositoryRoot = await realpath(requestedRepositoryRoot);
15
+ const cacheRoot = await resolveProspectiveRealPath(requestedCacheRoot);
16
+ if (samePath(repositoryRoot, cacheRoot) || isContained(repositoryRoot, cacheRoot)) {
17
+ throw new Error("Semantic cache must be outside the scanned repository so derived vectors cannot enter ranking or version control.");
18
+ }
19
+ const providerKey = embeddingProviderKey(provider);
20
+ const cachePath = join(cacheRoot, `${hashText(repositoryRoot)}-${hashText(providerKey)}-semantic-v1.json`);
21
+ const maxEntries = positiveInteger(options.maxEntries, DEFAULT_MAX_ENTRIES);
22
+ let cachePromise;
23
+ let writeQueue = Promise.resolve();
24
+ async function load() {
25
+ cachePromise ??= readCache(cachePath, providerKey, provider.dimensions);
26
+ return cachePromise;
27
+ }
28
+ return {
29
+ ...provider,
30
+ async embed(texts, context) {
31
+ const cache = await load();
32
+ const now = new Date().toISOString();
33
+ const keys = texts.map((text) => hashText(text));
34
+ const output = keys.map((key) => {
35
+ const hit = cache.entries[key];
36
+ if (!hit)
37
+ return undefined;
38
+ hit.lastUsedAt = now;
39
+ return [...hit.vector];
40
+ });
41
+ const missingIndexes = output.flatMap((vector, index) => vector ? [] : [index]);
42
+ if (missingIndexes.length > 0) {
43
+ const missingTexts = missingIndexes.map((index) => texts[index]);
44
+ const generated = await provider.embed(missingTexts, context);
45
+ if (generated.length !== missingTexts.length) {
46
+ throw new Error(`embedding provider returned ${generated.length} vectors for ${missingTexts.length} cache misses`);
47
+ }
48
+ generated.forEach((vector, generatedIndex) => {
49
+ const originalIndex = missingIndexes[generatedIndex];
50
+ const copied = Array.from(vector);
51
+ output[originalIndex] = copied;
52
+ cache.entries[keys[originalIndex]] = { vector: copied, lastUsedAt: now };
53
+ });
54
+ }
55
+ pruneEntries(cache.entries, maxEntries);
56
+ writeQueue = writeQueue.then(() => writeCache(cachePath, cache));
57
+ await writeQueue;
58
+ return output.map((vector) => vector);
59
+ }
60
+ };
61
+ }
62
+ /** Canonicalize a path before it exists by resolving its nearest existing ancestor. */
63
+ async function resolveProspectiveRealPath(path) {
64
+ let cursor = path;
65
+ const missing = [];
66
+ while (true) {
67
+ try {
68
+ return resolve(await realpath(cursor), ...missing.reverse());
69
+ }
70
+ catch (error) {
71
+ if (!isNodeError(error, "ENOENT"))
72
+ throw error;
73
+ const parent = dirname(cursor);
74
+ if (parent === cursor)
75
+ return path;
76
+ missing.push(basename(cursor));
77
+ cursor = parent;
78
+ }
79
+ }
80
+ }
81
+ function configuredSemanticCacheRoot() {
82
+ const configured = process.env.FIXMAP_CACHE_DIR;
83
+ if (configured)
84
+ return join(configured, "semantic");
85
+ return join(process.env.LOCALAPPDATA ?? process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "fixmap", "semantic");
86
+ }
87
+ async function readCache(path, providerKey, dimensions) {
88
+ try {
89
+ const candidate = JSON.parse(await readFile(path, "utf8"));
90
+ if (!isRecord(candidate) || candidate.version !== CACHE_VERSION || candidate.providerKey !== providerKey || !isRecord(candidate.entries)) {
91
+ return emptyCache(providerKey);
92
+ }
93
+ const entries = {};
94
+ for (const [key, value] of Object.entries(candidate.entries)) {
95
+ if (!/^[a-f0-9]{64}$/.test(key) || !isRecord(value) || !Array.isArray(value.vector) ||
96
+ value.vector.length !== dimensions || value.vector.some((number) => typeof number !== "number" || !Number.isFinite(number)) ||
97
+ typeof value.lastUsedAt !== "string" || !Number.isFinite(Date.parse(value.lastUsedAt)))
98
+ continue;
99
+ entries[key] = { vector: [...value.vector], lastUsedAt: value.lastUsedAt };
100
+ }
101
+ return { version: CACHE_VERSION, providerKey, entries };
102
+ }
103
+ catch {
104
+ return emptyCache(providerKey);
105
+ }
106
+ }
107
+ async function writeCache(path, cache) {
108
+ await mkdir(resolve(path, ".."), { recursive: true });
109
+ const temporary = `${path}.${randomUUID()}.tmp`;
110
+ try {
111
+ await writeFile(temporary, `${JSON.stringify(cache)}\n`, { encoding: "utf8", mode: 0o600 });
112
+ await rename(temporary, path);
113
+ }
114
+ finally {
115
+ await unlink(temporary).catch(() => undefined);
116
+ }
117
+ }
118
+ function emptyCache(providerKey) {
119
+ return { version: CACHE_VERSION, providerKey, entries: {} };
120
+ }
121
+ function pruneEntries(entries, maximum) {
122
+ const ordered = Object.entries(entries).sort((a, b) => Date.parse(b[1].lastUsedAt) - Date.parse(a[1].lastUsedAt) || a[0].localeCompare(b[0]));
123
+ for (const [key] of ordered.slice(maximum))
124
+ delete entries[key];
125
+ }
126
+ function embeddingProviderKey(provider) {
127
+ return [provider.id, provider.version, provider.model, provider.artifactHash, provider.runtime,
128
+ provider.dimensions, provider.normalization].join(":");
129
+ }
130
+ function hashText(text) {
131
+ return createHash("sha256").update(text).digest("hex");
132
+ }
133
+ function isContained(root, candidate) {
134
+ const distance = relative(root, candidate);
135
+ return distance !== "" && distance !== ".." && !distance.startsWith(`..${sep}`) && !isAbsolute(distance);
136
+ }
137
+ function samePath(left, right) {
138
+ return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
139
+ }
140
+ function positiveInteger(value, fallback) {
141
+ return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
142
+ }
143
+ function isRecord(candidate) {
144
+ return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
145
+ }
146
+ function isNodeError(error, code) {
147
+ return error instanceof Error && "code" in error && error.code === code;
148
+ }
149
+ //# sourceMappingURL=semantic-cache.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"semantic-cache.js","sourceRoot":"","sources":["../src/semantic-cache.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,78 @@
1
+ import type { createCustomLanguageContext } from "./custom-language-context.js";
2
+ import type { PathExcluder } from "./exclude.js";
3
+ import type { RankedFile, RepoMap, ScanDiagnostic } from "./types.js";
4
+ import type { RankingShape } from "./grounding.js";
5
+ export type EmbeddingNormalization = "l2" | "none";
6
+ export type EmbeddingProviderProvenance = {
7
+ id: string;
8
+ version: string;
9
+ model: string;
10
+ /** SHA-256 of the local model artifact or immutable model bundle manifest. */
11
+ artifactHash: string;
12
+ runtime: string;
13
+ dimensions: number;
14
+ normalization: EmbeddingNormalization;
15
+ local: boolean;
16
+ };
17
+ export type EmbeddingProvider = EmbeddingProviderProvenance & {
18
+ embed(texts: readonly string[], context: {
19
+ signal: AbortSignal;
20
+ }): Promise<readonly (readonly number[])[]>;
21
+ };
22
+ export type HybridRetrievalSignal = {
23
+ structuralRank?: number;
24
+ structuralScore?: number;
25
+ lexicalRank?: number;
26
+ symbolRank?: number;
27
+ semanticRank?: number;
28
+ semanticSimilarity?: number;
29
+ };
30
+ export type HybridRankedFile = RankedFile & {
31
+ /** Weighted reciprocal-rank-fusion score. This is not the structural score. */
32
+ fusionScore: number;
33
+ retrieval: HybridRetrievalSignal;
34
+ };
35
+ export type SemanticIndexProvenance = EmbeddingProviderProvenance & {
36
+ cacheKey: string;
37
+ indexedFiles: number;
38
+ truncatedFiles: number;
39
+ };
40
+ export type HybridRetrievalDiagnostic = {
41
+ code: "semantic-disabled" | "semantic-remote-disallowed" | "semantic-provider-invalid" | "semantic-provider-failed" | "semantic-candidates-truncated";
42
+ severity: "info" | "warning";
43
+ message: string;
44
+ };
45
+ export type HybridRankingResult = {
46
+ files: HybridRankedFile[];
47
+ mode: "structural-lexical" | "structural-lexical-semantic";
48
+ weights: {
49
+ structural: number;
50
+ lexical: number;
51
+ semantic: number;
52
+ reciprocalRankConstant: number;
53
+ };
54
+ semantic?: SemanticIndexProvenance;
55
+ diagnostics: HybridRetrievalDiagnostic[];
56
+ structuralDiagnostics: ScanDiagnostic[];
57
+ structuralRanking: RankingShape;
58
+ };
59
+ export type HybridRankingOptions = {
60
+ languageContext?: ReturnType<typeof createCustomLanguageContext>;
61
+ embeddingProvider?: EmbeddingProvider;
62
+ allowRemoteEmbeddings?: boolean;
63
+ exclude?: PathExcluder;
64
+ limit?: number;
65
+ minStructuralScore?: number;
66
+ maxSemanticCandidates?: number;
67
+ timeoutMs?: number;
68
+ weights?: Partial<Pick<HybridRankingResult["weights"], "structural" | "lexical" | "semantic">>;
69
+ };
70
+ /**
71
+ * Combines FixMap's structural rank, BM25, and an optional embedding provider using
72
+ * weighted reciprocal-rank fusion. Raw score scales never mix: every contribution records
73
+ * its source rank, and semantic similarity remains separately inspectable.
74
+ */
75
+ export declare function rankContextFilesHybrid(repo: RepoMap, input: {
76
+ issueText?: string | undefined;
77
+ diffText?: string | undefined;
78
+ }, options?: HybridRankingOptions): Promise<HybridRankingResult>;