pycforge 0.15.2__py3-none-any.whl

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 (221) hide show
  1. pycforge/__init__.py +8 -0
  2. pycforge/__main__.py +2 -0
  3. pycforge/_version.py +1 -0
  4. pycforge/converter/__init__.py +0 -0
  5. pycforge/converter/analysis/__init__.py +5 -0
  6. pycforge/converter/analysis/functions.py +723 -0
  7. pycforge/converter/analysis/model.py +158 -0
  8. pycforge/converter/analysis/planning.py +464 -0
  9. pycforge/converter/analysis/stage.py +1976 -0
  10. pycforge/converter/analysis/symbols.py +237 -0
  11. pycforge/converter/analysis/validation.py +2166 -0
  12. pycforge/converter/c_output/__init__.py +2 -0
  13. pycforge/converter/c_output/conformance.py +297 -0
  14. pycforge/converter/c_output/renderer.py +220 -0
  15. pycforge/converter/conditional_regions/__init__.py +71 -0
  16. pycforge/converter/conditional_regions/analysis.py +481 -0
  17. pycforge/converter/conditional_regions/lowering.py +579 -0
  18. pycforge/converter/conditional_regions/model.py +243 -0
  19. pycforge/converter/conditional_regions/validation.py +690 -0
  20. pycforge/converter/containers/__init__.py +19 -0
  21. pycforge/converter/containers/analysis.py +542 -0
  22. pycforge/converter/containers/lowering.py +290 -0
  23. pycforge/converter/containers/model.py +146 -0
  24. pycforge/converter/contracts/__init__.py +0 -0
  25. pycforge/converter/contracts/configuration.py +178 -0
  26. pycforge/converter/contracts/identifiers.py +68 -0
  27. pycforge/converter/contracts/versions.py +71 -0
  28. pycforge/converter/core/__init__.py +0 -0
  29. pycforge/converter/core/artifact_io.py +87 -0
  30. pycforge/converter/core/cancellation.py +7 -0
  31. pycforge/converter/core/canonicalization.py +254 -0
  32. pycforge/converter/core/context.py +13 -0
  33. pycforge/converter/core/diagnostics.py +95 -0
  34. pycforge/converter/core/enums.py +23 -0
  35. pycforge/converter/core/fingerprint.py +22 -0
  36. pycforge/converter/core/pipeline.py +8 -0
  37. pycforge/converter/core/progress.py +25 -0
  38. pycforge/converter/core/request.py +50 -0
  39. pycforge/converter/core/resource_policy.py +31 -0
  40. pycforge/converter/core/result.py +23 -0
  41. pycforge/converter/core/serialization.py +36 -0
  42. pycforge/converter/core/stage.py +10 -0
  43. pycforge/converter/core/stage_artifact.py +80 -0
  44. pycforge/converter/core/stage_outcome.py +15 -0
  45. pycforge/converter/decision_trace/__init__.py +0 -0
  46. pycforge/converter/decision_trace/recorder.py +52 -0
  47. pycforge/converter/facade.py +459 -0
  48. pycforge/converter/frontend/__init__.py +4 -0
  49. pycforge/converter/frontend/normalizer.py +59 -0
  50. pycforge/converter/frontend/parser.py +20 -0
  51. pycforge/converter/frontend/source_document.py +93 -0
  52. pycforge/converter/frontend/stages.py +518 -0
  53. pycforge/converter/frontend/validation.py +76 -0
  54. pycforge/converter/io/__init__.py +0 -0
  55. pycforge/converter/io/atomic_writer.py +33 -0
  56. pycforge/converter/ir/__init__.py +1 -0
  57. pycforge/converter/ir/c_ir/__init__.py +4 -0
  58. pycforge/converter/ir/c_ir/builder.py +26 -0
  59. pycforge/converter/ir/c_ir/model.py +318 -0
  60. pycforge/converter/ir/c_ir/serialization.py +88 -0
  61. pycforge/converter/ir/c_ir/validation.py +834 -0
  62. pycforge/converter/ir/python_ir/__init__.py +17 -0
  63. pycforge/converter/ir/python_ir/nodes.py +86 -0
  64. pycforge/converter/keyword_calls/__init__.py +68 -0
  65. pycforge/converter/keyword_calls/analysis.py +458 -0
  66. pycforge/converter/keyword_calls/lowering.py +271 -0
  67. pycforge/converter/keyword_calls/model.py +304 -0
  68. pycforge/converter/keyword_calls/validation.py +802 -0
  69. pycforge/converter/keyword_only_calls/__init__.py +68 -0
  70. pycforge/converter/keyword_only_calls/analysis.py +640 -0
  71. pycforge/converter/keyword_only_calls/lowering.py +376 -0
  72. pycforge/converter/keyword_only_calls/model.py +328 -0
  73. pycforge/converter/keyword_only_calls/validation.py +1357 -0
  74. pycforge/converter/lowering.py +1000 -0
  75. pycforge/converter/modules/__init__.py +13 -0
  76. pycforge/converter/modules/analysis.py +1250 -0
  77. pycforge/converter/modules/lowering.py +200 -0
  78. pycforge/converter/modules/model.py +73 -0
  79. pycforge/converter/modules/stage.py +192 -0
  80. pycforge/converter/numeric_semantics/__init__.py +23 -0
  81. pycforge/converter/numeric_semantics/analysis.py +420 -0
  82. pycforge/converter/numeric_semantics/lowering.py +153 -0
  83. pycforge/converter/numeric_semantics/model.py +123 -0
  84. pycforge/converter/records/__init__.py +34 -0
  85. pycforge/converter/records/analysis.py +1394 -0
  86. pycforge/converter/records/lowering.py +393 -0
  87. pycforge/converter/records/model.py +319 -0
  88. pycforge/converter/rules/__init__.py +3 -0
  89. pycforge/converter/support_templates/__init__.py +49 -0
  90. pycforge/converter/support_templates/assembly.py +106 -0
  91. pycforge/converter/support_templates/factories.py +348 -0
  92. pycforge/converter/support_templates/model.py +159 -0
  93. pycforge/converter/support_templates/registry.py +388 -0
  94. pycforge/converter/telemetry/__init__.py +0 -0
  95. pycforge/converter/telemetry/sink.py +39 -0
  96. pycforge/ide/__init__.py +19 -0
  97. pycforge/ide/__main__.py +5 -0
  98. pycforge/ide/_worker_event_codec.py +276 -0
  99. pycforge/ide/_worker_protocol_json.py +197 -0
  100. pycforge/ide/_worker_protocol_types.py +90 -0
  101. pycforge/ide/_worker_request_codec.py +200 -0
  102. pycforge/ide/_worker_request_data.py +260 -0
  103. pycforge/ide/_worker_result_data.py +343 -0
  104. pycforge/ide/action_contract.py +469 -0
  105. pycforge/ide/action_validation.py +229 -0
  106. pycforge/ide/command_palette.py +223 -0
  107. pycforge/ide/controller.py +904 -0
  108. pycforge/ide/controller_conversion.py +546 -0
  109. pycforge/ide/controller_io.py +205 -0
  110. pycforge/ide/editor.py +951 -0
  111. pycforge/ide/editor_commands_qt.py +274 -0
  112. pycforge/ide/editor_lexical.py +43 -0
  113. pycforge/ide/editor_sidebars.py +236 -0
  114. pycforge/ide/editor_syntax.py +243 -0
  115. pycforge/ide/find_replace.py +535 -0
  116. pycforge/ide/icons.py +91 -0
  117. pycforge/ide/io_service.py +196 -0
  118. pycforge/ide/model.py +164 -0
  119. pycforge/ide/panels.py +903 -0
  120. pycforge/ide/positions.py +220 -0
  121. pycforge/ide/process_worker.py +130 -0
  122. pycforge/ide/qt.py +230 -0
  123. pycforge/ide/qt_actions.py +418 -0
  124. pycforge/ide/qt_close.py +169 -0
  125. pycforge/ide/qt_command_palette.py +297 -0
  126. pycforge/ide/qt_contract.py +220 -0
  127. pycforge/ide/qt_documents.py +590 -0
  128. pycforge/ide/qt_editor_buffers.py +113 -0
  129. pycforge/ide/qt_editor_surfaces.py +112 -0
  130. pycforge/ide/qt_menus.py +324 -0
  131. pycforge/ide/qt_projection.py +500 -0
  132. pycforge/ide/qt_shell.py +348 -0
  133. pycforge/ide/qt_shell_interactions.py +320 -0
  134. pycforge/ide/qt_state.py +393 -0
  135. pycforge/ide/qt_workspace_features.py +398 -0
  136. pycforge/ide/qt_workspace_navigation.py +208 -0
  137. pycforge/ide/qt_workspace_observers.py +173 -0
  138. pycforge/ide/qt_workspace_panels.py +545 -0
  139. pycforge/ide/qt_workspace_widgets.py +228 -0
  140. pycforge/ide/resources/icons/about.svg +1 -0
  141. pycforge/ide/resources/icons/add-document.svg +1 -0
  142. pycforge/ide/resources/icons/brand-mark.svg +1 -0
  143. pycforge/ide/resources/icons/bundle-search.svg +1 -0
  144. pycforge/ide/resources/icons/cancel.svg +1 -0
  145. pycforge/ide/resources/icons/check.svg +1 -0
  146. pycforge/ide/resources/icons/chevron-right.svg +1 -0
  147. pycforge/ide/resources/icons/close.svg +1 -0
  148. pycforge/ide/resources/icons/collapse-all.svg +1 -0
  149. pycforge/ide/resources/icons/command-palette.svg +1 -0
  150. pycforge/ide/resources/icons/convert.svg +1 -0
  151. pycforge/ide/resources/icons/copy.svg +1 -0
  152. pycforge/ide/resources/icons/cut.svg +1 -0
  153. pycforge/ide/resources/icons/decision-trace.svg +1 -0
  154. pycforge/ide/resources/icons/details.svg +1 -0
  155. pycforge/ide/resources/icons/diagnostics.svg +1 -0
  156. pycforge/ide/resources/icons/duplicate-line.svg +1 -0
  157. pycforge/ide/resources/icons/exit.svg +1 -0
  158. pycforge/ide/resources/icons/expand-all.svg +1 -0
  159. pycforge/ide/resources/icons/export.svg +1 -0
  160. pycforge/ide/resources/icons/find.svg +1 -0
  161. pycforge/ide/resources/icons/go-to-line.svg +1 -0
  162. pycforge/ide/resources/icons/go-to-output.svg +1 -0
  163. pycforge/ide/resources/icons/go-to-source.svg +1 -0
  164. pycforge/ide/resources/icons/history.svg +1 -0
  165. pycforge/ide/resources/icons/indent.svg +1 -0
  166. pycforge/ide/resources/icons/link-c.svg +1 -0
  167. pycforge/ide/resources/icons/mappings.svg +1 -0
  168. pycforge/ide/resources/icons/module.svg +1 -0
  169. pycforge/ide/resources/icons/move-down.svg +1 -0
  170. pycforge/ide/resources/icons/move-line-down.svg +1 -0
  171. pycforge/ide/resources/icons/move-line-up.svg +1 -0
  172. pycforge/ide/resources/icons/move-up.svg +1 -0
  173. pycforge/ide/resources/icons/next.svg +1 -0
  174. pycforge/ide/resources/icons/open.svg +1 -0
  175. pycforge/ide/resources/icons/outdent.svg +1 -0
  176. pycforge/ide/resources/icons/outline.svg +1 -0
  177. pycforge/ide/resources/icons/paste.svg +1 -0
  178. pycforge/ide/resources/icons/previous.svg +1 -0
  179. pycforge/ide/resources/icons/primary-module.svg +1 -0
  180. pycforge/ide/resources/icons/redo.svg +1 -0
  181. pycforge/ide/resources/icons/remove-document.svg +1 -0
  182. pycforge/ide/resources/icons/replace.svg +1 -0
  183. pycforge/ide/resources/icons/save-as.svg +1 -0
  184. pycforge/ide/resources/icons/save.svg +1 -0
  185. pycforge/ide/resources/icons/select-all.svg +1 -0
  186. pycforge/ide/resources/icons/settings.svg +1 -0
  187. pycforge/ide/resources/icons/show-c.svg +1 -0
  188. pycforge/ide/resources/icons/split-view.svg +1 -0
  189. pycforge/ide/resources/icons/summary.svg +1 -0
  190. pycforge/ide/resources/icons/telemetry.svg +1 -0
  191. pycforge/ide/resources/icons/toggle-comment.svg +1 -0
  192. pycforge/ide/resources/icons/toggle-fold.svg +1 -0
  193. pycforge/ide/resources/icons/undo.svg +1 -0
  194. pycforge/ide/resources/icons/whitespace.svg +1 -0
  195. pycforge/ide/revisions.py +400 -0
  196. pycforge/ide/search_service.py +280 -0
  197. pycforge/ide/session_history.py +150 -0
  198. pycforge/ide/source_editing.py +417 -0
  199. pycforge/ide/source_structure.py +558 -0
  200. pycforge/ide/source_structure_async.py +191 -0
  201. pycforge/ide/supervisor.py +503 -0
  202. pycforge/ide/theme.py +119 -0
  203. pycforge/ide/theme_stylesheet.py +598 -0
  204. pycforge/ide/theme_workspace_stylesheet.py +155 -0
  205. pycforge/ide/visual_tokens.py +142 -0
  206. pycforge/ide/worker_protocol.py +80 -0
  207. pycforge/ide/workspace_search.py +462 -0
  208. pycforge/ide/workspace_session.py +256 -0
  209. pycforge/laboratory/__init__.py +6 -0
  210. pycforge/laboratory/audits.py +2244 -0
  211. pycforge/laboratory/checkpoint_e.py +2685 -0
  212. pycforge/laboratory/cli.py +119 -0
  213. pycforge/laboratory/exit_codes.py +11 -0
  214. pycforge/laboratory/keyword_audit.py +661 -0
  215. pycforge/laboratory/keyword_only_audit.py +481 -0
  216. pycforge-0.15.2.dist-info/METADATA +209 -0
  217. pycforge-0.15.2.dist-info/RECORD +221 -0
  218. pycforge-0.15.2.dist-info/WHEEL +5 -0
  219. pycforge-0.15.2.dist-info/entry_points.txt +5 -0
  220. pycforge-0.15.2.dist-info/licenses/LICENSE +674 -0
  221. pycforge-0.15.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,469 @@
1
+ """Headless contracts for PyCForge application actions and menu surfaces.
2
+
3
+ The declarations in this module contain no Qt objects. They are the stable
4
+ source for action identity, user-facing text, shortcuts, accessibility, and
5
+ surface placement. The optional Qt adapter materializes these declarations
6
+ without becoming a second source of action metadata.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass
12
+ from enum import Enum
13
+ from types import MappingProxyType
14
+ from typing import Iterable, Mapping
15
+
16
+
17
+ MAX_DYNAMIC_ACTIONS = 10
18
+ MAX_DYNAMIC_LABEL_CHARS = 160
19
+ MAX_DYNAMIC_TOOLTIP_CHARS = 4096
20
+
21
+
22
+ class PlacementKind(str, Enum):
23
+ """Kinds of entries accepted by a declared action surface."""
24
+
25
+ ACTION = "action"
26
+ SEPARATOR = "separator"
27
+ SUBMENU = "submenu"
28
+ DYNAMIC = "dynamic"
29
+
30
+
31
+ class SurfaceKind(str, Enum):
32
+ """Presentation roles supported by the Phase 15 action foundation."""
33
+
34
+ MENU = "menu"
35
+ TOOLBAR = "toolbar"
36
+ CONTEXT = "context"
37
+
38
+
39
+ @dataclass(frozen=True, slots=True)
40
+ class ActionSpec:
41
+ """Complete immutable presentation contract for one application action."""
42
+
43
+ action_id: str
44
+ menu_text: str
45
+ toolbar_text: str
46
+ tooltip: str
47
+ accessible_name: str
48
+ icon_name: str | None = None
49
+ standard_shortcut: str | None = None
50
+ shortcut: str | None = None
51
+ shortcut_context: str = "window"
52
+ checkable: bool = False
53
+ tone: str = "normal"
54
+ dynamic: bool = False
55
+
56
+
57
+ @dataclass(frozen=True, slots=True)
58
+ class ActionState:
59
+ """One bounded enabled/checked projection supplied by the application."""
60
+
61
+ enabled: bool = True
62
+ checked: bool | None = None
63
+ visible: bool = True
64
+
65
+
66
+ @dataclass(frozen=True, slots=True)
67
+ class ActionPlacement:
68
+ """An action, separator, submenu, or dynamic group in a surface."""
69
+
70
+ kind: PlacementKind
71
+ target: str = ""
72
+
73
+ @classmethod
74
+ def action(cls, action_id: str) -> "ActionPlacement":
75
+ return cls(PlacementKind.ACTION, action_id)
76
+
77
+ @classmethod
78
+ def separator(cls) -> "ActionPlacement":
79
+ return cls(PlacementKind.SEPARATOR)
80
+
81
+ @classmethod
82
+ def submenu(cls, surface_id: str) -> "ActionPlacement":
83
+ return cls(PlacementKind.SUBMENU, surface_id)
84
+
85
+ @classmethod
86
+ def dynamic(cls, group_id: str) -> "ActionPlacement":
87
+ return cls(PlacementKind.DYNAMIC, group_id)
88
+
89
+
90
+ @dataclass(frozen=True, slots=True)
91
+ class SurfaceSpec:
92
+ """Declarative composition of one main, toolbar, or context surface."""
93
+
94
+ surface_id: str
95
+ kind: SurfaceKind
96
+ title: str
97
+ accessible_name: str
98
+ placements: tuple[ActionPlacement, ...]
99
+
100
+
101
+ @dataclass(frozen=True, slots=True)
102
+ class DynamicActionEntry:
103
+ """Validated data for one bounded parameterized action instance."""
104
+
105
+ key: str
106
+ label: str
107
+ tooltip: str
108
+ accessible_name: str
109
+ payload: str
110
+ enabled: bool = True
111
+
112
+
113
+ def _action(
114
+ action_id: str,
115
+ menu_text: str,
116
+ tooltip: str,
117
+ accessible_name: str,
118
+ *,
119
+ toolbar_text: str | None = None,
120
+ icon_name: str | None = None,
121
+ standard_shortcut: str | None = None,
122
+ shortcut: str | None = None,
123
+ shortcut_context: str = "window",
124
+ checkable: bool = False,
125
+ tone: str = "normal",
126
+ dynamic: bool = False,
127
+ ) -> ActionSpec:
128
+ return ActionSpec(
129
+ action_id=action_id,
130
+ menu_text=menu_text,
131
+ toolbar_text=toolbar_text or menu_text.replace("&", ""),
132
+ tooltip=tooltip,
133
+ accessible_name=accessible_name,
134
+ icon_name=icon_name,
135
+ standard_shortcut=standard_shortcut,
136
+ shortcut=shortcut,
137
+ shortcut_context=shortcut_context,
138
+ checkable=checkable,
139
+ tone=tone,
140
+ dynamic=dynamic,
141
+ )
142
+
143
+
144
+ # Row fields after the four required strings are:
145
+ # toolbar, icon, standard key, literal key, context, checkable, tone, dynamic.
146
+ _ACTION_ROWS = (
147
+ ("file.open_python", "&Open Python…", "Open Python documents into the source bundle", "Open Python documents", "Open", "open", "Open", None, "window", False, "normal", False),
148
+ ("file.open_recent", "Open Recent Python", "Open this recent Python document", "Open recent Python document", None, "open", None, None, "window", False, "normal", True),
149
+ ("bundle.new_module", "&New Module", "Add a blank logical module to the source bundle", "Add source bundle module", "New Module", "add-document", "New", None, "window", False, "normal", False),
150
+ ("bundle.remove_module", "&Remove Module", "Remove the selected module from the source bundle", "Remove selected source bundle module", None, "remove-document", None, "Ctrl+Shift+W", "window", False, "danger", False),
151
+ ("bundle.move_up", "Move Module &Up", "Move the selected module one position earlier", "Move selected module up", None, "move-up", None, "Alt+Up", "widget", False, "normal", False),
152
+ ("bundle.move_down", "Move Module &Down", "Move the selected module one position later", "Move selected module down", None, "move-down", None, "Alt+Down", "widget", False, "normal", False),
153
+ ("bundle.make_primary", "Make &Primary", "Make the selected module the primary source document", "Make selected module primary", None, "primary-module", None, None, "window", False, "normal", False),
154
+ ("file.save_python", "&Save Python", "Atomically save the active Python document", "Save active Python document", "Save Python", "save-python", "Save", None, "window", False, "normal", False),
155
+ ("file.save_python_as", "Save Python &As…", "Atomically save the active document to a new Python path", "Save active Python document as", None, "save-as", "SaveAs", None, "window", False, "normal", False),
156
+ ("output.set_destination", "Set C &Destination…", "Choose the explicit destination for generated C", "Set generated C destination", "C Destination", "link-c", None, "Ctrl+Shift+L", "window", False, "normal", False),
157
+ ("output.save_c", "Save Generated &C", "Atomically save fresh generated C to its destination", "Save current generated C", "Save C", "save-c", None, "Ctrl+Alt+S", "window", False, "normal", False),
158
+ ("conversion.convert", "&Transpile Source Bundle", "Transpile the complete logical source bundle to C source", "Transpile source bundle to C source", "Transpile", "convert", None, "Ctrl+Return", "window", False, "primary", False),
159
+ ("conversion.cancel", "&Cancel Transpilation", "Cancel the current isolated transpilation", "Cancel current transpilation", "Cancel", "cancel", None, None, "window", False, "danger", False),
160
+ ("edit.undo", "&Undo", "Undo the most recent source edit", "Undo source edit", None, "undo", "Undo", None, "window", False, "normal", False),
161
+ ("edit.redo", "&Redo", "Redo the most recently undone source edit", "Redo source edit", None, "redo", "Redo", None, "window", False, "normal", False),
162
+ ("edit.cut", "Cu&t", "Cut the selected writable text", "Cut selected text", None, "cut", "Cut", None, "window", False, "normal", False),
163
+ ("edit.copy", "&Copy", "Copy the current selection", "Copy current selection", None, "copy", "Copy", None, "window", False, "normal", False),
164
+ ("edit.paste", "&Paste", "Paste text into the writable source surface", "Paste text into source", None, "paste", "Paste", None, "window", False, "normal", False),
165
+ ("edit.select_all", "Select &All", "Select all text or visible records in the focused surface", "Select all content", None, "select-all", "SelectAll", None, "window", False, "normal", False),
166
+ ("edit.duplicate_line", "&Duplicate Line or Selection", "Duplicate the selected Python source lines", "Duplicate selected Python source lines", None, "duplicate-line", None, "Ctrl+Shift+D", "widget", False, "normal", False),
167
+ ("edit.move_line_up", "Move &Line Up", "Move the selected Python source lines one line earlier", "Move selected Python source lines up", None, "move-line-up", None, "Alt+Shift+Up", "widget", False, "normal", False),
168
+ ("edit.move_line_down", "Move Line Do&wn", "Move the selected Python source lines one line later", "Move selected Python source lines down", None, "move-line-down", None, "Alt+Shift+Down", "widget", False, "normal", False),
169
+ ("edit.indent", "&Indent Lines", "Indent the selected Python source lines by four spaces", "Indent selected Python source lines", None, "indent", None, "Ctrl+]", "widget", False, "normal", False),
170
+ ("edit.outdent", "&Outdent Lines", "Outdent the selected Python source lines by up to four spaces", "Outdent selected Python source lines", None, "outdent", None, "Ctrl+[", "widget", False, "normal", False),
171
+ ("edit.toggle_comment", "Toggle Co&mment", "Toggle Python line comments for the selected source lines", "Toggle comments on selected Python source lines", None, "toggle-comment", None, "Ctrl+/", "widget", False, "normal", False),
172
+ ("search.find", "&Find…", "Find text in the focused editor", "Find text", "Find", "find", "Find", None, "window", False, "normal", False),
173
+ ("search.replace", "R&eplace…", "Find and replace text in Python source", "Find and replace Python source text", None, "replace", "Replace", None, "window", False, "normal", False),
174
+ ("search.bundle", "Find in Source &Bundle…", "Search exact text across the already-open source bundle", "Find text in the open source bundle", "Bundle Search", "bundle-search", None, "Ctrl+Shift+F", "window", False, "normal", False),
175
+ ("search.next_match", "Find &Next", "Move to the next literal search match", "Find next match", None, "next-match", "FindNext", None, "widget", False, "normal", False),
176
+ ("search.previous_match", "Find Pre&vious", "Move to the previous literal search match", "Find previous match", None, "previous-match", None, "Shift+F3", "widget", False, "normal", False),
177
+ ("search.replace_current", "Replace &Current", "Replace the active Python source match", "Replace current source match", None, "replace", None, None, "widget", False, "normal", False),
178
+ ("search.replace_all", "Replace &All", "Replace every exact match in the active Python source document", "Replace all source matches", None, "replace", None, None, "widget", False, "normal", False),
179
+ ("search.close", "&Close Find", "Close the find and replace controls", "Close find and replace", None, "close", None, "Escape", "widget", False, "normal", False),
180
+ ("view.source_bundle", "Source &Bundle", "Show or hide the source bundle navigator", "Show or hide source bundle", None, "settings", None, "Ctrl+Alt+B", "window", True, "normal", False),
181
+ ("view.generated_c", "Generated &C", "Show or hide the read-only generated C viewer", "Show or hide generated C", None, "view-c", None, "Ctrl+Shift+C", "window", True, "normal", False),
182
+ ("view.conversion_details", "Transpilation &Details", "Show or hide structured transpilation details", "Show or hide transpilation details", None, "details", None, "Ctrl+Alt+D", "window", True, "normal", False),
183
+ ("view.outline", "&Outline", "Show the bounded outline for already-open Python source", "Show Python source outline", None, "outline", None, "Ctrl+Shift+O", "window", False, "normal", False),
184
+ ("view.conversion_history", "Transpilation &History", "Show bounded transpilation history for this application session", "Show current session transpilation history", None, "history", None, "Ctrl+Alt+H", "window", False, "normal", False),
185
+ ("view.whitespace", "Show &Whitespace", "Show or hide whitespace marks in Python source views", "Show or hide Python source whitespace", None, "whitespace", None, "Ctrl+Alt+W", "window", True, "normal", False),
186
+ ("view.split_source", "Split Python &View", "Show or hide a second synchronized Python source view", "Split the Python source editor", None, "split-view", None, "Ctrl+\\", "window", True, "normal", False),
187
+ ("editor.toggle_fold", "Toggle Code Fold &State", "Fold or unfold the Python source region at the cursor", "Toggle Python source code fold", None, "toggle-fold", None, "Ctrl+Shift+[", "widget", False, "normal", False),
188
+ ("navigation.go_to_line", "&Go to Line…", "Move to a line in the active Python source document", "Go to a Python source line", None, "go-to-line", None, "Ctrl+G", "window", False, "normal", False),
189
+ ("workspace.command_palette", "&Command Palette…", "Search and invoke enabled declared PyCForge actions", "Open the PyCForge command palette", "Commands", "command-palette", None, "Ctrl+Shift+P", "window", False, "normal", False),
190
+ ("tree.expand_all", "E&xpand All", "Expand every currently projected inspector branch", "Expand all inspector branches", None, "expand-all", None, None, "window", False, "normal", False),
191
+ ("tree.collapse_all", "C&ollapse All", "Collapse every currently projected inspector branch", "Collapse all inspector branches", None, "collapse-all", None, None, "window", False, "normal", False),
192
+ ("diagnostics.reveal_source", "&Reveal in Python Source", "Reveal the selected diagnostic in its Python source document", "Reveal selected diagnostic in Python source", None, "go-to-source", None, None, "window", False, "normal", False),
193
+ ("mappings.reveal_output", "&Reveal in Generated C", "Reveal the selected mapping in read-only generated C", "Reveal selected mapping in generated C", None, "go-to-output", None, None, "window", False, "normal", False),
194
+ ("mappings.reveal_source", "Reveal Source &Module", "Reveal the source module owned by the selected mapping", "Reveal selected mapping source module", None, "go-to-source", None, None, "window", False, "normal", False),
195
+ )
196
+
197
+
198
+ def _catalog_action(row: tuple[object, ...]) -> ActionSpec:
199
+ (
200
+ action_id, menu_text, tooltip, accessible_name, toolbar_text,
201
+ icon_name, standard_shortcut, shortcut, shortcut_context,
202
+ checkable, tone, dynamic,
203
+ ) = row
204
+ return _action(
205
+ str(action_id), str(menu_text), str(tooltip), str(accessible_name),
206
+ toolbar_text=None if toolbar_text is None else str(toolbar_text),
207
+ icon_name=None if icon_name is None else str(icon_name),
208
+ standard_shortcut=(
209
+ None if standard_shortcut is None else str(standard_shortcut)
210
+ ),
211
+ shortcut=None if shortcut is None else str(shortcut),
212
+ shortcut_context=str(shortcut_context),
213
+ checkable=bool(checkable), tone=str(tone), dynamic=bool(dynamic),
214
+ )
215
+
216
+
217
+ _ACTION_SPECS = tuple(_catalog_action(row) for row in _ACTION_ROWS)
218
+
219
+ ACTION_SPECS: Mapping[str, ActionSpec] = MappingProxyType(
220
+ {spec.action_id: spec for spec in _ACTION_SPECS}
221
+ )
222
+
223
+ DYNAMIC_ACTION_GROUPS: Mapping[str, str] = MappingProxyType(
224
+ {"recent_python": "file.open_recent"}
225
+ )
226
+
227
+
228
+ def _surface(
229
+ surface_id: str,
230
+ kind: SurfaceKind,
231
+ title: str,
232
+ accessible_name: str,
233
+ *placements: ActionPlacement,
234
+ ) -> SurfaceSpec:
235
+ return SurfaceSpec(
236
+ surface_id,
237
+ kind,
238
+ title,
239
+ accessible_name,
240
+ tuple(placements),
241
+ )
242
+
243
+
244
+ def _layout(*tokens: str | None) -> tuple[ActionPlacement, ...]:
245
+ placements: list[ActionPlacement] = []
246
+ for token in tokens:
247
+ if token is None:
248
+ placements.append(ActionPlacement.separator())
249
+ elif token.startswith(">"):
250
+ placements.append(ActionPlacement.submenu(token[1:]))
251
+ elif token.startswith("$"):
252
+ placements.append(ActionPlacement.dynamic(token[1:]))
253
+ else:
254
+ placements.append(ActionPlacement.action(token))
255
+ return tuple(placements)
256
+
257
+
258
+ _SURFACE_SPECS = (
259
+ _surface(
260
+ "menu.file", SurfaceKind.MENU, "&File", "File menu",
261
+ *_layout(
262
+ "file.open_python", ">menu.open_recent", None,
263
+ "bundle.new_module", "bundle.remove_module", None,
264
+ "file.save_python", "file.save_python_as", None,
265
+ "output.set_destination", "output.save_c",
266
+ ),
267
+ ),
268
+ _surface(
269
+ "menu.open_recent", SurfaceKind.MENU, "Open Recen&t",
270
+ "Open recent Python documents menu", *_layout("$recent_python"),
271
+ ),
272
+ _surface(
273
+ "menu.edit", SurfaceKind.MENU, "&Edit", "Edit menu",
274
+ *_layout(
275
+ "edit.undo", "edit.redo", None, "edit.cut", "edit.copy",
276
+ "edit.paste", "edit.select_all", None,
277
+ "edit.duplicate_line", "edit.move_line_up",
278
+ "edit.move_line_down", "edit.indent", "edit.outdent",
279
+ "edit.toggle_comment", None, "search.find", "search.replace",
280
+ ),
281
+ ),
282
+ _surface(
283
+ "menu.view", SurfaceKind.MENU, "&View", "View menu",
284
+ *_layout(
285
+ "view.source_bundle", "view.generated_c",
286
+ "view.conversion_details", None, "view.split_source",
287
+ "view.whitespace", "editor.toggle_fold",
288
+ ),
289
+ ),
290
+ _surface(
291
+ "menu.navigate", SurfaceKind.MENU, "&Navigate", "Navigate menu",
292
+ *_layout(
293
+ "navigation.go_to_line", "search.bundle", "view.outline",
294
+ "view.conversion_history", None,
295
+ "workspace.command_palette",
296
+ ),
297
+ ),
298
+ _surface(
299
+ "menu.conversion", SurfaceKind.MENU, "&Transpile",
300
+ "Transpile menu",
301
+ *_layout("conversion.convert", "conversion.cancel"),
302
+ ),
303
+ _surface(
304
+ "toolbar.workspace", SurfaceKind.TOOLBAR, "PyCForge Workspace",
305
+ "PyCForge workspace actions",
306
+ *_layout(
307
+ "file.open_python", "file.save_python", None,
308
+ "conversion.convert", "conversion.cancel", None,
309
+ "view.generated_c", "view.conversion_details", "search.find",
310
+ None, "output.set_destination", "output.save_c",
311
+ ),
312
+ ),
313
+ _surface(
314
+ "context.python_source", SurfaceKind.CONTEXT, "Python Source",
315
+ "Python source editor menu",
316
+ *_layout(
317
+ "edit.undo", "edit.redo", None, "edit.cut", "edit.copy",
318
+ "edit.paste", None, "edit.select_all", None,
319
+ "edit.duplicate_line", "edit.move_line_up",
320
+ "edit.move_line_down", "edit.indent", "edit.outdent",
321
+ "edit.toggle_comment", None, "search.find",
322
+ "search.replace", "navigation.go_to_line",
323
+ "editor.toggle_fold",
324
+ ),
325
+ ),
326
+ _surface(
327
+ "context.generated_c", SurfaceKind.CONTEXT, "Generated C",
328
+ "Generated C viewer menu",
329
+ *_layout("edit.copy", "edit.select_all", None, "search.find"),
330
+ ),
331
+ _surface(
332
+ "context.source_bundle", SurfaceKind.CONTEXT, "Source Bundle",
333
+ "Source bundle menu",
334
+ *_layout(
335
+ "bundle.new_module", "bundle.remove_module", None,
336
+ "bundle.move_up", "bundle.move_down", "bundle.make_primary",
337
+ ),
338
+ ),
339
+ _surface(
340
+ "context.document_tabs", SurfaceKind.CONTEXT, "Document Tabs",
341
+ "Python document tabs menu",
342
+ *_layout(
343
+ "file.save_python", "file.save_python_as", None,
344
+ "bundle.remove_module", "bundle.make_primary", None,
345
+ "view.split_source",
346
+ ),
347
+ ),
348
+ _surface(
349
+ "context.diagnostics", SurfaceKind.CONTEXT, "Diagnostics",
350
+ "Diagnostics menu",
351
+ *_layout("edit.copy", None, "diagnostics.reveal_source"),
352
+ ),
353
+ _surface(
354
+ "context.mappings", SurfaceKind.CONTEXT, "Mappings",
355
+ "Source mappings menu",
356
+ *_layout(
357
+ "edit.copy", None, "mappings.reveal_output",
358
+ "mappings.reveal_source",
359
+ ),
360
+ ),
361
+ _surface(
362
+ "context.bundle_search", SurfaceKind.CONTEXT, "Bundle Search",
363
+ "Source bundle search results menu",
364
+ *_layout("edit.copy"),
365
+ ),
366
+ _surface(
367
+ "context.conversion_history", SurfaceKind.CONTEXT,
368
+ "Transpilation History", "Transpilation history menu",
369
+ *_layout("edit.copy"),
370
+ ),
371
+ _surface(
372
+ "context.inspector", SurfaceKind.CONTEXT, "Inspector",
373
+ "Inspector tree menu",
374
+ *_layout(
375
+ "edit.copy", None, "tree.expand_all", "tree.collapse_all",
376
+ ),
377
+ ),
378
+ _surface(
379
+ "context.text_input", SurfaceKind.CONTEXT, "Text Input",
380
+ "Text editing menu",
381
+ *_layout(
382
+ "edit.undo", "edit.redo", None, "edit.cut", "edit.copy",
383
+ "edit.paste", None, "edit.select_all",
384
+ ),
385
+ ),
386
+ _surface(
387
+ "context.read_only_text", SurfaceKind.CONTEXT, "Read-only Text",
388
+ "Read-only text menu",
389
+ *_layout("edit.copy", "edit.select_all"),
390
+ ),
391
+ )
392
+
393
+ SURFACE_SPECS: Mapping[str, SurfaceSpec] = MappingProxyType(
394
+ {spec.surface_id: spec for spec in _SURFACE_SPECS}
395
+ )
396
+
397
+ MAIN_MENU_SURFACES = (
398
+ "menu.file",
399
+ "menu.edit",
400
+ "menu.view",
401
+ "menu.navigate",
402
+ "menu.conversion",
403
+ )
404
+
405
+
406
+ def validated_dynamic_entries(
407
+ entries: Iterable[DynamicActionEntry],
408
+ ) -> tuple[DynamicActionEntry, ...]:
409
+ """Return bounded entries after rejecting ambiguous or oversized data."""
410
+
411
+ records = tuple(entries)
412
+ if len(records) > MAX_DYNAMIC_ACTIONS:
413
+ raise ValueError(
414
+ f"dynamic actions exceed the limit of {MAX_DYNAMIC_ACTIONS}"
415
+ )
416
+ seen: set[str] = set()
417
+ for entry in records:
418
+ if not isinstance(entry, DynamicActionEntry):
419
+ raise TypeError("dynamic entries must be DynamicActionEntry values")
420
+ if not entry.key or entry.key in seen:
421
+ raise ValueError("dynamic action keys must be non-empty and unique")
422
+ seen.add(entry.key)
423
+ if not entry.label or len(entry.label) > MAX_DYNAMIC_LABEL_CHARS:
424
+ raise ValueError("dynamic action label is empty or oversized")
425
+ if (
426
+ not entry.tooltip
427
+ or len(entry.tooltip) > MAX_DYNAMIC_TOOLTIP_CHARS
428
+ ):
429
+ raise ValueError("dynamic action tooltip is empty or oversized")
430
+ if not entry.accessible_name:
431
+ raise ValueError("dynamic action accessible name is required")
432
+ if not isinstance(entry.payload, str):
433
+ raise TypeError("dynamic action payload must be text")
434
+ return records
435
+
436
+
437
+ def validate_action_contract(
438
+ *,
439
+ action_specs: Mapping[str, ActionSpec] = ACTION_SPECS,
440
+ surface_specs: Mapping[str, SurfaceSpec] = SURFACE_SPECS,
441
+ dynamic_groups: Mapping[str, str] = DYNAMIC_ACTION_GROUPS,
442
+ ) -> tuple[str, ...]:
443
+ """Return deterministic contract errors without importing optional Qt."""
444
+
445
+ from .action_validation import validate_action_contract as validate
446
+
447
+ return validate(
448
+ action_specs=action_specs,
449
+ surface_specs=surface_specs,
450
+ dynamic_groups=dynamic_groups,
451
+ )
452
+
453
+
454
+ __all__ = [
455
+ "ACTION_SPECS",
456
+ "DYNAMIC_ACTION_GROUPS",
457
+ "MAIN_MENU_SURFACES",
458
+ "MAX_DYNAMIC_ACTIONS",
459
+ "ActionPlacement",
460
+ "ActionSpec",
461
+ "ActionState",
462
+ "DynamicActionEntry",
463
+ "PlacementKind",
464
+ "SURFACE_SPECS",
465
+ "SurfaceKind",
466
+ "SurfaceSpec",
467
+ "validate_action_contract",
468
+ "validated_dynamic_entries",
469
+ ]