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,17 @@
1
+ from .nodes import (
2
+ Provenance,
3
+ PythonIRBundle,
4
+ PythonIRBundleDocument,
5
+ PythonIRModule,
6
+ PythonIRNode,
7
+ python_ir_reference_ids,
8
+ )
9
+
10
+ __all__ = [
11
+ "PythonIRBundle",
12
+ "PythonIRBundleDocument",
13
+ "PythonIRModule",
14
+ "PythonIRNode",
15
+ "Provenance",
16
+ "python_ir_reference_ids",
17
+ ]
@@ -0,0 +1,86 @@
1
+ from __future__ import annotations
2
+ from dataclasses import dataclass
3
+ from typing import Any
4
+
5
+ JsonValue = None|bool|int|float|str|tuple["JsonValue",...]|tuple[tuple[str,"JsonValue"],...]
6
+
7
+ _SCALAR_FIELD_NAMES={"id","name","arg","attr","asname","module","level","kind","kwd_attrs","rest","tag","type_comment","conversion","is_async","simple","lineno"}
8
+
9
+
10
+ def python_ir_reference_ids(kind:str,field_name:str,value:Any,known_ids:object|None=None)->tuple[str,...]:
11
+ """Return stable child IDs from a declared Python 3.11 AST child slot."""
12
+ if field_name in _SCALAR_FIELD_NAMES:
13
+ return ()
14
+ if field_name == "names" and kind in {"Global","Nonlocal"}:
15
+ return ()
16
+ if field_name == "value" and kind in {"Constant","MatchSingleton"}:
17
+ return ()
18
+ if isinstance(value,str) and value.startswith(("py-","syn-")):
19
+ return (value,) if known_ids is None or value in known_ids else ()
20
+ if isinstance(value,(tuple,list)):
21
+ return tuple(reference for item in value for reference in python_ir_reference_ids(kind,field_name,item,known_ids))
22
+ if isinstance(value,dict):
23
+ return tuple(reference for item in value.values() for reference in python_ir_reference_ids(kind,field_name,item,known_ids))
24
+ return ()
25
+
26
+ @dataclass(frozen=True, slots=True)
27
+ class Provenance:
28
+ origin_kind: str
29
+ source_span: dict[str,Any]|None
30
+ origin_node_ids: tuple[str,...]=()
31
+ def to_dict(self)->dict[str,Any]: return {"origin_kind":self.origin_kind,"source_span":self.source_span,"origin_node_ids":list(self.origin_node_ids)}
32
+
33
+ @dataclass(frozen=True, slots=True)
34
+ class PythonIRNode:
35
+ node_id: str
36
+ kind: str
37
+ fields: tuple[tuple[str,JsonValue],...]
38
+ provenance: Provenance
39
+ def to_dict(self)->dict[str,Any]:
40
+ def thaw(v:JsonValue)->Any:
41
+ if isinstance(v,tuple):
42
+ if v and all(isinstance(x,tuple) and len(x)==2 and isinstance(x[0],str) for x in v): return {k:thaw(x) for k,x in v}
43
+ return [thaw(x) for x in v]
44
+ return v
45
+ return {"node_id":self.node_id,"kind":self.kind,"fields":{k:thaw(v) for k,v in self.fields},"provenance":self.provenance.to_dict()}
46
+
47
+ @dataclass(frozen=True, slots=True)
48
+ class PythonIRModule:
49
+ schema_version: str
50
+ document_id: str
51
+ root_node_id: str
52
+ nodes: tuple[PythonIRNode,...]
53
+ def to_dict(self)->dict[str,Any]: return {"schema_version":self.schema_version,"document_id":self.document_id,"root_node_id":self.root_node_id,"nodes":[n.to_dict() for n in self.nodes]}
54
+
55
+
56
+ @dataclass(frozen=True, slots=True)
57
+ class PythonIRBundleDocument:
58
+ module_id: str
59
+ logical_name: str
60
+ bundle_ordinal: int
61
+ is_primary: bool
62
+ module: PythonIRModule
63
+
64
+ def to_dict(self) -> dict[str, Any]:
65
+ return {
66
+ "module_id": self.module_id,
67
+ "logical_name": self.logical_name,
68
+ "bundle_ordinal": self.bundle_ordinal,
69
+ "is_primary": self.is_primary,
70
+ "document_id": self.module.document_id,
71
+ "python_ir": self.module.to_dict(),
72
+ }
73
+
74
+
75
+ @dataclass(frozen=True, slots=True)
76
+ class PythonIRBundle:
77
+ schema_version: str
78
+ primary_module_id: str
79
+ documents: tuple[PythonIRBundleDocument, ...]
80
+
81
+ def to_dict(self) -> dict[str, Any]:
82
+ return {
83
+ "schema_version": self.schema_version,
84
+ "primary_module_id": self.primary_module_id,
85
+ "documents": [document.to_dict() for document in self.documents],
86
+ }
@@ -0,0 +1,68 @@
1
+ """Phase 14C exact direct keyword-call analysis and lowering."""
2
+
3
+ from .analysis import KeywordCallAnalyzer
4
+ from .model import (
5
+ KEYWORD_CALL_FACT_SCHEMA,
6
+ KEYWORD_CALL_KEY_DOMAIN,
7
+ KEYWORD_CALL_LOWERING_SHAPE,
8
+ KEYWORD_CALL_OBLIGATIONS,
9
+ KEYWORD_CALL_PROVENANCE_EVIDENCE,
10
+ KEYWORD_CALL_RULE_ID,
11
+ KEYWORD_CALL_RULE_VERSION,
12
+ KEYWORD_CALL_TABLE_DEPENDENCIES,
13
+ KEYWORD_CALL_TABLE_ID,
14
+ KeywordArgumentBindingFact,
15
+ KeywordCallAnalysis,
16
+ KeywordCallAnalysisCanceled,
17
+ KeywordCallAnalysisError,
18
+ KeywordCallBindingFact,
19
+ KeywordCallRejection,
20
+ KeywordCallValidationCanceled,
21
+ keyword_call_binding_id,
22
+ )
23
+ from .validation import validate_keyword_call_binding_facts
24
+
25
+
26
+ _LOWERING_EXPORTS = {
27
+ "KeywordCallCIRLowerer",
28
+ "KeywordCallLoweringServices",
29
+ "bind_keyword_call_lowerer",
30
+ }
31
+
32
+
33
+ def __getattr__(name: str):
34
+ """Keep analysis/validation imports independent of the C IR layer."""
35
+
36
+ if name not in _LOWERING_EXPORTS:
37
+ raise AttributeError(name)
38
+ from . import lowering
39
+
40
+ value = getattr(lowering, name)
41
+ globals()[name] = value
42
+ return value
43
+
44
+
45
+ __all__ = [
46
+ "KEYWORD_CALL_FACT_SCHEMA",
47
+ "KEYWORD_CALL_KEY_DOMAIN",
48
+ "KEYWORD_CALL_LOWERING_SHAPE",
49
+ "KEYWORD_CALL_OBLIGATIONS",
50
+ "KEYWORD_CALL_PROVENANCE_EVIDENCE",
51
+ "KEYWORD_CALL_RULE_ID",
52
+ "KEYWORD_CALL_RULE_VERSION",
53
+ "KEYWORD_CALL_TABLE_DEPENDENCIES",
54
+ "KEYWORD_CALL_TABLE_ID",
55
+ "KeywordArgumentBindingFact",
56
+ "KeywordCallAnalysis",
57
+ "KeywordCallAnalysisCanceled",
58
+ "KeywordCallAnalysisError",
59
+ "KeywordCallAnalyzer",
60
+ "KeywordCallBindingFact",
61
+ "KeywordCallCIRLowerer",
62
+ "KeywordCallLoweringServices",
63
+ "KeywordCallRejection",
64
+ "KeywordCallValidationCanceled",
65
+ "bind_keyword_call_lowerer",
66
+ "keyword_call_binding_id",
67
+ "validate_keyword_call_binding_facts",
68
+ ]
@@ -0,0 +1,458 @@
1
+ """Closed, deterministic analysis for exact direct keyword-call binding."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Mapping, Sequence
6
+
7
+ from pycforge.converter.analysis.model import ValueCategory
8
+
9
+ from .model import (
10
+ KEYWORD_CALL_LOWERING_SHAPE,
11
+ KeywordArgumentBindingFact,
12
+ KeywordCallAnalysis,
13
+ KeywordCallAnalysisCanceled,
14
+ KeywordCallAnalysisError,
15
+ KeywordCallBindingFact,
16
+ KeywordCallRejection,
17
+ keyword_call_binding_id,
18
+ )
19
+
20
+
21
+ def _sequence(value: Any) -> bool:
22
+ return isinstance(value, (list, tuple))
23
+
24
+
25
+ def _value(item: Any, name: str, default: Any = None) -> Any:
26
+ if isinstance(item, Mapping):
27
+ return item.get(name, default)
28
+ return getattr(item, name, default)
29
+
30
+
31
+ def _category(value: ValueCategory | str | None) -> str:
32
+ return value.value if isinstance(value, ValueCategory) else str(value or "unknown")
33
+
34
+
35
+ def _source_span(item: Any) -> dict[str, object] | None:
36
+ if not isinstance(item, Mapping):
37
+ return None
38
+ provenance = item.get("provenance")
39
+ span = provenance.get("source_span") if isinstance(provenance, Mapping) else None
40
+ return span if isinstance(span, dict) else None
41
+
42
+
43
+ class KeywordCallAnalyzer:
44
+ """Classify only keyword-bearing calls to eligible direct source functions."""
45
+
46
+ def __init__(
47
+ self,
48
+ module: dict[str, Any],
49
+ *,
50
+ bindings: Sequence[Any],
51
+ signatures: Sequence[Any],
52
+ categories: Mapping[str, ValueCategory | str],
53
+ cancellation: Any,
54
+ ignored_call_node_ids: frozenset[str] = frozenset(),
55
+ ) -> None:
56
+ if not isinstance(module, Mapping):
57
+ raise KeywordCallAnalysisError(
58
+ "PYC2912",
59
+ "Keyword-call analysis requires a normalized module mapping",
60
+ "",
61
+ None,
62
+ )
63
+ self.module = module
64
+ self.cancellation = cancellation
65
+ self.ignored_call_node_ids = ignored_call_node_ids
66
+ self.nodes: dict[str, dict[str, Any]] = {}
67
+ self.node_order: dict[str, int] = {}
68
+ node_values = module.get("nodes")
69
+ if not _sequence(node_values):
70
+ self._malformed(
71
+ "Keyword-call analysis requires a normalized node sequence",
72
+ module,
73
+ )
74
+ self.node_values = tuple(node_values)
75
+ for ordinal, node in enumerate(self.node_values):
76
+ self._check_cancellation()
77
+ node_id = node.get("node_id") if isinstance(node, Mapping) else None
78
+ if not isinstance(node_id, str) or node_id in self.nodes:
79
+ raise KeywordCallAnalysisError(
80
+ "PYC2912",
81
+ "Keyword-call analysis requires unique normalized node identities",
82
+ str(node_id or module.get("root_node_id") or ""),
83
+ _source_span(node),
84
+ )
85
+ self.nodes[node_id] = node
86
+ self.node_order[node_id] = ordinal
87
+ if not isinstance(categories, Mapping):
88
+ self._malformed("Keyword-call categories are malformed", module)
89
+ self.categories = {key: _category(value) for key, value in categories.items()}
90
+ if any(not isinstance(key, str) for key in self.categories):
91
+ self._malformed("Keyword-call category identities are malformed", module)
92
+ if not _sequence(bindings):
93
+ self._malformed("Keyword-call binding evidence is malformed", module)
94
+ self.binding_by_occurrence: dict[str, Any] = {}
95
+ for binding in bindings:
96
+ self._check_cancellation()
97
+ binding_id = _value(binding, "binding_id")
98
+ occurrences = _value(binding, "occurrence_node_ids")
99
+ if (
100
+ not isinstance(binding_id, str)
101
+ or not binding_id
102
+ or not _sequence(occurrences)
103
+ or any(not isinstance(item, str) for item in occurrences)
104
+ ):
105
+ self._malformed("Keyword-call binding evidence is malformed", module)
106
+ for occurrence in occurrences:
107
+ existing = self.binding_by_occurrence.get(occurrence)
108
+ if existing is not None and _value(existing, "binding_id") != binding_id:
109
+ self._malformed(
110
+ "Keyword-call occurrence has conflicting binding evidence",
111
+ self.nodes.get(occurrence, module),
112
+ )
113
+ self.binding_by_occurrence[occurrence] = binding
114
+ if not _sequence(signatures):
115
+ self._malformed("Keyword-call signature evidence is malformed", module)
116
+ self.signature_by_binding: dict[str, Any] = {}
117
+ for signature in signatures:
118
+ self._check_cancellation()
119
+ binding_id = _value(signature, "binding_id")
120
+ parameters = _value(signature, "parameters")
121
+ if (
122
+ not isinstance(binding_id, str)
123
+ or not binding_id
124
+ or not _sequence(parameters)
125
+ or binding_id in self.signature_by_binding
126
+ ):
127
+ self._malformed("Keyword-call signature evidence is malformed", module)
128
+ self.signature_by_binding[binding_id] = signature
129
+
130
+ def analyze(self) -> KeywordCallAnalysis:
131
+ facts: list[KeywordCallBindingFact] = []
132
+ rejections: list[KeywordCallRejection] = []
133
+ for node in self.node_values:
134
+ self._check_cancellation()
135
+ if not self._candidate(node):
136
+ continue
137
+ fact = self._fact(node)
138
+ facts.append(fact)
139
+ if not fact.supported:
140
+ rejection_node = self.nodes.get(fact.rejection_node_id or fact.call_node_id, node)
141
+ rejections.append(
142
+ KeywordCallRejection(
143
+ fact.call_node_id,
144
+ fact.diagnostic_code or "PYC2910",
145
+ fact.reason or "Unsupported keyword-call binding",
146
+ fact.rejection_node_id or fact.call_node_id,
147
+ _source_span(rejection_node),
148
+ )
149
+ )
150
+ return KeywordCallAnalysis(tuple(facts), tuple(rejections))
151
+
152
+ def _candidate(self, node: dict[str, Any]) -> bool:
153
+ if node.get("kind") != "Call" or node.get("node_id") in self.ignored_call_node_ids:
154
+ return False
155
+ fields = node.get("fields")
156
+ if not isinstance(fields, Mapping) or not _sequence(fields.get("keywords")):
157
+ self._malformed("Call has malformed normalized keyword evidence", node)
158
+ if not fields["keywords"]:
159
+ return False
160
+ callee_id = fields.get("func")
161
+ if not isinstance(callee_id, str):
162
+ self._malformed("Call callee identity is malformed", node)
163
+ callee = self.nodes.get(callee_id)
164
+ if not callee or callee.get("kind") != "Name":
165
+ return False
166
+ binding = self.binding_by_occurrence.get(callee_id)
167
+ target_binding_id = _value(binding, "binding_id")
168
+ signature = self.signature_by_binding.get(target_binding_id)
169
+ if signature is None or _value(signature, "eligible") is not True:
170
+ return False
171
+ target = self.nodes.get(str(_value(signature, "function_node_id", "")))
172
+ target_fields = target.get("fields") if isinstance(target, Mapping) else None
173
+ arguments = (
174
+ self.nodes.get(target_fields.get("args"))
175
+ if isinstance(target_fields, Mapping)
176
+ else None
177
+ )
178
+ argument_fields = (
179
+ arguments.get("fields") if isinstance(arguments, Mapping) else None
180
+ )
181
+ return not bool(
182
+ isinstance(argument_fields, Mapping)
183
+ and argument_fields.get("kwonlyargs")
184
+ )
185
+
186
+ def _fact(self, call: dict[str, Any]) -> KeywordCallBindingFact:
187
+ self._check_cancellation()
188
+ fields = call.get("fields")
189
+ if not isinstance(fields, Mapping):
190
+ self._malformed("Call fields are malformed", call)
191
+ call_id = call["node_id"]
192
+ callee_id = fields.get("func")
193
+ if not isinstance(callee_id, str):
194
+ self._malformed("Call callee identity is malformed", call)
195
+ binding = self.binding_by_occurrence[callee_id]
196
+ target_binding_id = str(_value(binding, "binding_id"))
197
+ signature = self.signature_by_binding[target_binding_id]
198
+ target_function_id = str(_value(signature, "function_node_id"))
199
+ target = self.nodes.get(target_function_id)
200
+ if not target or target.get("kind") != "FunctionDef":
201
+ self._error("PYC2912", "Exact keyword binding requires the normalized target function", call)
202
+ target_fields = target.get("fields")
203
+ if not isinstance(target_fields, Mapping):
204
+ self._malformed("Target function fields are malformed", target)
205
+ arguments_node = self.nodes.get(target_fields.get("args"))
206
+ if not arguments_node or arguments_node.get("kind") != "arguments":
207
+ self._error("PYC2912", "Exact keyword binding requires normalized parameter evidence", target)
208
+
209
+ parameters_value = _value(signature, "parameters")
210
+ if not _sequence(parameters_value):
211
+ self._malformed("Eligible target signature parameters are malformed", target)
212
+ parameters = tuple(parameters_value)
213
+ parameter_node_ids = tuple(str(_value(item, "parameter_node_id", "")) for item in parameters)
214
+ parameter_names = tuple(str(_value(item, "source_name", "")) for item in parameters)
215
+ parameter_categories = tuple(_category(_value(item, "category")) for item in parameters)
216
+ if (
217
+ any(not value for value in parameter_node_ids)
218
+ or any(not value for value in parameter_names)
219
+ or len(parameter_names) != len(set(parameter_names))
220
+ or any(value not in self.nodes for value in parameter_node_ids)
221
+ ):
222
+ self._error("PYC2912", "Eligible target signature has incomplete keyword-binding evidence", target)
223
+ argument_fields = arguments_node.get("fields")
224
+ if (
225
+ not isinstance(argument_fields, Mapping)
226
+ or not _sequence(argument_fields.get("posonlyargs"))
227
+ ):
228
+ self._malformed("Normalized positional-only evidence is malformed", arguments_node)
229
+ positional_only_count = len(argument_fields["posonlyargs"])
230
+ if positional_only_count > len(parameters):
231
+ self._error("PYC2912", "Eligible target signature has inconsistent positional-only evidence", target)
232
+
233
+ if not _sequence(fields.get("args")) or not _sequence(fields.get("keywords")):
234
+ self._malformed("Call argument sequences are malformed", call)
235
+ positional_ids = tuple(fields["args"])
236
+ keyword_ids = tuple(fields["keywords"])
237
+ if any(not isinstance(item, str) for item in (*positional_ids, *keyword_ids)):
238
+ self._malformed("Call argument identities are malformed", call)
239
+ keyword_nodes: list[dict[str, Any]] = []
240
+ for keyword_id in keyword_ids:
241
+ self._check_cancellation()
242
+ keyword = self.nodes.get(keyword_id)
243
+ if not keyword or keyword.get("kind") != "keyword":
244
+ self._error("PYC2912", "Call contains malformed normalized keyword evidence", call)
245
+ keyword_fields = keyword.get("fields")
246
+ if not isinstance(keyword_fields, Mapping):
247
+ self._malformed("Call keyword fields are malformed", keyword)
248
+ value_id = keyword_fields.get("value")
249
+ if not isinstance(value_id, str) or value_id not in self.nodes:
250
+ self._error("PYC2912", "Call keyword has no normalized value expression", keyword)
251
+ keyword_nodes.append(keyword)
252
+
253
+ positional_entries: list[dict[str, Any]] = []
254
+ for position, argument_id in enumerate(positional_ids):
255
+ self._check_cancellation()
256
+ argument = self.nodes.get(argument_id)
257
+ if argument is None:
258
+ self._error("PYC2912", "Call argument node is absent", call)
259
+ positional_entries.append({
260
+ "entry_kind": "positional", "list_ordinal": position,
261
+ "source_argument_node_id": argument_id, "keyword_node_id": None,
262
+ "keyword_name": None, "order_node_id": argument_id,
263
+ })
264
+ keyword_entries: list[dict[str, Any]] = []
265
+ for position, keyword in enumerate(keyword_nodes):
266
+ self._check_cancellation()
267
+ keyword_entries.append({
268
+ "entry_kind": "keyword", "list_ordinal": position,
269
+ "source_argument_node_id": keyword["fields"]["value"],
270
+ "keyword_node_id": keyword["node_id"],
271
+ "keyword_name": keyword["fields"].get("arg"),
272
+ "order_node_id": keyword["node_id"],
273
+ })
274
+ source_entries = self._merge_source_entries(
275
+ positional_entries,
276
+ keyword_entries,
277
+ )
278
+ for source_ordinal, item in enumerate(source_entries):
279
+ item["source_ordinal"] = source_ordinal
280
+ entry_by_position = {(item["entry_kind"], item["list_ordinal"]): item for item in source_entries}
281
+
282
+ parameter_by_name = {name: ordinal for ordinal, name in enumerate(parameter_names)}
283
+ parameter_argument_ids: list[str | None] = [None] * len(parameters)
284
+ parameter_source_ordinals: list[int | None] = [None] * len(parameters)
285
+ source_parameter_ordinals: dict[tuple[str, int], int | None] = {}
286
+ binding_problems: list[tuple[str, str, str]] = []
287
+ unpacking: list[tuple[int, str]] = []
288
+ excess: list[tuple[int, str]] = []
289
+
290
+ saw_starred = False
291
+ for position, argument_id in enumerate(positional_ids):
292
+ self._check_cancellation()
293
+ entry = entry_by_position[("positional", position)]
294
+ argument = self.nodes[argument_id]
295
+ if argument.get("kind") == "Starred":
296
+ saw_starred = True
297
+ source_parameter_ordinals[("positional", position)] = None
298
+ unpacking.append((entry["source_ordinal"], argument_id))
299
+ continue
300
+ if saw_starred:
301
+ source_parameter_ordinals[("positional", position)] = None
302
+ continue
303
+ if position >= len(parameters):
304
+ source_parameter_ordinals[("positional", position)] = None
305
+ excess.append((entry["source_ordinal"], argument_id))
306
+ continue
307
+ source_parameter_ordinals[("positional", position)] = position
308
+ parameter_argument_ids[position] = argument_id
309
+ parameter_source_ordinals[position] = entry["source_ordinal"]
310
+
311
+ for position, keyword in enumerate(keyword_nodes):
312
+ self._check_cancellation()
313
+ entry = entry_by_position[("keyword", position)]
314
+ keyword_id = keyword["node_id"]
315
+ name = keyword["fields"].get("arg")
316
+ if name is None:
317
+ source_parameter_ordinals[("keyword", position)] = None
318
+ unpacking.append((entry["source_ordinal"], keyword_id))
319
+ continue
320
+ parameter_ordinal = parameter_by_name.get(name)
321
+ if parameter_ordinal is None:
322
+ source_parameter_ordinals[("keyword", position)] = None
323
+ binding_problems.append((keyword_id, f"Unknown keyword argument: {name}", name))
324
+ continue
325
+ source_parameter_ordinals[("keyword", position)] = parameter_ordinal
326
+ if parameter_ordinal < positional_only_count:
327
+ binding_problems.append((keyword_id, f"Positional-only parameter cannot be bound by keyword: {name}", name))
328
+ continue
329
+ if parameter_argument_ids[parameter_ordinal] is not None:
330
+ prior_source = parameter_source_ordinals[parameter_ordinal]
331
+ prior_entry = source_entries[prior_source] if isinstance(prior_source, int) and 0 <= prior_source < len(source_entries) else None
332
+ reason = f"Keyword argument duplicates a positionally bound parameter: {name}" if prior_entry and prior_entry["entry_kind"] == "positional" else f"Duplicate keyword argument: {name}"
333
+ binding_problems.append((keyword_id, reason, name))
334
+ continue
335
+ parameter_argument_ids[parameter_ordinal] = keyword["fields"]["value"]
336
+ parameter_source_ordinals[parameter_ordinal] = entry["source_ordinal"]
337
+
338
+ argument_bindings: list[KeywordArgumentBindingFact] = []
339
+ for entry in source_entries:
340
+ self._check_cancellation()
341
+ parameter_ordinal = source_parameter_ordinals.get((entry["entry_kind"], entry["list_ordinal"]))
342
+ valid_ordinal = isinstance(parameter_ordinal, int) and 0 <= parameter_ordinal < len(parameters)
343
+ argument_id = entry["source_argument_node_id"]
344
+ argument_bindings.append(KeywordArgumentBindingFact(
345
+ argument_id, entry["keyword_node_id"], entry["keyword_name"], entry["source_ordinal"],
346
+ parameter_node_ids[parameter_ordinal] if valid_ordinal else None,
347
+ parameter_names[parameter_ordinal] if valid_ordinal else None,
348
+ parameter_ordinal,
349
+ self.categories.get(argument_id, "unknown"),
350
+ parameter_categories[parameter_ordinal] if valid_ordinal else None,
351
+ ))
352
+
353
+ missing = [parameter_names[ordinal] for ordinal, argument_id in enumerate(parameter_argument_ids) if argument_id is None]
354
+ mismatches = [item for item in argument_bindings if item.parameter_ordinal is not None and item.expected_category is not None and item.category != item.expected_category and parameter_source_ordinals[item.parameter_ordinal] == item.source_ordinal]
355
+ parameter_coverage_exact = bool(not unpacking and not excess and not binding_problems and not missing and all(value is not None for value in parameter_argument_ids) and len(source_entries) == len(parameters))
356
+
357
+ code: str | None = None
358
+ reason: str | None = None
359
+ rejection_node_id: str | None = None
360
+ if unpacking:
361
+ _, rejection_node_id = min(unpacking, key=lambda item: item[0])
362
+ code, reason = "PYC2910", "Starred and unpacked call arguments are unsupported by the exact keyword profile"
363
+ elif excess:
364
+ _, rejection_node_id = min(excess, key=lambda item: item[0])
365
+ code, reason = "PYC2904", "Argument count exceeds the target signature"
366
+ elif binding_problems:
367
+ rejection_node_id, reason, _ = binding_problems[0]
368
+ code = "PYC2912"
369
+ elif missing:
370
+ rejection_node_id = call_id
371
+ code, reason = "PYC2904", "Every target parameter must be supplied exactly once; missing: " + ", ".join(missing)
372
+ elif mismatches:
373
+ mismatch = mismatches[0]
374
+ rejection_node_id = mismatch.keyword_node_id or mismatch.source_argument_node_id
375
+ code, reason = "PYC2905", f"Argument representation does not match parameter {mismatch.parameter_name}"
376
+ supported = code is None and parameter_coverage_exact
377
+ if code is None and not supported:
378
+ code, reason, rejection_node_id = "PYC2904", "Keyword arguments do not exactly cover the target signature", call_id
379
+
380
+ source_argument_ids = tuple(item.source_argument_node_id for item in argument_bindings)
381
+ source_categories = tuple(item.category for item in argument_bindings)
382
+ return KeywordCallBindingFact(
383
+ keyword_call_binding_id(call_id, target_binding_id), call_id, callee_id,
384
+ target_function_id, target_binding_id,
385
+ str(_value(signature, "source_name", target_fields.get("name", ""))),
386
+ positional_only_count, parameter_node_ids, parameter_names, parameter_categories,
387
+ positional_ids, keyword_ids,
388
+ tuple(keyword.get("fields", {}).get("arg") for keyword in keyword_nodes),
389
+ tuple(keyword["fields"]["value"] for keyword in keyword_nodes),
390
+ tuple(argument_bindings), source_argument_ids, source_categories,
391
+ tuple(item.parameter_ordinal for item in argument_bindings),
392
+ tuple(parameter_argument_ids), tuple(parameter_source_ordinals),
393
+ source_argument_ids, True, parameter_coverage_exact,
394
+ KEYWORD_CALL_LOWERING_SHAPE, "none", "none",
395
+ "proved-absent" if supported else "compile-time-rejected",
396
+ supported, code, reason, rejection_node_id,
397
+ )
398
+
399
+ def _merge_source_entries(
400
+ self,
401
+ positional: list[dict[str, Any]],
402
+ keywords: list[dict[str, Any]],
403
+ ) -> list[dict[str, Any]]:
404
+ """Linearly merge two normalized source-ordered argument lists."""
405
+
406
+ merged: list[dict[str, Any]] = []
407
+ positional_index = 0
408
+ keyword_index = 0
409
+ while positional_index < len(positional) and keyword_index < len(keywords):
410
+ self._check_cancellation()
411
+ positional_item = positional[positional_index]
412
+ keyword_item = keywords[keyword_index]
413
+ if self._source_key(positional_item["order_node_id"]) <= self._source_key(
414
+ keyword_item["order_node_id"]
415
+ ):
416
+ merged.append(positional_item)
417
+ positional_index += 1
418
+ else:
419
+ merged.append(keyword_item)
420
+ keyword_index += 1
421
+ merged.extend(positional[positional_index:])
422
+ merged.extend(keywords[keyword_index:])
423
+ return merged
424
+
425
+ def _source_key(self, node_id: str) -> tuple[int, int]:
426
+ node = self.nodes.get(node_id, {})
427
+ provenance = node.get("provenance")
428
+ span = provenance.get("source_span") if isinstance(provenance, Mapping) else None
429
+ start = span.get("start") if isinstance(span, Mapping) else None
430
+ offset = start.get("offset") if isinstance(start, Mapping) else None
431
+ return (
432
+ offset if isinstance(offset, int) else 2**63 - 1,
433
+ self.node_order.get(node_id, 2**63 - 1),
434
+ )
435
+
436
+ def _check_cancellation(self) -> None:
437
+ if self.cancellation is not None and bool(getattr(self.cancellation, "is_canceled", False)):
438
+ raise KeywordCallAnalysisCanceled
439
+
440
+ def _error(self, code: str, message: str, node: dict[str, Any]) -> None:
441
+ raise KeywordCallAnalysisError(
442
+ code,
443
+ message,
444
+ str(node.get("node_id", "")),
445
+ _source_span(node),
446
+ )
447
+
448
+ def _malformed(self, message: str, node: Any) -> None:
449
+ value = node if isinstance(node, Mapping) else {}
450
+ raise KeywordCallAnalysisError(
451
+ "PYC2912",
452
+ message,
453
+ str(value.get("node_id") or self.module.get("root_node_id") or ""),
454
+ _source_span(value),
455
+ )
456
+
457
+
458
+ __all__ = ["KeywordCallAnalyzer"]