pyvbaanalysis 1.0.0__tar.gz

pyvbaanalysis-1.0.0/.gitattributes

@@ -0,0 +1,3 @@
+# Normalize line endings to LF in the repository and working tree across
+# platforms. Python and the vendored JSON data package stay LF everywhere.
+* text=auto eol=lf

pyvbaanalysis-1.0.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  # Keep the GitHub Actions pinned in the workflows current.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+
+  # Keep the Python tooling and the runtime dependency current.
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly

pyvbaanalysis-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+# Run the lint, type, and test gate on every push to main and every pull request,
+# so a regression is caught before it can reach a release.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+# A new push to the same branch or PR cancels the in-progress run.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: python -m ruff check .
+      - name: Mypy
+        run: python -m mypy pyvbaanalysis
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install -e ".[dev]"
+      - name: Pytest
+        run: python -m pytest -q

pyvbaanalysis-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+# Publishes pyvbaanalysis to PyPI when a GitHub Release is published, using PyPI
+# Trusted Publishing (OIDC), so no API tokens are stored anywhere.
+#
+# One-time setup before the first release (see CONTRIBUTING.md for the full steps):
+#   1. PyPI -> Account -> Publishing -> add a pending publisher:
+#        Project name:     pyvbaanalysis
+#        Owner:            WilliamSmithEdward
+#        Repository name:  pyVBAanalysis
+#        Workflow name:    publish.yml
+#        Environment name: pypi
+#   2. GitHub -> repo Settings -> Environments -> create an environment named `pypi`.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pyvbaanalysis
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install package + dev/build tools
+        run: python -m pip install -e ".[dev,build]"
+      - name: Test gate (pytest / ruff / mypy)
+        run: |
+          python -m pytest -q
+          python -m ruff check .
+          python -m mypy pyvbaanalysis
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyvbaanalysis-1.0.0/.gitignore

@@ -0,0 +1,36 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+.python-version
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Note: the vendored XLIDE data package under pyvbaanalysis/data/ is intentionally
+# committed (it is the version-pinned contract surface), so it is NOT ignored here.

pyvbaanalysis-1.0.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to pyVBAanalysis are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html): a minor version
+per milestone.
+
+## 1.0.0 - 2026-06-20
+
+The first public release: a pure-Python static analyzer for Excel VBA with a
+no-false-positive discipline, where a diagnostic is reported only when it is
+provably correct and anything unknown or ambiguous stays quiet.
+
+### Analysis
+
+* The complete analysis stack: lexer, parser, symbol and project index,
+  conditional compilation, type inference, the Excel host object model, the
+  member-completion surface, and the project-type registry.
+* 85 diagnostic rules emitting a catalogue of 117 diagnostic codes, validated
+  against a corpus of 397 real Excel/VBE behavior cases.
+
+### Ingestion and entry points
+
+* `analyze_module` for one module's source text, and `analyze_project` for a set
+  of modules analyzed together with cross-module context.
+* `analyze_loose_file` / `analyze_loose_files` for loose `.bas` / `.cls` / `.frm`
+  export files, and `analyze_workbook` for VBA read directly out of Excel
+  workbooks. `build_project_index` and `analyze_module_options_for` expose the
+  per-module options for a custom pass.
+* A `pyvbaanalysis.reader` package that strips the VBE export header, infers the
+  module kind, and reads modules from Excel files.
+* A command-line interface: `python -m pyvbaanalysis PATH ...` over loose files,
+  folders, and Excel workbooks, with `--only`, `--severity`, `--select` /
+  `--ignore`, `--fail-level`, `--format`, and CI-friendly exit codes.
+* The headline entry points are re-exported from the package root, and the package
+  ships a `py.typed` marker.
+
+### Packaging
+
+* MIT license and a Trusted Publishing release workflow (OIDC, no API tokens).
+* One runtime dependency, pyOpenVBA, used to read VBA out of Excel workbooks and
+  imported lazily.
+
+### Documentation
+
+* A usage guide, an API reference, a generated diagnostics catalogue, and a
+  contributing guide.

pyvbaanalysis-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing
+
+pyVBAanalysis is a faithful Python port of the
+[XLIDE](https://github.com/WilliamSmithEdward/xlide_vscode) VBA analyzer. The
+overriding rule is the no-false-positive discipline: a diagnostic ships only when
+it is provably correct. When in doubt, stay quiet.
+
+## Development setup
+
+Python 3.10 or later.
+
+```
+pip install -e ".[dev]"
+```
+
+The `dev` extra adds the test, lint, and type tools. pyOpenVBA (the one runtime
+dependency, used to read VBA out of Excel workbooks) is installed with the base
+package, so the workbook reader is exercised by the test suite.
+
+## Local checks
+
+Run all three before sending a change. They are the same gate CI enforces:
+
+```
+pytest
+ruff check .
+mypy pyvbaanalysis
+```
+
+`mypy` runs in `--strict` mode. The suite is fast (a few seconds); run it often.
+
+## The XLIDE port model
+
+This repository ports XLIDE's TypeScript analyzer. XLIDE owns the language and
+host knowledge; pyVBAanalysis reproduces its behavior in Python.
+
+* The XLIDE source is expected as a sibling checkout at `../xlide_vscode`. The
+  data-extraction tools reference it through that relative path.
+* XLIDE also owns the oracle: the Excel/VBE evidence corpus and the provenance
+  audit. pyVBAanalysis consumes the emitted evidence verbatim as both porting spec
+  and test fixtures. Do not reimplement the oracle here.
+* The vendored data lives in `pyvbaanalysis/data/` (the host object model, the
+  runtime tables, the oracle cases, the rule metadata, and a manifest with
+  checksums). It is regenerated by the `tools/extract_*.mjs` scripts (run with
+  `npx tsx`) against the sibling XLIDE checkout, never hand-edited.
+
+The build plan, parity inventory, and module-by-module port map are in
+[agent.md](agent.md).
+
+## Adding or changing a rule
+
+* Port the rule from its XLIDE source; match the behavior, not just the shape.
+* A rule ships only with oracle backing. Validate it against the vendored corpus
+  and add direct tests for the positive and the no-false-positive control cases.
+* The diagnostic rule registry order is a contract: it is the diagnostic
+  output order, and it must remain a faithful subsequence of XLIDE's `registry.ts`.
+  Place a new entry at its XLIDE position; do not reorder existing entries.
+* Diagnostic codes and their metadata (default severity, category, evidence basis,
+  spec reference) live in the rule metadata. Regenerate the catalogue after a
+  metadata change:
+
+  ```
+  python tools/generate_diagnostics_catalogue.py
+  ```
+
+## Style
+
+* Write plain ASCII. No em dashes or other non-ASCII in code, comments,
+  docstrings, or commit messages; use a comma, colon, period, or parentheses.
+  Test fixtures that deliberately exercise Unicode are the only exception.
+* Avoid AI tells and marketing language. Prefer clear, direct prose.
+* Keep changes small and focused, with names and structure that match the
+  surrounding code.
+* Update the docs when behavior, setup, the API, or the architecture changes.
+* Report status honestly: "done" means the checks above were run and passed.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs the lint, type, and test gate on every push to
+`main` and every pull request, across Python 3.10 to 3.13. Dependabot
+(`.github/dependabot.yml`) opens weekly pull requests to update the GitHub Actions
+and the Python tooling.
+
+## Releasing
+
+Publishing is automated by `.github/workflows/publish.yml`, which builds the sdist
+and wheel and uploads them to PyPI through Trusted Publishing (OIDC, no API
+tokens) when a GitHub Release is published.
+
+One-time setup before the first release:
+
+1. On PyPI, go to Account -> Publishing and add a pending publisher with project
+   name `pyvbaanalysis`, owner `WilliamSmithEdward`, repository `pyVBAanalysis`,
+   workflow `publish.yml`, and environment `pypi`.
+2. On GitHub, go to repo Settings -> Environments and create an environment named
+   `pypi`. Optionally add required reviewers so a publish needs human approval.
+
+To cut a release:
+
+1. Bump `__version__` in `pyvbaanalysis/__init__.py` (the single source of the
+   version) and update `CHANGELOG.md`. Commit.
+2. Tag and push: `git tag vX.Y.Z` then `git push origin vX.Y.Z`.
+3. Publish a GitHub Release for that tag (for example
+   `gh release create vX.Y.Z --notes-file <notes>`). Publishing the release runs
+   `publish.yml`, which re-runs the gate, builds, and uploads to PyPI.

pyvbaanalysis-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Smith Edward
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyvbaanalysis-1.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: pyvbaanalysis
+Version: 1.0.0
+Summary: Pure-Python static analysis for Excel VBA
+Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyVBAanalysis
+Project-URL: Repository, https://github.com/WilliamSmithEdward/pyVBAanalysis
+Project-URL: Issues, https://github.com/WilliamSmithEdward/pyVBAanalysis/issues
+Author: William Smith Edward
+License-Expression: MIT
+License-File: LICENSE
+Keywords: excel,linter,static-analysis,vba
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyopenvba>=3.0.1
+Provides-Extra: build
+Requires-Dist: build>=1.2; extra == 'build'
+Requires-Dist: twine>=5; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyVBAanalysis
+
+Static analysis for Excel VBA. It reads your macros and reports likely bugs and the
+errors the VBA compiler would catch, without opening Excel or running any code.
+
+Point it at a workbook or a set of exported module files, and it returns the
+problems it finds, each with the exact line and a plain explanation.
+
+## What it checks
+
+It looks for more than a hundred kinds of problem, including:
+
+- Type errors, such as assigning a string to a `Long` or passing the wrong type to
+  a procedure.
+- Undeclared variables and calls to procedures or members that do not exist.
+- Code the VBA compiler rejects: duplicate declarations, a missing `Option
+  Explicit`, malformed statements, or a `Declare` that lacks `PtrSafe` on 64-bit
+  Office.
+- Likely run-time failures, such as dividing by a constant zero or a type mismatch
+  from a bad conversion.
+
+It only reports a problem when it can prove one, and stays quiet otherwise, so the
+output does not bury you in false alarms.
+
+## Install
+
+```
+pip install pyvbaanalysis
+```
+
+Python 3.10 or later. Nothing else to set up.
+
+## Use it from Python
+
+Analyze a workbook:
+
+```python
+from pyvbaanalysis import analyze_workbook
+
+for module, problems in analyze_workbook("Budget.xlsm").items():
+    for p in problems:
+        print(module, p.severity.value, p.code, p.message)
+```
+
+Analyze a single module's source:
+
+```python
+from pyvbaanalysis import analyze_module
+
+source = "Sub Test()\n    Dim n As Long\n    n = \"oops\"\nEnd Sub\n"
+for p in analyze_module(source):
+    print(p.code, p.message)
+```
+
+Each result has a `code`, a `message`, a `severity` (`error`, `warning`, or
+`information`), and a `span` giving the character offsets in the source.
+
+Analyze several exported files together, so references between them resolve:
+
+```python
+from pyvbaanalysis import analyze_loose_files
+
+analyze_loose_files(["Module1.bas", "Sheet1.cls", "UserForm1.frm"])
+```
+
+## Use it from the command line
+
+```
+pyvbaanalysis Budget.xlsm
+pyvbaanalysis ./exported_modules --format json
+pyvbaanalysis Budget.xlsm --only Sheet1
+```
+
+A path can be a workbook, a folder of exported `.bas` / `.cls` / `.frm` files, or a
+single file. The command exits 1 when it finds problems and 0 when the code is
+clean, so it drops into a CI check.
+
+## Scope
+
+This analyzes Excel VBA. It does not run macros and does not need Excel installed.
+Word and PowerPoint are not supported.
+
+## Documentation
+
+- [Usage guide](docs/usage.md)
+- [API reference](docs/api-reference.md)
+- [Diagnostic catalogue](docs/diagnostics-catalogue.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pyvbaanalysis-1.0.0/README.md

@@ -0,0 +1,91 @@
+# pyVBAanalysis
+
+Static analysis for Excel VBA. It reads your macros and reports likely bugs and the
+errors the VBA compiler would catch, without opening Excel or running any code.
+
+Point it at a workbook or a set of exported module files, and it returns the
+problems it finds, each with the exact line and a plain explanation.
+
+## What it checks
+
+It looks for more than a hundred kinds of problem, including:
+
+- Type errors, such as assigning a string to a `Long` or passing the wrong type to
+  a procedure.
+- Undeclared variables and calls to procedures or members that do not exist.
+- Code the VBA compiler rejects: duplicate declarations, a missing `Option
+  Explicit`, malformed statements, or a `Declare` that lacks `PtrSafe` on 64-bit
+  Office.
+- Likely run-time failures, such as dividing by a constant zero or a type mismatch
+  from a bad conversion.
+
+It only reports a problem when it can prove one, and stays quiet otherwise, so the
+output does not bury you in false alarms.
+
+## Install
+
+```
+pip install pyvbaanalysis
+```
+
+Python 3.10 or later. Nothing else to set up.
+
+## Use it from Python
+
+Analyze a workbook:
+
+```python
+from pyvbaanalysis import analyze_workbook
+
+for module, problems in analyze_workbook("Budget.xlsm").items():
+    for p in problems:
+        print(module, p.severity.value, p.code, p.message)
+```
+
+Analyze a single module's source:
+
+```python
+from pyvbaanalysis import analyze_module
+
+source = "Sub Test()\n    Dim n As Long\n    n = \"oops\"\nEnd Sub\n"
+for p in analyze_module(source):
+    print(p.code, p.message)
+```
+
+Each result has a `code`, a `message`, a `severity` (`error`, `warning`, or
+`information`), and a `span` giving the character offsets in the source.
+
+Analyze several exported files together, so references between them resolve:
+
+```python
+from pyvbaanalysis import analyze_loose_files
+
+analyze_loose_files(["Module1.bas", "Sheet1.cls", "UserForm1.frm"])
+```
+
+## Use it from the command line
+
+```
+pyvbaanalysis Budget.xlsm
+pyvbaanalysis ./exported_modules --format json
+pyvbaanalysis Budget.xlsm --only Sheet1
+```
+
+A path can be a workbook, a folder of exported `.bas` / `.cls` / `.frm` files, or a
+single file. The command exits 1 when it finds problems and 0 when the code is
+clean, so it drops into a CI check.
+
+## Scope
+
+This analyzes Excel VBA. It does not run macros and does not need Excel installed.
+Word and PowerPoint are not supported.
+
+## Documentation
+
+- [Usage guide](docs/usage.md)
+- [API reference](docs/api-reference.md)
+- [Diagnostic catalogue](docs/diagnostics-catalogue.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pyvbaanalysis-1.0.0/docs/api-reference.md

@@ -0,0 +1,86 @@
+# API reference
+
+The package root re-exports the headline entry points; the rest of the public
+surface lives in the submodules listed below. This page is an import map, not a
+full autodoc dump. For task-oriented examples see [usage.md](usage.md).
+
+## Headline API (`pyvbaanalysis`)
+
+These are re-exported at the package root for convenience:
+
+| Symbol | Role |
+| --- | --- |
+| `analyze_module(source, opts=None)` | Analyze one module's source; returns `list[VbaDiagnostic]`. Never raises. |
+| `analyze_project(modules, *, only=None, severity_overrides=None, conditional_compilation=None)` | Analyze a set of `ModuleInput`s with cross-module context; returns `dict[str, list[VbaDiagnostic]]`. |
+| `analyze_loose_file(path, *, severity_overrides=None, conditional_compilation=None)` | Analyze one `.bas`/`.cls`/`.frm` file. |
+| `analyze_loose_files(paths, *, only=None, severity_overrides=None, conditional_compilation=None)` | Analyze several loose files as one project. |
+| `analyze_workbook(path, *, only=None, severity_overrides=None, conditional_compilation=None)` | Analyze the VBA in an Excel workbook (via pyOpenVBA). |
+| `analyze_module_options_for(index, name, kind, *, severity_overrides=None, conditional_compilation=None)` | Build per-module `AnalyzeModuleOptions` from a populated `ProjectIndex`. |
+| `build_project_index(modules)` | A `ProjectIndex` with every module registered. |
+| `AnalyzeModuleOptions` | Inputs for `analyze_module` (name, kind, project context, overrides). |
+| `VbaDiagnostic` | A single diagnostic (`code`, `message`, `severity`, `span`, `spec_reference`). |
+| `ModuleInput` | One module fed into a project (`module_name`, `module_kind`, `source`). |
+| `ModuleSymbolKind` | `STANDARD`, `CLASS`, `DOCUMENT`, `USERFORM`. |
+| `ProjectIndex` | The cross-module symbol/type index. |
+| `__version__` | The package version string. |
+
+## Engine and result model (`pyvbaanalysis.diagnostics`)
+
+* Entry point: `analyze_module`, `AnalyzeModuleOptions`, `RulePassContext`, `PushFn`,
+  `is_object_module_kind`.
+* Result model: `VbaDiagnostic`, `VbaDiagnosticData`, `VbaEdit`, and the enums
+  `DiagnosticSeverity`, `DiagnosticCategory`, `DiagnosticEvidenceKind`,
+  `DiagnosticSuppressionScope`.
+* Registry and metadata: `DIAGNOSTIC_RULE_REGISTRY`, `DiagnosticRuleEntry`,
+  `STRUCTURAL_DIAGNOSTIC_RULES`, `DIAGNOSTIC_RULES`, `DiagnosticRuleMetadata`,
+  `diagnostic_metadata_for_code`, `rule_metadata_by_code`, `load_rule_metadata`,
+  `normalize_diagnostic_severity_override`.
+
+## Readers (`pyvbaanalysis.reader`)
+
+* High level: `analyze_loose_file`, `analyze_loose_files`, `analyze_workbook`,
+  `load_loose_module`, `read_workbook_modules`.
+* Building blocks: `LoadedModule`, `strip_export_header`, `classify_module_kind`,
+  `module_name_from_text`, `loaded_module_from_text`, `WorkbookReadError`,
+  `LOOSE_EXTENSIONS`, `EXCEL_EXTENSIONS`.
+
+## Project model (`pyvbaanalysis.symbols`)
+
+* Index: `ProjectIndex`, `ProjectIndexOptions`, `ModuleInput`, `ReferenceScope`,
+  `ShadowedSpan`.
+* Module symbols: `build_module_symbols`, `BuildModuleSymbolsOptions`,
+  `ModuleSymbols`, `ModuleSymbolKind`, `SymbolVisibility`, `VbaSymbol`,
+  `VbaSymbolKind`, `VbaSymbolAttribute`, `VbaProcedureSignature`,
+  `VbaProcedureParam`, and the predicates `is_procedure_kind`,
+  `is_bare_callable_kind`, `procedure_signature_from_symbol`,
+  `qualified_procedure_key`.
+* Name resolution: `resolve_bare_identifier_binding`, `source_identifier_names`,
+  `BareIdentifierContext`, `BareIdentifierResolution`.
+
+## Lower-level building blocks
+
+These are the analysis layers the engine is built on. Most consumers do not need
+them directly, but they are public and stable.
+
+| Package | What it provides |
+| --- | --- |
+| `pyvbaanalysis.lexer` | `tokenize`, `tokenize_cached`, `VbaToken`, `TokenKind`, and token helpers. |
+| `pyvbaanalysis.parser` | `parse_module`, `parse_expression`, `ModuleNode`, and the AST nodes. |
+| `pyvbaanalysis.conditional` | Conditional-compilation indexing and activity (`index_conditional_compilation`, `evaluate_conditional_expression`, ...). |
+| `pyvbaanalysis.types` | Type-name helpers: `normalize_type`, `is_known_scalar_type`, `is_numeric_type`, `numeric_literal_bounds`. |
+| `pyvbaanalysis.completion` | Member-completion surface and project-type resolution (`resolve_member_surface_at`, `resolve_type_name`, ...). |
+| `pyvbaanalysis.host` | The Excel host object model (`get_excel_object_model`, `resolve_host_alias`, ...). |
+| `pyvbaanalysis.runtime` | VBA runtime functions, constants, and objects (`resolve_runtime_function`, ...). |
+| `pyvbaanalysis.call` | Call-statement shape helpers. |
+| `pyvbaanalysis.flow` | Procedure labels and unstructured-flow detection. |
+| `pyvbaanalysis.constants` | Integer constant-expression evaluation. |
+
+Many helper free functions inside these packages are intentionally internal even
+when importable. The symbols listed above are the supported surface.
+
+## A note on the package root
+
+The package root exports only the headline API plus `__version__`. Everything
+else is imported from its submodule, e.g.
+`from pyvbaanalysis.diagnostics import DiagnosticSeverity` or
+`from pyvbaanalysis.symbols import ModuleSymbols`.