lvkit 0.7.0__tar.gz → 0.7.2__tar.gz

{lvkit-0.7.0 → lvkit-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lvkit
-Version: 0.7.0
+Version: 0.7.2
 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

{lvkit-0.7.0 → lvkit-0.7.2}/editors/vscode/README.md

@@ -35,6 +35,16 @@ Mode banner.
 | `lvkit.searchPaths` | `[]` | Extra dirs to search for SubVIs (repo root is auto-detected). |
 | `lvkit.diagramTheme` | `auto` | Diagram color theme (`auto`/`light`/`dark`); updated automatically when you cycle the in-viewer theme control. |
 
+## Recommending LVKit to your team
+
+If your project has LabVIEW files, add LVKit to your workspace's recommended
+extensions so teammates are prompted to install it when they open the folder:
+
+```json
+// .vscode/extensions.json
+{ "recommendations": ["pragmatest.lvkit"] }
+```
+
 ## Trademarks
 
 LVKit is an independent, clean-room project, not affiliated with, authorized by,

{lvkit-0.7.0 → lvkit-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lvkit"
-version = "0.7.0"
+version = "0.7.2"
 description = "Understand and convert LabVIEW VIs to Python without a LabVIEW license"
 readme = "README.md"
 requires-python = ">=3.10"

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"
 
 # The public API is exposed LAZILY (PEP 562 module ``__getattr__``): the graph /
 # parser / structure stacks (networkx, pydantic, pylabview, PIL — ~230 ms) load

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/cli.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
+import subprocess
 import sys
 import traceback
 import webbrowser
@@ -362,16 +364,23 @@ def main() -> int:
         "-v",
         "--verbose",
         action="store_true",
-        help="Include a full netlist section (see lvkit.graph.netlist)",
+        help=(
+            "Show full detail within each section (every VI Property, "
+            "Health, connector-pattern/pane-slot annotations, typed "
+            "terminals); with --format netlist, also emit a typed "
+            "## Components section before the netlist body."
+        ),
     )
     desc_parser.add_argument(
         "--format",
-        choices=["text", "json"],
+        choices=["text", "netlist", "json"],
         default="text",
         help=(
-            "'text' (default) prints the human-readable description; 'json' "
-            "emits the canonical netlist IR — the same structured payload the "
-            "MCP read_vi tool returns — for a program to parse."
+            "'text' (default) prints the human-readable description; "
+            "'netlist' prints the VI dataflow netlist body — the git-"
+            "textconv-friendly form (see `lvkit setup --git-textconv`); "
+            "'json' emits the canonical netlist IR — the same structured "
+            "payload the MCP read_vi tool returns — for a program to parse."
         ),
     )
     _add_project_root_arg(desc_parser)
@@ -627,6 +636,28 @@ def main() -> int:
         action="store_true",
         help="Overwrite existing skill files even if they have local edits",
     )
+    setup_parser.add_argument(
+        "--git-textconv",
+        action="store_true",
+        help=(
+            "Wire up `git diff`/`git show` on .vi files to render lvkit's "
+            "netlist text instead of the raw binary: appends `*.vi "
+            "diff=lvkit` to .gitattributes and sets the `diff.lvkit."
+            "textconv`/`diff.lvkit.cachetextconv` git config in the current "
+            "repo. Does ONLY this — skips the .lvkit/ store + skill install."
+        ),
+    )
+    setup_parser.add_argument(
+        "--textconv-format",
+        choices=["netlist", "text", "json"],
+        default="netlist",
+        help=(
+            "Which `describe` format `--git-textconv` renders in a `git diff`: "
+            "'netlist' (default, the dataflow netlist — most diff-friendly), "
+            "'text' (the human summary), or 'json' (the structured IR). The VS "
+            "Code extension sets this from the `lvkit.viTextFormat` setting."
+        ),
+    )
 
     # Unresolved command - batch-collect every resolution gap
     unresolved_parser = subparsers.add_parser(
@@ -1104,6 +1135,26 @@ def cmd_query(args: argparse.Namespace) -> int:
     return 0
 
 
+def _repo_relative_path(source: Path | None, base: Path) -> str | None:
+    """Best-effort repo/project-relative display path for ``source`` against
+    ``base`` -- for the ``-- <path>`` comment on each SubVI in a verbose
+    ``describe --format netlist`` ``## Components`` line, so a VS Code terminal
+    can click straight to the dependency instead of showing an absolute path.
+
+    Defensive by design: ``None`` when ``source`` is unresolvable (unknown/
+    unloaded VI) or ``os.path.relpath`` itself fails (e.g. a cross-drive path
+    on Windows, which raises ``ValueError``) -- a describe path annotation is
+    decoration, never load-bearing, so it silently falls back rather than
+    crashing the command.
+    """
+    if source is None:
+        return None
+    try:
+        return os.path.relpath(source.resolve(), base.resolve())
+    except (OSError, ValueError):
+        return None
+
+
 def cmd_describe(args: argparse.Namespace) -> int:
     """Handle the describe command - human-readable VI description."""
     from .graph.describe import describe_vi
@@ -1148,7 +1199,8 @@ def cmd_describe(args: argparse.Namespace) -> int:
         # VI (and its SubVIs under MINIMAL), so warm all of them.
         warm_all_loaded(graph)
 
-        if getattr(args, "format", "text") == "json":
+        fmt = getattr(args, "format", "text")
+        if fmt == "json":
             # Same structured netlist IR the MCP read_vi tool returns — parity
             # so a non-MCP (CLI/CI/skill) consumer gets the structured read too.
             from .graph.netlist import build_netlist, netlist_to_dict
@@ -1158,6 +1210,48 @@ def cmd_describe(args: argparse.Namespace) -> int:
                     netlist_to_dict(build_netlist(graph, vi_name)), indent=2
                 )
             )
+        elif fmt == "netlist":
+            # The dataflow netlist body alone — the git-textconv-friendly
+            # form (`lvkit setup --git-textconv`): a diff of two commits'
+            # `.vi` blobs through this render is a meaningful, near-source-
+            # stable text diff. The VI-line always uses the qualified display
+            # name (never an abspath — that would make every clone's diff
+            # differ), IDENTICAL in base and verbose. Verbose adds only a
+            # `## Components` declaration table with each SubVI's repo-relative
+            # path as a clickable `-- ` comment (paths never touch the semantic
+            # lines, and don't resolve under textconv's isolated blob anyway).
+            from .graph.netlist import build_netlist, component_line, render_netlist
+
+            module = build_netlist(graph, vi_name)
+            # SubVI paths are resolved relative to — the first auto-detected
+            # search path (explicit --search-path wins, else the input's own
+            # enclosing .lvkit/ project root), falling back to the input's own
+            # directory. So a VS Code terminal can click straight to the dep.
+            rel_base = search_paths[0] if search_paths else input_path.parent
+
+            # The VI signature line always uses the QUALIFIED name — identical in
+            # base and verbose, so the netlist body diffs the same either way.
+            # Paths live only in verbose, and only as COMMENTS (never in the
+            # semantic lines): each called SubVI's repo-relative path as a
+            # trailing `-- ` comment on its ## Components declaration (clickable),
+            # skipped for primitives / unresolved SubVIs.
+            display_name = graph.vi_display_name(vi_name)
+
+            out_lines: list[str] = []
+            if args.verbose and module.components:
+                out_lines.append("## Components")
+                for c in module.components:
+                    line = f"  {component_line(c)}"
+                    comp_rel = _repo_relative_path(
+                        graph.get_vi_source_path(c.name), rel_base
+                    )
+                    if comp_rel is not None:
+                        line += f"  -- {comp_rel}"
+                    out_lines.append(line)
+                out_lines.append("")
+
+            out_lines.append(render_netlist(module, display_name=display_name))
+            print("\n".join(out_lines))
         else:
             print(describe_vi(graph, vi_name, verbose=args.verbose))
 
@@ -1188,8 +1282,83 @@ def _detect_ai_editors(root: Path) -> list[str]:
     return editors
 
 
+def _setup_git_textconv(root: Path, fmt: str = "netlist") -> int:
+    """Wire up ``git diff``/``git show`` on ``.vi`` files to render lvkit's
+    ``describe`` text (``lvkit describe --format <fmt>``, default the dataflow
+    ``netlist``) instead of the raw binary blob — the ``lvkit setup
+    --git-textconv`` mode.
+
+    Appends ``*.vi diff=lvkit`` to the repo's ``.gitattributes`` (creating it
+    if missing; a no-op if the line is already present) and sets the
+    ``diff.lvkit.textconv``/``diff.lvkit.cachetextconv`` git config in the
+    repo ``root`` belongs to. Requires ``root`` to be inside a git repo —
+    reports a clear error and a non-zero exit otherwise (this is a git-only
+    feature; there is nothing sensible to do without one).
+    """
+    repo_toplevel = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if repo_toplevel.returncode != 0:
+        print(
+            f"Error: {root} is not inside a git repository — "
+            "--git-textconv requires git (see `git init`).",
+            file=sys.stderr,
+        )
+        return 1
+    repo_root = Path(repo_toplevel.stdout.strip())
+
+    attrs_path = repo_root / ".gitattributes"
+    attrs_line = "*.vi diff=lvkit"
+    existing = attrs_path.read_text(encoding="utf-8") if attrs_path.is_file() else ""
+    if attrs_line in existing.splitlines():
+        print(f"{attrs_path}: already has `{attrs_line}`")
+    else:
+        if existing and not existing.endswith("\n"):
+            existing += "\n"
+        attrs_path.write_text(existing + attrs_line + "\n", encoding="utf-8")
+        print(f"{attrs_path}: added `{attrs_line}`")
+
+    textconv_cmd = f"lvkit describe --format {fmt}"
+    for key, value in (
+        ("diff.lvkit.textconv", textconv_cmd),
+        ("diff.lvkit.cachetextconv", "true"),
+    ):
+        result = subprocess.run(
+            ["git", "config", key, value],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            print(
+                f"Error: `git config {key} {value!r}` failed: "
+                f"{result.stderr.strip()}",
+                file=sys.stderr,
+            )
+            return 1
+        print(f"git config {key} {value!r}")
+
+    print(
+        "\nGit textconv configured. `git diff`/`git show` on .vi files now "
+        "render lvkit's netlist text."
+    )
+    return 0
+
+
 def cmd_setup(args: argparse.Namespace) -> int:
     """Handle the setup command — install AI skills and create .lvkit/ store."""
+    if getattr(args, "git_textconv", False):
+        root = Path(args.directory or ".").resolve()
+        if not root.is_dir():
+            print(f"Error: Not a directory: {root}", file=sys.stderr)
+            return 1
+        return _setup_git_textconv(root, getattr(args, "textconv_format", "netlist"))
+
     # `directory` and `skills` are both optional positionals, so a lone
     # `lvkit setup copilot` binds "copilot" to `directory`. If the only
     # positional given is a skills choice, treat it as the skills target in

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/graph/describe.py

@@ -38,7 +38,6 @@ from .models import (
     WindowProps,
     bool_str,
 )
-from .netlist import build_netlist, component_line, render_netlist
 from .op_walk import (
     _const_value_str,
     _has_output_tunnel,
@@ -61,17 +60,18 @@ def describe_vi(
     """Describe a VI as a documentation page.
 
     Uses the graph's resolved types, names, constants, and dataflow to
-    produce a complete reference for what this VI does. Default
-    (non-verbose) output is unchanged: Inputs/Outputs/Class/Constants,
+    produce a complete reference for what this VI does. Output (verbose or
+    not) always has the same section shape: Inputs/Outputs/Class/Constants,
     then ``## Dependencies`` (subVI signatures) / ``## Control Flow`` /
     ``## Operations``.
 
-    ``verbose`` replaces Dependencies + Control Flow + Operations with a
-    declare-then-wire pair: ``## Components`` (every distinct subVI/primitive's
-    typed interface, declared once -- see ``lvkit.graph.netlist``) followed by
-    a final ``## Netlist`` (every node instantiated, node-first, with wiring
-    -- its ``case (selector):`` scopes already cover control flow, so there is
-    no separate ``## Control Flow`` section in verbose output).
+    ``verbose`` (``-v``) only adds DEPTH within those same sections -- every
+    VI Property (not just non-default ones), the ``## Health`` section even
+    when healthy, each pane terminal's connector-pattern slot index, and
+    typed terminal detail -- it never swaps in a different section shape.
+    The dataflow NETLIST (the declare-then-wire ``## Components`` +
+    node-first wiring body) is a SEPARATE output entirely -- see
+    ``lvkit.graph.netlist`` and the CLI's ``describe --format netlist``.
     """
     vi_name = graph.resolve_vi_name(vi_name)
     ctx = graph.get_vi_context(vi_name)
@@ -143,59 +143,41 @@ def describe_vi(
             lines.append(f"  {_describe_label_line(lbl)}")
         lines.append("")
 
-    # verbose: build the netlist IR once, shared by Components and Netlist.
-    netlist_module = build_netlist(graph, vi_name) if verbose else None
+    # Dependencies: SubVI calls with their signatures and descriptions.
+    # Same shape verbose or not -- verbose only deepens Properties/Health/
+    # pane detail above; it never swaps this section out.
+    subvi_names = _collect_subvi_names(ctx.operations)
+    if subvi_names:
+        lines.append("## Dependencies")
+        for name in sorted(subvi_names):
+            desc = _get_subvi_description(graph, name)
+            ports = _subvi_ports(graph, name)
+            sig = _render_ports(*ports) if ports is not None else None
+            entry = f"  {name}"
+            if sig:
+                entry += f": {sig}"
+            if desc:
+                entry += f" -- {desc}"
+            lines.append(entry)
+        lines.append("")
 
-    if verbose:
-        assert netlist_module is not None
-        if netlist_module.components:
-            lines.append("## Components")
-            for c in netlist_module.components:
-                lines.append(f"  {component_line(c)}")
-            lines.append("")
-    else:
-        # Dependencies: SubVI calls with their signatures and descriptions
-        subvi_names = _collect_subvi_names(ctx.operations)
-        if subvi_names:
-            lines.append("## Dependencies")
-            for name in sorted(subvi_names):
-                desc = _get_subvi_description(graph, name)
-                ports = _subvi_ports(graph, name)
-                sig = _render_ports(*ports) if ports is not None else None
-                entry = f"  {name}"
-                if sig:
-                    entry += f": {sig}"
-                if desc:
-                    entry += f" -- {desc}"
-                lines.append(entry)
-            lines.append("")
-
-    # Control flow: non-verbose only. Verbose's ``## Netlist`` below already
-    # covers control flow in full (its ``case (selector):`` scopes, with
-    # correctly tunnel-resolved selectors) -- this shallower summary would
-    # be both redundant and stale there (its selector naming doesn't hop
-    # through tunnels the way ``build_netlist`` does).
-    if not verbose:
-        structures = _collect_structures(
-            graph,
-            ctx,
-            ctx.operations,
-            index_terminal_owners(ctx.operations),
-        )
-        if structures:
-            lines.append("## Control Flow")
-            for s in structures:
-                lines.append(f"  {s}")
-            lines.append("")
-
-    if verbose:
-        assert netlist_module is not None
-        lines.append("## Netlist")
-        lines.append(render_netlist(netlist_module))
-    else:
-        # Operations
-        lines.append("## Operations")
-        _describe_op_list(ctx.operations, ctx.constants, lines, indent=0)
+    # Control flow: structure summary (case/loop/sequence/... with their
+    # gating selectors traced one hop back to the source).
+    structures = _collect_structures(
+        graph,
+        ctx,
+        ctx.operations,
+        index_terminal_owners(ctx.operations),
+    )
+    if structures:
+        lines.append("## Control Flow")
+        for s in structures:
+            lines.append(f"  {s}")
+        lines.append("")
+
+    # Operations
+    lines.append("## Operations")
+    _describe_op_list(ctx.operations, ctx.constants, lines, indent=0)
 
     return "\n".join(lines)
 

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/graph/netlist.py

@@ -2496,10 +2496,17 @@ def netlist_to_dict(module: NetlistModule) -> dict[str, Any]:
     }
 
 
-def render_netlist(module: NetlistModule) -> str:
+def render_netlist(module: NetlistModule, *, display_name: str | None = None) -> str:
     """Render a ``NetlistModule`` to the locked netlist text syntax.
 
     See ``.tmp/netlist-spec.md`` -- syntax is LOCKED, ASCII only.
+
+    ``display_name`` overrides the header line's VI label (``module.vi_name``
+    is the resolved ``vi_key`` -- a source-path identity, not fit for
+    display -- see ``describe.py``'s ``--format netlist`` naming rules,
+    which pass the qualified display name or a repo-relative path here).
+    Defaults to ``module.vi_name`` for every existing caller (JSON/diff/the
+    embedded viewer never pass this).
     """
     lines: list[str] = []
     in_names = ", ".join(name for name, _ in module.inputs)
@@ -2512,7 +2519,8 @@ def render_netlist(module: NetlistModule) -> str:
         else o.name
         for o in module.outputs
     )
-    lines.append(f"{module.vi_name} ({in_names}) -> ({out_names})")
+    header_name = display_name if display_name is not None else module.vi_name
+    lines.append(f"{header_name} ({in_names}) -> ({out_names})")
 
     _render_items(module.body, 0, lines, ambiguous)
 

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/graph/op_walk.py

@@ -2,10 +2,10 @@
 ``netlist``.
 
 Split out to avoid a circular import: ``netlist.py`` needs these to trace
-wires back to their producing operation, and ``describe.py`` needs
-``build_netlist``/``render_netlist`` for its ``## Netlist`` section. Neither
-module may import the other at module level, so the shared walk helpers
-live here instead.
+wires back to their producing operation, and ``describe.py`` walks the same
+operation tree for its own ``## Dependencies``/``## Control Flow``/
+``## Operations`` sections. Neither module may import the other at module
+level, so the shared walk helpers live here instead.
 """
 
 from __future__ import annotations

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/skill_templates/lvkit-convert/SKILL.md

@@ -56,8 +56,9 @@ wiring is expressed as `port -> source.net` bindings, not source order.
 `components` lists each distinct subVI/primitive's typed port interface
 once. This one call gives you everything — operations, wiring, structures,
 and constants — in one structured tree instead of five separate reads.
-`lvkit describe <vi-path> --search-path <library-path> -v` (no `--format`)
-prints the same facts as prose for a human instead of JSON for a program.
+`lvkit describe <vi-path> --search-path <library-path> --format netlist -v`
+prints the same facts as prose for a human instead of JSON for a program (`-v`
+adds the typed `## Components` declarations ahead of the netlist body).
 
 **A structure's output is a named MERGE net, not a plain wire.** A value
 leaving a case/loop/feedback node is selector- or iteration-dependent, so the

{lvkit-0.7.0 → lvkit-0.7.2}/src/lvkit/skill_templates/lvkit-describe/SKILL.md

@@ -23,9 +23,11 @@ together, not five separate reads.
 
 No MCP server connected? The CLI `lvkit describe` above is the twin of both:
 plain (no `--format`) prints the same prose as MCP `describe`; `-v/--verbose`
-adds the full netlist section inline; `--format json` emits the identical
-structured payload MCP `read_vi` returns, for a program instead of a person
-to parse.
+shows full detail within each section (every VI Property, Health, typed
+terminals) without changing its shape; `--format netlist` prints the VI
+dataflow netlist body on its own (add `-v` for a typed `## Components`
+section first); `--format json` emits the identical structured payload MCP
+`read_vi` returns, for a program instead of a person to parse.
 
 To see the VI's faithful block diagram, render it to SVG (CLI-only, no MCP
 twin):