lvkit 0.3.0__tar.gz → 0.4.0__tar.gz

{lvkit-0.3.0 → lvkit-0.4.0}/.gitignore

@@ -79,6 +79,7 @@ dmypy.json
 
 # Sample LabVIEW projects (external test data)
 samples/
+samples.bak/
 
 # Model files
 models/
@@ -101,3 +102,28 @@ outputs/
 docs/*.pdf
 docs/labview_ref_manual.txt
 docs/labview_programming_reference_manual*
+
+# NI-derived extracted primitive-icon PNGs (pulled from the reference PDF by
+# scripts/extract_lv_icons.py) — local-only build intermediates. Only the
+# vectorized .svg equivalents (scripts/vectorize_icons.py) are tracked/shipped.
+src/lvkit/data/glyphs/*.png
+
+# lv-renderer experiment scratch. Keep only the canonical gallery examples;
+# ignore the throwaway per-iteration review renders and icon-extraction probes.
+experiments/lv-renderer/gallery/*
+!experiments/lv-renderer/gallery/Build.svg
+!experiments/lv-renderer/gallery/Out.svg
+!experiments/lv-renderer/gallery/XML_Loop_Stack_Recursion.svg
+experiments/lv-renderer/icon_extract/
+experiments/lv-renderer/icon_probe/
+experiments/lv-renderer/icon_probe_reverse1d.png
+
+# NI-derived vectorized icon SVGs (from the reference PDF) — local-only,
+# regenerated by scripts/vectorize_icons.py; cleanroom package ships none.
+src/lvkit/data/glyphs/*.svg
+
+# Local-only experiment/scratch VIs (unprovable provenance — never redistribute)
+experiments/
+
+# Claude Code agent worktrees (transient)
+.claude/worktrees/

lvkit-0.4.0/NOTICE

@@ -0,0 +1,26 @@
+lvkit
+Copyright 2025-2026 Ryan Friedman
+
+This product is an independent, clean-room project. It is not affiliated with,
+authorized by, endorsed by, or sponsored by National Instruments Corporation.
+
+LabVIEW, NI, and National Instruments are trademarks of National Instruments
+Corporation, used herein only to identify the file format and software with
+which lvkit interoperates (nominative use).
+
+lvkit was developed using only publicly available information: public NI
+documentation, the open-source pylabview project, and observation of VI files.
+It was built without installing or running LabVIEW or any NI software, and
+without the use of any NI source code, internal or non-public specifications,
+or confidential or proprietary materials.
+
+lvkit's mappings of LabVIEW primitives and standard-library VIs (in
+src/lvkit/data/) are lvkit's own definitions, derived purely by inference from
+public documentation and from the VI XML produced by pylabview. They are
+best-effort inferences, not authoritative reproductions of any NI
+specification, and they contain no NI documentation text or artwork.
+
+lvkit depends on, but does not include, pylabview
+(https://github.com/mefistotelis/pylabview).
+
+See PROVENANCE.md for detail.

{lvkit-0.3.0 → lvkit-0.4.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: lvkit
-Version: 0.3.0
+Version: 0.4.0
 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
 Author: Pragmatest
 License-Expression: Apache-2.0
 License-File: LICENSE
+License-File: NOTICE
 Keywords: ast,code-generation,labview,mcp,ni,static-analysis,vi
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -38,6 +39,8 @@ Read, document, diff, and convert LabVIEW VI files — no LabVIEW license requir
 
 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.
 
+> **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).
+
 ## Contents
 
 - [Quick Start](#quick-start)
@@ -167,7 +170,22 @@ Five workflows ship: `lvkit-describe`, `lvkit-convert`, `lvkit-resolve-primitive
 
 ## Cleanroom approach
 
-lvkit has no access to LabVIEW source code or runtime. LabVIEW's built-in primitives and standard library VIs are **semantically replaced**: each operation is mapped to an equivalent Python implementation in JSON data files (`src/lvkit/data/primitives.json`, `src/lvkit/data/vilib/`). These mappings are built from published documentation and observed behavior.
+lvkit has no access to LabVIEW source code or runtime. LabVIEW's built-in primitives and standard library VIs are **semantically replaced**: each operation is mapped to an equivalent Python implementation in open, inspectable JSON data files (`src/lvkit/data/primitives.json`, `src/lvkit/data/vilib/`).
+
+These mappings are **lvkit's own definitions, derived purely by inference** from two public inputs and nothing else:
+
+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.
+
+### Provenance
+
+lvkit was developed **using only publicly available information** and clean-room methods. It was built **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**. Facts about LabVIEW's behavior are used as facts; no NI documentation prose or artwork is copied or redistributed — primitive glyphs are drawn procedurally, and the shipped data contains no NI text or images. See [`PROVENANCE.md`](PROVENANCE.md).
+
+### Trademarks
+
+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.
 

{lvkit-0.3.0 → lvkit-0.4.0}/README.md

@@ -4,6 +4,8 @@ Read, document, diff, and convert LabVIEW VI files — no LabVIEW license requir
 
 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.
 
+> **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).
+
 ## Contents
 
 - [Quick Start](#quick-start)
@@ -133,7 +135,22 @@ Five workflows ship: `lvkit-describe`, `lvkit-convert`, `lvkit-resolve-primitive
 
 ## Cleanroom approach
 
-lvkit has no access to LabVIEW source code or runtime. LabVIEW's built-in primitives and standard library VIs are **semantically replaced**: each operation is mapped to an equivalent Python implementation in JSON data files (`src/lvkit/data/primitives.json`, `src/lvkit/data/vilib/`). These mappings are built from published documentation and observed behavior.
+lvkit has no access to LabVIEW source code or runtime. LabVIEW's built-in primitives and standard library VIs are **semantically replaced**: each operation is mapped to an equivalent Python implementation in open, inspectable JSON data files (`src/lvkit/data/primitives.json`, `src/lvkit/data/vilib/`).
+
+These mappings are **lvkit's own definitions, derived purely by inference** from two public inputs and nothing else:
+
+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.
+
+### Provenance
+
+lvkit was developed **using only publicly available information** and clean-room methods. It was built **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**. Facts about LabVIEW's behavior are used as facts; no NI documentation prose or artwork is copied or redistributed — primitive glyphs are drawn procedurally, and the shipped data contains no NI text or images. See [`PROVENANCE.md`](PROVENANCE.md).
+
+### Trademarks
+
+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.
 

lvkit-0.4.0/deploy/cloudrun/README.md

@@ -0,0 +1,84 @@
+# lvkit on Cloud Run — VI → SVG service
+
+A tiny HTTP service: `POST` a `.vi` file, get an SVG block-diagram render back.
+A page can upload a VI and drop the returned SVG straight into the DOM.
+
+## Why this works cleanly
+
+lvkit needs **no LabVIEW and no native binary**. Extraction shells out to
+`python -m pylabview.readRSRC` (pure Python, an lvkit dependency), and
+`render_vi_file()` returns an SVG string. The container just needs Python +
+lvkit + a writable temp dir — Cloud Run provides `/tmp` (in-memory).
+
+Uploads are rendered with `expand_subvis=False`, which is effectively an
+**offline mode**: a standalone VI has no sibling subVI files, so the render
+never reaches the filesystem for dependencies (unresolved subVIs draw as
+fallback boxes). It only reads lvkit's own **bundled** primitive/vilib JSON,
+which ships inside the image. Nothing to configure.
+
+## Files
+
+| file | purpose |
+|------|---------|
+| `main.py` | Flask app: `GET /` demo page, `GET /health`, `POST /render` |
+| `Dockerfile` | installs lvkit (this branch) + flask/gunicorn; **build context = repo root** |
+| `cloudbuild.yaml` | build → push → deploy in one `gcloud builds submit` |
+| `static/index.html` | drop-a-VI demo page served at `/` |
+| `requirements.txt` | web deps for local dev |
+
+## Deploy
+
+From the **repo root** (not this folder — the Docker build needs the lvkit
+source in context):
+
+```bash
+gcloud builds submit --config deploy/cloudrun/cloudbuild.yaml \
+  --substitutions=_IMAGE=gcr.io/$(gcloud config get-value project)/lvkit-render,_REGION=us-central1 .
+```
+
+That builds `deploy/cloudrun/Dockerfile`, pushes the image, and deploys the
+`lvkit-render` service (`--allow-unauthenticated`, 1Gi, 1 CPU, 120s, max 5
+instances — tune in `cloudbuild.yaml`).
+
+### Local test
+
+```bash
+pip install -e .            # from repo root (installs lvkit + pylabview)
+pip install -r deploy/cloudrun/requirements.txt
+cd deploy/cloudrun && python main.py          # http://localhost:8080
+# or exactly like prod:
+docker build -f deploy/cloudrun/Dockerfile -t lvkit-render .   # from repo root
+docker run -p 8080:8080 -e PORT=8080 lvkit-render
+```
+
+## Calling it from a page
+
+```js
+const fd = new FormData();
+fd.append('vi', fileInput.files[0]);
+const svg = await (await fetch('https://YOUR-URL/render', { method:'POST', body: fd })).text();
+document.getElementById('out').innerHTML = svg;   // static picture
+```
+
+### Heads-up: interactive frames
+
+The SVG embeds an inline `<script>` for the case/stacked-sequence **frame
+selector**. Browsers do **not** run scripts inserted via `innerHTML`, so a VI
+rendered that way is a static image. To keep the frame toggles working, load the
+SVG so its script executes — e.g. an `<iframe>`:
+
+```js
+const url = URL.createObjectURL(new Blob([svg], {type:'image/svg+xml'}));
+iframe.src = url;   // scripts inside the SVG run here
+```
+
+## Notes / hardening
+
+- **Untrusted input**: you're parsing arbitrary uploaded binaries. Cloud Run's
+  per-request container is the isolation boundary; `main.py` caps size at 25 MB
+  (Cloud Run's own request limit is 32 MB).
+- **Memory**: `/tmp` is RAM on Cloud Run and holds the upload + extracted XML;
+  1Gi is a safe start. Raise `--memory`/lower concurrency for large VIs.
+- **Auth**: `--allow-unauthenticated` is for a public demo. Drop it (and add an
+  API key / IAM) for anything real.
+- **Cold start**: first request imports lvkit + pylabview (~1s); fine for a demo.

lvkit-0.4.0/docs/xml-schema/README.md

@@ -0,0 +1,102 @@
+# LabVIEW VI XML Schema Reference
+
+This directory documents lvkit's current understanding of the XML that
+[pylabview](https://github.com/mefistotelis/pylabview) extracts from a LabVIEW
+`.vi` binary. It is a "genome project" for these archaic, binary-derived fields:
+for each field, *what it is* and *what we currently believe it controls*, with
+the evidence and a confidence level.
+
+> **Grounding rule.** Every claim here is traced to lvkit parser code, a
+> pylabview enum/comment, a concrete extracted XML sample, or a confirmed
+> session finding. Where we genuinely do not know a field's meaning, it is
+> marked **confidence = unknown** rather than guessed. (This repo has a hard
+> "never fabricate looked-up facts" rule.)
+
+## The three files
+
+`extractor.extract_vi_xml(vi_path)` runs one pylabview subprocess per VI and
+writes three sibling XML files next to the `.vi` (plus a pile of `*.bin`
+side-blobs and `*.png` icons):
+
+| File | Nickname | Contents | Doc |
+|---|---|---|---|
+| `<name>_BDHb.xml` | **BD** — block-diagram heap | nodes, wires, structures, terminals, constants | [block-diagram.md](block-diagram.md) |
+| `<name>_FPHb.xml` | **FP** — front-panel heap | controls/indicators, connector pane, default data | [front-panel.md](front-panel.md) |
+| `<name>.xml` | **Base / main** | VI settings (LVSR/LVIN), type list (VCTP), dataspace default data (DFDS), link/dependency tables | [dataspace.md](dataspace.md) |
+
+Both `_BDHb.xml` and `_FPHb.xml` are **heaps**: recursively nested
+`<SL__arrayElement class="...">` objects, each carrying a `uid`, that model the
+on-screen object tree. The base `.xml` is different in shape — it is a set of
+named binary *sections* (LVSR, VCTP, DFDS, LIvi, LIbd, ...) that pylabview
+renders as structured XML plus `<!-- ... -->` comments.
+
+Suffix constants live in `src/lvkit/parser/constants.py:165-167`
+(`BD_XML_SUFFIX`, `FP_XML_SUFFIX`, `MAIN_XML_SUFFIX`), with
+`derive_fp_xml_path` / `derive_main_xml_path` / `derive_vi_name` helpers
+(`constants.py:191-204`).
+
+## How the parser reads them
+
+Pipeline (`src/lvkit/parser/vi.py:101` `parse_vi`):
+
+1. `_parse_metadata(main_xml)` — LVSR/LVIN qualified name, the **type map**
+   (`parse_type_map_rich`), and SubVI/dependency link tables. (`vi.py:170`)
+2. `_parse_selector_tables(main_xml)` — case-structure per-frame selector
+   values from the DFDS dataspace. (`vi.py:223`)
+3. `_parse_block_diagram(bd_xml, fp_xml, type_map, selector_tables)` — nodes,
+   wires, constants, terminals, loops, cases, sequences, IPES. (`vi.py:235`)
+4. `_parse_front_panel(fp_xml, ...)` and `parse_connector_pane(fp_xml)`.
+
+## Two SEPARATE type namespaces (they do NOT cross-reference)
+
+This is the single most important thing to internalize:
+
+- **BD heap `typeDesc` `TypeID(N)`** — an index into the **VCTP** (the
+  consolidated type list in the base `.xml`). Terminals, constants, tunnels and
+  FP DCOs all carry `<typeDesc>TypeID(N)</typeDesc>`; `N` is a *heap* TypeID,
+  resolved through the chain
+  `Heap TypeID → Consolidated TypeID → FlatTypeID → VCTP TypeDesc`
+  (`parser/type_mapping.py:17` `parse_type_map_rich`,
+  `parser/type_resolution.py:53` `resolve_type_rich`).
+- **Dataspace `DataFill TypeID="N"`** — an index into the **DFDS** (dataspace)
+  default-data list. Same integer space *shape*, totally different assignment.
+
+**A `DataFill TypeID` and a BD `typeDesc TypeID` with the same number are NOT
+the same type.** They are two independent enumerations. The case-selector
+correlation (see [dataspace.md](dataspace.md)) exploits the fact that, *within
+each namespace*, LabVIEW assigns indices in the same DCO-enumeration order — so
+you sort each side by its own index and zip. You never equate the two integers
+directly. (`parser/nodes/case.py:513` `_apply_selector_tables`; session
+finding, confirmed on "Draw Image from File__ogtk.vi".)
+
+## Coordinate spaces
+
+- All heap rects are LabVIEW `(top, left, bottom, right)` — note the order
+  (`render/layout.py:109` `_rect` reorders them to `x1,y1,x2,y2`).
+- A node's `<bounds>` is absolute (relative to the diagram it lives in; the
+  renderer accumulates diagram origins while recursing —
+  `render/layout.py:383` `walk`).
+- A terminal's `<termBounds>` is **relative to the node's icon origin**, and a
+  primitive's icon is *centered* within its clickable `<bounds>` — so the
+  renderer computes a centering offset before placing terminals
+  (`render/layout.py:252-280` `_map_terms`). Constant part bounds are relative
+  to the constant DDO's own top-left (`render/layout.py:118` `_const_value_box`).
+- Selector/label geometry lives in the heap; **selector VALUES do not** — they
+  are in the DFDS dataspace (see below).
+
+## A note on pylabview `OF__*` enums
+
+pylabview's `LVheap.py` defines `OBJ_FIELD_TAGS` with members like
+`OF__objFlags = 172`, `OF__bounds = 14`, `OF__termBounds = 266`
+(`LVheap.py:75-360`). **These integers are attribute-tag IDs** — they identify
+*which serialized attribute* a value belongs to inside the binary heap, and
+they become the XML element *name* (`<objFlags>`, `<bounds>`, ...). They are
+**NOT** bit positions within the `objFlags` integer. Do not conflate the two.
+The bit meanings of `objFlags` are documented per-element in the field docs and
+are lvkit session findings — pylabview does not decode them.
+
+## Field docs
+
+- [block-diagram.md](block-diagram.md) — `_BDHb.xml`
+- [front-panel.md](front-panel.md) — `_FPHb.xml`
+- [dataspace.md](dataspace.md) — base `.xml` (metadata + VCTP + DFDS + links)

{lvkit-0.3.0 → lvkit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lvkit"
-version = "0.3.0"
+version = "0.4.0"
 description = "Understand and convert LabVIEW VIs to Python without a LabVIEW license"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -70,6 +70,13 @@ dev = [
 # the wheel automatically. The resolvers and `lvkit setup` load
 # them via paths relative to the package or via importlib.resources.
 packages = ["src/lvkit"]
+# lvkit is cleanroom: it ships NO NI-derived primitive artwork. Primitive
+# glyphs are drawn procedurally by the render layer (OriginalGlyphResolver /
+# GeneratedGlyphResolver); un-migrated primitives render as a labeled box. The
+# NI-icon extraction path (a data/glyphs/ asset dir + PdfIconResolver) was
+# removed for licensing. These exclude globs remain as a guard so no such
+# asset can ever be packaged if the directory is reintroduced.
+exclude = ["src/lvkit/data/glyphs/*.png", "src/lvkit/data/glyphs/*.svg"]
 
 [tool.hatch.build.targets.sdist]
 include = [
@@ -86,6 +93,8 @@ exclude = [
     "outputs",
     "docs/labview_ref_manual.txt",
     "docs/*.pdf",
+    "src/lvkit/data/glyphs/*.png",
+    "src/lvkit/data/glyphs/*.svg",
     ".lvkit",
     ".tmp",
 ]