rea-agents 6.0.0 → 6.1.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 (343) hide show
  1. package/README.md +23 -17
  2. package/bridge/android/ReaJadxBridge.java +14 -5
  3. package/bridge/ghidra/ReaGhidraBridge.java +173 -47
  4. package/bridge/hopper_bridge.py +310 -128
  5. package/bridge/mitmproxy/capture.py +0 -2
  6. package/bridge/native/rea_lldb_tracer.py +630 -94
  7. package/bridge/process/ProcessRunTokenReader.swift +39 -5
  8. package/bridge/pwntools/recorded_crash_impl.py +4 -0
  9. package/dist/android/JadxConfiguration.js +196 -33
  10. package/dist/android/JadxMcpTransport.js +4 -0
  11. package/dist/android/JadxProtocol.js +6 -0
  12. package/dist/android/JadxProvider.js +19 -2
  13. package/dist/android/JadxSession.js +23 -4
  14. package/dist/application/AnalysisContextQueries.js +8 -35
  15. package/dist/application/AnalysisDocument.js +32 -0
  16. package/dist/application/AppBundleExecutable.js +67 -21
  17. package/dist/application/CallPathTracing.js +19 -3
  18. package/dist/application/CapabilityInventory.js +6 -3
  19. package/dist/application/ClientConfigurationDocument.js +871 -6
  20. package/dist/application/ClientRegistrationIdentity.js +26 -5
  21. package/dist/application/ClientRegistrationStatus.js +29 -14
  22. package/dist/application/DirectAnalysis.js +27 -37
  23. package/dist/application/Doctor.js +4 -2
  24. package/dist/application/DoctorScope.js +25 -13
  25. package/dist/application/EnhancedLiteralTracing.js +22 -25
  26. package/dist/application/EnhancedTools.js +13 -11
  27. package/dist/application/EvidenceBundleFiles.js +23 -11
  28. package/dist/application/FunctionAnalysisEvidence.js +2 -3
  29. package/dist/application/InventoryProjectionEvidence.js +4 -3
  30. package/dist/application/InvestigationProviders.js +3 -2
  31. package/dist/application/JsonFiles.js +50 -28
  32. package/dist/application/ProcedureAddressResolution.js +11 -0
  33. package/dist/application/ReconstructionCoverageService.js +7 -4
  34. package/dist/application/ReconstructionObligationLedgerService.js +4 -3
  35. package/dist/application/Setup.js +13 -1
  36. package/dist/application/SetupClientConfiguration.js +10 -15
  37. package/dist/application/SetupHost.js +5 -2
  38. package/dist/application/SetupPlan.js +5 -3
  39. package/dist/application/SupportedClients.js +34 -1
  40. package/dist/application/Uninstall.js +4 -3
  41. package/dist/application/Update.js +18 -3
  42. package/dist/application/UpdateRuntime.js +46 -25
  43. package/dist/application/WebModuleTraceService.js +4 -2
  44. package/dist/application/WebNetworkCaptureService.js +4 -2
  45. package/dist/application/WebRuntimeService.js +5 -3
  46. package/dist/application/WebScriptExportService.js +2 -2
  47. package/dist/application/WebSourceLocationService.js +4 -2
  48. package/dist/application/WorkflowEvidence.js +82 -0
  49. package/dist/application/binary/AnalysisProviderEvaluation.js +21 -5
  50. package/dist/application/binary/AnalysisProviderRegistry.js +2 -0
  51. package/dist/application/binary/AnalysisSnapshotCache.js +3 -6
  52. package/dist/application/binary/BinarySession.js +95 -68
  53. package/dist/application/binary/BinarySessionOpen.js +3 -3
  54. package/dist/application/binary/BinarySessionRecords.js +25 -3
  55. package/dist/application/binary/BinarySessionStatus.js +17 -1
  56. package/dist/application/binary/CompositeProvider.js +13 -0
  57. package/dist/application/binary/LazyAnalysisProvider.js +3 -0
  58. package/dist/application/binaryDiagnostics/BinaryLayoutService.js +4 -2
  59. package/dist/application/binaryDiagnostics/RecordedCrashService.js +4 -2
  60. package/dist/application/evm/EvmInterfaceService.js +4 -2
  61. package/dist/application/investigation/EvidenceLedger.js +21 -7
  62. package/dist/application/investigation/InvestigationRecords.js +8 -0
  63. package/dist/application/javascript/JavaScriptAnalysisControl.js +34 -0
  64. package/dist/application/javascript/JavaScriptApplicationEvidence.js +24 -3
  65. package/dist/application/javascript/JavaScriptApplicationEvidenceGraph.js +19 -2
  66. package/dist/application/javascript/JavaScriptApplicationService.js +22 -15
  67. package/dist/application/javascript/JavaScriptApplicationWorkflowService.js +5 -5
  68. package/dist/application/javascript/JavaScriptArtifactAnalysis.js +5 -4
  69. package/dist/application/javascript/JavaScriptArtifactGraphBuilder.js +39 -7
  70. package/dist/application/javascript/JavaScriptArtifactPathResolution.js +6 -3
  71. package/dist/application/javascript/JavaScriptArtifactReconstruction.js +11 -3
  72. package/dist/application/javascript/JavaScriptModuleRelationships.js +37 -8
  73. package/dist/application/javascript/JavaScriptRecoveryService.js +4 -2
  74. package/dist/application/javascript/JavaScriptRuntimeObservationService.js +3 -1
  75. package/dist/application/javascript/JavaScriptRuntimeReconciliationService.js +3 -3
  76. package/dist/application/javascript/JavaScriptSemanticGraphBuilder.js +63 -61
  77. package/dist/application/javascript/JavaScriptSemanticGraphValueProjection.js +23 -1
  78. package/dist/application/managed/ManagedApplicationGraphService.js +4 -3
  79. package/dist/application/managed/ManagedMemberComparisonService.js +7 -4
  80. package/dist/application/managed/ManagedNativeVerificationService.js +4 -3
  81. package/dist/application/managed/ManagedReconstructionService.js +4 -3
  82. package/dist/application/process/ProcessCli.js +14 -6
  83. package/dist/application/process/ProcessEvidence.js +4 -3
  84. package/dist/application/workflowInputError.js +18 -0
  85. package/dist/artifacts/ArtifactProvider.js +12 -2
  86. package/dist/artifacts/MachOSliceArtifactReader.js +98 -14
  87. package/dist/artifacts/NativeDmgArtifactReader.js +13 -6
  88. package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js +22 -3
  89. package/dist/artifacts/apple/InterfaceBuilderAnalysis.js +176 -56
  90. package/dist/artifacts/apple/InterfaceBuilderDecodeBudget.js +195 -0
  91. package/dist/artifacts/apple/KeyedArchiveReader.js +36 -22
  92. package/dist/artifacts/apple/MachoLoadCommandReader.js +92 -31
  93. package/dist/artifacts/apple/NibArchive.js +81 -14
  94. package/dist/artifacts/apple/NibViewHierarchy.js +10 -3
  95. package/dist/artifacts/apple/PlistNumberLiterals.js +164 -0
  96. package/dist/artifacts/inventory/ArtifactGraphConstruction.js +13 -8
  97. package/dist/artifacts/inventory/scanCanonical.js +11 -14
  98. package/dist/artifacts/javascript/JavaScriptArtifactFiles.js +6 -2
  99. package/dist/browser/CdpCaptureCompleteness.js +2 -0
  100. package/dist/browser/CdpCaptureEventHandlers.js +76 -11
  101. package/dist/browser/CdpCaptureEventTypes.js +5 -1
  102. package/dist/browser/CdpCaptureEvents.js +25 -0
  103. package/dist/browser/CdpConnection.js +30 -11
  104. package/dist/browser/CdpOptionalCommand.js +2 -3
  105. package/dist/browser/CdpPageCapture.js +23 -1
  106. package/dist/browser/PlaywrightElectronActiveActions.js +32 -23
  107. package/dist/browser/PlaywrightElectronActiveProjection.js +141 -0
  108. package/dist/browser/PlaywrightElectronActiveProvider.js +123 -124
  109. package/dist/browser/WebSourceMapFetcher.js +426 -72
  110. package/dist/browser/assets/LocalWebScriptArtifacts.js +2 -2
  111. package/dist/browser/history/CaptureFailures.js +37 -1
  112. package/dist/browser/history/CaptureRelease.js +5 -0
  113. package/dist/browser/history/HarCaptureAdapter.js +3 -3
  114. package/dist/browser/history/HarJson.js +3 -2
  115. package/dist/browser/history/HistoricalCaptureDecoder.js +4 -2
  116. package/dist/cli/analysisSelector.js +23 -0
  117. package/dist/cli/applicationCommands.js +2 -3
  118. package/dist/cli/coreBinaryCommands.js +70 -12
  119. package/dist/cli/electronCommands.js +7 -6
  120. package/dist/cli/javascriptApplicationAnalysis.js +7 -3
  121. package/dist/cli/jsonOutput.js +4 -99
  122. package/dist/cli/nativeCallCommands.js +2 -3
  123. package/dist/cli/webRuntimeCommands.js +8 -8
  124. package/dist/cli.js +2 -1
  125. package/dist/cliCommandNames.js +0 -1
  126. package/dist/cliJsonInput.js +9 -4
  127. package/dist/config/environment.js +4 -0
  128. package/dist/config/ghidraStartupTimeout.js +17 -0
  129. package/dist/config/mcpResponseBudget.js +22 -0
  130. package/dist/config/parseConfig.js +2 -1
  131. package/dist/contracts/enhancedInputs.js +5 -3
  132. package/dist/contracts/enhancedToolContracts.js +3 -3
  133. package/dist/contracts/hopperMemoryContracts.js +2 -5
  134. package/dist/contracts/javascript/electronToolContracts.js +1 -1
  135. package/dist/contracts/managed/managedToolContracts.js +2 -4
  136. package/dist/contracts/native/nativeToolContracts.js +4 -2
  137. package/dist/contracts/officialToolContracts.js +14 -15
  138. package/dist/contracts/promptContracts.js +3 -3
  139. package/dist/contracts/sessionLifecycleInputs.js +3 -7
  140. package/dist/contracts/sessionStatusContract.js +2 -4
  141. package/dist/contracts/sessionToolContracts.js +4 -6
  142. package/dist/contracts/sessionToolSchemas.js +2 -5
  143. package/dist/contracts/toolContractExamples.js +0 -1
  144. package/dist/contracts/toolContractHelpers.js +4 -1
  145. package/dist/contracts/toolEffects.js +0 -1
  146. package/dist/contracts/toolOutputSchemaGroups.js +28 -27
  147. package/dist/contracts/toolOutputSchemaPrimitives.js +18 -0
  148. package/dist/contracts/toolSchemaMetadata.js +69 -10
  149. package/dist/contracts/webNetworkCaptureToolContracts.js +1 -1
  150. package/dist/domain/analysisErrorBase.js +8 -3
  151. package/dist/domain/analysisErrorCore.js +3 -1
  152. package/dist/domain/analysisErrorPresentation.js +72 -17
  153. package/dist/domain/analysisErrorProjection.js +106 -27
  154. package/dist/domain/android/androidAnalysis.js +2 -4
  155. package/dist/domain/android/androidApplication.js +17 -9
  156. package/dist/domain/apple/appleApplication.js +41 -14
  157. package/dist/domain/apple/dyldEnvironment.js +73 -0
  158. package/dist/domain/apple/dylibResolution.js +120 -9
  159. package/dist/domain/apple/dylibResolutionFindings.js +9 -7
  160. package/dist/domain/apple/interfaceBuilderGraph.js +25 -13
  161. package/dist/domain/apple/interfaceBuilderKeyedArchive.js +13 -3
  162. package/dist/domain/apple/keyedArchive.js +9 -1
  163. package/dist/domain/apple/machoContainer.js +54 -0
  164. package/dist/domain/apple/plistNumbers.js +76 -0
  165. package/dist/domain/artifactIdentity.js +29 -0
  166. package/dist/domain/artifactInventoryEvidence.js +19 -24
  167. package/dist/domain/bridgeCandidateProjection.js +71 -0
  168. package/dist/domain/browserCompleteness.js +1 -0
  169. package/dist/domain/browserObservationError.js +24 -5
  170. package/dist/domain/browserScenarioValues.js +2 -6
  171. package/dist/domain/bundleComparison.js +3 -2
  172. package/dist/domain/canonicalJsonDigestSteps.js +133 -0
  173. package/dist/domain/canonicalOrdering.js +9 -5
  174. package/dist/domain/changedBehavior.js +6 -6
  175. package/dist/domain/comparisonSourceEvidence.js +40 -0
  176. package/dist/domain/configurationErrors.js +1 -1
  177. package/dist/domain/evidence.js +64 -9
  178. package/dist/domain/evidenceBundle.js +42 -1
  179. package/dist/domain/evidenceErrors.js +12 -1
  180. package/dist/domain/explicitSensitiveFailure.js +17 -1
  181. package/dist/domain/firmware/firmwareAnalysis.js +6 -7
  182. package/dist/domain/hopperErrors.js +23 -2
  183. package/dist/domain/hopperValues.js +51 -8
  184. package/dist/domain/immutableJson.js +114 -0
  185. package/dist/domain/inputIssueProjection.js +3 -0
  186. package/dist/domain/javascript/electronActiveObservation.js +30 -4
  187. package/dist/domain/javascript/electronStaticAnalysisValues.js +6 -12
  188. package/dist/domain/javascript/javascriptApplicationAnalysis.js +71 -23
  189. package/dist/domain/javascript/javascriptApplicationGraph.js +13 -0
  190. package/dist/domain/javascript/javascriptAstValues.js +20 -0
  191. package/dist/domain/javascript/javascriptRecovery.js +3 -8
  192. package/dist/domain/javascript/javascriptSemanticAnalysis.js +97 -2
  193. package/dist/domain/javascript/javascriptSemanticCoverage.js +6 -5
  194. package/dist/domain/javascript/javascriptSemanticDataEffectHelpers.js +9 -17
  195. package/dist/domain/javascript/javascriptSemanticDataEffects.js +22 -5
  196. package/dist/domain/javascript/javascriptSemanticGraph.js +13 -0
  197. package/dist/domain/javascript/javascriptSemanticGraphSchemas.js +1 -0
  198. package/dist/domain/javascript/javascriptSemanticPrimitives.js +25 -17
  199. package/dist/domain/javascript/javascriptSemanticQuerySchemas.js +8 -4
  200. package/dist/domain/javascript/javascriptSemanticResourceLimits.js +77 -0
  201. package/dist/domain/javascript/javascriptSemanticValues.js +83 -11
  202. package/dist/domain/javascript/javascriptSourceParser.js +6 -2
  203. package/dist/domain/javascript/javascriptStaticAnalysis.js +22 -17
  204. package/dist/domain/javascript/javascriptStaticAnalysisBundler.js +5 -3
  205. package/dist/domain/javascript/javascriptStaticAnalysisCalls.js +14 -4
  206. package/dist/domain/javascript/javascriptStaticAnalysisFindings.js +66 -7
  207. package/dist/domain/javascript/javascriptStaticAnalysisHelpers.js +28 -16
  208. package/dist/domain/javascript/javascriptStaticAnalysisState.js +3 -2
  209. package/dist/domain/jsonSerialization.js +109 -0
  210. package/dist/domain/jsonValue.js +90 -6
  211. package/dist/domain/localPath.js +6 -0
  212. package/dist/domain/managed/managedApplicationGraph.js +10 -10
  213. package/dist/domain/managed/managedInspectionEvidence.js +16 -0
  214. package/dist/domain/managed/managedMemberComparisonMatch.js +5 -9
  215. package/dist/domain/managed/managedNativeVerification.js +3 -9
  216. package/dist/domain/native/fileOffsetPartialObservation.js +1 -0
  217. package/dist/domain/native/nativeCallObservation.js +33 -11
  218. package/dist/domain/native/nativeCallPartialObservation.js +33 -0
  219. package/dist/domain/process/processCapture.js +8 -4
  220. package/dist/domain/process/processComparison.js +38 -4
  221. package/dist/domain/process/processScenario.js +11 -10
  222. package/dist/domain/propertyListKeys.js +1 -1
  223. package/dist/domain/propertyListXmlText.js +19 -0
  224. package/dist/domain/providerAdapterError.js +1 -1
  225. package/dist/domain/providerOperationHealth.js +54 -0
  226. package/dist/domain/reconstructionVerification.js +6 -43
  227. package/dist/domain/reconstructionVerificationSchemas.js +2 -2
  228. package/dist/domain/staticRuntimeCorrelation.js +6 -43
  229. package/dist/domain/webBundleAnalysis.js +20 -8
  230. package/dist/domain/webBundleAnalyzerInspection.js +13 -8
  231. package/dist/domain/webBundleAnalyzerResult.js +41 -2
  232. package/dist/domain/webRuntime.js +19 -5
  233. package/dist/domain/webSourceLocation.js +1 -0
  234. package/dist/firmware/FirmwareFiles.js +1 -1
  235. package/dist/generatedPackageMetadata.js +1 -1
  236. package/dist/ghidra/GhidraAnalysisProfile.js +5 -0
  237. package/dist/ghidra/GhidraClient.js +47 -14
  238. package/dist/ghidra/GhidraDiagnostics.js +7 -7
  239. package/dist/ghidra/GhidraFunctionValues.js +10 -7
  240. package/dist/ghidra/GhidraInstallation.js +18 -21
  241. package/dist/ghidra/GhidraInventoryValues.js +14 -4
  242. package/dist/ghidra/GhidraJavaLaunch.js +62 -0
  243. package/dist/ghidra/GhidraLauncher.js +33 -16
  244. package/dist/ghidra/GhidraProviderCapabilities.js +14 -2
  245. package/dist/ghidra/GhidraProviderClient.js +23 -12
  246. package/dist/ghidra/GhidraSessionError.js +11 -7
  247. package/dist/ghidra/GhidraTargetSnapshot.js +47 -12
  248. package/dist/ghidra/GhidraTransport.js +20 -0
  249. package/dist/hopper/BridgeLauncher.js +31 -11
  250. package/dist/hopper/HopperAnalysisProfile.js +62 -4
  251. package/dist/hopper/HopperCleanup.js +15 -3
  252. package/dist/hopper/HopperClient.js +222 -14
  253. package/dist/hopper/HopperFileOffset.js +237 -0
  254. package/dist/hopper/HopperMachOImage.js +196 -0
  255. package/dist/hopper/HopperOperationStage.js +6 -0
  256. package/dist/hopper/HopperProvider.js +63 -9
  257. package/dist/hopper/HopperProviderCapabilities.js +19 -1
  258. package/dist/hopper/HopperRegexSearch.js +137 -0
  259. package/dist/hopper/HopperRegexWorker.js +27 -0
  260. package/dist/hopper/HopperRequestQueue.js +68 -19
  261. package/dist/hopper/HopperTargetLease.js +3 -2
  262. package/dist/inspector/JavaScriptRuntimeScope.js +9 -1
  263. package/dist/inspector/V8InspectorCaptureProjection.js +8 -3
  264. package/dist/inspector/V8InspectorProvider.js +47 -11
  265. package/dist/javascript/sourceMaps/DecodedSourceMap.js +47 -0
  266. package/dist/javascript/sourceMaps/SourceMapCommand.js +16 -0
  267. package/dist/javascript/sourceMaps/SourceMapFormat.js +79 -31
  268. package/dist/javascript/sourceMaps/TraceSourceMap.js +14 -28
  269. package/dist/mcpDoctor.js +62 -2
  270. package/dist/native/AppleDispatchCoverage.js +47 -6
  271. package/dist/native/AppleDispatchDecodeFacts.js +6 -0
  272. package/dist/native/AppleDispatchMetadata.js +6 -3
  273. package/dist/native/AppleMachoFixups.js +48 -24
  274. package/dist/native/AppleMachoSelection.js +32 -16
  275. package/dist/native/AppleObjcCategories.js +6 -2
  276. package/dist/native/AppleObjcDispatchFacets.js +5 -2
  277. package/dist/native/AppleObjcProperties.js +2 -1
  278. package/dist/native/AppleSwiftDispatchFacets.js +27 -21
  279. package/dist/native/AppleSwiftVtables.js +21 -15
  280. package/dist/native/CommandRunner.js +81 -84
  281. package/dist/native/LldbCallTracer.js +365 -102
  282. package/dist/native/LldbRetainedObservations.js +178 -0
  283. package/dist/native/NativeCallObservation.js +62 -3
  284. package/dist/native/NativeMacOSProvider.js +98 -17
  285. package/dist/native/SignatureTargetBinding.js +155 -0
  286. package/dist/native/parsers/lipo.js +71 -1
  287. package/dist/native/pwndbg/PwndbgCoreContext.js +25 -5
  288. package/dist/native/pwntools/RecordedCrashStructureBindings.js +2 -0
  289. package/dist/process/DarwinProcessRunTokenReader.js +8 -9
  290. package/dist/process/ExecFileOutput.js +20 -0
  291. package/dist/process/OwnedCommand.js +7 -2
  292. package/dist/process/ProcessOwnership.js +203 -53
  293. package/dist/process/ProcessOwnershipObservation.js +49 -4
  294. package/dist/process/ProviderProcess.js +38 -7
  295. package/dist/process/capture/ProcessCaptureError.js +2 -2
  296. package/dist/process/capture/ProcessCaptureLifecycle.js +100 -34
  297. package/dist/server/EvidenceMcpServer.js +146 -0
  298. package/dist/server/createServer.js +15 -8
  299. package/dist/server/registerAndroidTools.js +2 -4
  300. package/dist/server/registerApplicationTools/helpers.js +2 -4
  301. package/dist/server/registerArtifactComparisonTool.js +11 -7
  302. package/dist/server/registerBinaryDiagnosticsTools.js +2 -4
  303. package/dist/server/registerBrowserScenarioTool.js +2 -4
  304. package/dist/server/registerBrowserTools.js +2 -4
  305. package/dist/server/registerBundleComparisonTool.js +2 -3
  306. package/dist/server/registerCloseLifecycleTool.js +8 -18
  307. package/dist/server/registerElectronTools.js +2 -4
  308. package/dist/server/registerEnhancedTools.js +18 -59
  309. package/dist/server/registerEvidenceTools.js +2 -4
  310. package/dist/server/registerEvmTools.js +2 -4
  311. package/dist/server/registerFirmwareTools.js +2 -4
  312. package/dist/server/registerFunctionComparisonTool.js +10 -6
  313. package/dist/server/registerInvestigationTools.js +7 -7
  314. package/dist/server/registerJavaScriptRecoveryTool.js +2 -4
  315. package/dist/server/registerJavaScriptRuntimeObservationTools.js +2 -4
  316. package/dist/server/registerManagedWorkflowTools/compareManagedMembers.js +2 -4
  317. package/dist/server/registerManagedWorkflowTools/importManagedReconstruction.js +2 -4
  318. package/dist/server/registerManagedWorkflowTools/projectManagedApplicationGraph.js +2 -4
  319. package/dist/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.js +2 -4
  320. package/dist/server/registerOfficialTools.js +2 -4
  321. package/dist/server/registerProcessComparisonTool.js +71 -45
  322. package/dist/server/registerRecordedCrashTools.js +2 -4
  323. package/dist/server/registerSessionRecordTools.js +5 -6
  324. package/dist/server/registerSessionStatusTool.js +17 -3
  325. package/dist/server/registerSessionTools.js +11 -3
  326. package/dist/server/registerWebModuleTool.js +2 -4
  327. package/dist/server/registerWebNetworkCaptureTool.js +2 -4
  328. package/dist/server/registerWebRuntimeTools.js +3 -7
  329. package/dist/server/registerWebScriptTool.js +2 -4
  330. package/dist/server/registerWebSourceLocationTool.js +2 -4
  331. package/dist/server/runDerivedOperation.js +15 -3
  332. package/dist/server/sessionAvailabilityPolicy.js +0 -1
  333. package/dist/server/toolRegistrationOptions.js +2 -2
  334. package/dist/server/toolResult.js +62 -10
  335. package/dist/server/toolResultEncoding.js +33 -0
  336. package/install.sh +1 -1
  337. package/native/windows/build/manifest.json +1 -1
  338. package/package.json +8 -3
  339. package/scripts/electron-active-hook-boundaries.cjs +18 -20
  340. package/scripts/electron-active-hook.cjs +241 -37
  341. package/skills/reverse-engineer-anything/SKILL.md +11 -3
  342. package/skills/reverse-engineer-anything/references/javascript-applications.md +8 -1
  343. package/dist/ghidra/GhidraDefaults.js +0 -2
@@ -6,10 +6,21 @@ import { z } from "zod";
6
6
  import { webSourceOffset } from "../../domain/webSourcePosition.js";
7
7
  import { webSourceMapReportSchema, WEB_SOURCE_MAP_LIMITS, } from "../../domain/webSourceLocation.js";
8
8
  import { inspectSourceMap, SourceMapFormatFailure, } from "./SourceMapFormat.js";
9
+ import { decodeValidatedSourceMapLeaves, isBeforeSourceMapLeafStop, } from "./DecodedSourceMap.js";
9
10
  /** Decode with the pinned upstream codec; preserve every equal-position candidate. */
10
11
  export const traceSourceMap = (text, url, position) => {
11
12
  const inspected = inspectSourceMap(text);
12
- const { map, rows } = decodeValidatedMap(inspected, url);
13
+ const map = new AnyMap(inspected.jsonText, url);
14
+ const decodedLeaves = decodeValidatedSourceMapLeaves(inspected.leaves, url);
15
+ for (const { leaf, rows } of decodedLeaves)
16
+ for (const [line, row] of rows.entries())
17
+ for (const segment of row)
18
+ if (!isBeforeSourceMapLeafStop(leaf, line, segment[0]))
19
+ throw new SourceMapFormatFailure("format", "Embedded source-map mappings overlap the following section boundary.");
20
+ const rows = inspected.format === "regular"
21
+ ? (decodedLeaves[0]?.rows ?? [])
22
+ : decodedMappings(map);
23
+ validateFlattenedRows(inspected, rows, map);
13
24
  const matched = greatestPosition(rows, position);
14
25
  const segments = matched === null
15
26
  ? []
@@ -48,38 +59,13 @@ export const traceSourceMap = (text, url, position) => {
48
59
  diagnostics: [],
49
60
  });
50
61
  };
51
- const decodeValidatedMap = (inspected, url) => {
52
- let regularRows;
53
- for (const leaf of inspected.leaves) {
54
- const decoded = decodedMappings(new TraceMap(JSON.stringify(leaf.map), url));
55
- if (inspected.format === "regular")
56
- regularRows = decoded;
57
- for (const [line, row] of decoded.entries())
58
- for (const segment of row) {
59
- if (segment.some((value) => !Number.isSafeInteger(value) || value < 0) ||
60
- (segment.length !== 1 && segment[1] >= leaf.map.sources.length) ||
61
- (segment.length === 5 && segment[4] >= leaf.map.names.length))
62
- throw new SourceMapFormatFailure("format", "Decoded section-local position, source index or name index is invalid.");
63
- const generatedLine = leaf.offset.line + line;
64
- const generatedColumn = segment[0] + (line === 0 ? leaf.offset.column : 0);
65
- if (leaf.stop !== null &&
66
- (generatedLine > leaf.stop.line ||
67
- (generatedLine === leaf.stop.line &&
68
- generatedColumn >= leaf.stop.column)))
69
- throw new SourceMapFormatFailure("format", "Embedded source-map mappings overlap the following section boundary.");
70
- }
71
- }
72
- const map = new AnyMap(inspected.jsonText, url);
73
- const rows = regularRows ?? decodedMappings(map);
62
+ const validateFlattenedRows = (inspected, rows, map) => {
74
63
  for (const row of rows)
75
64
  for (const segment of row) {
76
- if (![1, 4, 5].includes(segment.length) ||
77
- segment.some((v) => !Number.isSafeInteger(v) || v < 0) ||
78
- (segment.length !== 1 && segment[1] >= inspected.declarations.length) ||
65
+ if ((segment.length !== 1 && segment[1] >= inspected.declarations.length) ||
79
66
  (segment.length === 5 && segment[4] >= map.names.length))
80
67
  throw new SourceMapFormatFailure("format", "Decoded mapping has invalid component count, position, source index or name index.");
81
68
  }
82
- return { map, rows };
83
69
  };
84
70
  const greatestPosition = (rows, position) => {
85
71
  for (let line = Math.min(position.line - 1, rows.length - 1); line >= 0; line -= 1) {
package/dist/mcpDoctor.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { Client } from "@modelcontextprotocol/client";
2
2
  import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
3
- import { Formatter } from "incur";
3
+ import { Formatter, Help, z } from "incur";
4
4
  import { resolve } from "node:path";
5
5
  import { CATALOG_IDENTITY } from "./catalogIdentity.js";
6
6
  import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
@@ -8,6 +8,36 @@ import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
8
8
  import { PRODUCT_IDENTITY } from "./identity.js";
9
9
  import { MCP_STARTUP_POLICY } from "./mcpStartupPolicy.js";
10
10
  const OUTPUT_FORMATS = ["toon", "json", "yaml", "md", "jsonl"];
11
+ /**
12
+ * Canonical `rea mcp doctor` options. This schema is the single source of
13
+ * truth: the argument parser accepts exactly these options (plus the `-h`
14
+ * alias below) and the help renderer lists them. Keep them in sync by
15
+ * changing this schema, not either consumer.
16
+ */
17
+ const MCP_DOCTOR_OPTIONS = z.object({
18
+ format: z.enum(OUTPUT_FORMATS).optional().describe("Output format"),
19
+ json: z.boolean().optional().describe("Emit the report as JSON"),
20
+ fullOutput: z.boolean().optional().describe("Show the full output envelope"),
21
+ help: z.boolean().optional().describe("Show help"),
22
+ });
23
+ const MCP_DOCTOR_ALIAS = { help: "h" };
24
+ const MCP_DOCTOR_COMMAND = "rea mcp doctor";
25
+ const MCP_DOCTOR_DESCRIPTION = "Validate MCP server startup and tool listing";
26
+ /** Help flags derived from `MCP_DOCTOR_OPTIONS` plus its alias. */
27
+ const HELP_FLAGS = new Set(["--help", "-h"]);
28
+ /**
29
+ * Answer an advertised help request without starting a diagnostic session.
30
+ * Global options are hidden because this dispatcher entry accepts only the
31
+ * options above; the hint says so explicitly instead of implying full
32
+ * Incur parity.
33
+ */
34
+ const renderMcpDoctorHelp = () => Help.formatCommand(MCP_DOCTOR_COMMAND, {
35
+ description: MCP_DOCTOR_DESCRIPTION,
36
+ hideGlobalOptions: true,
37
+ options: MCP_DOCTOR_OPTIONS,
38
+ alias: MCP_DOCTOR_ALIAS,
39
+ hint: "This entry accepts only the options above.",
40
+ });
11
41
  /** Diagnose the actual production stdio adapter with one startup-bounded SDK session. */
12
42
  export const runProductionMcpDoctor = async (options) => {
13
43
  const deadline = Date.now() + (options.deadlineMs ?? MCP_STARTUP_POLICY.doctorDeadlineMs);
@@ -117,11 +147,14 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
117
147
  */
118
148
  export const runProductionMcpDoctorCli = async (arguments_, input) => {
119
149
  const parsed = parseOutputArguments(arguments_);
120
- if (!parsed.ok)
150
+ if (!parsed.ok) {
151
+ if (parsed.help)
152
+ return { output: `${renderMcpDoctorHelp()}\n`, exitCode: 0 };
121
153
  return {
122
154
  output: `${Formatter.format({ code: "VALIDATION_ERROR", message: parsed.message }, parsed.format)}\n`,
123
155
  exitCode: 1,
124
156
  };
157
+ }
125
158
  const result = await runProductionMcpDoctor({
126
159
  command: process.execPath,
127
160
  args: [resolve(input.dispatcherPath), "mcp"],
@@ -174,6 +207,12 @@ const parseIdentityToolResult = (input) => {
174
207
  };
175
208
  };
176
209
  const parseOutputArguments = (arguments_) => {
210
+ // Help wins over output selection and validation errors, but only when it
211
+ // appears in option position. A token consumed as `--format`'s value is
212
+ // not a flag, so `--format --help` reports an invalid format instead of
213
+ // masking the typo with usage.
214
+ if (hasHelpInOptionPosition(arguments_))
215
+ return { ok: false, help: true };
177
216
  let format = "toon";
178
217
  for (let index = 0; index < arguments_.length; index += 1) {
179
218
  const argument = arguments_[index];
@@ -191,6 +230,7 @@ const parseOutputArguments = (arguments_) => {
191
230
  if (!isOutputFormat(candidate))
192
231
  return {
193
232
  ok: false,
233
+ help: false,
194
234
  format,
195
235
  message: `Invalid output format: ${candidate ?? "missing"}`,
196
236
  };
@@ -199,14 +239,34 @@ const parseOutputArguments = (arguments_) => {
199
239
  }
200
240
  if (argument === "--full-output")
201
241
  continue;
242
+ if (HELP_FLAGS.has(argument ?? ""))
243
+ return { ok: false, help: true };
202
244
  return {
203
245
  ok: false,
246
+ help: false,
204
247
  format,
205
248
  message: `Unknown mcp doctor option: ${argument ?? "missing"}`,
206
249
  };
207
250
  }
208
251
  return { ok: true, format };
209
252
  };
253
+ /**
254
+ * Report whether `--help`/`-h` appears in option position. Tokens consumed
255
+ * as `--format`'s value are skipped so `--format --help` stays an invalid
256
+ * format error instead of silently becoming a help request.
257
+ */
258
+ const hasHelpInOptionPosition = (arguments_) => {
259
+ for (let index = 0; index < arguments_.length; index += 1) {
260
+ const argument = arguments_[index];
261
+ if (argument === "--format") {
262
+ index += 1;
263
+ continue;
264
+ }
265
+ if (HELP_FLAGS.has(argument ?? ""))
266
+ return true;
267
+ }
268
+ return false;
269
+ };
210
270
  const isOutputFormat = (value) => OUTPUT_FORMATS.some((candidate) => candidate === value);
211
271
  const requestOptions = (deadline, signal) => ({
212
272
  signal,
@@ -7,7 +7,7 @@ const describeFixups = (fixups) => {
7
7
  };
8
8
  /** Append the per-facet coverage of one Apple dispatch metadata decode. */
9
9
  export const pushDispatchCoverage = (input) => {
10
- const { result, failures, examined, categoriesExamined, truncated, fixups } = input;
10
+ const { result, failures, categoryIssues, examined, categoriesExamined, truncated, fixups, vtables, swift, } = input;
11
11
  result.coverage.push({
12
12
  facet: "objc_class_method_ivar_metadata",
13
13
  status: failures.length > 0 || truncated ? "partial" : "complete",
@@ -30,21 +30,25 @@ export const pushDispatchCoverage = (input) => {
30
30
  examined: result.relative_pointers.length,
31
31
  decoded: result.relative_pointers.filter((item) => item.decode.status === "decoded").length,
32
32
  });
33
- const categoryFailures = failures.filter((failure) => /^(?:Properties of|Category at)/u.test(failure));
33
+ const categoryFailures = categoryIssues.map(({ code, location, message }) => `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`);
34
34
  result.coverage.push({
35
35
  facet: "objc_properties_categories",
36
- status: categoryFailures.length > 0 ||
36
+ status: truncated ||
37
+ categoryFailures.length > 0 ||
37
38
  result.objc_categories.some(({ decode }) => decode.status !== "decoded")
38
39
  ? "partial"
39
40
  : "complete",
40
- reason: categoryFailures.join("; ") || null,
41
+ reason: [...categoryFailures, ...(truncated ? ["max_records_reached"] : [])].join("; ") || null,
41
42
  examined: categoriesExamined,
42
43
  decoded: result.objc_categories.filter(({ decode }) => decode.status === "decoded").length,
43
44
  });
44
45
  result.coverage.push({
45
46
  facet: "pointer_fixups",
46
- status: fixups.failures.length > 0 ? "partial" : "complete",
47
- reason: [describeFixups(fixups), ...fixups.failures].join("; "),
47
+ status: fixups.issues.length > 0 ? "partial" : "complete",
48
+ reason: [
49
+ describeFixups(fixups),
50
+ ...fixups.issues.map(({ code, location, message }) => `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`),
51
+ ].join("; "),
48
52
  examined: 0,
49
53
  decoded: 0,
50
54
  });
@@ -55,4 +59,41 @@ export const pushDispatchCoverage = (input) => {
55
59
  examined: 0,
56
60
  decoded: 0,
57
61
  });
62
+ result.coverage.push({
63
+ facet: "swift_conformances_static_witness_slots",
64
+ status: swift.exhaustive &&
65
+ !truncated &&
66
+ !result.swift_conformances.some(({ decode }) => decode.status !== "decoded") &&
67
+ !result.swift_dispatch_slots.some(({ table_kind, decode }) => table_kind === "witness_table" && decode.status !== "decoded")
68
+ ? "complete"
69
+ : "partial",
70
+ reason: [
71
+ ...swift.issues.map(formatIssue),
72
+ ...(truncated ? ["max_records_reached"] : []),
73
+ ...(result.swift_conformances.some(({ decode }) => decode.status !== "decoded") ||
74
+ result.swift_dispatch_slots.some(({ table_kind, decode }) => table_kind === "witness_table" && decode.status !== "decoded")
75
+ ? ["swift_records_unresolved"]
76
+ : []),
77
+ ].join("; ") || null,
78
+ examined: swift.examined,
79
+ decoded: swift.decoded,
80
+ });
81
+ result.coverage.push({
82
+ facet: "swift_class_vtable_descriptors",
83
+ status: vtables.exhaustive &&
84
+ !truncated &&
85
+ !result.swift_dispatch_slots.some(({ table_kind, decode }) => table_kind === "class_vtable" && decode.status !== "decoded")
86
+ ? "complete"
87
+ : "partial",
88
+ reason: [
89
+ ...vtables.issues.map(formatIssue),
90
+ ...(truncated ? ["max_records_reached"] : []),
91
+ ...(result.swift_dispatch_slots.some(({ table_kind, decode }) => table_kind === "class_vtable" && decode.status !== "decoded")
92
+ ? ["vtable_implementations_unresolved"]
93
+ : []),
94
+ ].join("; ") || null,
95
+ examined: vtables.examined,
96
+ decoded: vtables.decoded,
97
+ });
58
98
  };
99
+ const formatIssue = ({ code, location, message }) => `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`;
@@ -0,0 +1,6 @@
1
+ export const issue = (facet, code, message, location) => ({
2
+ facet,
3
+ code,
4
+ message,
5
+ ...(location === undefined ? {} : { location }),
6
+ });
@@ -77,7 +77,7 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
77
77
  evidence,
78
78
  offset,
79
79
  };
80
- const { failures, examined, categoriesExamined } = decodeObjcDispatchFacets({
80
+ const { failures, categoryIssues, examined, categoriesExamined } = decodeObjcDispatchFacets({
81
81
  bytes,
82
82
  sections,
83
83
  segments,
@@ -91,7 +91,7 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
91
91
  budget,
92
92
  result,
93
93
  });
94
- decodeSwiftDispatchFacets({
94
+ const swift = decodeSwiftDispatchFacets({
95
95
  sections,
96
96
  segments,
97
97
  readers,
@@ -108,7 +108,7 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
108
108
  if (section.size / 4 > maxRecords)
109
109
  budget.truncated = true;
110
110
  }
111
- decodeSwiftClassVtables({
111
+ const vtables = decodeSwiftClassVtables({
112
112
  entries: typeEntries,
113
113
  result,
114
114
  readers: {
@@ -126,10 +126,13 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
126
126
  pushDispatchCoverage({
127
127
  result,
128
128
  failures,
129
+ categoryIssues,
129
130
  examined,
130
131
  categoriesExamined,
131
132
  truncated: budget.truncated,
132
133
  fixups,
134
+ vtables,
135
+ swift,
133
136
  });
134
137
  return objcSwiftMetadataSchema.parse(result);
135
138
  };
@@ -1,3 +1,4 @@
1
+ import { issue } from "./AppleDispatchDecodeFacts.js";
1
2
  const POINTER_FORMATS = {
2
3
  1: "DYLD_CHAINED_PTR_ARM64E",
3
4
  2: "DYLD_CHAINED_PTR_64",
@@ -19,39 +20,42 @@ const cString = (bytes, offset, end) => {
19
20
  throw new RangeError("Fixup symbol name is outside the symbol pool");
20
21
  return bytes.toString("utf8", offset, stop);
21
22
  };
22
- const readImports = (data, header) => {
23
+ const readImport = (data, header, index) => {
23
24
  const { bytes, base, end, dylibs } = data;
24
25
  const size = header.format === 3 ? 16 : header.format === 2 ? 8 : 4;
25
26
  if (header.format < 1 || header.format > 3)
26
27
  throw new RangeError(`Unsupported chained import format ${header.format}`);
27
- if (base + header.offset + header.count * size > end)
28
+ if (!Number.isSafeInteger(header.count) ||
29
+ base + header.offset + header.count * size > end)
28
30
  throw new RangeError("Chained import table exceeds the fixup data");
29
- return Array.from({ length: header.count }, (_, index) => {
30
- const at = base + header.offset + index * size;
31
- if (header.format === 3) {
32
- const word = bytes.readBigUInt64LE(at);
33
- const ordinal = Number(signed(bits(word, 0, 16), 16));
34
- return {
35
- symbol: cString(bytes, base + header.symbols + Number(bits(word, 32, 32)), end),
36
- library: libraryName(ordinal, dylibs),
37
- weak: bits(word, 16, 1) === 1n,
38
- addend: bytes.readBigInt64LE(at + 8),
39
- };
40
- }
41
- const word = bytes.readUInt32LE(at);
42
- const ordinal = Number(signed(BigInt(word & 0xff), 8));
31
+ if (index < 0 || index >= header.count)
32
+ throw new RangeError("Chained import index is outside the table");
33
+ const at = base + header.offset + index * size;
34
+ if (header.format === 3) {
35
+ const word = bytes.readBigUInt64LE(at);
36
+ const ordinal = Number(signed(bits(word, 0, 16), 16));
43
37
  return {
44
- symbol: cString(bytes, base + header.symbols + (word >>> 9), end),
38
+ symbol: cString(bytes, base + header.symbols + Number(bits(word, 32, 32)), end),
45
39
  library: libraryName(ordinal, dylibs),
46
- weak: ((word >>> 8) & 1) === 1,
47
- addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,
40
+ weak: bits(word, 16, 1) === 1n,
41
+ addend: bytes.readBigInt64LE(at + 8),
48
42
  };
49
- });
43
+ }
44
+ const word = bytes.readUInt32LE(at);
45
+ const ordinal = Number(signed(BigInt(word & 0xff), 8));
46
+ return {
47
+ symbol: cString(bytes, base + header.symbols + (word >>> 9), end),
48
+ library: libraryName(ordinal, dylibs),
49
+ weak: ((word >>> 8) & 1) === 1,
50
+ addend: header.format === 2 ? BigInt(bytes.readInt32LE(at + 4)) : 0n,
51
+ };
50
52
  };
51
53
  /** Decode one raw chained pointer for its segment's pointer format. */
52
54
  export const decodeChainedPointer = (raw, format, baseAddress, imports) => {
53
55
  const bind = (ordinal, addend) => {
54
- const target = imports[Number(ordinal)];
56
+ const target = typeof imports === "function"
57
+ ? imports(Number(ordinal))
58
+ : imports[Number(ordinal)];
55
59
  if (target === undefined)
56
60
  throw new RangeError(`Chained bind ordinal ${ordinal} has no import`);
57
61
  return { kind: "bind", ...target, addend: target.addend + addend };
@@ -86,12 +90,19 @@ const chainedFixups = (image, range) => {
86
90
  if (range.size < 28 || end > bytes.length)
87
91
  throw new RangeError("Chained fixup header exceeds the target");
88
92
  const startsOffset = bytes.readUInt32LE(base + 4);
89
- const imports = readImports({ bytes, base, end, dylibs }, {
93
+ const importHeader = {
90
94
  offset: bytes.readUInt32LE(base + 8),
91
95
  symbols: bytes.readUInt32LE(base + 12),
92
96
  count: bytes.readUInt32LE(base + 16),
93
97
  format: bytes.readUInt32LE(base + 20),
94
- });
98
+ };
99
+ const importSize = importHeader.format === 3 ? 16 : importHeader.format === 2 ? 8 : 4;
100
+ const importTableEnd = base + importHeader.offset + importHeader.count * importSize;
101
+ if (importHeader.format < 1 || importHeader.format > 3)
102
+ throw new RangeError(`Unsupported chained import format ${importHeader.format}`);
103
+ if (!Number.isSafeInteger(importHeader.count) || importTableEnd > end)
104
+ throw new RangeError("Chained import table exceeds the fixup data");
105
+ const imports = (index) => readImport({ bytes, base, end, dylibs }, importHeader, index);
95
106
  if (bytes.readUInt32LE(base + 24) !== 0)
96
107
  throw new RangeError("Compressed chained-fixup symbol names are not supported");
97
108
  const starts = base + startsOffset;
@@ -113,10 +124,16 @@ const chainedFixups = (image, range) => {
113
124
  const formats = [
114
125
  ...new Set(ranges.map(({ format }) => POINTER_FORMATS[format] ?? `format-${format}`)),
115
126
  ];
127
+ const issues = ranges.flatMap(({ format, from }) => POINTER_FORMATS[format] === undefined
128
+ ? [
129
+ issue("pointer_fixups", "unsupported_pointer_format", `Unsupported chained pointer format ${format}`, `0x${from.toString(16)}`),
130
+ ]
131
+ : []);
116
132
  return {
117
133
  kind: "chained",
118
134
  formats,
119
- failures: [],
135
+ failures: issues.map(({ message }) => message),
136
+ issues,
120
137
  decode(address, raw) {
121
138
  const segment = ranges.find(({ from, to }) => address >= from && address < to);
122
139
  // Pointers outside fixup segments, such as in __TEXT, are stored plainly.
@@ -124,6 +141,11 @@ const chainedFixups = (image, range) => {
124
141
  return { kind: "rebase", target: raw };
125
142
  if (raw === 0n)
126
143
  return { kind: "rebase", target: 0n };
144
+ if (POINTER_FORMATS[segment.format] === undefined)
145
+ return {
146
+ kind: "unsupported",
147
+ reason: `Unsupported chained pointer format ${segment.format}`,
148
+ };
127
149
  return decodeChainedPointer(raw, segment.format, baseAddress, imports);
128
150
  },
129
151
  };
@@ -267,6 +289,7 @@ export const parsePointerFixups = (bytes, commands, segments, baseAddress) => {
267
289
  kind: "none",
268
290
  formats: [],
269
291
  failures: [],
292
+ issues: [],
270
293
  decode: (_address, raw) => ({ kind: "rebase", target: raw }),
271
294
  };
272
295
  const binds = new Map();
@@ -282,6 +305,7 @@ export const parsePointerFixups = (bytes, commands, segments, baseAddress) => {
282
305
  kind: "dyld-info",
283
306
  formats: [],
284
307
  failures,
308
+ issues: failures.map((message) => issue("pointer_fixups", "bind_stream_decode_failed", message)),
285
309
  decode(address, raw) {
286
310
  const bound = binds.get(address);
287
311
  return bound === undefined
@@ -1,3 +1,4 @@
1
+ import { readFatSliceDeclarations, validateFatSlice, } from "../domain/apple/machoContainer.js";
1
2
  const hex = (value) => `0x${value.toString(16)}`;
2
3
  /** Classify a FAT magic word; thin Mach-O returns null. */
3
4
  export const fatHeaderFormat = (magic) => {
@@ -25,9 +26,6 @@ export const selectMachoSlice = (bytes, architecture) => {
25
26
  const readUInt32 = littleEndian
26
27
  ? (offset) => bytes.readUInt32LE(offset)
27
28
  : (offset) => bytes.readUInt32BE(offset);
28
- const readUInt64 = littleEndian
29
- ? (offset) => bytes.readBigUInt64LE(offset)
30
- : (offset) => bytes.readBigUInt64BE(offset);
31
29
  const byteOrder = littleEndian ? "little-endian" : "big-endian";
32
30
  const malformed = (reason) => new RangeError(`${reason} (FAT header byte order: ${byteOrder})`);
33
31
  const invalid = (reason) => new TypeError(`${reason} (FAT header byte order: ${byteOrder})`);
@@ -38,22 +36,30 @@ export const selectMachoSlice = (bytes, architecture) => {
38
36
  if (count > 128 || headerEnd > bytes.length)
39
37
  throw malformed("Malformed FAT architecture table");
40
38
  const cpu = architecture === "arm64" ? 0x0100000c : 0x01000007;
39
+ const declarations = readFatSliceDeclarations(bytes.subarray(8, headerEnd), {
40
+ count,
41
+ wide: fat64,
42
+ littleEndian,
43
+ });
44
+ if (declarations.status !== "parsed")
45
+ throw malformed(declarations.reason);
41
46
  let selected;
42
- for (let index = 0; index < count; index++) {
43
- const offset = 8 + index * stride;
44
- if (readUInt32(offset) !== cpu)
47
+ for (const declaration of declarations.slices) {
48
+ const issue = validateFatSlice(declaration, bytes.length, headerEnd);
49
+ if (issue !== null)
50
+ throw malformed(issue);
51
+ if (declaration.cpuType !== cpu)
45
52
  continue;
46
53
  if (selected !== undefined)
47
54
  throw invalid("Ambiguous FAT architecture slice");
48
- const start = fat64
49
- ? readUInt64(offset + 8)
50
- : BigInt(readUInt32(offset + 8));
51
- const size = fat64
52
- ? readUInt64(offset + 16)
53
- : BigInt(readUInt32(offset + 12));
54
- if (start < BigInt(headerEnd) || start + size > BigInt(bytes.length))
55
- throw malformed("FAT slice exceeds file");
56
- selected = { slice: Number(start), sliceEnd: Number(start + size) };
55
+ selected = {
56
+ slice: declaration.offset,
57
+ sliceEnd: declaration.offset + declaration.size,
58
+ fatDeclaration: {
59
+ ...declaration,
60
+ tableEnd: headerEnd,
61
+ },
62
+ };
57
63
  }
58
64
  if (selected === undefined)
59
65
  throw invalid("Requested FAT architecture is absent");
@@ -63,11 +69,21 @@ export const selectMachoSlice = (bytes, architecture) => {
63
69
  export const parseMachoLayout = (bytes, architecture) => {
64
70
  if (bytes.length < 4)
65
71
  throw new RangeError("Truncated Mach-O header");
66
- const { slice, sliceEnd } = selectMachoSlice(bytes, architecture);
72
+ const selection = selectMachoSlice(bytes, architecture);
73
+ const { slice, sliceEnd } = selection;
67
74
  if (slice === 0 && sliceEnd === bytes.length && bytes.length < 32)
68
75
  throw new RangeError("Truncated Mach-O header");
69
76
  if (slice + 32 > sliceEnd || bytes.readUInt32LE(slice) !== 0xfeedfacf)
70
77
  throw new TypeError("Only little-endian 64-bit Mach-O metadata is supported");
78
+ const fat = selection.fatDeclaration;
79
+ if (fat !== undefined) {
80
+ const issue = validateFatSlice(fat, bytes.length, fat.tableEnd, {
81
+ cpuType: bytes.readUInt32LE(slice + 4),
82
+ cpuSubtype: bytes.readUInt32LE(slice + 8),
83
+ });
84
+ if (issue !== null)
85
+ throw new TypeError(issue);
86
+ }
71
87
  const commands = bytes.readUInt32LE(slice + 16);
72
88
  const commandEnd = slice + 32 + bytes.readUInt32LE(slice + 20);
73
89
  if (commands > 4096 || commandEnd > sliceEnd)
@@ -1,4 +1,5 @@
1
1
  import { readObjcPropertiesOf } from "./AppleObjcProperties.js";
2
+ import { issue } from "./AppleDispatchDecodeFacts.js";
2
3
  const CLASS_SYMBOL = /^_OBJC_(?:META)?CLASS_\$_(.+)$/u;
3
4
  /** External class name from a bound `_OBJC_CLASS_$_Name` symbol. */
4
5
  export const boundClassName = (read, field) => {
@@ -41,7 +42,8 @@ export const decodeObjcCategories = (input) => {
41
42
  properties: readObjcPropertiesOf(read, read.pointer(category + 40n), {
42
43
  owner: `category ${name}`,
43
44
  admit: input.admit,
44
- failures,
45
+ issues: input.issues,
46
+ location: `0x${read.pointer(category + 40n).toString(16)}`,
45
47
  }),
46
48
  location: read.location(category),
47
49
  decode: className === null
@@ -51,7 +53,9 @@ export const decodeObjcCategories = (input) => {
51
53
  });
52
54
  }
53
55
  catch (cause) {
54
- failures.push(`Category at ${`0x${field.toString(16)}`}: ${cause instanceof Error ? cause.message : String(cause)}`);
56
+ const message = cause instanceof Error ? cause.message : String(cause);
57
+ failures.push(`Category at 0x${field.toString(16)}: ${message}`);
58
+ input.issues.push(issue("objc_properties_categories", "category_decode_failed", message, `0x${field.toString(16)}`));
55
59
  }
56
60
  }
57
61
  }
@@ -30,6 +30,7 @@ const resolveSuperclass = (read, address, className, failures) => {
30
30
  export const decodeObjcDispatchFacets = (input) => {
31
31
  const { bytes, sections, segments, readers: read, budget, result } = input;
32
32
  const failures = [];
33
+ const categoryIssues = [];
33
34
  let examined = 0;
34
35
  const methods = (list, className, methodType, category) => {
35
36
  const selectors = [];
@@ -203,7 +204,8 @@ export const decodeObjcDispatchFacets = (input) => {
203
204
  properties: readObjcPropertiesOf(read, read.pointer(ro + 64n), {
204
205
  owner: name,
205
206
  admit: () => budget.admit(),
206
- failures,
207
+ issues: categoryIssues,
208
+ location: hex(read.pointer(ro + 64n)),
207
209
  }),
208
210
  protocols: protocolReader.list(read.pointer(ro + 40n)),
209
211
  ivar_count: ivarCount,
@@ -248,10 +250,11 @@ export const decodeObjcDispatchFacets = (input) => {
248
250
  read,
249
251
  result,
250
252
  failures,
253
+ issues: categoryIssues,
251
254
  admit: () => budget.admit(),
252
255
  methods,
253
256
  protocols: (list) => protocolReader.list(list),
254
257
  localClassName: (address) => localClassName(read, address),
255
258
  });
256
- return { failures, examined, categoriesExamined };
259
+ return { failures, categoryIssues, examined, categoriesExamined };
257
260
  };
@@ -1,3 +1,4 @@
1
+ import { issue } from "./AppleDispatchDecodeFacts.js";
1
2
  /**
2
3
  * Parse an `@property` attribute string such as `T@"NSString",C,N,V_name`.
3
4
  * Each comma-separated token is one attribute; `T` is the type encoding.
@@ -62,7 +63,7 @@ export const readObjcPropertiesOf = (read, list, context) => {
62
63
  return readObjcPropertyList(read, list, context.admit);
63
64
  }
64
65
  catch (cause) {
65
- context.failures.push(`Properties of ${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`);
66
+ context.issues.push(issue("objc_properties_categories", "property_decode_failed", `${context.owner}: ${cause instanceof Error ? cause.message : String(cause)}`, context.location));
66
67
  return [];
67
68
  }
68
69
  };