@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
package/README.md CHANGED
@@ -33,7 +33,57 @@ console.log(renderFixMapGraphMermaid(buildFixMapGraph(report)));
33
33
 
34
34
  `buildFixMapReport` runs the full pipeline: scan the repository, resolve exclusions, rank primary context against the task, build a separate likely-impact view, route to relevant test commands, and collect risk notes and diagnostics. Impact evidence includes imports, reverse dependents, routed tests, and repeated bounded Git co-change relationships; it is explicitly an inspection aid rather than a claim that every related file must change. Exact git states can reuse a seven-day scan cache, while `useCache: false` forces a fresh scan and reports the bypass.
35
35
 
36
- The package also exports the lower-level scanner, excluder, ranker, BM25 retriever, grounding, import graph, Context Pack and Impact Graph builders, test routing, risk, comparison, explanation, verification, structural validation, and Markdown/JSON/agent/Mermaid rendering APIs. Context budgets use the deterministic estimate `ceil(UTF-8 bytes / 4)` for source and report sample truncation explicitly. `@aryam/fixmap-core/browser` exposes the filesystem-free report, Context Pack, Impact Graph, Compare, Explain, Verify, validation, and rendering logic for browser applications.
36
+ The package also exports the lower-level scanner, excluder, ranker, BM25 retriever, grounding, import graph, Context Pack and Impact Graph builders, deterministic explicit-anchor Change Scope and persistent Capability Map primitives, test routing, risk, comparison, explanation, verification, structural validation, and Markdown/JSON/agent/Mermaid rendering APIs. Context budgets use the deterministic estimate `ceil(UTF-8 bytes / 4)` for source and report sample truncation explicitly.
37
+
38
+ The v0.10 graph API exposes `createGraphIdentity`, explicit `createGraphEquivalence` relationships, deterministic `buildIdentityGraph` snapshots, `buildGraphDependencyIndex`, and `invalidateIdentityGraph`. Identities cover repository, service, package, module, file, symbol, contract, runtime component, and deployment. `buildWorkspaceMap` uses exact `RepoFile.contentFingerprint` values to link Node, Python, and Maven repositories without guessing that similarly named entities are equivalent. `@aryam/fixmap-core/browser` exposes these filesystem-free workspace and identity primitives alongside report, Context Pack, Impact Graph, Compare, Explain, Verify, validation, and rendering logic for browser applications.
39
+
40
+ The language-adapter layer applies the same bounded evidence rules to JavaScript/TypeScript, Python, Java, Go, Rust, Ruby, PHP, and .NET. Built-in adapters extract declarations, imports, and test layouts; Core resolves only repository-backed relationships and feeds them into grounding, ranking, and impact graphs. Dynamic imports, macros, reflection, autoloading, generated code, and framework magic remain explicit limits unless a later evidence adapter supplies them.
41
+
42
+ Contract Guardian starts with `inventoryContracts` and `compareContractInventories`: it normalizes OpenAPI, AsyncAPI, GraphQL, Protobuf, JSON Schema, and SQL migrations into deterministic compatibility entries, retains exact before/after fingerprints, and can emit owned contract nodes through `contractGraphNodes`. Findings distinguish compatible, breaking, and unknown changes; incomplete scanner content is diagnosed instead of treated as an absent contract.
43
+
44
+ Human intent is represented by versioned annotations and authored decision records. `inventoryDecisionRecords` preserves ADR/RFC/design Context, Decision, Consequences, status, date, supersession, explicit scopes, and exact source fingerprints; `selectDecisionRecords` attaches only relevant records. Literal path mentions count only when that path exists in the scanned snapshot, and FixMap never rewrites generated prose as the author’s rationale.
45
+
46
+ Architecture policy is repository-owned in `.fixmap/policy.json`. `architecturePolicyFromRepo` and `evaluateArchitecturePolicy` apply bounded version-1 dependency boundaries, required test changes, reviewer routing, and breaking-contract constraints while retaining the exact policy fingerprint. `buildArchitectureSnapshot` and `compareArchitectureSnapshots` provide deterministic import edges, cyclic components, boundary violations, coupling, and drift; snapshots fail closed when a scanned file lacks an exact content identity.
47
+
48
+ Historical graph queries use `scanRepoAtRef`, `buildArchitectureSnapshotAtRef`, and `compareArchitectureRefs`. Refs are first resolved to immutable commit IDs, then exact Git blobs are read in a bounded batch. The API never checks out a ref, moves `HEAD`, or writes into the worktree.
49
+
50
+ `sensitiveDataFlowEvidenceProvider` is a built-in, network-free evidence provider for approximate credential, token, PII, and payment indicators near logging, network, storage, or analytics sinks. It reports only detector rule IDs, categories, exact file fingerprints, and low-confidence structural relationships—never matched values or source snippets—and explicitly states that its results are not taint analysis or a complete security proof.
51
+
52
+ Supply-chain data enters through `validateSupplyChainEvidenceBundle` and `createSupplyChainEvidenceProvider`. The versioned normalization contract retains external scanner/SBOM tool version, database version, timestamp, document SHA-256, package identity, confidence, advisory/fix data, and license policy. FixMap validates and relates those records but does not ship a CVE database or infer whether a package version or license is safe.
53
+
54
+ `detectChangeConflicts` compares explicit concurrent change intents on stable graph identities. It distinguishes intended edits, impact zones, contract zones, and graph baselines; reports edit/edit, directional edit/impact, shared-contract, and stale-baseline conflicts with evidence; and leaves unrelated identities alone. Display labels never establish sameness. Only explicit reviewed alias/equivalence edges in an identity graph canonicalize two zones.
55
+
56
+ `buildMigrationPlan` validates explicit migration steps against one exact identity-graph snapshot and produces dependency-ordered phases. Each step must name intended edits, impacts, contracts, a compatibility strategy (with exit criteria when a window exists), verification commands with reasons, and rollback triggers/actions. Every phase reports its blast radius; cycles, unknown identities, missing safety fields, and undeclared parallel edit/contract overlap fail closed.
57
+
58
+ `comparePlanAlternatives` requires every candidate to use the same exact graph fingerprint, then compares separate edit, impact, contract, policy, test-coverage, reversibility, and uncertainty axes. The output retains evidence and a non-dominated frontier. It intentionally has no winner field or scalar score: genuine tradeoffs remain visible instead of being hidden behind arbitrary weights.
59
+
60
+ Outcome feedback uses `OutcomeRecord` and the pure `addOutcomeRecord`, `removeOutcomeRecord`, and `summarizeOutcomeCalibration` APIs. Predictions, actual edits, command outcomes, and separately sourced task assessment remain distinct. Calibration exposes correct predictions, false positives, misses, precision/recall, and per-record evidence; it always declares `automaticWeightChanges: false` and never rewrites ranking weights.
61
+
62
+ `buildChangeDossier` creates one versioned lifecycle artifact linking request provenance, assumptions and their evidence status, plan/report and graph fingerprints, decision records, diff state, command outcomes, runtime observations/inferences, reviews, and optional release identifiers. It is valid before a diff or release exists, normalizes paths/timestamps, requires evidence for completed claims, and detects content that no longer matches its dossier fingerprint.
63
+
64
+ `routeReviewers` combines the highest-precedence CODEOWNERS file (with last matching rule semantics), active annotation owners, architecture-policy review rules, and bounded Git author history. Every suggestion keeps source fingerprints, paths and CODEOWNERS lines, confidence, and `availabilityInferred: false`. Historical authorship is low-confidence routing evidence only; FixMap never infers current employment or availability.
65
+
66
+ The Node entry point exports `buildSandboxInvocation` and `runSandbox` for explicitly consented execution of one exact declared command. Images must already exist locally and be pinned by SHA-256 digest. Docker runs in the local default context with pulls disabled, network off by default, source and root filesystem read-only, non-root user, dropped capabilities, no-new-privileges, IPC isolation, bounded tmpfs/CPU/memory/PIDs/time/output, and no inherited container environment. Results distinguish pass, fail, timeout, crash/output-limit, and unavailable; browser builds do not expose the Node/Docker runner.
67
+
68
+ Historical CI evidence is normalized by `validateTestHistoryBundle`, classified by `analyzeTestReliability`, and joined to declared `TestRoute` paths by `assessReliableCoverage`. Same-commit and same-environment disagreement is kept distinct from failures across code revisions; skips, quarantine, feature gates, and newest failures stay explicit. Reliable-running status requires at least five clean passes across two commits and every test identity sharing a declared path to qualify. The result retains exact external provenance and never claims test correctness or future stability.
69
+
70
+ `selectCIMatrix` chooses among caller-declared CI jobs without inventing commands or claiming that a job exercises an environment. OS, runtime, database, browser, feature-flag, and deployment requirements retain affected paths and exact repository/history/policy/runtime evidence; each candidate needs separate evidence for every coverage claim. Deterministic greedy set cover reduces the declared matrix, preserves all justifications, and reports uncovered requirements, omitted candidates, and `minimalityClaimed: false`.
71
+
72
+ `proposeCharacterizationTests` turns redaction-reviewed sandbox, trace, CI, or manual observations into deterministic structured arrange/act/assert drafts. Each proposal retains source and observation provenance, distinguishes a single observation from repeated multi-environment behavior, and says it preserves what was observed rather than what is correct. Drafts always require review and explicitly authorize neither execution nor commit; `renderCharacterizationProposalMarkdown` makes those boundaries visible in review output.
73
+
74
+ `mapRuntimeEvidence` normalizes redaction-reviewed OpenTelemetry/APM trace and Speedscope/pprof profile evidence onto exact repository file identities. A mapping requires both an explicit repository ID and repository-relative code path; names and symbols are never identity guesses. Span latency stays separate from profile self-sample share, all unmapped records retain their reason, and the output explicitly makes no CPU-time, wall-clock-time, or causal-impact claim.
75
+
76
+ `rankIncidentSuspects` combines bounded deployment timing, exact changed-file revisions, eligible error locations, mapped runtime locations, and repository-scoped impact links for regression triage. Each transparent rule contributes at most once per suspect so exporter volume cannot inflate rank; observations and inferences stay labeled with all evidence fingerprints and references. Old/future deployments and unresolved runtime records remain visible, and every result hard-codes that causality is not established.
77
+
78
+ Editor integrations share `createEditorProtocolSnapshot` and `handleEditorProtocolRequest` rather than reinterpreting reports independently. The v1 snapshot is a deep-frozen, content-fingerprinted projection of one explicit `reportVersion: 1`; local-only capabilities, plan, file, and annotation methods return stable errors and repeat the snapshot fingerprint. File views join context, impact, tests, annotations, authored decisions, policy, and clearly labeled repository risks without source upload or mutation.
79
+
80
+ `answerFixMapQuestion` provides a deterministic no-model path for structural plan, impact, test, risk, and authored-rationale questions using a bounded `buildAskEvidence` pack. An optional provider sees report evidence rather than source content, must cite only supplied IDs and expose unknowns, and falls back safely on invalid or failed output. Remote providers require explicit consent before receiving evidence; provider locality remains a caller-declared claim, and model text is never marked independently verified.
81
+
82
+ `draftReverseDocumentation` produces pure, review-only module or architecture Markdown from exact repository file fingerprints, an exact architecture snapshot, and validated authored decisions. Observations, coupling-based inferences, unknowns, and provenance are separate sections. Drafts authorize neither writes nor overwrites, and an existing requested destination is explicitly marked occupied rather than replaced.
83
+
84
+ Enterprise foundations use `authorizeEnterpriseAction`, SHA-256-linked `createEnterpriseAuditEvent`/`verifyEnterpriseAuditChain`, and `assessEnterpriseRetention`. Authorization is same-tenant, exact-grant, default-deny and treats host authentication as an unverified attestation. Audit events bind decisions and outcomes but still need an externally anchored or signed chain head. Retention only marks records eligible; legal holds win and automatic deletion is always false.
85
+
86
+ Verify includes a structured impact narrative: each sentence is labeled as an observation or inference and carries machine-readable evidence for changed files, structural or historical impact, routed tests, risk rules, annotations, decision records, and architecture policy. Markdown explains the risk; JSON preserves the proof.
37
87
 
38
88
  JSON reports use `reportVersion: 1`. Additive fields and diagnostic codes may appear within that version; consumers should ignore unknown fields and use diagnostic severity as the stable fallback.
39
89
 
@@ -0,0 +1,5 @@
1
+ import { type AnnotationStore } from "./annotations.js";
2
+ /** Read a repository-local store without creating one. */
3
+ export declare function readAnnotationStore(repoRoot: string): Promise<AnnotationStore>;
4
+ /** Apply one validated mutation under the shared cross-process store lock. */
5
+ export declare function updateAnnotationStore(repoRoot: string, update: (store: AnnotationStore) => AnnotationStore | Promise<AnnotationStore>): Promise<AnnotationStore>;
@@ -0,0 +1,117 @@
1
+ import { mkdir, open, readFile, realpath, rename, rm, stat, lstat } from "node:fs/promises";
2
+ import { resolve } from "node:path";
3
+ import { randomUUID } from "node:crypto";
4
+ import { emptyAnnotationStore, validateAnnotationStore } from "./annotations.js";
5
+ /** Read a repository-local store without creating one. */
6
+ export async function readAnnotationStore(repoRoot) {
7
+ return readStore(await annotationRoot(repoRoot));
8
+ }
9
+ /** Apply one validated mutation under the shared cross-process store lock. */
10
+ export async function updateAnnotationStore(repoRoot, update) {
11
+ const root = await annotationRoot(repoRoot);
12
+ return withStoreLock(root, async () => {
13
+ const updated = validateAnnotationStore(await update(await readStore(root)));
14
+ await writeStore(root, updated);
15
+ return updated;
16
+ });
17
+ }
18
+ async function annotationRoot(path) {
19
+ const root = await realpath(path);
20
+ if (!(await stat(root)).isDirectory())
21
+ throw new Error("Annotation repository must be a directory.");
22
+ return root;
23
+ }
24
+ async function readStore(repoRoot) {
25
+ await assertStoreBoundary(repoRoot);
26
+ const path = resolve(repoRoot, ".fixmap", "annotations.json");
27
+ try {
28
+ return validateAnnotationStore(JSON.parse(await readFile(path, "utf8")));
29
+ }
30
+ catch (error) {
31
+ if (isNodeError(error, "ENOENT"))
32
+ return emptyAnnotationStore();
33
+ if (error instanceof SyntaxError)
34
+ throw new Error(`${path} is not valid JSON; repair it before adding annotations.`);
35
+ throw error;
36
+ }
37
+ }
38
+ async function writeStore(repoRoot, store) {
39
+ const directory = resolve(repoRoot, ".fixmap");
40
+ await mkdir(directory, { recursive: true });
41
+ await assertStoreBoundary(repoRoot);
42
+ const target = resolve(directory, "annotations.json");
43
+ const temporary = resolve(directory, `.annotations.${process.pid}.${randomUUID()}.tmp`);
44
+ const handle = await open(temporary, "wx", 0o600);
45
+ try {
46
+ await handle.writeFile(`${JSON.stringify(validateAnnotationStore(store), null, 2)}\n`, "utf8");
47
+ await handle.sync();
48
+ }
49
+ finally {
50
+ await handle.close();
51
+ }
52
+ try {
53
+ await rename(temporary, target);
54
+ }
55
+ catch (error) {
56
+ await rm(temporary, { force: true });
57
+ throw error;
58
+ }
59
+ }
60
+ async function withStoreLock(repoRoot, operation) {
61
+ await assertStoreBoundary(repoRoot);
62
+ const directory = resolve(repoRoot, ".fixmap");
63
+ await mkdir(directory, { recursive: true });
64
+ await assertStoreBoundary(repoRoot);
65
+ const lockPath = resolve(directory, "annotations.lock");
66
+ let handle;
67
+ try {
68
+ handle = await open(lockPath, "wx", 0o600);
69
+ }
70
+ catch (error) {
71
+ if (!isNodeError(error, "EEXIST"))
72
+ throw error;
73
+ // Age cannot prove that a writer has stopped (for example after suspension).
74
+ // Never steal a lock: doing so permits overlapping read-modify-write cycles.
75
+ throw new Error("Another FixMap annotation update is in progress or left a lock. Retry after it finishes; if interrupted, confirm no annotation writer is running before manually removing .fixmap/annotations.lock.");
76
+ }
77
+ try {
78
+ await handle.writeFile(`${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`, "utf8");
79
+ await handle.sync();
80
+ return await operation();
81
+ }
82
+ finally {
83
+ try {
84
+ await handle.close();
85
+ }
86
+ finally {
87
+ await rm(lockPath, { force: true });
88
+ }
89
+ }
90
+ }
91
+ async function assertStoreBoundary(repoRoot) {
92
+ const directory = resolve(repoRoot, ".fixmap");
93
+ const directoryInfo = await lstat(directory).catch((error) => {
94
+ if (isNodeError(error, "ENOENT"))
95
+ return undefined;
96
+ throw error;
97
+ });
98
+ if (!directoryInfo)
99
+ return;
100
+ if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink() || await realpath(directory) !== directory) {
101
+ throw new Error("Annotation store directory must be a real repository-local .fixmap directory, not a link or junction.");
102
+ }
103
+ for (const name of ["annotations.json", "annotations.lock"]) {
104
+ const info = await lstat(resolve(directory, name)).catch((error) => {
105
+ if (isNodeError(error, "ENOENT"))
106
+ return undefined;
107
+ throw error;
108
+ });
109
+ if (info && (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)) {
110
+ throw new Error("Annotation store and lock must be regular, unlinked repository-local files.");
111
+ }
112
+ }
113
+ }
114
+ function isNodeError(error, code) {
115
+ return error instanceof Error && "code" in error && error.code === code;
116
+ }
117
+ //# sourceMappingURL=annotation-store.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"annotation-store.js","sourceRoot":"","sources":["../src/annotation-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAwB,MAAM,kBAAkB,CAAC;AAEvG,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACxD,OAAO,SAAS,CAAC,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgB,EAChB,MAA8E;IAE9E,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,aAAa,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QACpC,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,MAAM,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7E,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACrG,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,QAAgB;IACvC,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,oBAAoB,EAAE,CAAC;QAChE,IAAI,KAAK,YAAY,WAAW;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,0DAA0D,CAAC,CAAC;QACrH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,QAAgB,EAAE,KAAsB;IAChE,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,gBAAgB,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IACxF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAClD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,uBAAuB,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC/F,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAAI,QAAgB,EAAE,SAA2B;IAC3E,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IACxD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,MAAM,KAAK,CAAC;QAC/C,6EAA6E;QAC7E,6EAA6E;QAC7E,MAAM,IAAI,KAAK,CAAC,qMAAqM,CAAC,CAAC;IACzN,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACjD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACpE,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QACnD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,aAAa;QAAE,OAAO;IAC3B,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,IAAI,aAAa,CAAC,cAAc,EAAE,IAAI,MAAM,QAAQ,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;QAC9G,MAAM,IAAI,KAAK,CAAC,uGAAuG,CAAC,CAAC;IAC3H,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YAC1E,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;gBAAE,OAAO,SAAS,CAAC;YACnD,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,cAAc,EAAE,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;AACH,CAAC;AAGD,SAAS,WAAW,CAAC,KAAc,EAAE,IAAY;IAC/C,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAK,KAA+B,CAAC,IAAI,KAAK,IAAI,CAAC;AACrG,CAAC"}
@@ -0,0 +1,57 @@
1
+ import type { RepoMap } from "./types.js";
2
+ export type AnnotationScope = {
3
+ kind: "file";
4
+ path: string;
5
+ } | {
6
+ kind: "symbol";
7
+ path: string;
8
+ symbol: string;
9
+ } | {
10
+ kind: "service";
11
+ name: string;
12
+ } | {
13
+ kind: "contract";
14
+ name: string;
15
+ path?: string;
16
+ };
17
+ export type FixMapAnnotation = {
18
+ id: string;
19
+ scope: AnnotationScope;
20
+ note: string;
21
+ owner?: string;
22
+ createdAt: string;
23
+ expiresAt?: string;
24
+ sourceRevision?: string;
25
+ };
26
+ export type AnnotationStore = {
27
+ annotationStoreVersion: 1;
28
+ annotations: FixMapAnnotation[];
29
+ };
30
+ export type AnnotationAssessment = {
31
+ annotation: FixMapAnnotation;
32
+ status: "active" | "expired" | "missing-target" | "renamed-target";
33
+ message: string;
34
+ suggestedPath?: string;
35
+ };
36
+ export type AnnotationRename = {
37
+ from: string;
38
+ to: string;
39
+ };
40
+ export type CreateAnnotationInput = {
41
+ scope: AnnotationScope;
42
+ note: string;
43
+ owner?: string;
44
+ createdAt: string;
45
+ expiresAt?: string;
46
+ sourceRevision?: string;
47
+ };
48
+ export declare function emptyAnnotationStore(): AnnotationStore;
49
+ export declare function createAnnotation(input: CreateAnnotationInput): FixMapAnnotation;
50
+ export declare function addAnnotation(store: AnnotationStore, annotation: FixMapAnnotation): AnnotationStore;
51
+ export declare function removeAnnotation(store: AnnotationStore, id: string): AnnotationStore;
52
+ export declare function validateAnnotationStore(candidate: unknown): AnnotationStore;
53
+ export declare function assessAnnotations(store: AnnotationStore, repo: Pick<RepoMap, "files">, options: {
54
+ now: string;
55
+ renames?: readonly AnnotationRename[];
56
+ }): AnnotationAssessment[];
57
+ export declare function annotationsForPath(assessments: readonly AnnotationAssessment[], path: string): AnnotationAssessment[];
@@ -0,0 +1,221 @@
1
+ const ID = /^annotation:[a-f0-9]{16}$/;
2
+ const REVISION = /^[A-Za-z0-9][A-Za-z0-9._/@:+-]{0,255}$/;
3
+ export function emptyAnnotationStore() {
4
+ return { annotationStoreVersion: 1, annotations: [] };
5
+ }
6
+ export function createAnnotation(input) {
7
+ const normalized = normalizeAnnotationInput(input);
8
+ return {
9
+ id: `annotation:${stableHash(canonicalize(normalized))}`,
10
+ ...normalized
11
+ };
12
+ }
13
+ export function addAnnotation(store, annotation) {
14
+ const validated = validateAnnotationStore(store);
15
+ validateAnnotation(annotation);
16
+ if (validated.annotations.some((entry) => entry.id === annotation.id)) {
17
+ throw new Error(`Annotation ${annotation.id} already exists.`);
18
+ }
19
+ const semanticDuplicate = validated.annotations.find((entry) => canonicalize(entry.scope) === canonicalize(annotation.scope) && entry.note === annotation.note && entry.expiresAt === annotation.expiresAt);
20
+ if (semanticDuplicate)
21
+ throw new Error(`An equivalent annotation already exists as ${semanticDuplicate.id}.`);
22
+ return validateAnnotationStore({
23
+ annotationStoreVersion: 1,
24
+ annotations: [...validated.annotations, copyAnnotation(annotation)]
25
+ });
26
+ }
27
+ export function removeAnnotation(store, id) {
28
+ const validated = validateAnnotationStore(store);
29
+ if (!ID.test(id))
30
+ throw new Error(`Invalid annotation ID: ${id}`);
31
+ const annotations = validated.annotations.filter((annotation) => annotation.id !== id);
32
+ if (annotations.length === validated.annotations.length)
33
+ throw new Error(`Annotation ${id} does not exist.`);
34
+ return { annotationStoreVersion: 1, annotations };
35
+ }
36
+ export function validateAnnotationStore(candidate) {
37
+ if (!isRecord(candidate) || candidate.annotationStoreVersion !== 1 || !Array.isArray(candidate.annotations)) {
38
+ throw new Error("Unsupported or invalid FixMap annotation store. Expected annotationStoreVersion 1.");
39
+ }
40
+ const ids = new Set();
41
+ const annotations = candidate.annotations.map((value) => {
42
+ validateAnnotation(value);
43
+ if (ids.has(value.id))
44
+ throw new Error(`Duplicate annotation ID: ${value.id}`);
45
+ ids.add(value.id);
46
+ return copyAnnotation(value);
47
+ }).sort((a, b) => scopeKey(a.scope).localeCompare(scopeKey(b.scope)) || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
48
+ return { annotationStoreVersion: 1, annotations };
49
+ }
50
+ export function assessAnnotations(store, repo, options) {
51
+ const validated = validateAnnotationStore(store);
52
+ const now = parseTimestamp(options.now, "assessment time");
53
+ const paths = new Set(repo.files.map((file) => normalizePath(file.path)));
54
+ const renames = new Map((options.renames ?? []).map((rename) => {
55
+ const from = validateRelativePath(rename.from, "rename source");
56
+ const to = validateRelativePath(rename.to, "rename target");
57
+ return [from, to];
58
+ }));
59
+ return validated.annotations.map((annotation) => {
60
+ if (annotation.expiresAt && parseTimestamp(annotation.expiresAt, "annotation expiry") <= now) {
61
+ return { annotation, status: "expired", message: `Annotation ${annotation.id} expired at ${annotation.expiresAt}.` };
62
+ }
63
+ const targetPath = annotation.scope.kind === "file" || annotation.scope.kind === "symbol" ||
64
+ (annotation.scope.kind === "contract" && annotation.scope.path)
65
+ ? annotation.scope.path
66
+ : undefined;
67
+ if (targetPath) {
68
+ const renamedTo = renames.get(targetPath);
69
+ if (renamedTo) {
70
+ return {
71
+ annotation,
72
+ status: "renamed-target",
73
+ message: `Annotation target ${targetPath} was renamed to ${renamedTo}; review and update the annotation scope.`,
74
+ suggestedPath: renamedTo
75
+ };
76
+ }
77
+ if (!paths.has(targetPath)) {
78
+ return { annotation, status: "missing-target", message: `Annotation target ${targetPath} is not present in this repository snapshot.` };
79
+ }
80
+ }
81
+ return { annotation, status: "active", message: `Annotation ${annotation.id} is active.` };
82
+ });
83
+ }
84
+ export function annotationsForPath(assessments, path) {
85
+ const normalized = validateRelativePath(path, "query path");
86
+ return assessments.filter((assessment) => {
87
+ if (assessment.status === "renamed-target" && assessment.suggestedPath === normalized)
88
+ return true;
89
+ const scope = assessment.annotation.scope;
90
+ return (scope.kind === "file" || scope.kind === "symbol") && scope.path === normalized ||
91
+ scope.kind === "contract" && scope.path === normalized;
92
+ });
93
+ }
94
+ function normalizeAnnotationInput(input) {
95
+ const scope = validateScope(input.scope);
96
+ const note = normalizeText(input.note, "annotation note", 2_000);
97
+ const createdAt = new Date(parseTimestamp(input.createdAt, "annotation creation time")).toISOString();
98
+ const expiresAt = input.expiresAt
99
+ ? new Date(parseTimestamp(input.expiresAt, "annotation expiry")).toISOString()
100
+ : undefined;
101
+ if (expiresAt && Date.parse(expiresAt) <= Date.parse(createdAt))
102
+ throw new Error("Annotation expiry must be after its creation time.");
103
+ const owner = input.owner ? normalizeText(input.owner, "annotation owner", 200) : undefined;
104
+ const sourceRevision = input.sourceRevision?.trim();
105
+ if (sourceRevision && !REVISION.test(sourceRevision))
106
+ throw new Error(`Invalid annotation source revision: ${sourceRevision}`);
107
+ return {
108
+ scope,
109
+ note,
110
+ ...(owner ? { owner } : {}),
111
+ createdAt,
112
+ ...(expiresAt ? { expiresAt } : {}),
113
+ ...(sourceRevision ? { sourceRevision } : {})
114
+ };
115
+ }
116
+ function validateAnnotation(candidate) {
117
+ if (!isRecord(candidate) || typeof candidate.id !== "string" || !ID.test(candidate.id) ||
118
+ typeof candidate.note !== "string" || typeof candidate.createdAt !== "string") {
119
+ throw new Error("Invalid FixMap annotation record.");
120
+ }
121
+ const normalized = normalizeAnnotationInput({
122
+ scope: candidate.scope,
123
+ note: candidate.note,
124
+ ...(typeof candidate.owner === "string" ? { owner: candidate.owner } : {}),
125
+ createdAt: candidate.createdAt,
126
+ ...(typeof candidate.expiresAt === "string" ? { expiresAt: candidate.expiresAt } : {}),
127
+ ...(typeof candidate.sourceRevision === "string" ? { sourceRevision: candidate.sourceRevision } : {})
128
+ });
129
+ if (candidate.note !== normalized.note || candidate.createdAt !== normalized.createdAt ||
130
+ candidate.owner !== normalized.owner || candidate.expiresAt !== normalized.expiresAt ||
131
+ candidate.sourceRevision !== normalized.sourceRevision || canonicalize(candidate.scope) !== canonicalize(normalized.scope)) {
132
+ throw new Error(`Annotation ${candidate.id} is not canonically encoded.`);
133
+ }
134
+ const expectedId = `annotation:${stableHash(canonicalize(normalized))}`;
135
+ if (candidate.id !== expectedId)
136
+ throw new Error(`Annotation ${candidate.id} does not match its content identity.`);
137
+ }
138
+ function validateScope(candidate) {
139
+ if (!isRecord(candidate) || typeof candidate.kind !== "string")
140
+ throw new Error("Annotation scope is invalid.");
141
+ if (candidate.kind === "file") {
142
+ return { kind: "file", path: validateRelativePath(String(candidate.path ?? ""), "annotation file") };
143
+ }
144
+ if (candidate.kind === "symbol") {
145
+ return {
146
+ kind: "symbol",
147
+ path: validateRelativePath(String(candidate.path ?? ""), "annotation symbol file"),
148
+ symbol: normalizeText(String(candidate.symbol ?? ""), "annotation symbol", 300)
149
+ };
150
+ }
151
+ if (candidate.kind === "service") {
152
+ return { kind: "service", name: normalizeText(String(candidate.name ?? ""), "annotation service", 300) };
153
+ }
154
+ if (candidate.kind === "contract") {
155
+ const path = candidate.path === undefined ? undefined : validateRelativePath(String(candidate.path), "annotation contract file");
156
+ return {
157
+ kind: "contract",
158
+ name: normalizeText(String(candidate.name ?? ""), "annotation contract", 300),
159
+ ...(path ? { path } : {})
160
+ };
161
+ }
162
+ throw new Error("Unsupported annotation scope.");
163
+ }
164
+ function validateRelativePath(value, label) {
165
+ const normalized = normalizePath(value.trim());
166
+ if (!normalized || /^(?:[\\/]|[A-Za-z]:)/.test(value) || value.includes("\0") ||
167
+ normalized.split("/").some((part) => !part || part === "." || part === "..")) {
168
+ throw new Error(`Invalid ${label}: ${value}`);
169
+ }
170
+ return normalized;
171
+ }
172
+ function normalizePath(path) {
173
+ return path.replace(/\\/g, "/");
174
+ }
175
+ function normalizeText(value, label, maximum) {
176
+ const normalized = value.replace(/\r\n/g, "\n").trim();
177
+ if (!normalized || normalized.length > maximum || normalized.includes("\0"))
178
+ throw new Error(`Invalid ${label}.`);
179
+ return normalized;
180
+ }
181
+ function parseTimestamp(value, label) {
182
+ const parsed = Date.parse(value);
183
+ if (!Number.isFinite(parsed))
184
+ throw new Error(`Invalid ${label}: ${value}`);
185
+ return parsed;
186
+ }
187
+ function scopeKey(scope) {
188
+ if (scope.kind === "file")
189
+ return `file:${scope.path}`;
190
+ if (scope.kind === "symbol")
191
+ return `symbol:${scope.path}:${scope.symbol}`;
192
+ if (scope.kind === "service")
193
+ return `service:${scope.name}`;
194
+ return `contract:${scope.path ?? ""}:${scope.name}`;
195
+ }
196
+ function copyAnnotation(annotation) {
197
+ return { ...annotation, scope: { ...annotation.scope } };
198
+ }
199
+ function canonicalize(value) {
200
+ if (Array.isArray(value))
201
+ return `[${value.map(canonicalize).join(",")}]`;
202
+ if (value && typeof value === "object") {
203
+ return `{${Object.entries(value)
204
+ .filter(([, entry]) => entry !== undefined)
205
+ .sort(([left], [right]) => left.localeCompare(right))
206
+ .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalize(entry)}`).join(",")}}`;
207
+ }
208
+ return JSON.stringify(value);
209
+ }
210
+ function isRecord(value) {
211
+ return typeof value === "object" && value !== null && !Array.isArray(value);
212
+ }
213
+ function stableHash(value) {
214
+ let hash = 0xcbf29ce484222325n;
215
+ for (const byte of new TextEncoder().encode(value)) {
216
+ hash ^= BigInt(byte);
217
+ hash = BigInt.asUintN(64, hash * 0x100000001b3n);
218
+ }
219
+ return hash.toString(16).padStart(16, "0");
220
+ }
221
+ //# sourceMappingURL=annotations.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAyCA,MAAM,EAAE,GAAG,2BAA2B,CAAC;AACvC,MAAM,QAAQ,GAAG,wCAAwC,CAAC;AAE1D,MAAM,UAAU,oBAAoB;IAClC,OAAO,EAAE,sBAAsB,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,UAAU,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACnD,OAAO;QACL,EAAE,EAAE,cAAc,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,EAAE;QACxD,GAAG,UAAU;KACd,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAsB,EAAE,UAA4B;IAChF,MAAM,SAAS,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IACjD,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/B,IAAI,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,cAAc,UAAU,CAAC,EAAE,kBAAkB,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAC7D,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,SAAS,KAAK,UAAU,CAAC,SAAS,CAC3I,CAAC;IACF,IAAI,iBAAiB;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,iBAAiB,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9G,OAAO,uBAAuB,CAAC;QAC7B,sBAAsB,EAAE,CAAC;QACzB,WAAW,EAAE,CAAC,GAAG,SAAS,CAAC,WAAW,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;KACpE,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAsB,EAAE,EAAU;IACjE,MAAM,SAAS,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACvF,IAAI,WAAW,CAAC,MAAM,KAAK,SAAS,CAAC,WAAW,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IAC7G,OAAO,EAAE,sBAAsB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,SAAkB;IACxD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,sBAAsB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5G,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC;IACxG,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACtD,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/E,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5I,OAAO,EAAE,sBAAsB,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAsB,EACtB,IAA4B,EAC5B,OAA+D;IAE/D,MAAM,SAAS,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC7D,MAAM,IAAI,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QAChE,MAAM,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC,CAAC;IACJ,OAAO,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAwB,EAAE;QACpE,IAAI,UAAU,CAAC,SAAS,IAAI,cAAc,CAAC,UAAU,CAAC,SAAS,EAAE,mBAAmB,CAAC,IAAI,GAAG,EAAE,CAAC;YAC7F,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,UAAU,CAAC,EAAE,eAAe,UAAU,CAAC,SAAS,GAAG,EAAE,CAAC;QACvH,CAAC;QACD,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YACvF,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;YAC/D,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI;YACvB,CAAC,CAAC,SAAS,CAAC;QACd,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC1C,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO;oBACL,UAAU;oBACV,MAAM,EAAE,gBAAgB;oBACxB,OAAO,EAAE,qBAAqB,UAAU,mBAAmB,SAAS,2CAA2C;oBAC/G,aAAa,EAAE,SAAS;iBACzB,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,qBAAqB,UAAU,8CAA8C,EAAE,CAAC;YAC1I,CAAC;QACH,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7F,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,WAA4C,EAAE,IAAY;IAC3F,MAAM,UAAU,GAAG,oBAAoB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC5D,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE;QACvC,IAAI,UAAU,CAAC,MAAM,KAAK,gBAAgB,IAAI,UAAU,CAAC,aAAa,KAAK,UAAU;YAAE,OAAO,IAAI,CAAC;QACnG,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;QAC1C,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YACpF,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,wBAAwB,CAAC,KAA4B;IAC5D,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,CAAC,CAAC;IACjE,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,0BAA0B,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACtG,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS;QAC/B,CAAC,CAAC,IAAI,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC,CAAC,WAAW,EAAE;QAC9E,CAAC,CAAC,SAAS,CAAC;IACd,IAAI,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACvI,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5F,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IACpD,IAAI,cAAc,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,cAAc,EAAE,CAAC,CAAC;IAC/H,OAAO;QACL,KAAK;QACL,IAAI;QACJ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,SAAS;QACT,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAkB;IAC5C,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACpF,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,UAAU,GAAG,wBAAwB,CAAC;QAC1C,KAAK,EAAE,SAAS,CAAC,KAAwB;QACzC,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,GAAG,CAAC,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,GAAG,CAAC,OAAO,SAAS,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtF,GAAG,CAAC,OAAO,SAAS,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,SAAS,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtG,CAAC,CAAC;IACH,IAAI,SAAS,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,IAAI,SAAS,CAAC,SAAS,KAAK,UAAU,CAAC,SAAS;QACpF,SAAS,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK,IAAI,SAAS,CAAC,SAAS,KAAK,UAAU,CAAC,SAAS;QACpF,SAAS,CAAC,cAAc,KAAK,UAAU,CAAC,cAAc,IAAI,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7H,MAAM,IAAI,KAAK,CAAC,cAAc,SAAS,CAAC,EAAE,8BAA8B,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,UAAU,GAAG,cAAc,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;IACxE,IAAI,SAAS,CAAC,EAAE,KAAK,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,cAAc,SAAS,CAAC,EAAE,uCAAuC,CAAC,CAAC;AACtH,CAAC;AAED,SAAS,aAAa,CAAC,SAA0B;IAC/C,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAChH,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,iBAAiB,CAAC,EAAE,CAAC;IACvG,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,wBAAwB,CAAC;YAClF,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,mBAAmB,EAAE,GAAG,CAAC;SAChF,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,oBAAoB,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3G,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,0BAA0B,CAAC,CAAC;QACjI,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,qBAAqB,EAAE,GAAG,CAAC;YAC7E,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1B,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa,EAAE,KAAa;IACxD,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,IAAI,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC3E,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,KAAK,KAAK,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,aAAa,CAAC,KAAa,EAAE,KAAa,EAAE,OAAe;IAClE,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,GAAG,CAAC,CAAC;IAClH,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,WAAW,KAAK,KAAK,KAAK,EAAE,CAAC,CAAC;IAC5E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,QAAQ,CAAC,KAAsB;IACtC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,UAAU,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;IAC3E,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7D,OAAO,YAAY,KAAK,CAAC,IAAI,IAAI,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC;AAED,SAAS,cAAc,CAAC,UAA4B;IAClD,OAAO,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC1E,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aACxD,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;aAC1C,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;aACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACzF,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,IAAI,IAAI,GAAG,mBAAmB,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,GAAG,cAAc,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC"}
@@ -0,0 +1,33 @@
1
+ import type { ArchitectureDrift, ArchitectureSnapshot } from "./architecture.js";
2
+ import type { RepoMap } from "./types.js";
3
+ export type HistoricalRepoMap = {
4
+ requestedRef: string;
5
+ commit: string;
6
+ repo: RepoMap;
7
+ };
8
+ export type HistoricalArchitectureSnapshot = {
9
+ requestedRef: string;
10
+ commit: string;
11
+ snapshot: ArchitectureSnapshot;
12
+ };
13
+ /** Read a committed repository state through Git objects without checking it out. */
14
+ export declare function scanRepoAtRef(input: {
15
+ repoRoot: string;
16
+ ref: string;
17
+ }): Promise<HistoricalRepoMap>;
18
+ export declare function buildArchitectureSnapshotAtRef(input: {
19
+ repoRoot: string;
20
+ ref: string;
21
+ applyRepositoryPolicy?: boolean;
22
+ }): Promise<HistoricalArchitectureSnapshot>;
23
+ export declare function compareArchitectureRefs(input: {
24
+ repoRoot: string;
25
+ fromRef: string;
26
+ toRef: string;
27
+ applyRepositoryPolicy?: boolean;
28
+ couplingDelta?: number;
29
+ }): Promise<{
30
+ from: HistoricalArchitectureSnapshot;
31
+ to: HistoricalArchitectureSnapshot;
32
+ drift: ArchitectureDrift;
33
+ }>;