lvkit 0.5.2__tar.gz → 0.5.4__tar.gz

lvkit-0.5.4/.pre-commit-config.yaml

@@ -0,0 +1,64 @@
+# See https://pre-commit.com for usage and configuration
+#
+# Install hooks once per clone:
+#     uv run pre-commit install
+#
+# Run against all files (e.g. after editing config):
+#     uv run pre-commit run --all-files
+#
+# pytest runs the FULL suite locally, where the sample corpus is present
+# (scripts/pull_samples.sh). On a fresh clone without it, `needs_samples` tests
+# auto-skip (tests/conftest.py) rather than fail. CI mirrors these checks and
+# additionally pulls the corpus — see .github/workflows/ci.yml.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.14
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+
+  # Pyright and pytest run against the project's own venv (via `uv run`) so they
+  # see the full resolved dependency tree — identical to CI. lvkit type-checks
+  # src/ (its shipped package); scripts/ and branding/ are auxiliary, not gated.
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright src/
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+
+      - id: pytest
+        name: pytest
+        entry: uv run pytest -q
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true
+        stages: [pre-commit]
+
+      - id: sync-skills
+        name: sync skill templates
+        entry: scripts/sync_skills.sh
+        language: system
+        # Trigger on any SKILL.md change under either tree. The script
+        # discovers skills dynamically from src/lvkit/skill_templates/ —
+        # adding a new packaged skill requires no hook-config change.
+        files: '^(\.claude/skills/.*/SKILL\.md|src/lvkit/skill_templates/claude/.*/SKILL\.md)$'
+        pass_filenames: false

{lvkit-0.5.2 → lvkit-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvkit
-Version: 0.5.2
+Version: 0.5.4
 Summary: Understand and convert LabVIEW VIs to Python without a LabVIEW license
 Project-URL: Repository, https://github.com/pragmatest-dev/lvkit
 Project-URL: Issues, https://github.com/pragmatest-dev/lvkit/issues
@@ -35,22 +35,20 @@ Description-Content-Type: text/markdown
 
 # lvkit
 
-Read, document, diff, and convert LabVIEW VI files — no LabVIEW license required.
+Read, render, document, and diff LabVIEW VI files — no LabVIEW license required.
 
-**lvkit never modifies a VI — it reads what LabVIEW writes.**
+lvkit parses `.vi`, `.ctl`, `.lvclass`, `.lvlib`, and `.lvproj` files directly into queryable dependency and dataflow graphs. From that graph it renders block diagrams, describes what a VI does, generates documentation, and diffs two versions — from a terminal, in CI, or through an AI agent. It can also generate a Python transliteration of a VI, though that path is experimental and how far it gets varies from VI to VI.
 
-lvkit parses `.vi`, `.ctl`, `.lvclass`, and `.lvlib` files directly into queryable dependency and dataflow graphs. Use it to document code, track changes in CI, feed VI structure to AI tools, or generate equivalent Python.
+> **Reads, never writes.** lvkit only ever reads a VI — it never modifies, re-saves, or edits one. Every capability, including convert, parses the source and writes to a *separate* output file; your `.vi` files are never touched, and LabVIEW stays the only thing that authors them.
 
-> **Reads, never writes.** lvkit only ever reads a VI — it never modifies, re-saves, or edits one. Your files are never touched, and LabVIEW stays the only thing that authors them. This holds across every capability, including convert: generating Python parses the VI and emits a *separate* file — it never edits the source.
-
-> **Independent, clean-room project — not affiliated with NI.** lvkit was built using **only publicly available information**: public NI documentation, the open-source [pylabview](https://github.com/mefistotelis/pylabview) project, and observation of VI files. It was developed **without installing or running LabVIEW or any NI software**, and with **no NI source code, internal or non-public specifications, or confidential or proprietary materials**. LabVIEW, NI, and National Instruments are trademarks of National Instruments Corporation, used here only to identify the format lvkit interoperates with; lvkit is not affiliated with, authorized by, endorsed by, or sponsored by NI. See [Cleanroom approach](#cleanroom-approach), [`NOTICE`](NOTICE), and [`PROVENANCE.md`](PROVENANCE.md).
+> **Independent, clean-room project — not affiliated with NI.** Built from public NI documentation, the open-source [pylabview](https://github.com/mefistotelis/pylabview) parser, and observation of VI files — with no LabVIEW install and no NI source or non-public specifications. Details in [Cleanroom approach](#cleanroom-approach); see also [`NOTICE`](NOTICE) and [`PROVENANCE.md`](PROVENANCE.md).
 
 ## Contents
 
 - [Quick Start](#quick-start)
 - [What you can do with it](#what-you-can-do-with-it)
 - [How it works](#how-it-works)
-- [AI and IDE integration](#ai-and-ide-integration)
+- [Editor and AI integration](#editor-and-ai-integration)
 - [Cleanroom approach](#cleanroom-approach)
 - [Development](#development)
 
@@ -71,22 +69,23 @@ For a global install: `pipx install lvkit` or `uv tool install lvkit`.
 
 | Command | Description |
 |---------|-------------|
-| `lvkit describe` | Human-readable VI description with signature and operations |
+| `lvkit describe` | Human-readable VI summary: signature, operations, dataflow, structures |
+| `lvkit render` | Render a VI's block diagram to a faithful SVG (or interactive HTML) |
+| `lvkit diff` | Compare two VI versions — operations, structures, wiring, constants |
 | `lvkit docs` | Generate cross-referenced HTML documentation |
-| `lvkit diff` | Compare two VI versions — terminals, operations, wiring |
-| `lvkit visualize` | Interactive dependency or data flow graph HTML |
+| `lvkit visualize` | Interactive dataflow or dependency graph (HTML) |
 | `lvkit generate` | Generate Python from a VI, library, or class (experimental — see [Cleanroom approach](#cleanroom-approach)) |
-| `lvkit render` | Render an interactive block diagram SVG from a VI |
-| `lvkit structure` | Inspect `.lvlib` or `.lvclass` structure |
-| `lvkit setup` | Install AI agent skills; create `.lvkit/` resolution store |
+| `lvkit structure` | Inspect `.lvproj`, `.lvlib`, or `.lvclass` structure |
+| `lvkit detect` | Detect a locally installed LabVIEW and its `vi.lib` / `user.lib` |
+| `lvkit setup` | Install AI agent skills; create the `.lvkit/` resolution store |
 | `lvkit mcp` | Start the MCP server for IDE integration |
 
-`lvkit visualize` requires `pip install lvkit[visualize]` (it uses pyvis). All other commands work on a bare `pip install lvkit`.
+`describe`, `render`, `diff`, `docs`, and `visualize` work from the graph alone and need no semantic mappings. Only `generate` requires primitive/vi.lib mappings. `lvkit visualize` needs the pyvis extra: `pip install lvkit[visualize]`.
 
 ## What you can do with it
 
 ### Describe what a VI does
-Get a human-readable signature, inputs/outputs, operations, and control flow — without opening LabVIEW. Never requires primitive or vi.lib mappings.
+A human-readable signature, inputs/outputs, operations, and control flow — without opening LabVIEW.
 
 ```
 lvkit describe <path-to.vi> [--search-path <libraries/>] [--verbose]
@@ -94,24 +93,33 @@ lvkit describe <path-to.vi> [--search-path <libraries/>] [--verbose]
 
 `--verbose` adds a full netlist — a text projection of the block diagram.
 
-### Generate documentation
-Cross-referenced HTML docs for a `.vi`, `.lvlib`, or `.lvclass` — inputs, outputs, operations, wiring diagrams.
+### Render the block diagram
+Render a VI's block diagram to a faithful, self-contained SVG — nodes, wires, structures, and SubVI icons, all drawn from the parsed graph. No LabVIEW, no screenshots.
 
 ```
-lvkit docs <input-path> <output-dir> [--search-path <libraries/>]
+lvkit render <path-to.vi> [--format {svg,html}] [--theme {light,dark,auto}] [--search-path <libraries/>]
 ```
 
+`--format html` writes an interactive single-VI viewer with zoom/pan and a light/dark diagram-theme toggle; hover a node to see its connector pane and documentation. The same renderer powers `diff --format html` and the VS Code extension.
+
 ### Diff two versions of a VI
 See what changed between two `.vi` files — added/removed operations and structures, rewired connections, changed constants. Useful in code review and CI.
 
 ```
-lvkit diff <vi-a> <vi-b> [--format {text,json,html}]
+lvkit diff <vi-a> <vi-b> [--format {text,json,html}] [--open]
 ```
 
-Text output is a concise, logical change summary. `--format json` emits a UID-correlated change map for scripts, CI, or an AI agent. `--format html` (or `--open`) writes an **interactive diff viewer** — synced before/after panes, click a change to spotlight it, deep-linkable.
+Text (the default) is a concise, logical change summary for stdout or CI. `--format json` emits a UID-correlated change map for scripts or an AI agent. `--format html` (or `--open`) writes an **interactive diff viewer** — synced before/after panes, click a change to spotlight it, deep-linkable.
+
+### Generate documentation
+Cross-referenced HTML docs for a `.vi`, `.lvlib`, or `.lvclass` — inputs, outputs, operations, wiring diagrams.
+
+```
+lvkit docs <input-path> <output-dir> [--search-path <libraries/>]
+```
 
-### Generate Python
-Convert a VI, library, or class to Python. Deterministic — same VI in, same Python out, every run, no LLM involved.
+### Generate Python (experimental)
+This is lvkit's least mature capability, and the one most likely to need hand-finishing. It walks the graph to emit a Python transliteration of a `.vi`, `.lvlib`, or `.lvclass`. The transliteration is deterministic (same VI in, same Python out, no LLM), but coverage is incremental: a VI only converts cleanly when every primitive and vi.lib VI it uses is already mapped, so how far it gets varies widely. Expect to resolve unknowns and clean up the output — see [Cleanroom approach](#cleanroom-approach).
 
 ```
 lvkit generate <input-path> -o <output-dir> [--search-path <libraries>] [--placeholder-on-unresolved]
@@ -119,23 +127,23 @@ lvkit generate <input-path> -o <output-dir> [--search-path <libraries>] [--place
 
 `--placeholder-on-unresolved` lets the build succeed when mappings are missing — unresolved calls become inline `raise PrimitiveResolutionNeeded(...)` in the output so you can track them down at runtime.
 
-Coverage is incremental and results will vary — see [Cleanroom approach](#cleanroom-approach) for what that means in practice.
-
 ## How it works
 
 lvkit reads VI binaries directly — no LabVIEW installation required. The pipeline has three stages:
 
 1. **Parse** — the VI binary is extracted to XML (via [pylabview](https://github.com/mefistotelis/pylabview)), then parsed into a typed representation of the block diagram: nodes, wires, constants, types, and front panel terminals.
 
-2. **Graph** — all loaded VIs are linked into a graph that captures two things: the dependency tree (which VIs call which) and the dataflow within each VI (how data moves between operations). This is what `describe`, `docs`, `diff`, and `visualize` query — no semantic mappings needed.
+2. **Graph** — all loaded VIs are linked into a graph that captures two things: the dependency tree (which VIs call which) and the dataflow within each VI (how data moves between operations). This is what `describe`, `render`, `diff`, `docs`, and `visualize` query — no semantic mappings needed.
+
+3. **Generate** — the graph is walked deterministically to produce Python source, HTML documentation, or diagrams. Code generation is pure AST construction: same VI in, same output every run, no LLM.
 
-3. **Generate** — the graph is walked deterministically to produce Python source, HTML documentation, or flowcharts. Code generation is pure AST construction: same VI in, same output every run, no LLM.
+See the [command reference](docs/reference/index.md) for full, flag-level docs on every command.
 
-See [`docs/graph-reference.md`](docs/graph-reference.md) for the full graph type reference.
+## Editor and AI integration
 
-## AI and IDE integration
+The CLI works standalone from any terminal or CI script. For deeper integration, lvkit ships three optional layers.
 
-The CLI works standalone from any terminal or CI script. For deeper IDE integration, lvkit ships two optional layers.
+**VS Code extension** — [**LVKit** on the Marketplace](https://marketplace.visualstudio.com/items?itemName=pragmatest.lvkit). Opening a `.vi` renders its block diagram inline instead of the "binary file" placeholder, and clicking a SubVI opens it. **Open Visual Diff** — right-click a changed `.vi` in Source Control, the Explorer, or the editor tab — shows a before/after block-diagram diff for code review. It ships a bundled lvkit, so it works with no separate install; point the `lvkit.path` setting at a project venv or a PATH install to use your own instead. `.vi` files only today.
 
 **AI agent skills** — install lvkit's built-in workflows into Claude Code or Copilot so your AI agent can describe VIs, convert them, and resolve unknowns without you writing prompts. All five workflows call the CLI under the hood — no MCP server required.
 
@@ -160,16 +168,16 @@ Five workflows ship: `lvkit-describe`, `lvkit-convert`, `lvkit-resolve-primitive
 
 | Tool | Description |
 |------|-------------|
-| `load` | Load VI into the in-memory graph |
+| `load` | Load a VI into the in-memory graph |
 | `list_loaded` | List loaded VIs |
+| `clear` | Clear the in-memory graph |
 | `get_context` | Full VI context: inputs, outputs, operations, wires |
-| `generate_ast_code` | Generate Python from a loaded VI |
 | `describe` | Human-readable VI description |
 | `get_operations` | List operations in a VI |
 | `get_dataflow` | Show wire connections |
 | `get_structure` | Inspect a structure node (loop, case, sequence) |
 | `get_constants` | List constant values |
-| `analyze` | Parse and describe VI structure (stateless) |
+| `generate_ast_code` | Generate Python from a loaded VI |
 | `generate_documents` | Generate HTML docs for VIs/libraries (stateless) |
 | `generate_python` | Generate Python from a VI (stateless) |
 
@@ -182,7 +190,9 @@ These mappings are **lvkit's own definitions, derived purely by inference** from
 1. **Public NI documentation** — pages published openly on ni.com, accessed with no login, partner portal, or NDA gate.
 2. **The VI XML produced by [pylabview](https://github.com/mefistotelis/pylabview)** — the open-source parser that extracts the VI binary to XML. That XML is lvkit's *only* window into the format; lvkit has no other view of it.
 
-The definitions are open source and fully inspectable, and many carry a note recording how each was inferred (the public doc consulted, the observed terminal signature, a `verified`/`guess_reason` marker). They are **best-effort inferences, not authoritative** — they have been wrong and corrected over time. That imperfection is a direct consequence of working from *only* public documentation and the pylabview XML, with **no access to any internal or authoritative NI specification** — an insider would not need to infer.
+The definitions are open source and fully inspectable, and many carry a note recording how each was inferred (the public doc consulted, the observed terminal signature, a `verified`/`guess_reason` marker). They are **best-effort inferences, not authoritative** — they have been wrong and corrected over time. That imperfection is a direct consequence of working from *only* public documentation and the pylabview XML, with **no access to any internal or authoritative NI specification**.
+
+Coverage is incremental. When `lvkit generate` encounters an unmapped primitive or vi.lib VI, it raises an error with diagnostic context so the mapping can be added. `describe`, `render`, `diff`, `docs`, and `visualize` are unaffected — they work from the graph, not the semantic mappings.
 
 ### Provenance
 
@@ -192,8 +202,6 @@ lvkit was developed **using only publicly available information** and clean-room
 
 LabVIEW, NI, and National Instruments are trademarks of National Instruments Corporation. lvkit is an independent project and is not affiliated with, authorized by, endorsed by, or sponsored by NI. Those names are used only to identify the file format and software lvkit interoperates with (nominative use).
 
-Coverage is incremental. When `lvkit generate` encounters an unmapped primitive or vi.lib VI, it raises an error with diagnostic context so the mapping can be added. `describe`, `docs`, `diff`, and `visualize` are unaffected — they work from the graph, not the semantic mappings.
-
 ### Project-local resolution store (`.lvkit/`)
 
 You can supplement the bundled mappings with a `.lvkit/` directory in your project root. lvkit reads `.lvkit/` first and falls back to its bundled data.
@@ -222,8 +230,7 @@ Apache-2.0. See [LICENSE](LICENSE).
 
 ## Further reading
 
-- [`docs/graph-reference.md`](docs/graph-reference.md) — graph type reference (nodes, VIContext, operations, wires)
-- [`docs/vi-xml-reference.md`](docs/vi-xml-reference.md) — pylabview XML format reference
-- [`docs/highlight-reel.md`](docs/highlight-reel.md) — design narrative and architecture decisions
-- [`docs/demo-script.md`](docs/demo-script.md) — 30-minute demo script / tutorial
+- [`docs/reference/`](docs/reference/index.md) — per-command reference for the full CLI
+- [`docs/reference/netlist.md`](docs/reference/netlist.md) — the netlist text syntax (`describe --verbose`, `diff`)
+- [`docs/reference/subvi-resolution.md`](docs/reference/subvi-resolution.md) — how lvkit finds SubVIs and libraries
 - [pylabview](https://github.com/mefistotelis/pylabview) — the VI binary parser lvkit builds on

{lvkit-0.5.2 → lvkit-0.5.4}/README.md

@@ -1,21 +1,19 @@
 # lvkit
 
-Read, document, diff, and convert LabVIEW VI files — no LabVIEW license required.
+Read, render, document, and diff LabVIEW VI files — no LabVIEW license required.
 
-**lvkit never modifies a VI — it reads what LabVIEW writes.**
+lvkit parses `.vi`, `.ctl`, `.lvclass`, `.lvlib`, and `.lvproj` files directly into queryable dependency and dataflow graphs. From that graph it renders block diagrams, describes what a VI does, generates documentation, and diffs two versions — from a terminal, in CI, or through an AI agent. It can also generate a Python transliteration of a VI, though that path is experimental and how far it gets varies from VI to VI.
 
-lvkit parses `.vi`, `.ctl`, `.lvclass`, and `.lvlib` files directly into queryable dependency and dataflow graphs. Use it to document code, track changes in CI, feed VI structure to AI tools, or generate equivalent Python.
+> **Reads, never writes.** lvkit only ever reads a VI — it never modifies, re-saves, or edits one. Every capability, including convert, parses the source and writes to a *separate* output file; your `.vi` files are never touched, and LabVIEW stays the only thing that authors them.
 
-> **Reads, never writes.** lvkit only ever reads a VI — it never modifies, re-saves, or edits one. Your files are never touched, and LabVIEW stays the only thing that authors them. This holds across every capability, including convert: generating Python parses the VI and emits a *separate* file — it never edits the source.
-
-> **Independent, clean-room project — not affiliated with NI.** lvkit was built using **only publicly available information**: public NI documentation, the open-source [pylabview](https://github.com/mefistotelis/pylabview) project, and observation of VI files. It was developed **without installing or running LabVIEW or any NI software**, and with **no NI source code, internal or non-public specifications, or confidential or proprietary materials**. LabVIEW, NI, and National Instruments are trademarks of National Instruments Corporation, used here only to identify the format lvkit interoperates with; lvkit is not affiliated with, authorized by, endorsed by, or sponsored by NI. See [Cleanroom approach](#cleanroom-approach), [`NOTICE`](NOTICE), and [`PROVENANCE.md`](PROVENANCE.md).
+> **Independent, clean-room project — not affiliated with NI.** Built from public NI documentation, the open-source [pylabview](https://github.com/mefistotelis/pylabview) parser, and observation of VI files — with no LabVIEW install and no NI source or non-public specifications. Details in [Cleanroom approach](#cleanroom-approach); see also [`NOTICE`](NOTICE) and [`PROVENANCE.md`](PROVENANCE.md).
 
 ## Contents
 
 - [Quick Start](#quick-start)
 - [What you can do with it](#what-you-can-do-with-it)
 - [How it works](#how-it-works)
-- [AI and IDE integration](#ai-and-ide-integration)
+- [Editor and AI integration](#editor-and-ai-integration)
 - [Cleanroom approach](#cleanroom-approach)
 - [Development](#development)
 
@@ -36,22 +34,23 @@ For a global install: `pipx install lvkit` or `uv tool install lvkit`.
 
 | Command | Description |
 |---------|-------------|
-| `lvkit describe` | Human-readable VI description with signature and operations |
+| `lvkit describe` | Human-readable VI summary: signature, operations, dataflow, structures |
+| `lvkit render` | Render a VI's block diagram to a faithful SVG (or interactive HTML) |
+| `lvkit diff` | Compare two VI versions — operations, structures, wiring, constants |
 | `lvkit docs` | Generate cross-referenced HTML documentation |
-| `lvkit diff` | Compare two VI versions — terminals, operations, wiring |
-| `lvkit visualize` | Interactive dependency or data flow graph HTML |
+| `lvkit visualize` | Interactive dataflow or dependency graph (HTML) |
 | `lvkit generate` | Generate Python from a VI, library, or class (experimental — see [Cleanroom approach](#cleanroom-approach)) |
-| `lvkit render` | Render an interactive block diagram SVG from a VI |
-| `lvkit structure` | Inspect `.lvlib` or `.lvclass` structure |
-| `lvkit setup` | Install AI agent skills; create `.lvkit/` resolution store |
+| `lvkit structure` | Inspect `.lvproj`, `.lvlib`, or `.lvclass` structure |
+| `lvkit detect` | Detect a locally installed LabVIEW and its `vi.lib` / `user.lib` |
+| `lvkit setup` | Install AI agent skills; create the `.lvkit/` resolution store |
 | `lvkit mcp` | Start the MCP server for IDE integration |
 
-`lvkit visualize` requires `pip install lvkit[visualize]` (it uses pyvis). All other commands work on a bare `pip install lvkit`.
+`describe`, `render`, `diff`, `docs`, and `visualize` work from the graph alone and need no semantic mappings. Only `generate` requires primitive/vi.lib mappings. `lvkit visualize` needs the pyvis extra: `pip install lvkit[visualize]`.
 
 ## What you can do with it
 
 ### Describe what a VI does
-Get a human-readable signature, inputs/outputs, operations, and control flow — without opening LabVIEW. Never requires primitive or vi.lib mappings.
+A human-readable signature, inputs/outputs, operations, and control flow — without opening LabVIEW.
 
 ```
 lvkit describe <path-to.vi> [--search-path <libraries/>] [--verbose]
@@ -59,24 +58,33 @@ lvkit describe <path-to.vi> [--search-path <libraries/>] [--verbose]
 
 `--verbose` adds a full netlist — a text projection of the block diagram.
 
-### Generate documentation
-Cross-referenced HTML docs for a `.vi`, `.lvlib`, or `.lvclass` — inputs, outputs, operations, wiring diagrams.
+### Render the block diagram
+Render a VI's block diagram to a faithful, self-contained SVG — nodes, wires, structures, and SubVI icons, all drawn from the parsed graph. No LabVIEW, no screenshots.
 
 ```
-lvkit docs <input-path> <output-dir> [--search-path <libraries/>]
+lvkit render <path-to.vi> [--format {svg,html}] [--theme {light,dark,auto}] [--search-path <libraries/>]
 ```
 
+`--format html` writes an interactive single-VI viewer with zoom/pan and a light/dark diagram-theme toggle; hover a node to see its connector pane and documentation. The same renderer powers `diff --format html` and the VS Code extension.
+
 ### Diff two versions of a VI
 See what changed between two `.vi` files — added/removed operations and structures, rewired connections, changed constants. Useful in code review and CI.
 
 ```
-lvkit diff <vi-a> <vi-b> [--format {text,json,html}]
+lvkit diff <vi-a> <vi-b> [--format {text,json,html}] [--open]
 ```
 
-Text output is a concise, logical change summary. `--format json` emits a UID-correlated change map for scripts, CI, or an AI agent. `--format html` (or `--open`) writes an **interactive diff viewer** — synced before/after panes, click a change to spotlight it, deep-linkable.
+Text (the default) is a concise, logical change summary for stdout or CI. `--format json` emits a UID-correlated change map for scripts or an AI agent. `--format html` (or `--open`) writes an **interactive diff viewer** — synced before/after panes, click a change to spotlight it, deep-linkable.
+
+### Generate documentation
+Cross-referenced HTML docs for a `.vi`, `.lvlib`, or `.lvclass` — inputs, outputs, operations, wiring diagrams.
+
+```
+lvkit docs <input-path> <output-dir> [--search-path <libraries/>]
+```
 
-### Generate Python
-Convert a VI, library, or class to Python. Deterministic — same VI in, same Python out, every run, no LLM involved.
+### Generate Python (experimental)
+This is lvkit's least mature capability, and the one most likely to need hand-finishing. It walks the graph to emit a Python transliteration of a `.vi`, `.lvlib`, or `.lvclass`. The transliteration is deterministic (same VI in, same Python out, no LLM), but coverage is incremental: a VI only converts cleanly when every primitive and vi.lib VI it uses is already mapped, so how far it gets varies widely. Expect to resolve unknowns and clean up the output — see [Cleanroom approach](#cleanroom-approach).
 
 ```
 lvkit generate <input-path> -o <output-dir> [--search-path <libraries>] [--placeholder-on-unresolved]
@@ -84,23 +92,23 @@ lvkit generate <input-path> -o <output-dir> [--search-path <libraries>] [--place
 
 `--placeholder-on-unresolved` lets the build succeed when mappings are missing — unresolved calls become inline `raise PrimitiveResolutionNeeded(...)` in the output so you can track them down at runtime.
 
-Coverage is incremental and results will vary — see [Cleanroom approach](#cleanroom-approach) for what that means in practice.
-
 ## How it works
 
 lvkit reads VI binaries directly — no LabVIEW installation required. The pipeline has three stages:
 
 1. **Parse** — the VI binary is extracted to XML (via [pylabview](https://github.com/mefistotelis/pylabview)), then parsed into a typed representation of the block diagram: nodes, wires, constants, types, and front panel terminals.
 
-2. **Graph** — all loaded VIs are linked into a graph that captures two things: the dependency tree (which VIs call which) and the dataflow within each VI (how data moves between operations). This is what `describe`, `docs`, `diff`, and `visualize` query — no semantic mappings needed.
+2. **Graph** — all loaded VIs are linked into a graph that captures two things: the dependency tree (which VIs call which) and the dataflow within each VI (how data moves between operations). This is what `describe`, `render`, `diff`, `docs`, and `visualize` query — no semantic mappings needed.
+
+3. **Generate** — the graph is walked deterministically to produce Python source, HTML documentation, or diagrams. Code generation is pure AST construction: same VI in, same output every run, no LLM.
 
-3. **Generate** — the graph is walked deterministically to produce Python source, HTML documentation, or flowcharts. Code generation is pure AST construction: same VI in, same output every run, no LLM.
+See the [command reference](docs/reference/index.md) for full, flag-level docs on every command.
 
-See [`docs/graph-reference.md`](docs/graph-reference.md) for the full graph type reference.
+## Editor and AI integration
 
-## AI and IDE integration
+The CLI works standalone from any terminal or CI script. For deeper integration, lvkit ships three optional layers.
 
-The CLI works standalone from any terminal or CI script. For deeper IDE integration, lvkit ships two optional layers.
+**VS Code extension** — [**LVKit** on the Marketplace](https://marketplace.visualstudio.com/items?itemName=pragmatest.lvkit). Opening a `.vi` renders its block diagram inline instead of the "binary file" placeholder, and clicking a SubVI opens it. **Open Visual Diff** — right-click a changed `.vi` in Source Control, the Explorer, or the editor tab — shows a before/after block-diagram diff for code review. It ships a bundled lvkit, so it works with no separate install; point the `lvkit.path` setting at a project venv or a PATH install to use your own instead. `.vi` files only today.
 
 **AI agent skills** — install lvkit's built-in workflows into Claude Code or Copilot so your AI agent can describe VIs, convert them, and resolve unknowns without you writing prompts. All five workflows call the CLI under the hood — no MCP server required.
 
@@ -125,16 +133,16 @@ Five workflows ship: `lvkit-describe`, `lvkit-convert`, `lvkit-resolve-primitive
 
 | Tool | Description |
 |------|-------------|
-| `load` | Load VI into the in-memory graph |
+| `load` | Load a VI into the in-memory graph |
 | `list_loaded` | List loaded VIs |
+| `clear` | Clear the in-memory graph |
 | `get_context` | Full VI context: inputs, outputs, operations, wires |
-| `generate_ast_code` | Generate Python from a loaded VI |
 | `describe` | Human-readable VI description |
 | `get_operations` | List operations in a VI |
 | `get_dataflow` | Show wire connections |
 | `get_structure` | Inspect a structure node (loop, case, sequence) |
 | `get_constants` | List constant values |
-| `analyze` | Parse and describe VI structure (stateless) |
+| `generate_ast_code` | Generate Python from a loaded VI |
 | `generate_documents` | Generate HTML docs for VIs/libraries (stateless) |
 | `generate_python` | Generate Python from a VI (stateless) |
 
@@ -147,7 +155,9 @@ These mappings are **lvkit's own definitions, derived purely by inference** from
 1. **Public NI documentation** — pages published openly on ni.com, accessed with no login, partner portal, or NDA gate.
 2. **The VI XML produced by [pylabview](https://github.com/mefistotelis/pylabview)** — the open-source parser that extracts the VI binary to XML. That XML is lvkit's *only* window into the format; lvkit has no other view of it.
 
-The definitions are open source and fully inspectable, and many carry a note recording how each was inferred (the public doc consulted, the observed terminal signature, a `verified`/`guess_reason` marker). They are **best-effort inferences, not authoritative** — they have been wrong and corrected over time. That imperfection is a direct consequence of working from *only* public documentation and the pylabview XML, with **no access to any internal or authoritative NI specification** — an insider would not need to infer.
+The definitions are open source and fully inspectable, and many carry a note recording how each was inferred (the public doc consulted, the observed terminal signature, a `verified`/`guess_reason` marker). They are **best-effort inferences, not authoritative** — they have been wrong and corrected over time. That imperfection is a direct consequence of working from *only* public documentation and the pylabview XML, with **no access to any internal or authoritative NI specification**.
+
+Coverage is incremental. When `lvkit generate` encounters an unmapped primitive or vi.lib VI, it raises an error with diagnostic context so the mapping can be added. `describe`, `render`, `diff`, `docs`, and `visualize` are unaffected — they work from the graph, not the semantic mappings.
 
 ### Provenance
 
@@ -157,8 +167,6 @@ lvkit was developed **using only publicly available information** and clean-room
 
 LabVIEW, NI, and National Instruments are trademarks of National Instruments Corporation. lvkit is an independent project and is not affiliated with, authorized by, endorsed by, or sponsored by NI. Those names are used only to identify the file format and software lvkit interoperates with (nominative use).
 
-Coverage is incremental. When `lvkit generate` encounters an unmapped primitive or vi.lib VI, it raises an error with diagnostic context so the mapping can be added. `describe`, `docs`, `diff`, and `visualize` are unaffected — they work from the graph, not the semantic mappings.
-
 ### Project-local resolution store (`.lvkit/`)
 
 You can supplement the bundled mappings with a `.lvkit/` directory in your project root. lvkit reads `.lvkit/` first and falls back to its bundled data.
@@ -187,8 +195,7 @@ Apache-2.0. See [LICENSE](LICENSE).
 
 ## Further reading
 
-- [`docs/graph-reference.md`](docs/graph-reference.md) — graph type reference (nodes, VIContext, operations, wires)
-- [`docs/vi-xml-reference.md`](docs/vi-xml-reference.md) — pylabview XML format reference
-- [`docs/highlight-reel.md`](docs/highlight-reel.md) — design narrative and architecture decisions
-- [`docs/demo-script.md`](docs/demo-script.md) — 30-minute demo script / tutorial
+- [`docs/reference/`](docs/reference/index.md) — per-command reference for the full CLI
+- [`docs/reference/netlist.md`](docs/reference/netlist.md) — the netlist text syntax (`describe --verbose`, `diff`)
+- [`docs/reference/subvi-resolution.md`](docs/reference/subvi-resolution.md) — how lvkit finds SubVIs and libraries
 - [pylabview](https://github.com/mefistotelis/pylabview) — the VI binary parser lvkit builds on

{lvkit-0.5.2 → lvkit-0.5.4}/editors/vscode/README.md

@@ -1,4 +1,4 @@
-# LVKit — View and diff VIs without LabVIEW
+# LVKit - View and diff VIs without LabVIEW
 
 View `.vi` block diagrams and **visual before/after diffs** directly in VS Code, on a
 machine with **no LabVIEW installed**. Powered by [LVKit](https://pragmatest.com), an open-source tool from **[PragmaTest](https://pragmatest.com)**.
@@ -12,11 +12,11 @@ Both open **read-only** in an editor tab, with zoom/pan and a light/dark diagram
 
 Nodes LVKit doesn't have a glyph for yet render as labeled boxes.
 
-**View** — click a `.vi` in the Explorer.
+**View** - click a `.vi` in the Explorer.
 
 ![A .vi open in VS Code as an interactive block diagram](https://github.com/pragmatest-dev/lvkit/raw/main/editors/vscode/View.png)
 
-**Diff** — right-click a changed `.vi` and select "Open Visual Diff"
+**Diff** - right-click a changed `.vi` and select "Open Visual Diff"
 
 ![The visual before/after diff, opened from the Source Control context menu](https://github.com/pragmatest-dev/lvkit/raw/main/editors/vscode/Diff.png)
 

{lvkit-0.5.2 → lvkit-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lvkit"
-version = "0.5.2"
+version = "0.5.4"
 description = "Understand and convert LabVIEW VIs to Python without a LabVIEW license"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -107,5 +107,13 @@ target-version = "py310"
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP"]
 
+[tool.ruff.lint.per-file-ignores]
+# Auxiliary generators/utilities (not shipped in the package) whose long lines
+# are inherent literal content — SVG path/format strings.
+"branding/*.py" = ["E501"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+    "needs_samples: test reads the local-only sample VI corpus (.lvkit/cache/samples). Auto-skipped when the corpus is absent; pull it with scripts/pull_samples.sh.",
+]

{lvkit-0.5.2 → lvkit-0.5.4}/src/lvkit/__init__.py

@@ -1,6 +1,6 @@
 """lvkit - Convert LabVIEW VIs to Python code."""
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"
 
 from .graph.models import Constant as GraphConstant
 from .graph.models import Wire as GraphWire

lvkit-0.5.4/src/lvkit/__main__.py

@@ -0,0 +1,7 @@
+"""Enable ``python -m lvkit`` — the invocation the VS Code extension uses when
+running lvkit through a bundled (signed) Python interpreter, since a generated
+console-script ``.exe`` gets blocked by Windows Application Control policies."""
+
+from lvkit.cli import main
+
+raise SystemExit(main())

{lvkit-0.5.2 → lvkit-0.5.4}/src/lvkit/_pylabview_patches.py

@@ -25,13 +25,28 @@ import). It is idempotent.
 
 from __future__ import annotations
 
+import warnings
 from decimal import Decimal
 
-import pylabview.LVblock as _lv_block  # type: ignore[import-untyped]
-import pylabview.LVdatatype as _lv_datatype  # type: ignore[import-untyped]
-import pylabview.LVmisc as _lv_misc  # type: ignore[import-untyped]
-import pylabview.LVrsrcontainer as _lv_rsrc  # type: ignore[import-untyped]
-import pylabview.LVxml as _lv_xml  # type: ignore[import-untyped]
+# pylabview's LVheap.py uses invalid escape sequences in plain strings (e.g.
+# re.match("^\\(...")), which Python 3.12+ emits as a *compile-time*
+# SyntaxWarning — and a future Python turns into a hard SyntaxError. A runtime
+# monkeypatch can't touch a compile-time warning; it fires the moment pylabview
+# is first compiled, which is the import below (this module is imported ahead of
+# pylabview by lvkit.extractor). A ``module=``-scoped filter does NOT catch it —
+# a compile-time SyntaxWarning is attributed to the *importer's* frame, not
+# "pylabview.LVheap", so only a category filter active during the compile
+# matches (verified on Windows: module-scoped passes through, category-only
+# suppresses). We scope that category filter to exactly this import with
+# catch_warnings, leaving the process-wide filter state untouched. The real fix
+# is owning the pylabview source (fork/vendor) and correcting it — task #81.
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", SyntaxWarning)
+    import pylabview.LVblock as _lv_block  # type: ignore[import-untyped]
+    import pylabview.LVdatatype as _lv_datatype  # type: ignore[import-untyped]
+    import pylabview.LVmisc as _lv_misc  # type: ignore[import-untyped]
+    import pylabview.LVrsrcontainer as _lv_rsrc  # type: ignore[import-untyped]
+    import pylabview.LVxml as _lv_xml  # type: ignore[import-untyped]
 
 _installed = False