stata-code 0.12.2__tar.gz → 0.14.0__tar.gz

{stata_code-0.12.2 → stata_code-0.14.0}/CHANGELOG.md

@@ -6,6 +6,141 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ## [Unreleased]
 
+## 0.14.0 — 2026-10-03
+
+The `.dta` viewer added in 0.13 could only be scrolled. It can now be queried:
+filter with a Stata `if` expression, sort, summarize a variable, copy a range,
+and export the view or the codebook. No changes to the Python package or the
+result schema beyond the version number.
+
+### Added
+
+- **VS Code data viewer: filter rows with a Stata `if` expression.** The bar
+  under the title accepts expressions such as `age > 60 & !missing(income)`,
+  `region == "South":regionlbl` or `inlist(city, "Boston", "北京")`. The
+  evaluator follows Stata's semantics rather than JavaScript's — missing
+  values sort above every number, arithmetic on a missing value is missing,
+  any nonzero value (missing included) is true, and a string compared with a
+  number is a `type mismatch` — and is tested against Stata 18's own
+  `count if` on 48 expressions. It covers the operators
+  `! ~ ^ - * / + == != ~= < <= > >= & |`, `_n` / `_N`, `"text":labelname`,
+  and about 30 functions (`missing`, `inlist`, `inrange`, `strpos`, `regexm`,
+  `strmatch`, `substr`, `round`, `mod`, `mdy`, `td()`, …). Variable
+  abbreviations, time-series operators and macros are not supported.
+- **VS Code data viewer: sort by any column.** Click the arrow in a column
+  header (ascending, descending, off); Shift-click adds further keys. Order
+  matches Stata's `sort` / `gsort`: underlying values rather than label text,
+  missing values last, ties in dataset order. The gutter keeps showing each
+  row's observation number in the file.
+- **VS Code data viewer: per-variable summary.** Selecting a variable shows
+  count, missing, distinct, mean, standard deviation, min, quartiles and max
+  over the rows in view — equal to `summarize, detail` to 12 significant
+  digits on the test dataset — and, for categorical variables, the most
+  frequent values. Clicking a value filters to it. Order statistics of a date
+  variable print as dates.
+- **VS Code data viewer: range selection and copy.** Drag, Shift-click or
+  Shift-arrow selects a rectangle; `Cmd/Ctrl+C` copies it as tab-separated
+  text, `Cmd/Ctrl+Shift+C` with variable names, `Cmd/Ctrl+A` selects the view.
+- **VS Code data viewer: export.** *Export view as CSV* writes the filtered,
+  sorted view with numbers at full precision (not display precision), dates as
+  dates, and value labels as text when the toggle is on. *Export codebook*
+  writes one row per variable (type, format, value label, variable label,
+  notes) and a second file with every value-label mapping — the metadata a CSV
+  cannot carry.
+- **VS Code: `Stata: Load Data File in Session (use, clear)`.** On the
+  Explorer context menu of `.dta` files and in the viewer's menu. Asks before
+  discarding unsaved changes in the session.
+- **VS Code data viewer: resizable columns.** Drag a header's right edge;
+  double-click to fit. Widths survive a reload of the same dataset.
+
+Filtering, sorting and summaries scan the whole column and are limited to
+20 million observations; browsing has no such limit.
+
+## 0.13.0 — 2026-10-03
+
+A data viewer for `.dta` files. Opening a dataset in VS Code used to mean
+either launching Stata or converting to CSV and losing the variable labels,
+value labels, formats and notes on the way. The extension now reads `.dta`
+directly and shows all of it.
+
+### Added
+
+- **VS Code: a Stata-free `.dta` data viewer.** Double-click any `.dta` file
+  and it opens in a read-only grid, registered as the default editor for
+  `*.dta`. The file is parsed in the extension itself, from StataCorp's
+  published format documentation, so it needs neither Stata, Python, nor the
+  MCP server. What the viewer keeps that a CSV round trip drops:
+  - variable labels (under each column name and in the variables panel);
+  - value labels, shown in place of their codes, with a *Value labels* toggle
+    to see the underlying numbers;
+  - display formats — `%td` / `%tc` / `%tm` / `%tq` / `%th` / `%tw` / `%ty`
+    dates including custom detail codes (`%tdCCYY-NN-DD`), `%w.df`, `%w.de`,
+    `%w.dg`, comma variants — printed as Stata prints them;
+  - the 27 missing values as `.`, `.a` … `.z`, including value labels attached
+    to extended missing values;
+  - dataset and variable notes, the dataset label, sort order and timestamp;
+  - `strL` variables and non-ASCII text.
+
+  Observations are fixed-width records, so the viewer reads only the rows on
+  screen; a 3-million-row file opens and jumps to its last row as fast as a
+  5-row one. A variables panel filters by name or label and jumps to a column;
+  *Go to row*, arrow / Page / Home / End keys and `Cmd/Ctrl+C` work as
+  expected; the viewer reloads when Stata re-saves the file.
+
+  Formats covered: 113–115 (Stata 8–12), 117 (Stata 13), 118 / 119
+  (Stata 14+), 120 / 121 (Stata 18 alias variables), in either byte order.
+  The parser is tested against fixtures written by a real Stata, and its
+  formatted cells are asserted equal to Stata's own `list` output.
+- **VS Code: `stataCode.dtaLegacyEncoding` setting** (default `auto`) for
+  `.dta` formats older than 118, which predate UTF-8. `auto` tries UTF-8,
+  then GB18030, then Windows-1252.
+- **`dataset.variables[*].format` and `.value_label`.** Each variable now
+  reports its display format when that differs from the storage type's
+  default, and the name of its value label when one is attached — so a
+  consumer can tell that an integer is a `%td` date or that `foreign` is
+  labelled by `origin` without running `describe`. Both keys are *omitted*
+  (not `null`) when they have nothing to say, so the common variable costs no
+  extra tokens. Additive; `schema_version` stays `1.0`. Reported by both the
+  pystata and the console backend.
+- **VS Code: the Data sidebar shows those two fields** next to each variable
+  (`long %td · Sale date`, `byte · [origin] · Car origin`).
+
+### Changed
+
+- **VS Code: "View data preview" opens the data viewer instead of a text
+  listing.** The first `stataCode.dataPreviewObs` observations in memory are
+  copied through a scratch frame into a temporary `.dta` and shown in the same
+  grid as a file on disk, so in-memory data gets labels, formats and notes
+  too. The user's frame is not touched — not its data, sort order,
+  `c(filename)`, `c(changed)`, nor `r()` — and the temporary file is deleted
+  when the panel closes. One panel per session; previewing again refreshes it.
+  On Stata 15 or older (no frames) and with the console backend the command
+  falls back to the text listing below.
+- **VS Code: `stataCode.dataPreviewObs` now defaults to `1000`** (was `50`)
+  and accepts up to `100000` (was `10000`): the grid scrolls, a text document
+  does not. The text fallback is capped at 200 rows regardless.
+- **VS Code: the fallback text listing is shorter and no longer line-wrapped.**
+  `list` is run with a widened `linesize` (restored afterwards) so wide
+  datasets stop folding into `>` continuation lines; the command echo is
+  stripped from the body; the header collapses to a session line plus a
+  `74 obs x 12 vars - showing all 74` summary and the dataset path; and the
+  variable list is column-aligned instead of tab-separated.
+- **VS Code: utility runs (data preview, `pwd`, `cd`) no longer hijack the
+  Output panel.** They used to force it visible and echo their whole log into
+  it. They now log one status line on success and only surface the panel on
+  failure.
+
+### Fixed
+
+- **VS Code: "View data preview" failed on every dataset with fewer than 100
+  observations.** The preview listed rows with `list in 1/100`, and an `in`
+  range whose upper bound exceeds `_N` is an error in Stata, so the command
+  returned `r(198) observation numbers out of range` for `auto.dta` (74 obs)
+  and most other teaching datasets — while the document header still claimed
+  `showing: 0 of 74 observations`. The preview now selects rows with
+  `if _n <= N`, which lists whatever is there (including nothing at all), and
+  a failed preview reports its `rc` and message instead of a row count.
+
 ## 0.12.2 — 2026-08-11
 
 Correctness release. `results.estimation` could report confidence intervals

{stata_code-0.12.2 → stata_code-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: stata-code
-Version: 0.12.2
+Version: 0.14.0
 Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
 Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
 Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
@@ -527,7 +527,7 @@ Then open Jupyter Notebook / JupyterLab (or a `.ipynb` in VS Code), pick **Stata
 
 ### As a VS Code Extension
 
-The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a **seven-view sidebar** (sessions / last result / **data variables** / run history / logs / graphs / **outputs**) — including an agent-native equivalent of Stata's **Variables window** and an **Outputs** panel that surfaces the `esttab` tables and `export` files each run writes to disk — status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
+The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a **seven-view sidebar** (sessions / last result / **data variables** / run history / logs / graphs / **outputs**) — including an agent-native equivalent of Stata's **Variables window** and an **Outputs** panel that surfaces the `esttab` tables and `export` files each run writes to disk — status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors. It also registers a **Stata-free `.dta` data viewer**: double-click any `.dta` file to browse it in a grid with its variable labels, value labels, display formats, notes and missing-value codes intact, reading only the rows on screen so multi-gigabyte files open instantly.
 
 ```bash
 # from the VS Code CLI

{stata_code-0.12.2 → stata_code-0.14.0}/README.en.md

@@ -488,7 +488,7 @@ Then open Jupyter Notebook / JupyterLab (or a `.ipynb` in VS Code), pick **Stata
 
 ### As a VS Code Extension
 
-The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a **seven-view sidebar** (sessions / last result / **data variables** / run history / logs / graphs / **outputs**) — including an agent-native equivalent of Stata's **Variables window** and an **Outputs** panel that surfaces the `esttab` tables and `export` files each run writes to disk — status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
+The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a **seven-view sidebar** (sessions / last result / **data variables** / run history / logs / graphs / **outputs**) — including an agent-native equivalent of Stata's **Variables window** and an **Outputs** panel that surfaces the `esttab` tables and `export` files each run writes to disk — status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors. It also registers a **Stata-free `.dta` data viewer**: double-click any `.dta` file to browse it in a grid with its variable labels, value labels, display formats, notes and missing-value codes intact, reading only the rows on screen so multi-gigabyte files open instantly.
 
 ```bash
 # from the VS Code CLI

{stata_code-0.12.2 → stata_code-0.14.0}/README.md

@@ -456,7 +456,7 @@ jupyter kernelspec list
 
 ### 作为 VS Code 扩展
 
-配套扩展已发布到 Marketplace：[`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode)。它会以子进程方式启动 `stata-code-mcp`，并提供语法高亮、`**#` section 和 `program define` 的 Outline、`.do` 文件的 code-lens "Run cell" / "Run section"、**七视图侧边栏**（sessions / last result / **data 变量浏览器** / run history / logs / graphs / **outputs**）——其中包含一个 agent-native 版的 Stata **变量窗口**，以及一个把每次运行写到磁盘的 `esttab` 表格和 `export` 文件呈现出来的 **Outputs** 面板——状态栏指示器、补全、帮助跳转、保守变量重命名，以及来自 v1.0 typed errors 的内联诊断。
+配套扩展已发布到 Marketplace：[`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode)。它会以子进程方式启动 `stata-code-mcp`，并提供语法高亮、`**#` section 和 `program define` 的 Outline、`.do` 文件的 code-lens "Run cell" / "Run section"、**七视图侧边栏**（sessions / last result / **data 变量浏览器** / run history / logs / graphs / **outputs**）——其中包含一个 agent-native 版的 Stata **变量窗口**，以及一个把每次运行写到磁盘的 `esttab` 表格和 `export` 文件呈现出来的 **Outputs** 面板——状态栏指示器、补全、帮助跳转、保守变量重命名，以及来自 v1.0 typed errors 的内联诊断。扩展还注册了一个**不依赖 Stata 的 `.dta` 数据浏览器**：双击任意 `.dta` 文件即可在表格中浏览，变量标签、值标签、显示格式、notes 和缺失值代码全部保留；只读取屏幕上可见的行，几个 GB 的文件也能瞬间打开。
 
 ```bash
 # 从 VS Code 命令行

{stata_code-0.12.2 → stata_code-0.14.0}/SCHEMA.md

@@ -425,9 +425,19 @@ A summary of the active Stata frame *after* the command ran. Always populated.
 
 ```json
 { "name": "mpg", "type": "int", "label": "Mileage (mpg)" }
+{ "name": "foreign", "type": "byte", "label": "Car origin", "value_label": "origin" }
+{ "name": "saledate", "type": "long", "label": "Sale date", "format": "%td" }
 ```
 
-`type` is Stata's storage type (`byte`, `int`, `long`, `float`, `double`, `str#`, `strL`). `label` is the variable label string, or `""` if none.
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | `string` | Variable name. |
+| `type` | `string` | Stata's storage type (`byte`, `int`, `long`, `float`, `double`, `str#`, `strL`). |
+| `label` | `string` | The variable label, or `""` if none. |
+| `format` | `string`, optional | The display format, **only when it differs from the storage type's default** (`%8.0g` for `byte`/`int`, `%12.0g` for `long`, `%9.0g` for `float`, `%10.0g` for `double`, `%{max(9,#)}s` for `str#`, `%9s` for `strL`). Absent means "the default". This is how a consumer learns that an integer is a date (`%td`, `%tc`, `%tm`, …). |
+| `value_label` | `string`, optional | Name of the value label attached to the variable. Absent when none is attached. The mapping itself is not shipped; run `label list <name>`. |
+
+`format` and `value_label` are **omitted, not `null`**, when they have nothing to say: the variable list rides along on every run, so a null on most variables would cost tokens to carry no information. Added in 0.13 (additive; `schema_version` stays `"1.0"`). Consumers must treat a missing key and `null` alike.
 
 When `n_vars` is large (default cap: 200), the producer truncates `variables` to the first 200 entries and emits a warning of kind `dataset_variables_truncated`. Agents wanting all variables should call `describe` directly.
 

{stata_code-0.12.2 → stata_code-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stata-code"
-version = "0.12.2"
+version = "0.14.0"
 description = "Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)"
 # The repo default README (README.md) is Chinese; keep the PyPI long description
 # English by pointing at README.en.md.

{stata_code-0.12.2 → stata_code-0.14.0}/schema/run_result.schema.json

@@ -1145,6 +1145,18 @@
     "VariableInfo": {
       "additionalProperties": true,
       "properties": {
+        "format": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Format"
+        },
         "label": {
           "default": "",
           "title": "Label",
@@ -1157,6 +1169,18 @@
         "type": {
           "title": "Type",
           "type": "string"
+        },
+        "value_label": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Value Label"
         }
       },
       "required": [

{stata_code-0.12.2 → stata_code-0.14.0}/stata_code/__init__.py

@@ -260,7 +260,7 @@ def is_available() -> bool:
     return True
 
 
-__version__ = "0.12.2"
+__version__ = "0.14.0"
 
 __all__ = [
     # Primary entry points

{stata_code-0.12.2 → stata_code-0.14.0}/stata_code/core/console.py

@@ -57,6 +57,7 @@ from stata_code.core.schema import (
     StataInfo,
     StataReturns,
     VariableInfo,
+    default_display_format,
 )
 
 
@@ -217,6 +218,7 @@ MARK_SECTION = f"{_M}|SECTION|"
 MARK_MATRIX = f"{_M}|MATRIX|"
 MARK_DS = f"{_M}|DS|"
 MARK_VAR = f"{_M}|VAR|"
+MARK_VARFMT = f"{_M}|VARFMT|"
 MARK_BEGIN = f"{_M}|BEGIN"
 MARK_END = f"{_M}|END"
 
@@ -274,6 +276,9 @@ def build_wrapper_do(code: str, *, working_dir: str | None = None) -> str:
         # Stata: display "<MARK>`__v'|`: type `__v''|`: variable label `__v''"
         # Built by concatenation to avoid f-string quote/backtick collisions.
         "        display \"" + MARK_VAR + "`__v'|`: type `__v''|`: variable label `__v''\"",
+        # A second line rather than two more fields on the first: a variable
+        # label may itself contain "|", so it has to stay the last field.
+        "        display \"" + MARK_VARFMT + "`__v'|`: format `__v''|`: value label `__v''\"",
         "    }",
         "}",
         f'display "{MARK_END}"',
@@ -298,6 +303,7 @@ _SCALAR_RE = re.compile(r"^\s*[re]\(([A-Za-z_][A-Za-z0-9_]*)\)\s*=\s*(.+?)\s*$")
 _MACRO_RE = re.compile(r'^\s*[re]\(([A-Za-z_][A-Za-z0-9_]*)\)\s*:\s*"?(.*?)"?\s*$')
 _DS_RE = re.compile(r"^\s*" + re.escape(MARK_DS) + r"(\w+)\|(.*)$")
 _VAR_RE = re.compile(r"^\s*" + re.escape(MARK_VAR) + r"(.+?)\|(.*?)\|(.*)$")
+_VARFMT_RE = re.compile(r"^\s*" + re.escape(MARK_VARFMT) + r"(.+?)\|(.*?)\|(.*)$")
 # `matrix list` dimension header:  e(b)[1,2]  or  symmetric e(V)[2,2]
 _MATRIX_HEADER_RE = re.compile(r"^\s*(symmetric\s+)?[A-Za-z_][A-Za-z0-9_]*\([^)]*\)\[\d+,\d+\]")
 
@@ -536,6 +542,16 @@ def _parse_dataset(block: str) -> DatasetInfo:
                     label=v.group(3).strip(),
                 )
             )
+            continue
+        x = _VARFMT_RE.search(raw)
+        if x and variables and variables[-1].name == x.group(1).strip():
+            # Same contract as the pystata backend: report a format only when
+            # it is not the storage type's default, a value label only when set.
+            var = variables[-1]
+            fmt = x.group(2).strip()
+            if fmt and fmt != default_display_format(var.type):
+                var.format = fmt
+            var.value_label = x.group(3).strip() or None
     return DatasetInfo(
         frame="default",
         n_obs=n_obs,

{stata_code-0.12.2 → stata_code-0.14.0}/stata_code/core/runner.py

@@ -75,6 +75,7 @@ from stata_code.core.schema import (
     StataReturns,
     StataWarning,
     VariableInfo,
+    default_display_format,
 )
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -685,6 +686,34 @@ def _cap_macro(value: str) -> str:
     return f"{value[:MACRO_INLINE_CHAR_CAP]}… ({dropped} more chars elided)"
 
 
+def _variable_info(sfi: Any, index: int) -> VariableInfo:
+    """Describe variable ``index``: name, storage type, label, and — only when
+    they carry information — its display format and attached value label."""
+    Data = sfi.Data
+    storage_type = Data.getVarType(index)
+    fmt: str | None = None
+    value_label: str | None = None
+    # Both lookups are best-effort: an sfi build without them must not cost
+    # the caller the variable list.
+    try:
+        raw = Data.getVarFormat(index) or ""
+        if raw and raw != default_display_format(storage_type):
+            fmt = raw
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        value_label = sfi.ValueLabel.getVarValueLabel(index) or None
+    except Exception:  # noqa: BLE001
+        pass
+    return VariableInfo(
+        name=Data.getVarName(index),
+        type=storage_type,
+        label=Data.getVarLabel(index) or "",
+        format=fmt,
+        value_label=value_label,
+    )
+
+
 def _collect_dataset(rt: Any, include_variables: bool) -> DatasetInfo:
     sfi = rt.sfi
     Data = sfi.Data
@@ -716,14 +745,7 @@ def _collect_dataset(rt: Any, include_variables: bool) -> DatasetInfo:
     variables: list[VariableInfo] | None
     if include_variables and n_vars > 0:
         cap = min(n_vars, _DATASET_VAR_CAP)
-        variables = [
-            VariableInfo(
-                name=Data.getVarName(i),
-                type=Data.getVarType(i),
-                label=Data.getVarLabel(i) or "",
-            )
-            for i in range(cap)
-        ]
+        variables = [_variable_info(sfi, i) for i in range(cap)]
     else:
         variables = None
 

{stata_code-0.12.2 → stata_code-0.14.0}/stata_code/core/schema.py

@@ -6,7 +6,15 @@ import re
 from enum import Enum
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    SerializerFunctionWrapHandler,
+    field_validator,
+    model_serializer,
+    model_validator,
+)
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Enums (closed at v1.0; new values are minor-version additive)
@@ -247,10 +255,49 @@ class ResultsInfo(_Base):
     estimation: EstimationResult | None = None
 
 
+def default_display_format(storage_type: str) -> str | None:
+    """The display format Stata assigns a new variable of ``storage_type``.
+
+    ``None`` for a type with no fixed default (an alias variable, or a string
+    the caller did not recognise).
+    """
+    numeric = {
+        "byte": "%8.0g",
+        "int": "%8.0g",
+        "long": "%12.0g",
+        "float": "%9.0g",
+        "double": "%10.0g",
+    }
+    if storage_type in numeric:
+        return numeric[storage_type]
+    if storage_type == "strL":
+        return "%9s"
+    m = re.fullmatch(r"str(\d+)", storage_type)
+    if m:
+        return f"%{max(9, int(m.group(1)))}s"
+    return None
+
+
 class VariableInfo(_Base):
     name: str
     type: str  # Stata storage type: byte/int/long/float/double/str#/strL
     label: str = ""
+    # Both are omitted from the wire when ``None`` (see ``_drop_unset``): the
+    # variable list rides along on every run, so a field that is null for most
+    # variables would cost tokens to say nothing.
+    format: str | None = None
+    """Display format, only when it differs from the storage type's default
+    (so ``%td`` / ``%tc`` / ``%9.2f`` appear, ``%9.0g`` on a float does not)."""
+    value_label: str | None = None
+    """Name of the attached value label, only when one is attached."""
+
+    @model_serializer(mode="wrap")
+    def _drop_unset(self, handler: SerializerFunctionWrapHandler) -> dict[str, object]:
+        data: dict[str, object] = handler(self)
+        for key in ("format", "value_label"):
+            if data.get(key) is None:
+                data.pop(key, None)
+        return data
 
 
 class DatasetInfo(_Base):

{stata_code-0.12.2 → stata_code-0.14.0}/stata_code/mcp/server.py

@@ -102,7 +102,7 @@ from stata_code.core.runner import (
 )
 from stata_code.core.schema import RunResult
 
-__version__ = "0.12.2"
+__version__ = "0.14.0"
 
 SERVER_INSTRUCTIONS = (
     "Use stata-code for running and inspecting Stata code. Prefer structuredContent "

{stata_code-0.12.2 → stata_code-0.14.0}/tests/test_console.py

@@ -110,6 +110,16 @@ __STATACODE__|VAR|mpg|int|Mileage (mpg)
 __STATACODE__|END
 """
 
+VARFMT_LOG = REGRESS_LOG.replace(
+    "__STATACODE__|VAR|mpg|int|Mileage (mpg)\n",
+    "__STATACODE__|VAR|mpg|int|Mileage (mpg)\n"
+    "__STATACODE__|VARFMT|mpg|%8.0g|\n"
+    "__STATACODE__|VAR|foreign|byte|Car origin\n"
+    "__STATACODE__|VARFMT|foreign|%8.0g|origin\n"
+    "__STATACODE__|VAR|day|long|Sale date | first\n"
+    "__STATACODE__|VARFMT|day|%td|\n",
+)
+
 ERROR_LOG = r"""
 . capture noisily {
 .     regress mpg wgt
@@ -233,6 +243,23 @@ class TestSuccessParse:
         assert make.type == "str18"
         assert make.label == "Make and model"
 
+    def test_variable_format_and_value_label(self):
+        r = _build(VARFMT_LOG)
+        by_name = {v.name: v for v in r.dataset.variables}
+        # A log from before the VARFMT line existed still parses.
+        assert by_name["make"].format is None and by_name["make"].value_label is None
+        # The storage type's default format is not reported.
+        assert by_name["mpg"].format is None
+        assert by_name["foreign"].value_label == "origin"
+        assert by_name["foreign"].format is None
+        assert by_name["day"].format == "%td"
+        # A "|" inside a variable label does not derail the parse.
+        assert by_name["day"].label == "Sale date | first"
+
+    def test_wrapper_asks_for_format_and_value_label(self):
+        wrapper = console.build_wrapper_do("describe")
+        assert "__STATACODE__|VARFMT|`__v'|`: format `__v''|`: value label `__v''" in wrapper
+
     def test_no_marker_leakage_in_log(self):
         r = _build(REGRESS_LOG)
         assert "__STATACODE__" not in r.log.head

{stata_code-0.12.2 → stata_code-0.14.0}/tests/test_real_stata.py

@@ -293,3 +293,37 @@ class TestHandoffReal:
         bad = verify_dataset(r.dataset, n_obs=100, required_vars=["nope"])
         assert bad.ok is False
         assert len(bad.issues) == 2
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Variable metadata: display format and value label
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TestVariableMetadataReal:
+    def test_format_and_value_label_only_when_informative(self):
+        r = _run(
+            "sysuse auto, clear\n"
+            "generate long day = 22000 + _n\n"
+            "format day %td\n"
+            "format price %9.0fc",
+            "rs_varmeta",
+        )
+        assert r.ok, r.error
+        by_name = {v.name: v for v in r.dataset.variables}
+
+        # Non-default formats are reported; they are what tells an agent that
+        # 22001 is a date and that price prints with thousands separators.
+        assert by_name["day"].format == "%td"
+        assert by_name["price"].format == "%9.0fc"
+        # auto.dta's `foreign` carries the `origin` value label.
+        assert by_name["foreign"].value_label == "origin"
+        # A storage type's default format carries no information.
+        assert by_name["trunk"].format is None
+        assert by_name["trunk"].value_label is None
+
+        wire = {v["name"]: v for v in json.loads(r.model_dump_json())["dataset"]["variables"]}
+        assert wire["day"] == {"name": "day", "type": "long", "label": "", "format": "%td"}
+        assert wire["foreign"]["value_label"] == "origin"
+        # Unset fields are absent from the wire, not null.
+        assert set(wire["trunk"]) == {"name", "type", "label"}

{stata_code-0.12.2 → stata_code-0.14.0}/tests/test_schema.py

@@ -596,3 +596,47 @@ class TestSuggestions:
 
     def test_unknown_has_no_canonical_suggestion(self):
         assert suggestions_for(ErrorKind.UNKNOWN) == []
+
+
+class TestVariableInfo:
+    def test_unset_format_and_value_label_are_absent_from_the_wire(self):
+        from stata_code.core.schema import VariableInfo
+
+        v = VariableInfo(name="mpg", type="int", label="Mileage (mpg)")
+        assert v.format is None and v.value_label is None
+        assert v.model_dump() == {"name": "mpg", "type": "int", "label": "Mileage (mpg)"}
+        assert json.loads(v.model_dump_json()) == v.model_dump()
+
+    def test_set_fields_roundtrip(self):
+        from stata_code.core.schema import VariableInfo
+
+        v = VariableInfo(name="day", type="long", format="%td", value_label="daylbl")
+        dumped = json.loads(v.model_dump_json())
+        assert dumped == {
+            "name": "day",
+            "type": "long",
+            "label": "",
+            "format": "%td",
+            "value_label": "daylbl",
+        }
+        assert VariableInfo.model_validate(dumped) == v
+
+    def test_pre_0_13_payload_still_validates(self):
+        from stata_code.core.schema import VariableInfo
+
+        v = VariableInfo.model_validate({"name": "make", "type": "str18", "label": "Make"})
+        assert v.format is None
+
+    def test_default_display_format_matches_stata(self):
+        from stata_code.core.schema import default_display_format
+
+        assert default_display_format("byte") == "%8.0g"
+        assert default_display_format("int") == "%8.0g"
+        assert default_display_format("long") == "%12.0g"
+        assert default_display_format("float") == "%9.0g"
+        assert default_display_format("double") == "%10.0g"
+        assert default_display_format("str5") == "%9s"
+        assert default_display_format("str80") == "%80s"
+        assert default_display_format("str2045") == "%2045s"
+        assert default_display_format("strL") == "%9s"
+        assert default_display_format("alias") is None