A deterministic PGX compiler front end and VS Code workbench for writing addressable terms and ordered traversal expressions.
PGX stands for Pointer Geometry. It keeps the source compact—raw pointers, explicit groups, and a tiny lawful syntax—while editor projections make the structure readable without semantic inference, AI calls, or hidden interpretation.
pgx: || A109 || stress-root || [((A108):(A14):(A98)):((A105):(A8):(A103))] ||
The same traversal can be inspected as pointer-aware hover text, a source-linked structure tree, or a small deterministic graph:
flowchart TD
T["Traversal"] --> G1["Group 1"]
T --> G2["Group 2"]
G1 --> A108["A108 · grand-traversal"]
G1 --> A14["A14 · and"]
G1 --> A98["A98 · integrated-Sweetpea"]
G2 --> A105["A105 · genomic-construal"]
G2 --> A8["A8 · through"]
G2 --> A103["A103 · Sweetpea-witnessed"]
The text remains authoritative. Every visual unit links back to its exact source occurrence.
Open this repository in VS Code and press F5. The checked-in launch configuration starts an Extension Development Host with stress-showcase.pgx open.
Scroll to any traversal-valued node and use its CodeLens:
- Open Structure opens the authored grouping tree in Explorer.
- Open Mini Graph opens the source-linked node diagram beside the editor.
Traversal action hints are hidden by default to reduce visual clutter. Use the eye button in the PGX editor title to show or hide them without affecting CodeLens in other languages.
Hover a pointer to inspect its proximally bound declaration. Use Ctrl+click or F12 to navigate to it. Hover inside a traversal to see its recursively resolved title projection.
To exercise authoring, select A28 A29 A30, press Ctrl+., and choose Convert selection to PGX traversal. The deterministic result is:
[(A28):(A29):(A30)]
| Capability | Behavior |
|---|---|
| Pointer completion | Shows title and metadata, inserts only the raw pointer |
| Field highlighting | Gives titles and descriptions distinct, subdued, theme-aware colors |
| Proximal binding | Resolves the nearest document declaration before profile fallback |
| Navigation | Hover, Go to Definition, Peek Definition, and source-linked visual nodes |
| Diagnostics | Separates universal lawful syntax from Schema Profile 1 interpretation |
| Traversal refactoring | Converts selected pointers and retained grouping into canonical syntax |
| Batch conversion | Converts independent selected lines transactionally in one edit |
| Title projection | Substitutes immediate declaration titles while preserving grouping |
| Recursive projection | Expands traversal-valued descriptions with cycle and budget protection |
| Structure Peek | Shows exact authored order and parenthetical grouping as a native tree |
| Mini Graph | Shows the same expression as a stable, accessible node-link diagram |
Everything is deterministic. The editor and stress checker consume the same reusable core.
A lawful node starts literally with pgx:. Fields are separated and terminated by ||.
pgx: || A40 || traversal expression 1 || [(A28):(A29):(A30)] ||
Schema Profile 1 interprets fields positionally:
sigil, pointer, title, description, data1, data2, ...
data1 is the canonical first extension field. Additional data fields remain open-ended.
The pointer field is authoritative. PGX does not require an A series, numeric suffix, or case normalization. Ordinary identities such as B30, PRN001, and node-alpha appear bare in traversals; identities containing whitespace or traversal punctuation use a quoted representation such as ("node with spaces").
The workbench nevertheless recommends compact pointer shapes for legibility and reliable recognition. Uppercase letters followed by digits, such as A1, AB11, or CONTEXT6, are preferred. Numeric variants such as AB1-2 remain valid and receive only a hint. Natural-language, escape-prone, or unusually elaborate identities remain fully lawful and functional but receive a style warning.
Traversal expressions are ordered grouping structures over pointers. These expressions are intentionally different:
[(A1):((A2):(A3))]
[((A1):(A2)):(A3)]
The compiler retains both the reference graph and the traversal syntax tree, including exact pointer spans and group paths.
Read the complete PGX language reference.
| Command | Purpose |
|---|---|
PGX: Convert Selection to Traversal |
Normalize selected pointers and grouping into traversal syntax |
PGX: Convert Traversal to Direct Title Projection |
Replace pointers with immediate titles without recursive expansion |
PGX: Peek Traversal Structure |
Open the source-linked native structure tree |
PGX: Open Traversal Mini View |
Render the authored expression as a deterministic mini graph |
PGX: Toggle Traversal Action Hints |
Show or hide PGX traversal CodeLens for the current workspace |
The graph view is intentionally small in scope. It visualizes traversal-expression geometry only: traversal root, explicit groups, source order, pointers, and proximal titles. It is not a pointer-neighborhood browser or general graph visualization engine.
See VS Code workflows for hands-on examples.
flowchart LR
S["PGX source"] --> F["Compiler front end"]
J["JSON profile"] --> F
F --> I["Structural intermediate representation"]
I --> B["Contextual bindings + reference graph"]
I --> A["Traversal AST + source spans"]
B --> R["Recursive projections"]
A --> D["Structure + geometry projections"]
R --> V["VS Code adapters"]
D --> V
pgx-core/ is the editor-independent compiler front end. It owns lawful parsing, Schema Profile interpretation, traversal AST construction, declaration indexing, contextual pointer binding, graph-shaped intermediate representations, projection policies, cycle detection, safety budgets, and deterministic traversal geometry.
extension.js is the thin VS Code adapter. It owns ranges, menus, CodeLens, completion presentation, hovers, Tree Views, and the mini-view webview. It does not reimplement the language.
Read the detailed architecture guide.
PGX currently does not infer meaning, invent relationships, rewrite prose semantically, or call a model. Titles are human-authored metadata. Traversals preserve explicit punctuation and order. Recursive expansion follows declared pointers under explicit resolution and truncation policies.
This repository is not a graph database, NetworkX wrapper, semantic parser, general visualization system, or production language server. “Compiler front end” means deterministic structural compilation into syntax trees, bindings, diagnostics, and graph-shaped intermediate representations; it does not claim to compute a traversal's meaning or perform 4C semantic compilation.
Run the complete deterministic check suite:
npm run checkRun the 110-node graph and recursive projection stress fixture:
npm run stressThe A109 gate protects recursive output geometry with an exact SHA-256 snapshot and separately checks its authored mini-view geometry: 12 pointers, four explicit groups, 17 visual nodes, and 16 edges.
| Path | Role |
|---|---|
pgx-core/ |
Compiler front end: parsing, binding, graph IR, projection, and geometry |
extension.js |
VS Code language and visualization adapters |
pgx-profile.json |
Deterministic completion and fallback registry |
example.pgx |
Compact introductory fixture |
stress-showcase.pgx |
Baroque interactive and recursive test document |
scripts/ |
Core assertions and performance/stress gates |
docs/ |
Language, architecture, and workflow documentation |
PGX Language Workbench is an early language-tooling prototype with a tested compiler front end and a deliberately restrained editor surface. Planned work is tracked in GitHub Issues under the planned-feature label.
Conventions for changes are documented in CONTRIBUTING.md.
PGX Language Workbench is source-available, not open source. It is licensed under the PolyForm Noncommercial License 1.0.0. Noncommercial use, modification, and distribution are permitted under those terms. Commercial use requires a separate license from the copyright holder.