prism-code-workspace 1.0.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.
- prism_code_workspace-1.0.0/.gitignore +220 -0
- prism_code_workspace-1.0.0/LICENSE +21 -0
- prism_code_workspace-1.0.0/PKG-INFO +272 -0
- prism_code_workspace-1.0.0/README.md +244 -0
- prism_code_workspace-1.0.0/assets/icon.ico +0 -0
- prism_code_workspace-1.0.0/assets/icon.png +0 -0
- prism_code_workspace-1.0.0/pyproject.toml +50 -0
- prism_code_workspace-1.0.0/python_app/__init__.py +3 -0
- prism_code_workspace-1.0.0/python_app/ai.py +225 -0
- prism_code_workspace-1.0.0/python_app/analysis.py +953 -0
- prism_code_workspace-1.0.0/python_app/compare.py +685 -0
- prism_code_workspace-1.0.0/python_app/compare_engine.py +284 -0
- prism_code_workspace-1.0.0/python_app/compiled_analysis.py +727 -0
- prism_code_workspace-1.0.0/python_app/desktop.py +181 -0
- prism_code_workspace-1.0.0/python_app/function_pov/__init__.py +16 -0
- prism_code_workspace-1.0.0/python_app/function_pov/analyzer.py +464 -0
- prism_code_workspace-1.0.0/python_app/function_pov/graph.py +50 -0
- prism_code_workspace-1.0.0/python_app/function_pov/models.py +53 -0
- prism_code_workspace-1.0.0/python_app/function_pov/pov/__init__.py +17 -0
- prism_code_workspace-1.0.0/python_app/function_pov/pov/engine.py +1630 -0
- prism_code_workspace-1.0.0/python_app/function_pov/pov/exercises.py +1263 -0
- prism_code_workspace-1.0.0/python_app/function_pov_ui.py +1749 -0
- prism_code_workspace-1.0.0/python_app/i18n.py +570 -0
- prism_code_workspace-1.0.0/python_app/installer.nsi +70 -0
- prism_code_workspace-1.0.0/python_app/installer_runtime.nsi +70 -0
- prism_code_workspace-1.0.0/python_app/js_analysis.py +709 -0
- prism_code_workspace-1.0.0/python_app/launch.py +6 -0
- prism_code_workspace-1.0.0/python_app/launch_native.py +14 -0
- prism_code_workspace-1.0.0/python_app/metrics_advisor.py +79 -0
- prism_code_workspace-1.0.0/python_app/native_app.py +1709 -0
- prism_code_workspace-1.0.0/python_app/requirements.txt +7 -0
- prism_code_workspace-1.0.0/python_app/server.py +453 -0
- prism_code_workspace-1.0.0/samples/Shape.java +22 -0
- prism_code_workspace-1.0.0/samples/ShapeRefactored.java +38 -0
- prism_code_workspace-1.0.0/samples/report_after.py +26 -0
- prism_code_workspace-1.0.0/samples/report_before.py +23 -0
- prism_code_workspace-1.0.0/screenshots/ai-modal-dark.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ai-modal-final.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ai-modal-light.png +0 -0
- prism_code_workspace-1.0.0/screenshots/app-shell-scrolled.png +0 -0
- prism_code_workspace-1.0.0/screenshots/guide-examples-modal.png +0 -0
- prism_code_workspace-1.0.0/screenshots/guide-examples-tab.png +0 -0
- prism_code_workspace-1.0.0/screenshots/guide-tab-final.png +0 -0
- prism_code_workspace-1.0.0/screenshots/guide-tabs-crop.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-final-editor.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-final-imported.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-final-intake.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-final-light.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-final-palette.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-final-studio.png +0 -0
- prism_code_workspace-1.0.0/screenshots/ide-header-icon.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-ai-settings.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-ai.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-guide.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-java-data.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-java-guide.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-java-trace.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-java-tree.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-java.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-javascript-guide.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-javascript-trace.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-javascript.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-portable.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-studio.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-trace.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-trimmed.png +0 -0
- prism_code_workspace-1.0.0/screenshots/native-welcome.png +0 -0
- prism_code_workspace-1.0.0/screenshots/python-desktop.png +0 -0
- prism_code_workspace-1.0.0/screenshots/python-engine-flow.png +0 -0
- prism_code_workspace-1.0.0/screenshots/python-engine-guide.png +0 -0
- prism_code_workspace-1.0.0/screenshots/python-engine-trace.png +0 -0
- prism_code_workspace-1.0.0/screenshots/python-engine-tree.png +0 -0
- prism_code_workspace-1.0.0/screenshots/simple-editor-light.png +0 -0
- prism_code_workspace-1.0.0/screenshots/simple-editor.png +0 -0
- prism_code_workspace-1.0.0/screenshots/simple-studio.png +0 -0
- prism_code_workspace-1.0.0/screenshots/simple-welcome-light.png +0 -0
- prism_code_workspace-1.0.0/screenshots/simple-welcome.png +0 -0
- prism_code_workspace-1.0.0/tests_py/test_ai.py +38 -0
- prism_code_workspace-1.0.0/tests_py/test_analysis.py +115 -0
- prism_code_workspace-1.0.0/tests_py/test_compare.py +177 -0
- prism_code_workspace-1.0.0/tests_py/test_compiled.py +64 -0
- prism_code_workspace-1.0.0/tests_py/test_entry_points.py +21 -0
- prism_code_workspace-1.0.0/tests_py/test_flowchart.py +90 -0
- prism_code_workspace-1.0.0/tests_py/test_function_pov.py +549 -0
- prism_code_workspace-1.0.0/tests_py/test_i18n.py +117 -0
- prism_code_workspace-1.0.0/tests_py/test_javascript.py +60 -0
- prism_code_workspace-1.0.0/tests_py/test_metrics_advisor.py +62 -0
- prism_code_workspace-1.0.0/tests_py/test_pov_exercises.py +413 -0
- prism_code_workspace-1.0.0/tests_py/test_server.py +106 -0
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[codz]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
share/python-wheels/
|
|
24
|
+
*.egg-info/
|
|
25
|
+
.installed.cfg
|
|
26
|
+
*.egg
|
|
27
|
+
MANIFEST
|
|
28
|
+
|
|
29
|
+
# PyInstaller
|
|
30
|
+
# Usually these files are written by a python script from a template
|
|
31
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
32
|
+
*.manifest
|
|
33
|
+
*.spec
|
|
34
|
+
|
|
35
|
+
# Installer logs
|
|
36
|
+
pip-log.txt
|
|
37
|
+
pip-delete-this-directory.txt
|
|
38
|
+
|
|
39
|
+
# Unit test / coverage reports
|
|
40
|
+
htmlcov/
|
|
41
|
+
.tox/
|
|
42
|
+
.nox/
|
|
43
|
+
.coverage
|
|
44
|
+
.coverage.*
|
|
45
|
+
.cache
|
|
46
|
+
nosetests.xml
|
|
47
|
+
coverage.xml
|
|
48
|
+
*.cover
|
|
49
|
+
*.py.cover
|
|
50
|
+
*.lcov
|
|
51
|
+
.hypothesis/
|
|
52
|
+
.pytest_cache/
|
|
53
|
+
cover/
|
|
54
|
+
|
|
55
|
+
# Translations
|
|
56
|
+
*.mo
|
|
57
|
+
*.pot
|
|
58
|
+
|
|
59
|
+
# Django stuff:
|
|
60
|
+
*.log
|
|
61
|
+
local_settings.py
|
|
62
|
+
db.sqlite3
|
|
63
|
+
db.sqlite3-journal
|
|
64
|
+
|
|
65
|
+
# Flask stuff:
|
|
66
|
+
instance/
|
|
67
|
+
.webassets-cache
|
|
68
|
+
|
|
69
|
+
# Scrapy stuff:
|
|
70
|
+
.scrapy
|
|
71
|
+
|
|
72
|
+
# Sphinx documentation
|
|
73
|
+
docs/_build/
|
|
74
|
+
|
|
75
|
+
# PyBuilder
|
|
76
|
+
.pybuilder/
|
|
77
|
+
target/
|
|
78
|
+
|
|
79
|
+
# Jupyter Notebook
|
|
80
|
+
.ipynb_checkpoints
|
|
81
|
+
|
|
82
|
+
# IPython
|
|
83
|
+
profile_default/
|
|
84
|
+
ipython_config.py
|
|
85
|
+
|
|
86
|
+
# pyenv
|
|
87
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
88
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
89
|
+
# .python-version
|
|
90
|
+
|
|
91
|
+
# pipenv
|
|
92
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
93
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
94
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
95
|
+
# install all needed dependencies.
|
|
96
|
+
# Pipfile.lock
|
|
97
|
+
|
|
98
|
+
# uv
|
|
99
|
+
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
|
100
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
101
|
+
# commonly ignored for libraries.
|
|
102
|
+
# uv.lock
|
|
103
|
+
|
|
104
|
+
# poetry
|
|
105
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
106
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
107
|
+
# commonly ignored for libraries.
|
|
108
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
109
|
+
# poetry.lock
|
|
110
|
+
# poetry.toml
|
|
111
|
+
|
|
112
|
+
# pdm
|
|
113
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
114
|
+
# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
|
|
115
|
+
# https://pdm-project.org/en/latest/usage/project/#working-with-version-control
|
|
116
|
+
# pdm.lock
|
|
117
|
+
# pdm.toml
|
|
118
|
+
.pdm-python
|
|
119
|
+
.pdm-build/
|
|
120
|
+
|
|
121
|
+
# pixi
|
|
122
|
+
# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
|
|
123
|
+
# pixi.lock
|
|
124
|
+
# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
|
|
125
|
+
# in the .venv directory. It is recommended not to include this directory in version control.
|
|
126
|
+
.pixi/*
|
|
127
|
+
!.pixi/config.toml
|
|
128
|
+
|
|
129
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
130
|
+
__pypackages__/
|
|
131
|
+
|
|
132
|
+
# Celery stuff
|
|
133
|
+
celerybeat-schedule*
|
|
134
|
+
celerybeat.pid
|
|
135
|
+
|
|
136
|
+
# Redis
|
|
137
|
+
*.rdb
|
|
138
|
+
*.aof
|
|
139
|
+
*.pid
|
|
140
|
+
|
|
141
|
+
# RabbitMQ
|
|
142
|
+
mnesia/
|
|
143
|
+
rabbitmq/
|
|
144
|
+
rabbitmq-data/
|
|
145
|
+
|
|
146
|
+
# ActiveMQ
|
|
147
|
+
activemq-data/
|
|
148
|
+
|
|
149
|
+
# SageMath parsed files
|
|
150
|
+
*.sage.py
|
|
151
|
+
|
|
152
|
+
# Environments
|
|
153
|
+
.env
|
|
154
|
+
.envrc
|
|
155
|
+
.venv
|
|
156
|
+
env/
|
|
157
|
+
venv/
|
|
158
|
+
ENV/
|
|
159
|
+
env.bak/
|
|
160
|
+
venv.bak/
|
|
161
|
+
|
|
162
|
+
# Spyder project settings
|
|
163
|
+
.spyderproject
|
|
164
|
+
.spyproject
|
|
165
|
+
|
|
166
|
+
# Rope project settings
|
|
167
|
+
.ropeproject
|
|
168
|
+
|
|
169
|
+
# mkdocs/Zensical documentation
|
|
170
|
+
/site
|
|
171
|
+
|
|
172
|
+
# mypy
|
|
173
|
+
.mypy_cache/
|
|
174
|
+
.dmypy.json
|
|
175
|
+
dmypy.json
|
|
176
|
+
|
|
177
|
+
# Pyre type checker
|
|
178
|
+
.pyre/
|
|
179
|
+
|
|
180
|
+
# pytype static type analyzer
|
|
181
|
+
.pytype/
|
|
182
|
+
|
|
183
|
+
# Cython debug symbols
|
|
184
|
+
cython_debug/
|
|
185
|
+
|
|
186
|
+
# PyCharm
|
|
187
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
188
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
189
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
190
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
191
|
+
# .idea/
|
|
192
|
+
|
|
193
|
+
# Abstra
|
|
194
|
+
# Abstra is an AI-powered process automation framework.
|
|
195
|
+
# Ignore directories containing user credentials, local state, and settings.
|
|
196
|
+
# Learn more at https://abstra.io/docs
|
|
197
|
+
.abstra/
|
|
198
|
+
|
|
199
|
+
# Visual Studio Code
|
|
200
|
+
# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
|
|
201
|
+
# can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
|
|
202
|
+
# and can be added to the global gitignore or merged into this file. However, if you prefer, you
|
|
203
|
+
# could uncomment the following to ignore the entire vscode folder
|
|
204
|
+
# .vscode/
|
|
205
|
+
# Temporary file for partial code execution
|
|
206
|
+
tempCodeRunnerFile.py
|
|
207
|
+
|
|
208
|
+
# Ruff stuff:
|
|
209
|
+
.ruff_cache/
|
|
210
|
+
|
|
211
|
+
# PyPI configuration file
|
|
212
|
+
.pypirc
|
|
213
|
+
|
|
214
|
+
# Marimo
|
|
215
|
+
marimo/_static/
|
|
216
|
+
marimo/_lsp/
|
|
217
|
+
__marimo__/
|
|
218
|
+
|
|
219
|
+
# Streamlit
|
|
220
|
+
.streamlit/secrets.toml
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ryan25576868
|
|
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,272 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: prism-code-workspace
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A native Python workspace for understanding code with flowchart, AST, safe trace, structural diff, and beginner guide.
|
|
5
|
+
Project-URL: Homepage, https://github.com/ryan25576868/cs1302-group02
|
|
6
|
+
Project-URL: Repository, https://github.com/ryan25576868/cs1302-group02
|
|
7
|
+
Author: CS1302 Group 02
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: ast,code-analysis,diff,education,pyside6,visualization
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Education
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Requires-Dist: tree-sitter-c>=0.23.0
|
|
18
|
+
Requires-Dist: tree-sitter-cpp>=0.23.0
|
|
19
|
+
Requires-Dist: tree-sitter-java>=0.23.0
|
|
20
|
+
Requires-Dist: tree-sitter-javascript>=0.23.0
|
|
21
|
+
Requires-Dist: tree-sitter-typescript>=0.23.0
|
|
22
|
+
Requires-Dist: tree-sitter>=0.23.0
|
|
23
|
+
Provides-Extra: compare
|
|
24
|
+
Requires-Dist: structscope>=0.1.0; extra == 'compare'
|
|
25
|
+
Provides-Extra: gui
|
|
26
|
+
Requires-Dist: pyside6>=6.7.0; extra == 'gui'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# Prism
|
|
30
|
+
|
|
31
|
+
**A native Python workspace for understanding code.**
|
|
32
|
+
|
|
33
|
+
Prism turns a source file into a linked set of views—flow, syntax, execution, and data—and explains the program in plain English. It is built for beginners, runs entirely on the local machine, and is implemented with **PySide6** rather than a browser runtime.
|
|
34
|
+
|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
## Highlights
|
|
38
|
+
|
|
39
|
+
- **Six languages** — Python, JavaScript, TypeScript, Java, C++, and C.
|
|
40
|
+
- **Four linked views** — Flowchart, Syntax Tree, Live Trace, and Data Flow.
|
|
41
|
+
- **Structural compare** — diff two versions of one file by classes and functions instead of by lines, powered by [structscope](https://pypi.org/project/structscope/).
|
|
42
|
+
- **Beginner's guide** — overview, mental model, step-by-step walkthrough, line-by-line notes, concepts, common mistakes, and a quick check.
|
|
43
|
+
- **Function POV** — practise whole-program or function execution with a bounded, non-executing simulator, interactive challenges, and verified similar exercises.
|
|
44
|
+
- **Native motion** — page and tab transitions, sequenced flowchart nodes, trace-detail fades, and a drifting welcome illustration.
|
|
45
|
+
- **Optional AI** — add a second explanation with OpenAI-compatible, DeepSeek, Grok, Anthropic, or Gemini. Local analysis needs no AI.
|
|
46
|
+
- **Bilingual interface** — switch between English and 简体中文 from the top bar; the window re-labels itself without a restart.
|
|
47
|
+
- **Local-first** — source code is parsed and simulated in-process. No account, telemetry, or browser tab required.
|
|
48
|
+
- **Source-only** — the project is a Python application, not a web wrapper.
|
|
49
|
+
|
|
50
|
+
## Supported languages
|
|
51
|
+
|
|
52
|
+
| Language | Parser | Analysis module |
|
|
53
|
+
| --- | --- | --- |
|
|
54
|
+
| Python | Python `ast` | `python_app/analysis.py` |
|
|
55
|
+
| JavaScript | tree-sitter | `python_app/js_analysis.py` |
|
|
56
|
+
| TypeScript | tree-sitter | `python_app/js_analysis.py` |
|
|
57
|
+
| Java | tree-sitter | `python_app/compiled_analysis.py` |
|
|
58
|
+
| C++ | tree-sitter | `python_app/compiled_analysis.py` |
|
|
59
|
+
| C | tree-sitter | `python_app/compiled_analysis.py` |
|
|
60
|
+
|
|
61
|
+
The trace is a safe, bounded interpreter—not an execution of the original program. It covers common beginner constructs such as variables, arithmetic, conditions, loops, functions, returns, and print output. See [Limitations](#limitations) for the deliberately excluded surface.
|
|
62
|
+
|
|
63
|
+
## Quick start
|
|
64
|
+
|
|
65
|
+
Requires **Python 3.11 or newer** on Windows.
|
|
66
|
+
|
|
67
|
+
```powershell
|
|
68
|
+
python -m pip install -r python_app\requirements.txt
|
|
69
|
+
python python_app\launch_native.py
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
No installer is included; this is the source-only distribution.
|
|
73
|
+
|
|
74
|
+
The app opens with a blank document. Choose a language, then:
|
|
75
|
+
|
|
76
|
+
- **Open editor** to write code.
|
|
77
|
+
- **Import file** to load a source file.
|
|
78
|
+
- **Try a case** to start from a small example.
|
|
79
|
+
- **Compare versions** to diff two versions of one file by structure.
|
|
80
|
+
|
|
81
|
+
## Usage
|
|
82
|
+
|
|
83
|
+
1. Select a language from the welcome screen.
|
|
84
|
+
2. Open the editor, import a file, or load an example.
|
|
85
|
+
3. Press **Visualize & explain**.
|
|
86
|
+
4. Explore the results:
|
|
87
|
+
|
|
88
|
+
- **Flowchart** — follow decisions, loops, and the order of statements.
|
|
89
|
+
- **Syntax Tree** — inspect the structural tree of the parsed program.
|
|
90
|
+
- **Live Trace** — step through values, variables, output, and loop iterations.
|
|
91
|
+
- **Data Flow** — see assignments and the names they depend on.
|
|
92
|
+
- **Guide** — read the generated explanation from top to bottom.
|
|
93
|
+
|
|
94
|
+
5. Use **Enhance guide** to request an optional AI explanation.
|
|
95
|
+
6. Use **Save guide** to export the generated guide as Markdown.
|
|
96
|
+
|
|
97
|
+
For Python analyses, choose **Function POV** beside the result actions to open
|
|
98
|
+
the **Be the Code** and **Be the Function** modes. Be the Code follows
|
|
99
|
+
top-level statements even when there are no functions; Be the Function lets you
|
|
100
|
+
select a function and enter JSON arguments, with blank optional values using
|
|
101
|
+
their defaults. Both modes reuse the same challenges, hints, answer history,
|
|
102
|
+
source highlighting, variable and call-stack views, and completion summary.
|
|
103
|
+
Prism validates a restricted AST subset before play and simulates it without
|
|
104
|
+
executing the source. After completing a practice, choose **Practice Similar
|
|
105
|
+
Questions** for **New Values** or **Similar Logic**. New Values changes
|
|
106
|
+
supported literal inputs or function arguments while keeping the original AST
|
|
107
|
+
structure and source intact. It prefers coordinated numeric changes and, for
|
|
108
|
+
simple comparisons, values near branch boundaries. Similar Logic uses a small
|
|
109
|
+
catalog of beginner-friendly, predefined patterns and requires an AST logic
|
|
110
|
+
change beyond renamed variables or changed literals. It also explains the
|
|
111
|
+
concept being practised. Generated code is parsed and simulated before it is
|
|
112
|
+
shown; each session avoids repeating the same variant. The side-by-side preview
|
|
113
|
+
keeps the original exercise available for comparison.
|
|
114
|
+
|
|
115
|
+

|
|
116
|
+
|
|
117
|
+
## Interface language
|
|
118
|
+
|
|
119
|
+
The language box in the top-left of the window switches the interface between
|
|
120
|
+
English and 简体中文. The choice applies immediately — menus, buttons, status
|
|
121
|
+
lines and dialogs are re-labelled in place, with no restart — and is remembered
|
|
122
|
+
for the next launch.
|
|
123
|
+
|
|
124
|
+
Strings live in `python_app/i18n.py` as one dictionary per language, keyed by the
|
|
125
|
+
English text. Adding a language means adding one dictionary; a test walks the UI
|
|
126
|
+
modules and fails when a `tr(...)` string has no translation, so the table cannot
|
|
127
|
+
silently drift behind the interface. Code-level names (Python, Java, C++) stay
|
|
128
|
+
untranslated on purpose, and the explanation text Prism generates for a program
|
|
129
|
+
remains in English.
|
|
130
|
+
|
|
131
|
+
## Compare two versions
|
|
132
|
+
|
|
133
|
+
Prism can diff two versions of the same file by **structure** instead of by
|
|
134
|
+
lines. Open **Compare versions** on the welcome screen, or use
|
|
135
|
+
**Tools → Compare two versions…** (`Ctrl+D`).
|
|
136
|
+
|
|
137
|
+
1. Pick the language, then choose a *before* file and an *after* file — or
|
|
138
|
+
press **Sample pair** to load the bundled example for Python or Java.
|
|
139
|
+
2. Press **Compare**.
|
|
140
|
+
3. Read the map: every class, function and method appears twice — once per
|
|
141
|
+
version — joined by a curve when the two sides matched.
|
|
142
|
+
|
|
143
|
+
| Colour | Meaning |
|
|
144
|
+
| --- | --- |
|
|
145
|
+
| green | added in the after version |
|
|
146
|
+
| red | removed from the before version |
|
|
147
|
+
| amber | same symbol, changed body or signature |
|
|
148
|
+
| blue | same body, different name (moved) |
|
|
149
|
+
| grey | unchanged |
|
|
150
|
+
|
|
151
|
+
Card width tracks the number of code lines, and the complexity badge appears
|
|
152
|
+
when a symbol got more or less branching. Hover a card to lift it, light up its
|
|
153
|
+
partner on the other side and dim everything else — the pair you are looking at
|
|
154
|
+
stays readable however crowded the map gets. Click any card to see the two
|
|
155
|
+
excerpts aligned line by line, with added, removed and replaced lines toned
|
|
156
|
+
differently. The filter next to the language box dims everything except one
|
|
157
|
+
status, which makes "what actually changed" readable at a glance.
|
|
158
|
+
|
|
159
|
+
The diff itself comes from [structscope](https://pypi.org/project/structscope/),
|
|
160
|
+
a small library that matches symbols across two parses. Prism already builds
|
|
161
|
+
the trees, so no second parser is involved: `compare_engine.py` adapts Prism's
|
|
162
|
+
analysis trees into structscope's symbol model.
|
|
163
|
+
|
|
164
|
+
If `structscope` is not installed the Compare page explains what to run:
|
|
165
|
+
|
|
166
|
+
```console
|
|
167
|
+
pip install structscope
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
While working on both projects side by side, install the checkout instead:
|
|
171
|
+
|
|
172
|
+
```console
|
|
173
|
+
pip install -e ..\structdiff
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Optional AI
|
|
177
|
+
|
|
178
|
+
Open **Connect AI** in the top bar, or **Tools → Connect AI**.
|
|
179
|
+
|
|
180
|
+
| Provider | Base URL | Default model |
|
|
181
|
+
| --- | --- | --- |
|
|
182
|
+
| OpenAI / compatible | `https://api.openai.com/v1` | `gpt-6.1-terra` |
|
|
183
|
+
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-flash` |
|
|
184
|
+
| Grok (xAI) | `https://api.x.ai/v1` | `grok-4.7` |
|
|
185
|
+
| Anthropic | `https://api.anthropic.com` | `claude-fable-5-2` |
|
|
186
|
+
| Google Gemini | `https://generativelanguage.googleapis.com` | `gemini-4-hydrogen` |
|
|
187
|
+
|
|
188
|
+
Model IDs change frequently. The model field is editable, so use the identifier published by your provider.
|
|
189
|
+
|
|
190
|
+
1. Choose a provider.
|
|
191
|
+
2. Confirm the base URL and model.
|
|
192
|
+
3. Enter an API key when the provider requires one.
|
|
193
|
+
4. Use **Test connection**.
|
|
194
|
+
5. Press **Save**, then **Enhance guide** from the results header.
|
|
195
|
+
|
|
196
|
+
The request is sent only when you explicitly test a connection or enhance a guide. The key is used for that request and is not written to logs. **Remember the key on this device** stores it in the local Qt settings store.
|
|
197
|
+
|
|
198
|
+
## Architecture
|
|
199
|
+
|
|
200
|
+
```text
|
|
201
|
+
python_app/
|
|
202
|
+
native_app.py PySide6 window, editor, views, guide, dialogs
|
|
203
|
+
analysis.py Python AST analysis, safe trace, guide generator
|
|
204
|
+
js_analysis.py tree-sitter JavaScript/TypeScript analysis and trace
|
|
205
|
+
compiled_analysis.py tree-sitter Java/C++/C analysis and trace
|
|
206
|
+
compare.py Compare page: two-version map and aligned excerpts
|
|
207
|
+
compare_engine.py Prism trees -> structscope symbol model, structural diff
|
|
208
|
+
function_pov/ Restricted Python analyzer, simulator, and exercise generator
|
|
209
|
+
function_pov_ui.py Native Function POV selection and practice screens
|
|
210
|
+
i18n.py Interface strings: English source text + translations
|
|
211
|
+
ai.py Optional AI provider calls and validation
|
|
212
|
+
launch_native.py Application entry point
|
|
213
|
+
requirements.txt PySide6 and tree-sitter grammars
|
|
214
|
+
tests_py/
|
|
215
|
+
test_analysis.py
|
|
216
|
+
test_javascript.py
|
|
217
|
+
test_compiled.py
|
|
218
|
+
test_ai.py
|
|
219
|
+
test_compare.py
|
|
220
|
+
test_i18n.py
|
|
221
|
+
samples/ before/after pairs used by the Compare page
|
|
222
|
+
assets/ Application icon
|
|
223
|
+
screenshots/ Native app screenshots
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Design principles
|
|
227
|
+
|
|
228
|
+
- **One process, one language.** The UI, parser adapters, trace engines, guide generator, and AI calls are all Python.
|
|
229
|
+
- **Native rendering.** Diagrams are drawn with `QGraphicsScene`; the editor, trees, tables, and guide are native Qt widgets.
|
|
230
|
+
- **Bounded execution.** Traces have step, loop, and source-size limits. Unsupported constructs stop the trace rather than producing invented values.
|
|
231
|
+
- **No browser runtime.** There is no HTML/CSS/JS application layer, no Electron, and no Node dependency.
|
|
232
|
+
- **Local by default.** AI is an optional outbound request, never a background process.
|
|
233
|
+
|
|
234
|
+
## Tests
|
|
235
|
+
|
|
236
|
+
```powershell
|
|
237
|
+
python -m unittest discover -s tests_py -v
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
**85 tests discovered: 78 passed, 7 skipped, 0 failed.** The 7 structural-compare tests are skipped when the optional `structscope` package is unavailable. Coverage includes Python, JavaScript, TypeScript, Java, C++, and C analysis; trace output; guide generation; syntax errors; AI settings validation; empty input; Be the Code and Be the Function's bounded simulations and native UI flow; deterministic and duplicate-safe similar exercises; Flowchart viewport fitting; and translated interface strings. The structural-compare tests cover model mapping, statuses, renames, and line alignment when `structscope` is installed.
|
|
241
|
+
|
|
242
|
+
## Troubleshooting
|
|
243
|
+
|
|
244
|
+
- **`ModuleNotFoundError: PySide6` or `tree_sitter`** — install the requirements with `python -m pip install -r python_app\requirements.txt`.
|
|
245
|
+
- **No source file imports** — use the file dialog or drag support is intentionally not implemented in this native edition; use **Import file**.
|
|
246
|
+
- **Trace stops early** — the code uses a construct outside the bounded beginner subset. The structural views and guide remain available.
|
|
247
|
+
- **AI connection fails** — verify the base URL, model ID, API key, and network access. The local guide does not depend on AI.
|
|
248
|
+
|
|
249
|
+
## Limitations
|
|
250
|
+
|
|
251
|
+
- The compiled-language trace supports a beginner subset. Complex generics, pointer arithmetic, macros, multithreading, and exception-heavy Java are not fully interpreted.
|
|
252
|
+
- JavaScript and TypeScript coverage is intentionally conservative; some higher-order and dynamic constructs are outside the trace subset.
|
|
253
|
+
- Function POV is Python-only. Be the Code supports simple top-level assignments and updates, expressions, nested `if/else`, bounded `for`/`while`, safe built-ins, direct project-function calls, and `print` output. Be the Function supports simple positional parameters, assignments, conditions, bounded loops, direct calls, and returns. Imports, classes, async/nested functions, decorated functions, advanced parameters, arbitrary attributes, file/network access, and other side effects are not simulated. Simulations cap source size, AST nodes, steps, call depth, values, output, and total loop iterations; unsupported behavior is rejected before play.
|
|
254
|
+
- Practice Similar Questions is limited to safe literal input changes for top-level scalar/list/tuple assignments, simple JSON scalar/list/tuple function arguments, and integer `range` bounds. New Values preserves the AST structure; branch-focused candidates are currently limited to simple numeric comparisons against literals or known inputs, including loop variables over numeric lists/tuples. Similar Logic requires a normalized AST difference in an operator, expression, or control-flow structure; renaming identifiers or changing literals alone is rejected. Its supported patterns are Be the Code list-accumulation loops (with or without one condition), bounded counter `while` loops, and simple conditional output; Be the Function list-accumulation loops with returns, one- or two-parameter branch/return functions, simple arithmetic returns, and a direct helper call followed by arithmetic. Multi-function Be the Code programs remain unsupported for Similar Logic. Other structures, multiple interacting patterns, unsupported defaults, or exhausted variants are explained rather than approximated. Every candidate must pass the same restricted AST simulator before display.
|
|
255
|
+
- The flow and data views are explanatory diagrams, not compiler-grade control-flow graphs or SSA.
|
|
256
|
+
- Source snippets are capped at 60,000 characters.
|
|
257
|
+
- AI output depends on the selected provider and model. The local guide remains available if a request fails.
|
|
258
|
+
- The app targets Windows 10/11 x64.
|
|
259
|
+
|
|
260
|
+
## More screenshots
|
|
261
|
+
|
|
262
|
+
### Beginner's guide
|
|
263
|
+
|
|
264
|
+

|
|
265
|
+
|
|
266
|
+
### Optional AI settings
|
|
267
|
+
|
|
268
|
+

|
|
269
|
+
|
|
270
|
+
## License
|
|
271
|
+
|
|
272
|
+
This project is distributed under the MIT License; see [LICENSE](./LICENSE).
|