simdref 0.0.8__tar.gz → 0.0.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simdref
-Version: 0.0.8
+Version: 0.0.9
 Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP.
 Author: Marco
 License: GPL-3.0-or-later

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

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

{simdref-0.0.8 → simdref-0.0.9}/src/simdref/display.py

@@ -9,6 +9,7 @@ delegate to these functions for all Rich-based output.
 from __future__ import annotations
 
 import re
+import urllib.parse
 from typing import TYPE_CHECKING
 
 from rich.console import Console
@@ -480,6 +481,68 @@ def isa_visible(values: list[str], show_fp16: bool = False) -> bool:
 # ---------------------------------------------------------------------------
 
 
+_WEB_APP_URL = "https://simdref.diamondinoia.com"
+
+
+def web_deep_link(kind: str, key: str) -> str:
+    """Deep link into the simdref web app for a record key."""
+    # Match the web app's encodeURIComponent(entry.key): parens stay literal.
+    return f"{_WEB_APP_URL}/#{urllib.parse.quote(str(key), safe='()')}"
+
+
+def instruction_markdown(item, conn=None) -> str:
+    """Render the full instruction page as Markdown (hover docs, exports).
+
+    Carries the same data as :func:`render_instruction` prints to the
+    terminal: metadata, every description section, the intrinsic mapping
+    and the per-microarchitecture performance table, plus reference URLs.
+    """
+    lines = [f"```asm\n{item.key}\n```"]
+    lines.append(f"**isa.** {display_isa(item.isa)}")
+    for key, value in instruction_metadata_rows(item):
+        lines.append(f"**{key}.** {value}")
+    if item.description:
+        shown: set[str] = set()
+        for section in _DESCRIPTION_ORDER:
+            if section in item.description:
+                lines.append(f"## {section}\n\n{item.description[section].strip()}")
+                shown.add(section)
+        for section, body in item.description.items():
+            if section not in shown:
+                lines.append(f"## {section}\n\n{body.strip()}")
+    if item.linked_intrinsics:
+        lines.append(
+            "## instruction to intrinsic mapping\n\n"
+            + "\n".join(f"- `{name}`" for name in item.linked_intrinsics)
+        )
+    lines.extend(_perf_markdown_lines(measurement_rows(item)))
+    return "\n\n".join(lines)
+
+
+def _perf_markdown_lines(rows: list[dict]) -> list[str]:
+    """Markdown table for measurement rows, one section per source kind."""
+    sections: list[str] = []
+    for kind, group in split_perf_rows(rows):
+        group = [row for row in group if row]
+        columns = [
+            column
+            for column in _MEASUREMENT_PREFERRED_ORDER
+            if column not in _MEASUREMENT_EXCLUDE_KEYS and any(column in row for row in group)
+        ]
+        if not columns:
+            continue
+        header = [_GENERIC_TABLE_LABEL_MAP.get(column, column) for column in columns]
+        table = ["| " + " | ".join(header) + " |", "|" + "---|" * len(columns)]
+        for row in sorted(group, key=lambda r: uarch_sort_key(r.get("uarch", ""))):
+            cells = []
+            for column in columns:
+                value = row.get(column, "-")
+                cells.append(display_uarch(str(value)) if column == "uarch" else str(value))
+            table.append("| " + " | ".join(cells) + " |")
+        sections.append(f"## {perf_panel_title(kind)}\n\n" + "\n".join(table))
+    return sections
+
+
 def canonical_url(path: str) -> str:
     if not path:
         return ""

{simdref-0.0.8 → simdref-0.0.9}/src/simdref/lsp.py

@@ -9,6 +9,7 @@ import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
+from simdref.display import canonical_url, instruction_markdown, web_deep_link
 from simdref.perf import best_cpi, best_latency
 from simdref.queries import linked_instruction_records
 from simdref.search import search_records
@@ -97,7 +98,40 @@ def _line_prefix(text: str, line: int, character: int) -> str:
     return match.group(0) if match else ""
 
 
-def _hover_markdown(conn, word: str, allow_instruction: bool = True) -> str | None:
+def _match_form(matches, operand_count: int | None = None, operand_text: str = ""):
+    """Pick the same form the line names: exact operand count, then width, then smallest."""
+    if operand_count is None:
+        return matches[0] if matches else None
+    # ponytail: a line has no architecture, so take the first form with the same operand count.
+    # The fallback takes the first form with fewest operands, never a form with more
+    # operands than the line: a zero-operand "movsd" must not get the MOVSD_XMM hint.
+    same_count = [m for m in matches if len(_operands_of_key(m.key)) == operand_count]
+    if not same_count:
+        return min(matches, key=lambda m: len(_operands_of_key(m.key)), default=None)
+    # Score candidates by how many operands agree with the register width the
+    # line names ("ymm0" vs "YMM, YMM, M128"). Skip the tiebreak on a tie.
+    tokens = re.findall(r"\b(zmm|ymm|xmm|m512|m256|m128|m64|m32)\d*\b", operand_text.casefold())
+    if tokens:
+        width = tokens[0].rstrip("0123456789")
+        if width.startswith(("x", "y", "z")):
+
+            def _score(item):
+                operands = [op.casefold().rstrip("0123456789") for op in _operands_of_key(item.key)]
+                return sum(1 for op in operands if op == width)
+
+            scored = sorted(same_count, key=lambda m: (-_score(m), m.key))
+            if _score(scored[0]) > _score(scored[-1]):
+                return scored[0]
+    return same_count[0]
+
+
+def _hover_markdown(
+    conn,
+    word: str,
+    allow_instruction: bool = True,
+    operand_count: int | None = None,
+    operand_text: str = "",
+) -> str | None:
     intrinsic = load_intrinsic_from_db(conn, word)
     if intrinsic is not None:
         lines = [f"```c\n{intrinsic.signature}\n```"]
@@ -139,32 +173,18 @@ def _hover_markdown(conn, word: str, allow_instruction: bool = True) -> str | No
         return None
     instruction = load_instruction_from_db(conn, word)
     if instruction is None:
-        # Catalog keys look like "VADDPS (XMM, XMM, XMM)", so a bare mnemonic needs this lookup.
         matches = load_instructions_by_mnemonic_from_db(conn, word)
-        instruction = matches[0] if matches else None
+        # Match the form on the source line like _hint_label does, so
+        # "vaddps ymm0, ymm1, ymm2" gets the YMM form, not the first row.
+        instruction = _match_form(matches, operand_count, operand_text)
     if instruction is not None:
-        lines = [f"```asm\n{instruction.key}\n```"]
-        if instruction.summary:
-            lines.append(instruction.summary)
-        meta = []
-        if instruction.isa:
-            meta.append(f"ISA {', '.join(instruction.isa)}")
-        if instruction.metadata.get("category"):
-            meta.append(f"category {instruction.metadata['category']}")
-        if meta:
-            lines.append(" | ".join(meta))
-        if instruction.linked_intrinsics:
-            lines.append(f"Intrinsics: {', '.join(instruction.linked_intrinsics[:6])}")
-        perf = []
-        lat = best_latency(instruction.arch_details)
-        cpi = best_cpi(instruction.arch_details)
-        if lat != "-":
-            perf.append(f"best latency {lat} cycles")
-        if cpi != "-":
-            perf.append(f"best cycle/instr {cpi}")
-        if perf:
-            lines.append("Performance: " + ", ".join(perf))
-        return "\n\n".join(lines)
+        body = instruction_markdown(instruction, conn=conn)
+        links = [f"Full page: {web_deep_link('instruction', instruction.key)}"]
+        if instruction.metadata.get("url"):
+            links.append(canonical_url(instruction.metadata["url"]))
+        if instruction.metadata.get("url-ref"):
+            links.append(canonical_url(instruction.metadata["url-ref"]))
+        return body + "\n\n" + "\n".join(links)
     return None
 
 
@@ -275,13 +295,7 @@ def _hint_label(db_path: str, mnemonic: str, operand_count: int) -> str | None:
     matches = _mnemonic_matches(db_path, mnemonic)
     if not matches:
         return None
-    # ponytail: a line has no architecture, so take the first form with the same operand count.
-    # The fallback takes the first form with fewest operands, never a form with more
-    # operands than the line: a zero-operand "movsd" must not get the MOVSD_XMM hint.
-    chosen = next(
-        (m for m in matches if len(_operands_of_key(m.key)) == operand_count),
-        min(matches, key=lambda m: len(_operands_of_key(m.key))),
-    )
+    chosen = _match_form(matches, operand_count)
     return _cut_label(chosen.summary or "")
 
 
@@ -289,7 +303,13 @@ def _inlay_hints(conn, text: str, language_id: str, uri: str, start: int, end: i
     db_path = conn.execute("PRAGMA database_list").fetchone()[2]
     source_lines = [line.rstrip("\r") for line in text.split("\n")]
     is_c_doc = _is_c_doc(language_id, uri)
-    semicolon_is_comment = not is_c_doc and uri.lower().endswith(".asm")
+    # A .s/.S extension means GAS syntax: ";" stays a statement separator there
+    # even if the client tags the buffer with an assembly languageId.
+    semicolon_is_comment = (
+        not is_c_doc
+        and not uri.lower().endswith(".s")
+        and (language_id in ("asm", "nasm", "masm") or uri.lower().endswith((".asm", ".nasm")))
+    )
     if is_c_doc:
         candidates = [
             (text.count("\n", 0, offset), segment)
@@ -386,10 +406,28 @@ def main() -> int:
             line, character = params["position"]["line"], params["position"]["character"]
             word = _word_at(text, line, character)
             # In C/C++ only the asm strings hold instructions; intrinsics hover everywhere.
-            allow_instruction = not _is_c_doc(session.languages.get(uri, ""), uri) or (
-                _in_asm_string(text, line, character)
+            is_c_doc = _is_c_doc(session.languages.get(uri, ""), uri)
+            allow_instruction = not is_c_doc or (_in_asm_string(text, line, character))
+            operand_count = None
+            operand_text = ""
+            if word and allow_instruction:
+                source_lines = text.split("\n")
+                source_line = source_lines[line] if line < len(source_lines) else ""
+                operand_text = source_line
+                parsed = _mnemonic_from_asm_line(source_line)
+                if parsed and parsed[0].casefold() == word.casefold():
+                    operand_count = parsed[1]
+            body = (
+                _hover_markdown(
+                    conn,
+                    word,
+                    allow_instruction,
+                    operand_count=operand_count,
+                    operand_text=operand_text,
+                )
+                if conn and word
+                else None
             )
-            body = _hover_markdown(conn, word, allow_instruction) if conn and word else None
             _jsonrpc_write(
                 {
                     "jsonrpc": "2.0",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simdref
-Version: 0.0.8
+Version: 0.0.9
 Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, and LSP.
 Author: Marco
 License: GPL-3.0-or-later

{simdref-0.0.8 → simdref-0.0.9}/tests/test_lsp_stdio.py

@@ -79,14 +79,14 @@ def _read_msg(proc, timeout_s=10):
 
 
 class _Server:
-    def __init__(self, catalog):
+    def __init__(self, catalog, extra_env=None):
         self.proc = subprocess.Popen(
             [sys.executable, "-m", "simdref.lsp"],
             stdin=subprocess.PIPE,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             bufsize=0,
-            env={**os.environ, "SIMDREF_CATALOG": str(catalog)},
+            env={**os.environ, "SIMDREF_CATALOG": str(catalog), **(extra_env or {})},
         )
         self.next_id = 0
         self.notifications = []
@@ -198,6 +198,49 @@ class LspEndToEndTests(unittest.TestCase):
         self.assertIsNotNone(result, "hover on vfmadd231ps returned null")
         self.assertIn("VFMADD231PS", result["contents"]["value"])
 
+    def test_hover_instruction_full_page_operand_matched(self):
+        self.server.open(ASM_URI, "asm", ASM_TEXT)
+        result = self.server.hover(ASM_URI, 5, 6)
+        self.assertIsNotNone(result, "hover on vaddps returned null")
+        value = result["contents"]["value"]
+        # The 3-operand YMM form, not the first masked (XMM, K, ...) row.
+        self.assertIn("VADDPS (YMM, YMM, YMM)", value)
+        self.assertNotIn("VADDPS (XMM, K, XMM, M128)", value)
+        self.assertIn("## Description", value)
+        self.assertIn("Add Packed Single Precision Floating-Point Values", value)
+        self.assertIn("## SIMD Floating-Point Exceptions", value)
+        self.assertIn("## instruction to intrinsic mapping", value)
+        self.assertIn("_mm256_add_ps", value)
+        # The per-uarch perf table as a Markdown table.
+        self.assertIn("| microarch |", value)
+        self.assertIn("| ZEN5 |", value)
+        # Links at the end: web deep link, uops.info, felixcloutier.
+        self.assertIn("https://simdref.diamondinoia.com/#VADDPS%20(YMM%2C%20YMM%2C%20YMM)", value)
+        self.assertIn("https://www.uops.info/html-instr/VADDPS_YMM_YMM_YMM.html", value)
+        self.assertIn("https://www.felixcloutier.com/x86/addps", value)
+
+    def test_hover_makes_no_network_call(self):
+        # The server is a subprocess, so block sockets there via sitecustomize.
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as sitepkg:
+            Path(sitepkg, "sitecustomize.py").write_text(
+                "import socket\n"
+                "def _blocked(*a, **k): raise OSError('network blocked in test')\n"
+                "socket.socket = _blocked\n"
+                "socket.create_connection = _blocked\n"
+            )
+            server = _Server(
+                CATALOG,
+                {"PYTHONPATH": sitepkg + os.pathsep + os.environ.get("PYTHONPATH", "")},
+            )
+            self.addCleanup(server.stop)
+            server.start()
+            server.open(ASM_URI, "asm", ASM_TEXT)
+            result = server.hover(ASM_URI, 5, 6)
+        self.assertIsNotNone(result)
+        self.assertIn("VADDPS (YMM, YMM, YMM)", result["contents"]["value"])
+
     def test_cpp_two_instructions_on_one_source_line_get_one_joined_hint(self):
         text = 'asm volatile("vaddps %ymm1, %ymm2, %ymm0\\n\\tvmulps %ymm0, %ymm0, %ymm3");\n'
         self.server.open(CPP_URI, "cpp", text)
@@ -240,6 +283,25 @@ class LspEndToEndTests(unittest.TestCase):
             [h["label"] for h in hints],
             ["Add Packed Single Precision Floating-Point Values."],
         )
+        # "adc eax, ebx ; j, k" parses as 4 operands in a .s file even when the client
+        # sends languageId "nasm": the 4-operand form label differs from the 2-operand one.
+        self.server.open(uri, "nasm", "adc eax, ebx ; j, k\n")
+        self.assertEqual(self.server.hints(uri)[0]["label"], "Adc instruction.")
+
+    def test_asm_semicolon_comment_in_dot_nasm_file(self):
+        uri = "file:///tmp/simdref_lsp_test.nasm"
+        self.server.open(uri, "asm", "adc eax, ebx ; j, k\n")
+        hints = self.server.hints(uri)
+        self.assertEqual([h["position"]["line"] for h in hints], [0])
+        # With ";" a comment the line is the 2-operand form, not the 4-operand parse.
+        self.assertEqual(hints[0]["label"], "Add With Carry.")
+
+    def test_asm_semicolon_comment_from_language_id_masm(self):
+        uri = "file:///tmp/simdref_lsp_test.txt"
+        self.server.open(uri, "masm", "adc eax, ebx ; j, k\n")
+        hints = self.server.hints(uri)
+        self.assertEqual([h["position"]["line"] for h in hints], [0])
+        self.assertEqual(hints[0]["label"], "Add With Carry.")
 
     def test_hint_avx512_mask_and_broadcast_operands(self):
         uri = "file:///tmp/simdref_lsp_test_zmm.s"

{simdref-0.0.8 → simdref-0.0.9}/tests/test_lsp_web.py

@@ -36,7 +36,7 @@ class LspWebTests(unittest.TestCase):
         markdown = _hover_markdown(self._conn, "vadd.vv")
         self.assertIsNotNone(markdown)
         self.assertIn("vadd.vv", markdown)
-        self.assertIn("ISA V", markdown)
+        self.assertIn("**isa.** V", markdown)
 
     def test_sqlite_runtime_preserves_riscv_counts_sections_and_policy_metadata(self):
         intrinsic_count = self._conn.execute(