simdref 0.0.1__tar.gz → 0.0.4__tar.gz

{simdref-0.0.1/src/simdref.egg-info → simdref-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simdref
-Version: 0.0.1
+Version: 0.0.4
 Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export.
 Author: Marco
 License: GPL-3.0-or-later
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: click<10,>=8.1
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: msgpack<2,>=1.0
 Requires-Dist: pdfplumber<1,>=0.11
@@ -33,7 +34,7 @@ Dynamic: license-file
 
 [![CI](https://github.com/DiamonDinoia/simdref/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamonDinoia/simdref/actions/workflows/ci.yml)
 [![TestPyPI](https://img.shields.io/pypi/v/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org&label=TestPyPI)](https://test.pypi.org/project/simdref/)
-[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/simdref/)
+[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://pypi.org/project/simdref/)
 
 A single searchable reference for SIMD intrinsics and instructions across
 **x86 (Intel + uops.info)**, **Arm (ACLE / AARCHMRS)**, and **RISC-V

{simdref-0.0.1 → simdref-0.0.4}/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/DiamonDinoia/simdref/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamonDinoia/simdref/actions/workflows/ci.yml)
 [![TestPyPI](https://img.shields.io/pypi/v/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org&label=TestPyPI)](https://test.pypi.org/project/simdref/)
-[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/simdref/)
+[![Python](https://img.shields.io/pypi/pyversions/simdref?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://pypi.org/project/simdref/)
 
 A single searchable reference for SIMD intrinsics and instructions across
 **x86 (Intel + uops.info)**, **Arm (ACLE / AARCHMRS)**, and **RISC-V

{simdref-0.0.1 → simdref-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simdref"
-version = "0.0.1"
+version = "0.0.4"
 description = "Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,6 +26,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
+  "click>=8.1,<10",
   "httpx>=0.28,<1",
   "msgpack>=1.0,<2",
   "pdfplumber>=0.11,<1",

simdref-0.0.4/src/simdref/__init__.py

@@ -0,0 +1,10 @@
+"""simdref package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("simdref")
+except PackageNotFoundError:  # uninstalled source checkout
+    __version__ = "0.0.0+source"

{simdref-0.0.1 → simdref-0.0.4}/src/simdref/annotate.py

@@ -68,8 +68,6 @@ def parse_asm_line(line: str, *, track_positions: bool = False) -> AsmLine:
         return AsmLine(LineKind.COMMENT, stripped)
     if bare.startswith("."):
         return AsmLine(LineKind.DIRECTIVE, stripped)
-    if _LABEL_RE.match(stripped):
-        return AsmLine(LineKind.LABEL, stripped)
 
     address: int | None = None
     if track_positions:
@@ -97,6 +95,9 @@ def parse_asm_line(line: str, *, track_positions: bool = False) -> AsmLine:
         # source keywords ("return", "if", "for", ...) as mnemonics.
         return AsmLine(LineKind.COMMENT, stripped)
 
+    if _LABEL_RE.match(stripped):
+        return AsmLine(LineKind.LABEL, stripped)
+
     m = _INSTR_RE.match(stripped)
     if not m:
         return AsmLine(LineKind.COMMENT, stripped)

{simdref-0.0.1 → simdref-0.0.4}/src/simdref/cli.py

@@ -70,6 +70,7 @@ from simdref.ingest_sources import (
     refresh_local_arm_intrinsics_bundle,
 )
 from simdref.manpages import open_manpage, write_manpages
+from simdref import perf
 from simdref.perf import variant_perf_summary
 from simdref.queries import intrinsic_perf_summary_runtime, instruction_rows_for_intrinsic
 from simdref.search import (
@@ -92,10 +93,12 @@ from simdref.storage import (
     load_instructions_by_mnemonic_from_db,
     load_instructions_by_mnemonic_prefix_from_db,
     open_db,
+    read_installed_version_stamp,
     save_catalog,
     search_instruction_candidates_from_db,
     search_intrinsic_candidates_from_db,
     sqlite_schema_is_current,
+    write_installed_version_stamp,
 )
 from simdref.web import export_web
 
@@ -287,6 +290,18 @@ def _download_from_release() -> None:
                     f"failed to download {asset}: {exc.response.status_code}", style="red"
                 )
                 raise typer.Exit(code=1) from exc
+            except (
+                httpx.ConnectError,
+                httpx.ConnectTimeout,
+                httpx.ReadTimeout,
+                httpx.NetworkError,
+            ) as exc:
+                err_console.print(
+                    "[bold yellow]warning:[/bold yellow] no internet connectivity — "
+                    f"could not reach the release server ({exc.__class__.__name__}). "
+                    "Some features may not work correctly until the catalog is refreshed.",
+                )
+                raise typer.Exit(code=1) from exc
         return False
 
     for asset in ("catalog.msgpack", "catalog.db"):
@@ -444,6 +459,7 @@ def _build_runtime_locally(*, man_dir: Path, include_sdm: bool = False) -> None:
         f"updated catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
         style="green",
     )
+    write_installed_version_stamp(__version__)
 
 
 def _refresh_runtime_from_existing_catalog(*, man_dir: Path) -> None:
@@ -463,6 +479,7 @@ def _refresh_runtime_from_existing_catalog(*, man_dir: Path) -> None:
         f"refreshed runtime from existing catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
         style="green",
     )
+    write_installed_version_stamp(__version__)
 
 
 def _finalize_runtime_from_download(*, man_dir: Path) -> None:
@@ -476,6 +493,7 @@ def _finalize_runtime_from_download(*, man_dir: Path) -> None:
         f"refreshed local web/man assets from downloaded catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
         style="green",
     )
+    write_installed_version_stamp(__version__)
 
 
 def _download_release_or_fallback(*, man_dir: Path) -> None:
@@ -559,9 +577,16 @@ def ensure_catalog():
 
 
 def ensure_runtime() -> None:
-    """Ensure catalog + SQLite are present and current."""
+    """Ensure catalog + SQLite are present and current.
+
+    If the package version recorded in the data dir does not match the
+    currently installed version, transparently re-run the release-download
+    flow so users don't need to invoke ``simdref update`` manually after
+    a ``pip``/``uv`` install or upgrade. Honors ``SIMDREF_SKIP_AUTOUPDATE``.
+    """
     if not CATALOG_PATH.exists():
         _bootstrap_interactive()
+        _maybe_auto_update_for_version_change()
         return
     if not sqlite_schema_is_current():
         err_console.print(
@@ -569,6 +594,37 @@ def ensure_runtime() -> None:
             style="yellow",
         )
         _refresh_runtime_from_existing_catalog(man_dir=DEFAULT_MAN_DIR)
+    _maybe_auto_update_for_version_change()
+
+
+def _maybe_auto_update_for_version_change() -> None:
+    """Refresh data when the package version differs from the stamped one."""
+    if os.environ.get("SIMDREF_SKIP_AUTOUPDATE"):
+        return
+    stamped = read_installed_version_stamp()
+    if stamped == __version__:
+        return
+    if stamped is None:
+        # First run after install: stamp without re-downloading. The catalog
+        # we just bootstrapped (or that already exists locally) is what the
+        # user expects to see.
+        write_installed_version_stamp(__version__)
+        return
+    err_console.print(
+        f"simdref upgraded from {stamped} to {__version__}; refreshing catalog "
+        "(set SIMDREF_SKIP_AUTOUPDATE=1 to disable)",
+        style="yellow",
+    )
+    try:
+        _download_release_or_fallback(man_dir=DEFAULT_MAN_DIR)
+    except typer.Exit:
+        err_console.print(
+            "[bold yellow]warning:[/bold yellow] auto-update failed; continuing with the existing catalog. "
+            "Some features may not work correctly until `simdref update` succeeds.",
+        )
+        # Stamp anyway so we don't retry on every invocation; the user has
+        # been warned and can re-run `simdref update` once back online.
+        write_installed_version_stamp(__version__)
 
 
 def _catalog_meta(catalog) -> dict:
@@ -700,10 +756,11 @@ def _llm_result_payload(
                 intrinsic_map[result.key] = item
         if item is not None:
             lat, cpi = intrinsic_perf_summary_runtime(conn, item, instruction_map)
-            return {
+            payload: dict = {
                 "query": item.name,
                 "intrinsic": item.name,
                 "signature": item.signature,
+                "url": getattr(item, "url", "") or "",
                 "instructions": item.instructions,
                 "instruction_refs": item.instruction_refs,
                 "summary": item.description,
@@ -711,6 +768,10 @@ def _llm_result_payload(
                 "lat": lat,
                 "cpi": cpi,
             }
+            operation = _intrinsic_operation_text(item)
+            if operation:
+                payload["operation"] = operation
+            return payload
     item = instruction_map.get(result.key)
     if item is None:
         item = load_instruction_from_db(conn, result.key)
@@ -739,7 +800,7 @@ def _llm_result_payload(
 def _llm_intrinsic_payload(conn, intrinsic) -> dict:
     instruction_map: dict[str, object] = {}
     lat, cpi = intrinsic_perf_summary_runtime(conn, intrinsic, instruction_map)
-    return {
+    payload: dict = {
         "query": intrinsic.name,
         "intrinsic": intrinsic.name,
         "signature": intrinsic.signature,
@@ -751,6 +812,23 @@ def _llm_intrinsic_payload(conn, intrinsic) -> dict:
         "cpi": cpi,
         "summary": intrinsic.description,
     }
+    operation = _intrinsic_operation_text(intrinsic)
+    if operation:
+        # Encodes algorithmic quirks (e.g. the bit-1 selector in
+        # ``_mm_permutevar_pd``) that the one-line summary cannot convey.
+        payload["operation"] = operation
+    return payload
+
+
+def _intrinsic_operation_text(intrinsic) -> str:
+    """Return the SDM-style ``Operation`` pseudocode for *intrinsic*, or ``""``.
+
+    Intel ingest stores it under ``doc_sections["Operation"]``; ARM ACLE under
+    ``doc_sections["ACLE Operation"]``. Both are pseudocode the LLM payload
+    needs to surface so callers can reason about behavior beyond the summary.
+    """
+    sections = getattr(intrinsic, "doc_sections", None) or {}
+    return (sections.get("Operation") or sections.get("ACLE Operation") or "").strip()
 
 
 def _llm_instruction_payload(item) -> dict:
@@ -762,9 +840,24 @@ def _llm_instruction_payload(item) -> dict:
         "lat": lat,
         "cpi": cpi,
         "summary": item.summary,
+        "source_kinds": _payload_source_kinds(item.arch_details),
     }
 
 
+def _payload_source_kinds(arch_details) -> list[str]:
+    """Return the distinct provenance kinds present in an instruction's arch_details."""
+    if not isinstance(arch_details, dict):
+        return []
+    kinds: list[str] = []
+    for details in arch_details.values():
+        if not isinstance(details, dict):
+            continue
+        kind = perf._source_kind(details)
+        if kind not in kinds:
+            kinds.append(kind)
+    return kinds
+
+
 # ---------------------------------------------------------------------------
 # Search results
 # ---------------------------------------------------------------------------
@@ -1184,6 +1277,9 @@ def _llm_filter_records(
 
 def _record_has_source_kind(rec: dict, wanted: str) -> bool:
     """Check whether an llm payload dict carries at least one entry with *wanted* provenance."""
+    slim = rec.get("source_kinds")
+    if isinstance(slim, list) and any(k == wanted for k in slim):
+        return True
     arch_details = rec.get("arch_details") or {}
     if isinstance(arch_details, dict):
         for details in arch_details.values():
@@ -1323,6 +1419,14 @@ def _llm_schema_payload() -> dict:
                     "lat": {"type": "string"},
                     "cpi": {"type": "string"},
                     "summary": {"type": "string"},
+                    "url": {
+                        "type": "string",
+                        "description": "Vendor documentation URL (Intel Intrinsics Guide / ARM ACLE).",
+                    },
+                    "operation": {
+                        "type": "string",
+                        "description": "SDM-style pseudocode describing the intrinsic's behavior, when available.",
+                    },
                 },
             },
             "results": {"type": "array", "items": {"$ref": "#/properties/result"}},

{simdref-0.0.1 → simdref-0.0.4}/src/simdref/ingest_catalog.py

@@ -275,6 +275,13 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
             name = node.attrib.get("name", "").strip()
             if not name:
                 continue
+            operation_text = ""
+            op_node = node.find("./operation")
+            if op_node is not None:
+                # ``<operation>`` carries SDM-style pseudocode; preserve internal
+                # whitespace (it encodes the algorithm) but trim outer padding.
+                raw = "".join(op_node.itertext())
+                operation_text = raw.strip("\n").rstrip() if raw else ""
             return_node = node.find("./return")
             ret = (
                 node.attrib.get("rettype", "").strip()
@@ -321,6 +328,7 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
                     header=(
                         (node.findtext("./header") or "").strip() or node.attrib.get("header", "")
                     ),
+                    url=_intel_intrinsic_url(name),
                     architecture="x86",
                     isa=_normalize_isa(
                         cpuid or node.attrib.get("isa", "") or node.attrib.get("tech", "")
@@ -332,6 +340,7 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
                     subcategory=node.attrib.get("tech", "").strip(),
                     instructions=instructions,
                     instruction_refs=[ref | {"architecture": "x86"} for ref in instruction_refs],
+                    doc_sections=({"Operation": operation_text} if operation_text else {}),
                     notes=notes,
                     aliases=[],
                 )
@@ -384,12 +393,16 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
         description = str(
             item.get("description") or item.get("summary") or item.get("technology", "")
         ).strip()
+        operation_text = (
+            str(item.get("operation") or item.get("Operation") or "").strip("\n").rstrip()
+        )
         records.append(
             IntrinsicRecord(
                 name=name,
                 signature=signature,
                 description=description,
                 header=str(item.get("header") or item.get("include") or "").strip(),
+                url=str(item.get("url") or "").strip() or _intel_intrinsic_url(name),
                 architecture="x86",
                 isa=_normalize_isa(
                     item.get("isa") or item.get("tech") or item.get("instructionSet") or []
@@ -402,6 +415,7 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
                     for value in instructions
                     if str(value).strip()
                 ],
+                doc_sections=({"Operation": operation_text} if operation_text else {}),
                 notes=[str(value).strip() for value in notes if str(value).strip()],
                 aliases=[str(value).strip() for value in aliases if str(value).strip()],
             )
@@ -476,6 +490,16 @@ def _arm_intrinsic_url(name: str) -> str:
     return urljoin(_ARM_ACLE_INTRINSIC_BASE_URL, quote(name))
 
 
+_INTEL_INTRINSIC_BASE_URL = (
+    "https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html"
+)
+
+
+def _intel_intrinsic_url(name: str) -> str:
+    """Stable Intel Intrinsics Guide deep link for *name* (uses ``#text=`` fragment)."""
+    return f"{_INTEL_INTRINSIC_BASE_URL}#text={quote(name)}"
+
+
 def _arm_slug(text: str) -> str:
     slug = re.sub(r"[^a-z0-9]+", "-", text.casefold()).strip("-")
     return slug or "intrinsics"

{simdref-0.0.1 → simdref-0.0.4}/src/simdref/perf.py

@@ -70,9 +70,16 @@ def latency_cycle_values(latencies: list[dict[str, Any]]) -> list[str]:
     """
     values: list[str] = []
     for latency in latencies:
+        mem_is_upper = latency.get("cycles_mem_is_upper_bound") == "1"
         for key in ("cycles", "cycles_mem", "cycles_addr", "cycles_addr_index"):
             value = latency.get(key)
-            if value and value not in values:
+            if not value:
+                continue
+            if key == "cycles_mem" and mem_is_upper and _is_numeric(value) and float(value) == 0:
+                # uops.info convention: cycles_mem=0 with the upper-bound flag
+                # is a "not measured" marker, not a real zero-cycle latency.
+                continue
+            if value not in values:
                 values.append(value)
     return values
 

{simdref-0.0.1 → simdref-0.0.4}/src/simdref/storage.py

@@ -82,7 +82,27 @@ else:
 
 CATALOG_PATH = DATA_DIR / "catalog.msgpack"
 SQLITE_PATH = DATA_DIR / "catalog.db"
-SQLITE_SCHEMA_VERSION = "11"
+INSTALLED_VERSION_STAMP = DATA_DIR / "installed_version"
+SQLITE_SCHEMA_VERSION = "12"
+
+
+def read_installed_version_stamp() -> str | None:
+    """Return the package version that last refreshed the data dir, or None."""
+    try:
+        return INSTALLED_VERSION_STAMP.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def write_installed_version_stamp(version: str) -> None:
+    """Record the package version that just refreshed the data dir."""
+    try:
+        INSTALLED_VERSION_STAMP.parent.mkdir(parents=True, exist_ok=True)
+        INSTALLED_VERSION_STAMP.write_text(version.strip() + "\n", encoding="utf-8")
+    except OSError:
+        pass  # best-effort — stamp persistence must not break commands
+
+
 FTS_TOKEN_RE = re.compile(r"[A-Za-z0-9]+")
 SQLITE_INSERT_BATCH_SIZE = 512