simdref 0.0.6__tar.gz → 0.0.8__tar.gz

{simdref-0.0.6/src/simdref.egg-info → simdref-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simdref
-Version: 0.0.6
+Version: 0.0.8
 Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP.
 Author: Marco
 License: GPL-3.0-or-later
@@ -42,19 +42,20 @@ A single searchable reference for SIMD intrinsics and instructions across
 **x86 (Intel + uops.info)**, **Arm (ACLE / AARCHMRS)**, and **RISC-V
 (RVV + unified-db)**. Runs as a CLI, a Textual TUI, an LSP server,
 on-demand manpages (`simdref man` — or run `simdref install-manpages`
-so plain `man vpaddd` works), a static web app, and a structured JSON
-interface for LLM skills.
+so plain `man vpaddd` works), a JSON site-data export for
+[simdref-web](https://github.com/simd-labs/simdref-web), and a
+structured JSON interface for LLM skills.
 
 [Web App](https://simdref.diamondinoia.com/) ·
 [TestPyPI](https://test.pypi.org/project/simdref/) ·
 [GitHub](https://github.com/simd-labs/simdref) ·
 [Contributing](CONTRIBUTING.md)
 
-<!-- Screenshots are hosted on the `docs-assets` branch so the main
+<!-- Screenshots are hosted on the `assets/docs` ref so the main
      branch stays lightweight to clone. -->
 
 <p align="center">
-  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/docs-assets/img/tui.svg" width="720">
+  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/refs/assets/docs/img/tui.svg" width="720">
   <br><em>Interactive TUI with ISA filters, ranked results, and measured/modeled performance tables.</em>
 </p>
 
@@ -105,7 +106,7 @@ isa                  # open the interactive TUI
 **Web app** — a self-contained static SPA with filters and performance
 tables, published to GitHub Pages at
 [simdref.diamondinoia.com](https://simdref.diamondinoia.com/) and
-built from the `simdref-web` repo. This repo (`simdref-core`) exports the
+built from the `simdref-web` repo. This repo exports the
 JSON data it consumes:
 
 ```bash

{simdref-0.0.6 → simdref-0.0.8}/README.md

@@ -8,19 +8,20 @@ A single searchable reference for SIMD intrinsics and instructions across
 **x86 (Intel + uops.info)**, **Arm (ACLE / AARCHMRS)**, and **RISC-V
 (RVV + unified-db)**. Runs as a CLI, a Textual TUI, an LSP server,
 on-demand manpages (`simdref man` — or run `simdref install-manpages`
-so plain `man vpaddd` works), a static web app, and a structured JSON
-interface for LLM skills.
+so plain `man vpaddd` works), a JSON site-data export for
+[simdref-web](https://github.com/simd-labs/simdref-web), and a
+structured JSON interface for LLM skills.
 
 [Web App](https://simdref.diamondinoia.com/) ·
 [TestPyPI](https://test.pypi.org/project/simdref/) ·
 [GitHub](https://github.com/simd-labs/simdref) ·
 [Contributing](CONTRIBUTING.md)
 
-<!-- Screenshots are hosted on the `docs-assets` branch so the main
+<!-- Screenshots are hosted on the `assets/docs` ref so the main
      branch stays lightweight to clone. -->
 
 <p align="center">
-  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/docs-assets/img/tui.svg" width="720">
+  <img alt="simdref TUI" src="https://raw.githubusercontent.com/simd-labs/simdref/refs/assets/docs/img/tui.svg" width="720">
   <br><em>Interactive TUI with ISA filters, ranked results, and measured/modeled performance tables.</em>
 </p>
 
@@ -71,7 +72,7 @@ isa                  # open the interactive TUI
 **Web app** — a self-contained static SPA with filters and performance
 tables, published to GitHub Pages at
 [simdref.diamondinoia.com](https://simdref.diamondinoia.com/) and
-built from the `simdref-web` repo. This repo (`simdref-core`) exports the
+built from the `simdref-web` repo. This repo exports the
 JSON data it consumes:
 
 ```bash

{simdref-0.0.6 → simdref-0.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simdref"
-version = "0.0.6"
+version = "0.0.8"
 description = "Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP."
 readme = "README.md"
 requires-python = ">=3.10"

{simdref-0.0.6 → simdref-0.0.8}/src/simdref/cli.py

@@ -9,6 +9,7 @@ Display and formatting logic lives in :mod:`simdref.display`.
 
 from __future__ import annotations
 
+import contextlib
 import json
 import os
 import shutil
@@ -56,7 +57,6 @@ from simdref.display import (
     display_isa,
     instruction_query_text,
     instruction_variant_items,
-    isa_sort_key,
     isa_visible,
     normalize_instruction_query,
     render_intrinsic,
@@ -92,6 +92,7 @@ from simdref.storage import (
     DEFAULT_MAN_DIR,
     SQLITE_PATH,
     WEB_DIR,
+    _write_atomic,
     build_sqlite,
     load_catalog,
     load_catalog_from_db,
@@ -230,6 +231,10 @@ def _release_asset_url(tag: str, asset_name: str) -> str:
     return f"https://github.com/{GITHUB_REPO}/releases/download/{tag}/{asset_name}"
 
 
+class _ReleaseAssetMissing(Exception):
+    """The release carries no compatible asset for this name."""
+
+
 def _download_from_release() -> None:
     """Download pre-built catalog and database from GitHub Release.
 
@@ -244,7 +249,7 @@ def _download_from_release() -> None:
 
     is_tty = err_console.is_terminal and os.environ.get("GITHUB_ACTIONS") != "true"
 
-    def _fetch_into(asset: str, dest: Path) -> bool:
+    def _fetch_into(asset: str, fh) -> bool:
         for tag in _release_tag_candidates():
             url = _release_asset_url(tag, asset)
             try:
@@ -268,17 +273,15 @@ def _download_from_release() -> None:
                         )
                         with progress:
                             task = progress.add_task(f"downloading {asset} ({tag})", total=total)
-                            with open(dest, "wb") as f:
-                                for chunk in resp.iter_bytes(chunk_size=1024 * 64):
-                                    f.write(chunk)
-                                    progress.update(task, advance=len(chunk))
+                            for chunk in resp.iter_bytes(chunk_size=1024 * 64):
+                                fh.write(chunk)
+                                progress.update(task, advance=len(chunk))
                     else:
                         err_console.print(f"downloading {asset} from {tag}...", style="dim")
                         written = 0
-                        with open(dest, "wb") as f:
-                            for chunk in resp.iter_bytes(chunk_size=1024 * 64):
-                                f.write(chunk)
-                                written += len(chunk)
+                        for chunk in resp.iter_bytes(chunk_size=1024 * 64):
+                            fh.write(chunk)
+                            written += len(chunk)
                         if total:
                             err_console.print(
                                 f"downloaded {asset}: {written / 1_048_576:.1f} MB "
@@ -313,12 +316,19 @@ def _download_from_release() -> None:
 
     for asset in ("catalog.msgpack", "catalog.db"):
         dest = DATA_DIR / asset
-        if not _fetch_into(asset, dest):
+
+        def write(fh, asset=asset):
+            if not _fetch_into(asset, fh):
+                raise _ReleaseAssetMissing(asset)
+
+        try:
+            _write_atomic(dest, write)
+        except _ReleaseAssetMissing:
             err_console.print(
                 f"failed to download {asset}: no compatible release asset found", style="red"
             )
             err_console.print("try 'simdref build' to build locally", style="yellow")
-            raise typer.Exit(code=1)
+            raise typer.Exit(code=1) from None
     err_console.print("download complete", style="green")
 
 
@@ -458,9 +468,7 @@ def _build_runtime_locally(*, man_dir: Path, include_sdm: bool = False) -> None:
 
         web_task = count_progress.add_task("Exporting site data", total=1)
         export_site_data(catalog, WEB_DIR)
-        count_progress.update(
-            web_task, completed=1, description="Exporting site data \u2713"
-        )
+        count_progress.update(web_task, completed=1, description="Exporting site data \u2713")
 
     err_console.print(
         f"updated catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
@@ -972,7 +980,11 @@ def _payload_source_kinds(arch_details) -> list[str]:
 # ---------------------------------------------------------------------------
 
 
-def _print_search_results_runtime(conn, query: str, limit: int = 20) -> None:
+def _print_search_results_runtime(conn, query: str, limit: int = 20, as_json: bool = False) -> int:
+    """Render the ranked search table (or JSON) in the search's own
+    relevance order. Returns the number of rows actually printed — callers
+    use 0 to fall through to the no-match branch instead of printing an
+    empty table."""
     results, intrinsic_map, instruction_map = _search_runtime(conn, query, limit=limit)
     prepared_rows = []
     for result in results:
@@ -980,7 +992,6 @@ def _print_search_results_runtime(conn, query: str, limit: int = 20) -> None:
         isa = "-"
         lat = "-"
         cpi = "-"
-        isa_sort = (99, "-")
         if result.kind == "instruction":
             item = instruction_map.get(result.key)
             if item is not None:
@@ -988,7 +999,6 @@ def _print_search_results_runtime(conn, query: str, limit: int = 20) -> None:
                     continue
                 arch = display_architecture(item.architecture)
                 isa = display_isa(item.isa)
-                isa_sort = isa_sort_key(item.isa)
                 lat, cpi = variant_perf_summary(item.arch_details)
         elif result.kind == "intrinsic":
             item = intrinsic_map.get(result.key)
@@ -997,18 +1007,37 @@ def _print_search_results_runtime(conn, query: str, limit: int = 20) -> None:
                     continue
                 arch = display_architecture(item.architecture)
                 isa = display_isa(item.isa)
-                isa_sort = isa_sort_key(item.isa)
                 lat, cpi = intrinsic_perf_summary_runtime(conn, item, instruction_map)
-        prepared_rows.append((result, arch, isa, lat, cpi, isa_sort))
-    prepared_rows.sort(
-        key=lambda row: (
-            row[0].kind != "instruction",
-            row[5],
-            row[0].title.casefold(),
-            row[0].key.casefold(),
+        prepared_rows.append((result, arch, isa, lat, cpi))
+    if not prepared_rows:
+        return 0
+    if as_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "query": query,
+                    "mode": "search",
+                    "results": [
+                        {
+                            "kind": r.kind,
+                            "key": r.key,
+                            "title": r.title,
+                            "subtitle": r.subtitle,
+                            "arch": arch,
+                            "isa": isa,
+                            "latency_cycles": lat,
+                            "tput_cpi": cpi,
+                        }
+                        for r, arch, isa, lat, cpi in prepared_rows
+                    ],
+                },
+                indent=2,
+                default=str,
+            )
         )
-    )
-    render_search_results([(r, arch, isa, lat, cpi) for r, arch, isa, lat, cpi, _ in prepared_rows])
+        return len(prepared_rows)
+    render_search_results(prepared_rows)
+    return len(prepared_rows)
 
 
 # ---------------------------------------------------------------------------
@@ -1024,21 +1053,45 @@ def _smart_lookup(
 ) -> int:
     """Dispatch a bare query.
 
-    If ``query`` resolves to known instruction records, print a plain-text
-    (or JSON) summary to stdout and exit — never blocks on a TUI. Only
-    open the TUI when the query is unknown and stdio is a TTY, so the user
-    can explore; in non-TTY contexts an unknown query exits with code 2.
+    Exact intrinsic match prints the intrinsic detail and exits 0. Exact
+    instruction match prints a plain-text (or JSON) summary and exits 0;
+    ``--arch`` applies to this branch only. Fuzzy hits print the ranked
+    search list (or JSON) and exit 0, on a TTY or not. Nothing found opens
+    the TUI on a TTY (never under ``--json``) or exits 2 non-interactively.
     """
     ensure_runtime()
-    records = _find_instructions_fast(query)
-    if records:
-        return _print_non_interactive_summary(query, records=records, arch=arch, as_json=as_json)
-    if not (sys.stdin.isatty() and sys.stdout.isatty()):
-        err_console.print(
-            f"no instruction match for {query!r} (non-interactive; run in a TTY to search).",
-            style="yellow",
-        )
-        return 2
+    with contextlib.closing(open_db()) as conn:
+        intrinsic = load_intrinsic_from_db(conn, query)
+        if intrinsic is not None and arch is not None:
+            err_console.print("--arch applies to instruction queries only", style="red")
+            return 2
+        if intrinsic is not None:
+            if as_json:
+                typer.echo(json.dumps(asdict(intrinsic), indent=2, default=str))
+            else:
+                render_intrinsic(None, intrinsic, conn=conn)
+            return 0
+        records = _find_instructions_fast(query)
+        if records:
+            return _print_non_interactive_summary(
+                query, records=records, arch=arch, as_json=as_json
+            )
+        if arch is not None:
+            err_console.print("--arch applies to instruction queries only", style="red")
+            return 2
+        printed = _print_search_results_runtime(conn, query, as_json=as_json)
+        if printed:
+            if not as_json and sys.stdin.isatty() and sys.stdout.isatty():
+                # A fuzzy match on a TTY opens the TUI (preset as passed, like
+                # origin/main); non-TTY and --json keep printing the list.
+                return _run_tui(initial_query=query, initial_preset=preset)
+            return 0
+        if as_json or not (sys.stdin.isatty() and sys.stdout.isatty()):
+            err_console.print(
+                f"no match for {query!r} (non-interactive; run in a TTY to search).",
+                style="yellow",
+            )
+            return 2
     return _run_tui(initial_query=query, initial_preset=preset)
 
 

{simdref-0.0.6 → simdref-0.0.8}/src/simdref/export.py

@@ -313,12 +313,20 @@ def _columnar_instructions(entries: list[dict]) -> dict:
         cols["form"].append(0 if e["form"] == e["display_form"] else e["form"])
         cols["dmn"].append(e["display_mnemonic"])
         cols["mn"].append(0 if e["mnemonic"] == e["display_mnemonic"] else e["mnemonic"])
-        cols["key"].append(0 if e["key"] == e["architecture"] + ":" + e["form"].lower() else e["key"])
+        cols["key"].append(
+            0 if e["key"] == e["architecture"] + ":" + e["form"].lower() else e["key"]
+        )
         cols["sum"].append(f[3])
         cols["isa"].append(isa([e["isa"], e["display_isa"], e["isa_families"], e["isa_subs"]]))
         cols["arch"].append(arch([e["architecture"], e["display_architecture"]]))
         cols["perf"].append(perf([e["lat"], e["cpi"]]))
-        if f != [e["display_mnemonic"], e["display_key"], e["display_form"], f[3], e["display_isa"]]:
+        if f != [
+            e["display_mnemonic"],
+            e["display_key"],
+            e["display_form"],
+            f[3],
+            e["display_isa"],
+        ]:
             fields[i] = f
         if _truncate(f[3], 80) != e["summary"]:
             summaries[i] = e["summary"]