sv-query 0.3.0__tar.gz

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 (158) hide show
  1. sv_query-0.3.0/LICENSE +196 -0
  2. sv_query-0.3.0/LICENSE_MIT +21 -0
  3. sv_query-0.3.0/PKG-INFO +344 -0
  4. sv_query-0.3.0/README.md +302 -0
  5. sv_query-0.3.0/pyproject.toml +195 -0
  6. sv_query-0.3.0/setup.cfg +4 -0
  7. sv_query-0.3.0/src/cli/__init__.py +5 -0
  8. sv_query-0.3.0/src/cli/_common.py +408 -0
  9. sv_query-0.3.0/src/cli/_entry.py +35 -0
  10. sv_query-0.3.0/src/cli/_evidence_helpers.py +784 -0
  11. sv_query-0.3.0/src/cli/_output.py +51 -0
  12. sv_query-0.3.0/src/cli/_paths.py +36 -0
  13. sv_query-0.3.0/src/cli/_registry.py +1575 -0
  14. sv_query-0.3.0/src/cli/_session_adapter.py +84 -0
  15. sv_query-0.3.0/src/cli/_session_runner.py +57 -0
  16. sv_query-0.3.0/src/cli/core/__init__.py +12 -0
  17. sv_query-0.3.0/src/cli/core/diagnose/__init__.py +11 -0
  18. sv_query-0.3.0/src/cli/core/diagnose/dispatch.py +72 -0
  19. sv_query-0.3.0/src/cli/core/diagnose/imports.py +301 -0
  20. sv_query-0.3.0/src/cli/core/diagnose/report.py +174 -0
  21. sv_query-0.3.0/src/cli/core/diagnose/timescale.py +157 -0
  22. sv_query-0.3.0/src/cli/core/diagnose/widths.py +282 -0
  23. sv_query-0.3.0/src/cli/core/locate/__init__.py +1 -0
  24. sv_query-0.3.0/src/cli/core/locate/capabilities.py +125 -0
  25. sv_query-0.3.0/src/cli/core/locate/filelist_cmd.py +94 -0
  26. sv_query-0.3.0/src/cli/core/locate/graph.py +285 -0
  27. sv_query-0.3.0/src/cli/core/locate/search.py +134 -0
  28. sv_query-0.3.0/src/cli/core/locate/session_cmd.py +65 -0
  29. sv_query-0.3.0/src/cli/core/semantic/__init__.py +4 -0
  30. sv_query-0.3.0/src/cli/core/semantic/_bit_args.py +136 -0
  31. sv_query-0.3.0/src/cli/core/semantic/_bit_hints.py +76 -0
  32. sv_query-0.3.0/src/cli/core/semantic/_common.py +57 -0
  33. sv_query-0.3.0/src/cli/core/semantic/audit.py +97 -0
  34. sv_query-0.3.0/src/cli/core/semantic/classes.py +319 -0
  35. sv_query-0.3.0/src/cli/core/semantic/condition_analysis.py +298 -0
  36. sv_query-0.3.0/src/cli/core/semantic/constraints.py +286 -0
  37. sv_query-0.3.0/src/cli/core/semantic/controlflow.py +289 -0
  38. sv_query-0.3.0/src/cli/core/semantic/covergroups.py +319 -0
  39. sv_query-0.3.0/src/cli/core/semantic/dataflow.py +300 -0
  40. sv_query-0.3.0/src/cli/core/semantic/frontier.py +79 -0
  41. sv_query-0.3.0/src/cli/core/semantic/instances.py +291 -0
  42. sv_query-0.3.0/src/cli/core/semantic/params.py +59 -0
  43. sv_query-0.3.0/src/cli/core/semantic/paths.py +196 -0
  44. sv_query-0.3.0/src/cli/core/semantic/ports.py +63 -0
  45. sv_query-0.3.0/src/cli/core/semantic/scope.py +223 -0
  46. sv_query-0.3.0/src/cli/core/semantic/tb_join.py +112 -0
  47. sv_query-0.3.0/src/cli/core/semantic/trace.py +1327 -0
  48. sv_query-0.3.0/src/cli/core/semantic/trace_common.py +898 -0
  49. sv_query-0.3.0/src/cli/core/semantic/trace_evidence.py +421 -0
  50. sv_query-0.3.0/src/cli/core/semantic/trace_lookup.py +191 -0
  51. sv_query-0.3.0/src/cli/core/semantic/trace_manifest.py +89 -0
  52. sv_query-0.3.0/src/cli/core/semantic/trace_overview.py +320 -0
  53. sv_query-0.3.0/src/cli/core/semantic/trace_profile.py +552 -0
  54. sv_query-0.3.0/src/cli/core/semantic/verify.py +682 -0
  55. sv_query-0.3.0/src/cli/core/state/__init__.py +1 -0
  56. sv_query-0.3.0/src/cli/core/state/diff.py +153 -0
  57. sv_query-0.3.0/src/cli/core/state/snapshot.py +400 -0
  58. sv_query-0.3.0/src/cli/errors.py +128 -0
  59. sv_query-0.3.0/src/cli/main.py +487 -0
  60. sv_query-0.3.0/src/cli/view/__init__.py +1 -0
  61. sv_query-0.3.0/src/cli/view/architecture.py +127 -0
  62. sv_query-0.3.0/src/cli/view/review.py +272 -0
  63. sv_query-0.3.0/src/sv_query/__init__.py +10 -0
  64. sv_query-0.3.0/src/sv_query/errors.py +39 -0
  65. sv_query-0.3.0/src/sv_query/session.py +211 -0
  66. sv_query-0.3.0/src/sv_query/trace/__init__.py +57 -0
  67. sv_query-0.3.0/src/sv_query/trace/_safe.py +215 -0
  68. sv_query-0.3.0/src/sv_query/trace/core/__init__.py +65 -0
  69. sv_query-0.3.0/src/sv_query/trace/core/analysis/__init__.py +13 -0
  70. sv_query-0.3.0/src/sv_query/trace/core/analysis/audit.py +620 -0
  71. sv_query-0.3.0/src/sv_query/trace/core/ast_utils.py +283 -0
  72. sv_query-0.3.0/src/sv_query/trace/core/bit_select_handler.py +504 -0
  73. sv_query-0.3.0/src/sv_query/trace/core/builder/__init__.py +0 -0
  74. sv_query-0.3.0/src/sv_query/trace/core/builder/graph_pipeline.py +159 -0
  75. sv_query-0.3.0/src/sv_query/trace/core/builder/subroutine_expander.py +926 -0
  76. sv_query-0.3.0/src/sv_query/trace/core/cache/__init__.py +3 -0
  77. sv_query-0.3.0/src/sv_query/trace/core/cache/ast_cache.py +547 -0
  78. sv_query-0.3.0/src/sv_query/trace/core/class_graph_builder.py +1729 -0
  79. sv_query-0.3.0/src/sv_query/trace/core/class_hierarchy.py +197 -0
  80. sv_query-0.3.0/src/sv_query/trace/core/compiler.py +767 -0
  81. sv_query-0.3.0/src/sv_query/trace/core/connection_extractor.py +763 -0
  82. sv_query-0.3.0/src/sv_query/trace/core/coverage_models.py +250 -0
  83. sv_query-0.3.0/src/sv_query/trace/core/covergroup_extractor.py +641 -0
  84. sv_query-0.3.0/src/sv_query/trace/core/driver_extractor.py +1428 -0
  85. sv_query-0.3.0/src/sv_query/trace/core/edge_factory.py +82 -0
  86. sv_query-0.3.0/src/sv_query/trace/core/extractor_models.py +37 -0
  87. sv_query-0.3.0/src/sv_query/trace/core/extractors/__init__.py +14 -0
  88. sv_query-0.3.0/src/sv_query/trace/core/extractors/_common.py +962 -0
  89. sv_query-0.3.0/src/sv_query/trace/core/extractors/alias_extractor.py +79 -0
  90. sv_query-0.3.0/src/sv_query/trace/core/extractors/always_extractor.py +915 -0
  91. sv_query-0.3.0/src/sv_query/trace/core/extractors/assign_extractor.py +779 -0
  92. sv_query-0.3.0/src/sv_query/trace/core/extractors/expr_tree_builder.py +159 -0
  93. sv_query-0.3.0/src/sv_query/trace/core/extractors/function_extractor.py +1228 -0
  94. sv_query-0.3.0/src/sv_query/trace/core/extractors/net_decl_extractor.py +244 -0
  95. sv_query-0.3.0/src/sv_query/trace/core/extractors/statement_flattener.py +244 -0
  96. sv_query-0.3.0/src/sv_query/trace/core/extractors/wire_init_extractor.py +103 -0
  97. sv_query-0.3.0/src/sv_query/trace/core/filelist.py +224 -0
  98. sv_query-0.3.0/src/sv_query/trace/core/fsm_analyzer.py +199 -0
  99. sv_query-0.3.0/src/sv_query/trace/core/graph/__init__.py +106 -0
  100. sv_query-0.3.0/src/sv_query/trace/core/graph/analyzer/__init__.py +18 -0
  101. sv_query-0.3.0/src/sv_query/trace/core/graph/analyzer/_dot_common.py +185 -0
  102. sv_query-0.3.0/src/sv_query/trace/core/graph/analyzer/controlflow_analyzer.py +303 -0
  103. sv_query-0.3.0/src/sv_query/trace/core/graph/analyzer/pipeline_viz.py +1210 -0
  104. sv_query-0.3.0/src/sv_query/trace/core/graph/analyzer/signal_classifier.py +411 -0
  105. sv_query-0.3.0/src/sv_query/trace/core/graph/call_graph_models.py +116 -0
  106. sv_query-0.3.0/src/sv_query/trace/core/graph/contracts.py +178 -0
  107. sv_query-0.3.0/src/sv_query/trace/core/graph/controlflow.py +201 -0
  108. sv_query-0.3.0/src/sv_query/trace/core/graph/controlflow_models.py +301 -0
  109. sv_query-0.3.0/src/sv_query/trace/core/graph/covergroup_models.py +93 -0
  110. sv_query-0.3.0/src/sv_query/trace/core/graph/dataflow.py +1146 -0
  111. sv_query-0.3.0/src/sv_query/trace/core/graph/diff.py +400 -0
  112. sv_query-0.3.0/src/sv_query/trace/core/graph/models.py +884 -0
  113. sv_query-0.3.0/src/sv_query/trace/core/graph/search_budget.py +85 -0
  114. sv_query-0.3.0/src/sv_query/trace/core/graph/sva_models.py +125 -0
  115. sv_query-0.3.0/src/sv_query/trace/core/graph/uvm_models.py +156 -0
  116. sv_query-0.3.0/src/sv_query/trace/core/graph/viz/__init__.py +1 -0
  117. sv_query-0.3.0/src/sv_query/trace/core/graph/viz/expression_tree.py +553 -0
  118. sv_query-0.3.0/src/sv_query/trace/core/graph_builder.py +2298 -0
  119. sv_query-0.3.0/src/sv_query/trace/core/module_extractor.py +511 -0
  120. sv_query-0.3.0/src/sv_query/trace/core/module_instance_graph.py +549 -0
  121. sv_query-0.3.0/src/sv_query/trace/core/native_adapter.py +354 -0
  122. sv_query-0.3.0/src/sv_query/trace/core/pipeline.py +103 -0
  123. sv_query-0.3.0/src/sv_query/trace/core/query/__init__.py +39 -0
  124. sv_query-0.3.0/src/sv_query/trace/core/query/architecture.py +274 -0
  125. sv_query-0.3.0/src/sv_query/trace/core/query/clock_domain.py +241 -0
  126. sv_query-0.3.0/src/sv_query/trace/core/query/constraint.py +416 -0
  127. sv_query-0.3.0/src/sv_query/trace/core/query/covergroup.py +267 -0
  128. sv_query-0.3.0/src/sv_query/trace/core/query/frontier.py +181 -0
  129. sv_query-0.3.0/src/sv_query/trace/core/query/load.py +133 -0
  130. sv_query-0.3.0/src/sv_query/trace/core/query/module.py +186 -0
  131. sv_query-0.3.0/src/sv_query/trace/core/query/signal.py +2013 -0
  132. sv_query-0.3.0/src/sv_query/trace/core/query/structural.py +169 -0
  133. sv_query-0.3.0/src/sv_query/trace/core/query/subgraph.py +300 -0
  134. sv_query-0.3.0/src/sv_query/trace/core/query/uvm.py +130 -0
  135. sv_query-0.3.0/src/sv_query/trace/core/semantic/__init__.py +22 -0
  136. sv_query-0.3.0/src/sv_query/trace/core/semantic/_expr_helpers.py +432 -0
  137. sv_query-0.3.0/src/sv_query/trace/core/semantic/_wrappers.py +118 -0
  138. sv_query-0.3.0/src/sv_query/trace/core/semantic/classes.py +254 -0
  139. sv_query-0.3.0/src/sv_query/trace/core/semantic/connections.py +302 -0
  140. sv_query-0.3.0/src/sv_query/trace/core/semantic/exprs_drivers.py +1134 -0
  141. sv_query-0.3.0/src/sv_query/trace/core/semantic/modules.py +604 -0
  142. sv_query-0.3.0/src/sv_query/trace/core/semantic/ports_ifaces.py +442 -0
  143. sv_query-0.3.0/src/sv_query/trace/core/semantic/source_core.py +189 -0
  144. sv_query-0.3.0/src/sv_query/trace/core/semantic_adapter.py +127 -0
  145. sv_query-0.3.0/src/sv_query/trace/core/snapshot_manager.py +325 -0
  146. sv_query-0.3.0/src/sv_query/trace/core/source_assignment.py +176 -0
  147. sv_query-0.3.0/src/sv_query/trace/core/sv_preprocessor.py +293 -0
  148. sv_query-0.3.0/src/sv_query/trace/core/sva_extractor.py +972 -0
  149. sv_query-0.3.0/src/sv_query/trace/core/top_prune.py +131 -0
  150. sv_query-0.3.0/src/sv_query/trace/core/trace_evidence.py +845 -0
  151. sv_query-0.3.0/src/sv_query/trace/py.typed +0 -0
  152. sv_query-0.3.0/src/sv_query/trace/unified_tracer.py +1276 -0
  153. sv_query-0.3.0/src/sv_query.egg-info/PKG-INFO +344 -0
  154. sv_query-0.3.0/src/sv_query.egg-info/SOURCES.txt +156 -0
  155. sv_query-0.3.0/src/sv_query.egg-info/dependency_links.txt +1 -0
  156. sv_query-0.3.0/src/sv_query.egg-info/entry_points.txt +2 -0
  157. sv_query-0.3.0/src/sv_query.egg-info/requires.txt +17 -0
  158. sv_query-0.3.0/src/sv_query.egg-info/top_level.txt +2 -0
sv_query-0.3.0/LICENSE ADDED
@@ -0,0 +1,196 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the
44
+ purposes of this License, Derivative Works shall not include works
45
+ that remain separable from, or merely link (or bind by name) to
46
+ the interfaces of, the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to the Licensor for inclusion in the Work by the owner
52
+ or by an individual or Legal Entity authorized to submit on behalf
53
+ of the copyright owner. For the purposes of this definition,
54
+ "submitted" means any form of electronic, verbal, or written
55
+ communication sent to the Licensor or its representatives,
56
+ including but not limited to communication on electronic mailing
57
+ lists, source code control systems, and issue tracking systems
58
+ that are managed by, or on behalf of, the Licensor for the
59
+ purpose of discussing and improving the Work, but excluding
60
+ communication that is conspicuously marked or otherwise designated
61
+ in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor or any individual or Legal Entity
64
+ that licenses, at, or with respect to, the Work the same.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute
71
+ the Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have
77
+ made, use, offer to sell, sell, import, and otherwise transfer
78
+ the Work, where such license applies only to those patent claims
79
+ licensable by such Contributor that are necessarily infringed by
80
+ their Contribution(s) alone or by combination of their
81
+ Contribution(s) with the Work to which such Contribution(s)
82
+ was submitted. If You institute patent litigation against any
83
+ entity (including a cross-claim or counterclaim in a lawsuit)
84
+ alleging that the Work or a Contribution incorporated within
85
+ the Work constitutes direct or contributory patent infringement,
86
+ then any patent licenses granted to You under this License for
87
+ that Work shall terminate as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute
108
+ must include a readable copy of the attribution notices
109
+ contained within such NOTICE file, excluding those notices
110
+ that do not pertain to any part of the Derivative Works,
111
+ in at least one of the following places: within a NOTICE
112
+ text file distributed as part of the Derivative Works;
113
+ within the Source form or documentation, if provided
114
+ along with the Derivative Works; or, within a display
115
+ generated by the Derivative Works, if and wherever such
116
+ third-party notices normally appear. The contents of the
117
+ NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own
119
+ attribution notices within Derivative Works that You
120
+ distribute, alongside or as an addendum to the NOTICE
121
+ text from the Work, provided that such additional
122
+ attribution notices cannot be construed as modifying
123
+ the License.
124
+
125
+ You may add Your own copyright statement to Your modifications
126
+ and may provide additional or different license terms and
127
+ conditions for use, reproduction, or distribution of Your
128
+ modifications, or for any such Derivative Works as a whole,
129
+ provided Your use, reproduction, and distribution of the Work
130
+ otherwise complies with the conditions stated in this License.
131
+
132
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
133
+ any Contribution intentionally submitted for inclusion in the
134
+ Work by You to the Licensor shall be under the terms and
135
+ conditions of this License, without any additional terms or
136
+ conditions. Notwithstanding the above, nothing herein shall
137
+ supersede or modify the terms of any separate license agreement
138
+ you may have executed with Licensor regarding such Contributions.
139
+
140
+ 6. Trademarks. This License does not grant permission to use the trade
141
+ names, trademarks, service marks, or product names of the
142
+ Licensor, except as required for reasonable and customary use
143
+ in describing the origin of the Work and reproducing the content
144
+ of the NOTICE file.
145
+
146
+ 7. Disclaimer of Warranty. Unless required by applicable law or
147
+ agreed to in writing, Licensor provides the Work (and each
148
+ Contributor provides its Contributions) on an "AS IS" BASIS,
149
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
150
+ implied, including, without limitation, any warranties or
151
+ conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
152
+ FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible
153
+ for determining the appropriateness of using or redistributing
154
+ the Work and assume any risks associated with Your exercise
155
+ of permissions under this License.
156
+
157
+ 8. Limitation of Liability. In no event and under no legal theory,
158
+ whether in tort (including negligence), contract, or otherwise,
159
+ unless required by applicable law (such as deliberate and grossly
160
+ negligent acts) or agreed to in writing, shall any Contributor
161
+ be liable to You for damages, including any direct, indirect,
162
+ special, incidental, or consequential damages of any character
163
+ arising as a result of this License or out of the use or
164
+ inability to use the Work (including but not limited to damages
165
+ for loss of goodwill, work stoppage, computer failure or
166
+ malfunction, or any and all other commercial damages or losses),
167
+ even if such Contributor has been advised of the possibility
168
+ of such damages.
169
+
170
+ 9. Accepting Warranty or Additional Liability. While redistributing
171
+ the Work or Derivative Works thereof, You may choose to offer,
172
+ and charge a fee for, acceptance of support, warranty,
173
+ indemnity, or other liability obligations and/or rights
174
+ consistent with this License. However, in accepting such
175
+ obligations, You may act only on Your own behalf and on Your
176
+ sole responsibility, not on behalf of any other Contributor,
177
+ and only if You agree to indemnify, defend, and hold each
178
+ Contributor harmless for any liability incurred by, or
179
+ claims asserted against, such Contributor by reason of
180
+ your accepting any such warranty or additional liability.
181
+
182
+ END OF TERMS AND CONDITIONS
183
+
184
+ Copyright 2024-2026 sv_query contributors
185
+
186
+ Licensed under the Apache License, Version 2.0 (the "License");
187
+ you may not use this file except in compliance with the License.
188
+ You may obtain a copy of the License at
189
+
190
+ http://www.apache.org/licenses/LICENSE-2.0
191
+
192
+ Unless required by applicable law or agreed to in writing, software
193
+ distributed under the License is distributed on an "AS IS" BASIS,
194
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
195
+ implied. See the License for the specific language governing
196
+ permissions and limitations under the License.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 sv_query contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,344 @@
1
+ Metadata-Version: 2.4
2
+ Name: sv_query
3
+ Version: 0.3.0
4
+ Summary: SystemVerilog 信号追踪查询引擎 - 让验证工程师直接问'这个信号谁驱动的'
5
+ Author: sv_query contributors
6
+ License: MIT OR Apache-2.0
7
+ Project-URL: Homepage, https://github.com/fundou1081/sv_query
8
+ Project-URL: Repository, https://github.com/fundou1081/sv_query.git
9
+ Project-URL: Issues, https://github.com/fundou1081/sv_query/issues
10
+ Project-URL: Changelog, https://github.com/fundou1081/sv_query/blob/main/CHANGELOG.md
11
+ Keywords: systemverilog,rtl,verification,signal-tracing,static-analysis,dataflow,cdc,sva,tcl,eda
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: License :: OSI Approved :: Apache Software License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ License-File: LICENSE_MIT
26
+ Requires-Dist: networkx>=3.0
27
+ Requires-Dist: typer<0.26,>=0.25.1
28
+ Requires-Dist: click<9,>=8.2.1
29
+ Requires-Dist: rich<15,>=14.3
30
+ Requires-Dist: pyslang<12.0.0,>=11.0.0
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7.0; extra == "dev"
33
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
34
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
35
+ Requires-Dist: pytest-randomly>=3.12; extra == "dev"
36
+ Requires-Dist: ruff>=0.1.0; extra == "dev"
37
+ Requires-Dist: jsonschema>=4.0; extra == "dev"
38
+ Requires-Dist: PyYAML>=6.0; extra == "dev"
39
+ Provides-Extra: all
40
+ Requires-Dist: scipy>=1.10; extra == "all"
41
+ Dynamic: license-file
42
+
43
+ # sv_query — 面向 agent 的 SystemVerilog 语义查询 + 客观校验引擎
44
+
45
+ [![Tests](https://github.com/fundou1081/sv_query/actions/workflows/tests.yml/badge.svg)](https://github.com/fundou1081/sv_query/actions/workflows/tests.yml)
46
+ [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
47
+
48
+ > **PyPI 状态**: `0.3.0` 发布工程已就绪但尚未上传;下面先给出来源安装方式,
49
+ > PyPI 发布后再恢复 `pip install sv_query`。
50
+
51
+ **让 agent 查询并验证 RTL 事实,而不是靠读源码猜。**
52
+
53
+ > **Beta(0.3.0)**: 质量足以试用,但明确不宣称 1.0 的语义完整性/外部准确率。
54
+ > 发布前已知限制见 [KNOWN_LIMITATIONS](docs/KNOWN_LIMITATIONS.md);
55
+ > 发布流程见 [RELEASE.md](RELEASE.md)。
56
+
57
+ > agent 面向的 RTL **查询 + 客观校验层**:服务动态 debug(波形值由外部工具提供)与 design 理解;
58
+ > 核心是 canonical identity、evidence、双向验证,而不是自然语言解释。
59
+
60
+ > 回归基线见 [docs/INDEX.md 当前基线](docs/INDEX.md#-当前基线-单一真相源--计数只写在这里) | Python 3.11+ | pyslang 语义 AST | NetworkX graph | 真实项目 + 性能基准 + agent 对照(内部)
61
+
62
+ > 更新日期: 2026-11-19(0.3.0 beta 发布准备;基线计数统一引用 INDEX)
63
+
64
+ ---
65
+
66
+ ## Install
67
+
68
+ ```bash
69
+ # PyPI 0.3.0 尚未发布;从 Git 安装当前 beta:
70
+ pip install "sv_query @ git+https://github.com/fundou1081/sv_query.git@main"
71
+ # or, in an isolated environment:
72
+ uv pip install "sv_query @ git+https://github.com/fundou1081/sv_query.git@main"
73
+
74
+ # PyPI 发布后:
75
+ # pip install sv_query
76
+ ```
77
+
78
+ For repository development:
79
+
80
+ ```bash
81
+ git clone https://github.com/fundou1081/sv_query.git
82
+ cd sv_query
83
+ pip install -e ".[dev]"
84
+ ```
85
+
86
+ ## CVA6 真实历史案例(non-blind)
87
+
88
+ 已用两个 CVA6 历史 fix 做 grep vs `sv_query` 对照:
89
+
90
+ - canonical address check 的 `_i → _q` 周期错位(CVA6 #3410);
91
+ - DTLB PPN 位选 + `dtlb_is_page_q → _n` 门控(CVA6 #3347)。
92
+
93
+ 结论不是“自动发现 bug”,而是:
94
+
95
+ - `drivers --evidence` 能直接绑定驱动表达式;
96
+ - 总线级查询会漏掉位选缺陷,需要 `graph nodes --match` 下钻;
97
+ - 案例按 fix diff 选取,不是盲测;动态 oracle 未本地重跑。
98
+
99
+ 完整报告与可复现归档:
100
+
101
+ - [P187_VALUE_CASES_CVA6_2026-11-19.md](docs/validation/P187_VALUE_CASES_CVA6_2026-11-19.md)
102
+ - [p187_cva6_2026-11-19/README.md](docs/validation/p187_cva6_2026-11-19/README.md)
103
+ - [P187_FOLLOWUPS_2026-11-19.md](docs/validation/P187_FOLLOWUPS_2026-11-19.md)
104
+
105
+ ## English summary
106
+
107
+ `sv_query` is an agent-facing query and objective-verification layer for SystemVerilog.
108
+ It builds a semantic graph from pyslang, exposes read-only JSON queries (drivers, loads,
109
+ paths, dataflow, scope, constraints, covergroups, consistency/claim verification), and
110
+ reports evidence strength explicitly (`verified` / `partial` / `unknown`). It is a beta:
111
+ structural queries are useful today, but semantic completeness and external accuracy
112
+ claims remain limited; see [KNOWN_LIMITATIONS](docs/KNOWN_LIMITATIONS.md).
113
+
114
+ ## 为什么用 sv_query
115
+
116
+ - **位级追踪(scoped)**: `SignalSource` 结构化存储 bit_range + op + casts;位对位只在已建模算子/连接上成立,比较/变量移位等仍总线粒度(见 KNOWN_LIMITATIONS)
117
+ - **穿透子模块**: wrapper port passthrough + bus 位桥(同构直连 / 切片偏移)
118
+ - **语义优先**: class / constraint / covergroup / UVM role 走 pyslang semantic AST;
119
+ UVM 宏/调用因预处理器会丢宏,是唯一 `syntactic` regex 例外(显式标 confidence,不作为 verify 证明)
120
+ - **class/constraint/covergroup/UVM**: 继承约束链、rand/randc 标记、covergroup 采样/反向查询、
121
+ UVM sequence/factory 静态关系
122
+ - **客观校验**: 全图 / bit-level 结构一致性 + claim 验证 + finding 局部证据
123
+ - **可复现验证**: strict_uart / verilog-axi / picorv32 / SERV smoke;3 设计性能基准;
124
+ 单级 CDC 反幻觉 walkthrough;12 题双模型 source-only vs sv_query 对照(内部)。
125
+ **尚未跑 HWE-Bench/VeriBugBench**,不宣称对外准确率/成本收益。
126
+
127
+ > 全设计图已退役;局部 finding review 仍为 `exp`(`review render`),不是核心能力。
128
+ > RTL typo detection / ranking 属于独立项目 `rtl_typo_checker`,不在 sv_query core。
129
+ > 语义纪律见 [DISCIPLINE §3.5](docs/dev/DISCIPLINE.md)。
130
+
131
+ ---
132
+
133
+ ## 项目定位(2026-11-05)
134
+
135
+ 完整方向见 [product_direction_2026-10-31](docs/architecture/product_direction_2026-10-31.md)。
136
+
137
+ - **主场景**:agent 的 RTL debug / design 理解;迭代查询、多批脚本、按结论继续追问。
138
+ - **动态 debug 分工**:波形值由外部工具提取;sv_query 提供 canonical id/别名、层级、位映射、clock/reset、sequential stage、源码 evidence。
139
+ - **函数/class**:RTL 函数名 + 源码足够(不 inline);class 关注调用链/继承/对象关系、
140
+ constraint/covergroup 与 UVM 静态关系。
141
+ - **证据分级**:semantic 结果优先;UVM 宏相关的 `confidence=syntactic` 只作线索,不作证明。
142
+ - **核心原则**:事实与证据优先;未知/空/歧义显式;双向一致性 + claim verification。
143
+
144
+ ---
145
+
146
+ ## 5 分钟快速上手
147
+
148
+ ```bash
149
+ pip install sv_query
150
+ sv_query capabilities --json
151
+ ```
152
+
153
+ From a source checkout:
154
+
155
+ ```bash
156
+ git clone https://github.com/fundou1081/sv_query.git
157
+ cd sv_query
158
+ pip install -e ".[dev]"
159
+ ```
160
+
161
+ ### 查询信号驱动
162
+
163
+ ```bash
164
+ # 谁驱动 result
165
+ sv_query drivers top.result -f top.sv --json
166
+
167
+ # 下游负载
168
+ sv_query loads top.result -f top.sv --json
169
+
170
+ # 跨模块路径
171
+ sv_query paths top.a top.y -f top.sv --json
172
+
173
+ # 结构一致性
174
+ sv_query verify consistency --full --checks reciprocity,bit -f top.sv --json
175
+ ```
176
+
177
+ ### 波形 / 类型元数据
178
+
179
+ ```bash
180
+ sv_query trace profile top.data -f top.sv --json
181
+ sv_query trace manifest --path top.data -f top.sv --json
182
+ ```
183
+
184
+ ### 5 分钟反幻觉 walkthrough:单级 CDC
185
+
186
+ 一个常见错误结论:
187
+
188
+ > “`dst_valid` 在 `dst_clk` 域寄存过,所以有两级同步器,CDC 安全。”
189
+
190
+ ```bash
191
+ sv_query trace profile cdc_bug.dst_valid -f examples/anti_hallucination_cdc/cdc_bug.sv --json
192
+ # clock_domains = ["dst_clk"] ← 只能说明域,不证明同步链
193
+
194
+ sv_query trace fanin cdc_bug.dst_valid -f examples/anti_hallucination_cdc/cdc_bug.sv --json
195
+ # drivers: src_valid (distance=1), 1'b0 ← 没有 meta 中间级
196
+ ```
197
+
198
+ 结构证据直接反驳“两级同步器”:`src_valid → dst_valid` 只有一拍。
199
+ 完整命令、输出与 ground truth:
200
+ [examples/anti_hallucination_cdc/README.md](examples/anti_hallucination_cdc/README.md)。
201
+
202
+ 性能数据(单机实测、构图 vs 图内查询拆分):
203
+ [docs/validation/QUERY_PERF_2026-11-04.md](docs/validation/QUERY_PERF_2026-11-04.md)。
204
+
205
+ ---
206
+
207
+ ## 功能分层
208
+
209
+ | 层 | 命令 |
210
+ |---|---|
211
+ | **Scope** | `scope` / `instances` / `hierarchy` / `ports` / `params` / `connections` / `class` |
212
+ | **Trace** | `drivers` / `loads` / `paths` / `dataflow analyze` / `controlflow analyze` / `trace evidence/profile/lookup/manifest` |
213
+ | **Verify** | `verify consistency` / `verify claim` / `verify structural`(仅客观结构一致性;RTL typo 是独立项目) |
214
+ | **Class/约束/覆盖** | `class --relations`(含 UVM 静态) / `trace constraints` / `trace covergroups` / `trace coverpoints` / `trace covergroup` |
215
+ | **Locate** | `stats` / `search` / `graph nodes/edges` / `graph subgraph` / `capabilities` |
216
+ | **State** | `snapshot save/list/compare/delete` |
217
+ | **exp** | `audit` / `diagnose` / `trace overview` / `review render` / `architecture graph` / `trace impact`(默认隐藏,不承诺契约) |
218
+
219
+ > `visualize` / `arch` / `design` 全设计图命令已于 2026-11-03 退役;`review render` 仍是 exp。
220
+
221
+ ---
222
+
223
+ ## 验证状态(2026-11-11)
224
+
225
+ | 项 | 状态 |
226
+ |---|---|
227
+ | 全量回归 | 见 [INDEX 当前基线](docs/INDEX.md#-当前基线-单一真相源--计数只写在这里):canonical 0 failed;opensource/skip 计数不写死(口径见 INDEX) |
228
+ | 开源 smoke | strict_uart / verilog-axi / picorv32 / SERV |
229
+ | 性能基准 | picorv32 / verilog-axi / SERV;build、warm query、cold CLI、peak RSS |
230
+ | 反幻觉 | 单级 CDC walkthrough:profile + fanin/fanout 反驳“两级同步器” |
231
+ | Agent 对照(内部) | 固定协议 12 题 ×2 模型 ×2 臂 ×2 seed:**T2 48/48,source 32/48**;见下方 |
232
+ | 硬隔离 | 96-cell 矩阵;source 无 repo/CLI,T2 无 truth/task JSON;12×3 未跑 |
233
+ | 未做 | 外部 VeriBug/HWE 对照、真实根因/patch、token 成本、3rd seed |
234
+
235
+ 性能:构图是 cold CLI 主导成本(本机 verilog-axi 约 26 s / 13.8k nodes),
236
+ 图内查询为毫秒级。不要把 warm query 的毫秒数字误读成冷启动查询。
237
+ 详见 [性能基准](docs/validation/QUERY_PERF_2026-11-04.md) 与
238
+ [反幻觉 walkthrough](examples/anti_hallucination_cdc/README.md)。
239
+
240
+ ### Agent 对照(内部,2026-11-07)
241
+
242
+ 12 个“源码远、结构近”任务(AXI / SERV / PicoRV32),固定协议:
243
+ source/T2 hard isolation、fact check、`--depth 1`、query log;2 seed。
244
+
245
+ | 模型 / 臂 | exact(24 cells) | high-conf 错 |
246
+ |---|---:|---:|
247
+ | MiniMax-M3 / source | 17/24 | 7/24 |
248
+ | MiniMax-M3 / svq | **24/24** | 0/24 |
249
+ | DeepSeek-Flash / source | 15/24 | 2/24 |
250
+ | DeepSeek-Flash / svq | **24/24** | 0/24 |
251
+
252
+ 合计:
253
+
254
+ ```text
255
+ source: 32/48
256
+ svq: 48/48
257
+ ```
258
+
259
+ 观察:
260
+
261
+ - svq 在两个 seed、两个模型上均 48/48;
262
+ - source 仍出现 high-confidence 错误(9/48);
263
+ - 这是 **direct structural query**,不是 debug reasoning;
264
+ - token/cold-warm 成本未拆分,不能声称成本更低;
265
+ - 不声称 HWE/VeriBug 或真实项目准确率。
266
+
267
+ 硬隔离:source 臂拒绝 repo / `sv_query` / pilot artifact;T2 拒绝 task JSON/truth。
268
+ 已跑 96-cell 矩阵;12×3 未跑(3rd seed 不做)。
269
+
270
+ 详见 [12-task 固定协议](docs/validation/LONG_RANGE_12_FIXED_2026-11-07.md)、
271
+ [最终验证摘要](docs/validation/FINAL_VALIDATION_SUMMARY_2026-11-07.md)、
272
+ [硬隔离审计](docs/validation/HARD_ISOLATION_2026-11-05.md)。
273
+
274
+ ---
275
+
276
+ ## Python API
277
+
278
+ ```python
279
+ from sv_query.trace.unified_tracer import UnifiedTracer
280
+
281
+ tracer = UnifiedTracer(sources={"top.sv": src})
282
+ tracer.build_graph()
283
+ graph = tracer.get_graph()
284
+
285
+ drivers = tracer.trace_fanin_detailed("top.result")
286
+ for d in drivers:
287
+ print(d.node.id, "<-", d.expression)
288
+ print(" when:", d.condition or "always")
289
+ ```
290
+
291
+ ---
292
+
293
+ ## 项目结构
294
+
295
+ ```
296
+ sv_query/
297
+ ├── src/sv_query/trace/ # 核心图/追踪/校验
298
+ │ ├── unified_tracer.py # 统一入口
299
+ │ ├── core/
300
+ │ │ ├── graph/ # SignalGraph / models / analyzer
301
+ │ │ ├── driver_extractor.py
302
+ │ │ ├── graph_builder.py
303
+ │ │ └── visitors/
304
+ ├── src/cli/ # CLI (core/exp)
305
+ ├── sim/tests/ # 测试
306
+ ├── examples/ # 可复现 walkthrough(反幻觉 CDC)
307
+ ├── docs/ # 文档 / 性能数据
308
+ ├── skills/ # OpenClaw skill 包 (sv-query, 供 agent 加载)
309
+ └── tools/ # 独立工具(含 benchmark/query_perf.py)
310
+ ```
311
+
312
+ ---
313
+
314
+ ## 测试
315
+
316
+ ```bash
317
+ pip install -e ".[dev]"
318
+
319
+ # 日常主回归
320
+ python -m pytest sim/tests/ -m "not opensource" -q
321
+
322
+ # 开源项目验证
323
+ python -m pytest sim/tests/ -m opensource -v
324
+ ```
325
+
326
+ 详见 [TESTING.md](TESTING.md)。计数以 [docs/INDEX.md](docs/INDEX.md) 当前基线为准。
327
+
328
+ ---
329
+
330
+ ## 相关文档
331
+
332
+ - [产品方向](docs/architecture/product_direction_2026-10-31.md)
333
+ - [结构审查/动态子图计划](docs/architecture/structural_review_plan_2026-11-02.md)
334
+ - [查询性能基准](docs/validation/QUERY_PERF_2026-11-04.md) · [反幻觉 CDC walkthrough](examples/anti_hallucination_cdc/README.md)
335
+ - [12-task 固定协议](docs/validation/LONG_RANGE_12_FIXED_2026-11-07.md) · [最终验证摘要](docs/validation/FINAL_VALIDATION_SUMMARY_2026-11-07.md) · [硬隔离审计](docs/validation/HARD_ISOLATION_2026-11-05.md)
336
+ - [架构文档](docs/ARCHITECTURE.md)
337
+ - [准确性审计](docs/architecture/signal_graph_accuracy_audit.md)
338
+ - [语义 regex 纪律](docs/dev/DISCIPLINE.md) · [开发纪律](AGENTS.md) · [当前任务](CURRENT_TODO.md)
339
+ - [文档索引](docs/INDEX.md)
340
+ - [已知限制](docs/KNOWN_LIMITATIONS.md)
341
+
342
+ ## 许可
343
+
344
+ MIT + Apache 2.0 双许可