Prepare veralang distribution for PyPI publication

[aallan]

Summary

• rename the Python distribution from vera to veralang while preserving the vera command and vera import package
• update self-referencing extras and the lockfile to use veralang[lsp] / veralang[dev]
• document both pip install veralang and the existing GitHub editable-install route across the README, language reference, LSP guide, PyPI README, and generated site assets
• build and inspect the wheel and sdist in CI, then smoke-test the installed wheel outside the checkout

Why

The vera distribution name on PyPI belongs to an unrelated project. This establishes veralang as Vera's registry identity without changing the user-facing CLI or Python module names.

User and developer impact

Released installs will use python -m pip install veralang and continue to run the vera command. GitHub source installs remain supported. Existing editable development environments should be refreshed after the metadata rename, for example with python -m pip install -e ".[dev]".

Scope

This is PR 1 of the publication plan in #737. It validates publication-ready artifacts but does not upload them. Trusted Publishing, TestPyPI/PyPI release automation, approval gates, and release-trigger policy remain follow-up work under #481.

Validation

• 7315 passed, 70 skipped
• Ruff and mypy
• uv lock --check
• version, licence, changelog, documentation, and generated-site checks
• python -m build
• twine check dist/*
• distribution archive content validation
• installed-wheel vera version, vera check, and vera run smoke tests outside the checkout

Summary by CodeRabbit

• New Features

  • Added support for installing Vera from PyPI as the veralang package.
  • Retained the vera command-line tool and vera Python import name.
  • Added installation guidance for the optional language-server integration.

• Documentation

  • Updated installation instructions across project documentation.
  • Added a dedicated PyPI package README with setup and usage examples.

• Quality Improvements

  • Added automated checks for distribution contents and installed-package CLI behaviour.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 14 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6887773a-fc1e-4cfa-a27b-542047721e1f

📥 Commits

Reviewing files that changed from the base of the PR and between 69d2835 and fd7407b.

⛔ Files ignored due to path filters (2)

• docs/SKILL.md is excluded by !docs/**
• docs/llms-full.txt is excluded by !docs/**

📒 Files selected for processing (1)

• SKILL.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/veralang-publication-readiness

---

_{Comment @coderabbitai help to get the list of available commands.}

[aallan]

One-time local environment migration after merge

This PR does not rename the CLI or import package: the command remains vera and Python imports remain import vera.

However, pip treats the old vera distribution metadata and the new veralang distribution metadata as different installed projects. An existing editable development environment should therefore be refreshed once after this change lands; merely installing the new name can leave stale vera metadata behind.

For an existing pip-managed development venv:

python -m pip uninstall -y vera veralang
python -m pip install -e ".[dev]"

This temporarily removes and then recreates the same vera command. Recreating .venv from scratch is the cleanest alternative, but it is optional rather than required.

For a uv-managed environment:

uv sync --extra dev

This is a one-time development-environment cleanup caused by the distribution rename; normal Vera CLI usage is otherwise unchanged.

[greptile-apps]

Greptile Summary

This PR renames the Python distribution from vera to veralang for PyPI publication while keeping the vera CLI command and vera import namespace unchanged. It adds a dedicated PyPI README, a new package-distribution CI job that builds and smoke-tests the wheel outside the checkout, and a check_distribution.py validation script that asserts archive contents match expected structure.

• pyproject.toml / uv.lock: name changed to veralang; self-referencing extras (veralang[lsp], veralang[dev]) and the lockfile updated consistently.
• scripts/check_distribution.py: New script validates wheel and sdist contents (required files, no test/ leakage, no bytecode, correct entry point, correct METADATA name/version).
• CI package-distribution job: Builds with python -m build, validates with twine check and check_distribution.py, then installs the wheel into a fresh venv outside the checkout and runs vera version, vera check, and vera run hello_world.vera with output assertion.

Confidence Score: 5/5

Safe to merge. The rename is mechanical and consistent across all affected files; the user-facing CLI name and Python import name are unchanged.

All changes are naming/metadata updates and additive CI/tooling work. The dist rename from vera to veralang is applied uniformly across pyproject.toml, uv.lock, self-referencing extras, and all documentation. The new CI job and check_distribution.py are well-structured and do not touch production code paths.

No files require special attention.

Important Files Changed

Filename	Overview
.github/workflows/ci.yml	Adds package-distribution job: builds wheel/sdist, runs twine check, validates archive contents, and smoke-tests the installed wheel outside the checkout.
scripts/check_distribution.py	New validation script for wheel/sdist contents. Wheel filename is hardcoded as {name}-{version}-py3-none-any.whl, correct for pure-Python but fragile if a compiled extension is ever added.
pyproject.toml	Renames distribution from vera to veralang, updates self-referencing extras, adds Python 3.13 classifier, and switches readme to PYPI_README.md.
PYPI_README.md	New PyPI landing page with correct install instructions and veralang/vera name-split explanation.
uv.lock	Lockfile updated to reflect the veralang package rename; self-referencing extras also updated.
scripts/check_licenses.py	Updates _SELF_PACKAGES from 'vera' to 'veralang' so the project itself is correctly excluded from license checks.
scripts/check_version_sync.py	Updates regex to match [[package]] name = "veralang" in uv.lock; comments and error messages updated accordingly.

_{Reviews (3): Last reviewed commit: "docs: PyPI verification must not depend ..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

SKILL.md (1)

29-34: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not use repository examples after a PyPI-only install.

After the PyPI route, examples/hello_world.vera is not available unless the user is already in a source checkout, so this verification command cannot test the installed package as claimed. Use vera version or a temporary self-contained .vera file for the PyPI path, and keep repository-relative examples under the source-install instructions.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@SKILL.md` around lines 29 - 34, Separate verification by installation route
in SKILL.md: keep examples/hello_world.vera checks only under the source
checkout installation instructions, and for the PyPI-only path verify with vera
version or a temporary self-contained .vera file. Ensure the PyPI verification
does not depend on repository files.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Line 267: Pin the actions/checkout and actions/setup-python uses in this
workflow, including the occurrences around the referenced lines and the existing
wheel-preflight job, to verified immutable commit SHAs for their intended
versions. Replace mutable tag references only and preserve each action’s current
version and configuration.
- Around line 285-294: Strengthen the installed-wheel smoke test in the “Install
and smoke-test the wheel outside the checkout” step by capturing the stdout from
“vera run hello_world.vera” and asserting it contains the expected hello-world
output. Preserve the existing version and check commands while ensuring a
successful exit alone is insufficient.

In `@README.md`:
- Around line 126-129: Add an explicit compatibility statement to the
installation guidance in README.md lines 126-129 and PYPI_README.md lines 30-32:
after installing the veralang distribution, users should continue importing the
Python package as vera, while preserving the existing vera executable guidance.
- Around line 120-124: Make every virtual-environment installation block usable
on Windows by adding a PowerShell and/or Command Prompt activation alternative
alongside the existing POSIX command. Apply the same update to README.md ranges
120-124 and 134-140, LSP_SERVER.md ranges 30-33 and 37-41, and SKILL.md ranges
14-17 and 23-27; update scripts/build_site.py range 611-615 so the generated
landing page emits the Windows alternative as well.

In `@scripts/build_site.py`:
- Around line 89-90: Update the generated editable-install command in the
source-install template within the build-site generation flow to use the
canonical development command, python -m pip install -e ".[dev]". Keep the
existing PyPI installation guidance unchanged.

---

Outside diff comments:
In `@SKILL.md`:
- Around line 29-34: Separate verification by installation route in SKILL.md:
keep examples/hello_world.vera checks only under the source checkout
installation instructions, and for the PyPI-only path verify with vera version
or a temporary self-contained .vera file. Ensure the PyPI verification does not
depend on repository files.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 260f55c0-2c9f-418f-bf46-70aec581f5de

📥 Commits

Reviewing files that changed from the base of the PR and between bce2701 and 53e156a.

⛔ Files ignored due to path filters (5)

• docs/SKILL.md is excluded by !docs/**
• docs/index.md is excluded by !docs/**
• docs/llms-full.txt is excluded by !docs/**
• docs/llms.txt is excluded by !docs/**
• uv.lock is excluded by !**/*.lock, !uv.lock

📒 Files selected for processing (11)

• .github/workflows/ci.yml
• CHANGELOG.md
• LSP_SERVER.md
• PYPI_README.md
• README.md
• SKILL.md
• pyproject.toml
• scripts/build_site.py
• scripts/check_distribution.py
• scripts/check_licenses.py
• scripts/check_version_sync.py

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• aallan/vera-bench (manual)

[aallan]

@coderabbitai Good catch on the outside-diff finding — fixed in fd7407b. SKILL.md's post-install verification is now split by route: vera version verifies either route with no checkout, and the examples/hello_world.vera check is kept under the source-checkout path — so the PyPI install path no longer depends on a repository file.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
git log --oneline -5
git show fd7407b --stat
sed -n '1,80p' SKILL.md

Length of output: 6364

---

@aallan Confirmed — commit fd7407b correctly resolves this. vera version now stands alone as the no-checkout verification step for either install route, and the examples/hello_world.vera check/run commands are scoped under the source-checkout section only. Verified the same split was applied consistently across SKILL.md, docs/SKILL.md, and docs/llms-full.txt, so the generated site assets stay in sync. Good fix.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.51%. Comparing base (bce2701) to head (fd7407b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1027   +/-   ##
=======================================
  Coverage   93.51%   93.51%           
=======================================
  Files          96       96           
  Lines       32024    32024           
  Branches      456      456           
=======================================
  Hits        29948    29948           
  Misses       2063     2063           
  Partials       13       13           

Flag	Coverage Δ
javascript	78.41% <ø> (ø)
python	95.29% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.