pyvbaanalysis 1.4.2__tar.gz → 2.0.0__tar.gz

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/CHANGELOG.md

@@ -5,6 +5,92 @@ All notable changes to pyVBAanalysis are recorded here. The format follows
 follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html): a minor version
 per milestone.
 
+## 2.0.0 - 2026-08-19
+
+Multi-host analysis: VBA is now measured against the object model of the Office
+host it actually belongs to. Ports the XLIDE host-model seam and the Word,
+PowerPoint and Access models (xlide_vscode 790e6ea and e56098b, its issues #24
+and #25).
+
+### Added
+
+* A host seam on the analysis entry points. `analyze_project` and
+  `analyze_module_options_for` take a `host` token (`"excel"`, `"word"`,
+  `"powerpoint"`, `"access"`, ...), and `AnalyzeModuleOptions` carries `host`
+  alongside the existing `host_model`. The semantics are deliberately
+  asymmetric: absent means Excel, so every existing caller is unchanged, while a
+  NAMED host with no model asserts no host knowledge rather than falling back to
+  Excel's. An explicit `host_model` still outranks the token.
+* Word, PowerPoint and Access object models, vendored as
+  `data/{word,powerpoint,access}_host_model.json` and extracted mechanically by
+  `tools/extract_host_model.mjs` from the generated XLIDE host modules, the same
+  pipeline that has always produced the Excel model. 364, 201 and 188
+  member-bearing types; 3,742, 1,480 and 1,116 enum constants. Every type is
+  non-exhaustive by construction, so absence never becomes a finding.
+* `analyze_office_file(path)` and `read_office_modules(path)` read any container
+  pyOpenVBA opens: Excel (`.xlsm`, `.xlsb`, `.xlam`, `.xls`), Word (`.docm`,
+  `.dotm`, `.doc`), PowerPoint (`.pptm`, `.potm`) and Access (`.accdb`, `.mdb`,
+  read-only). The extension selects the host, so a Word document is analyzed
+  against Word's model without the caller saying anything. The CLI accepts them
+  all on the same footing.
+* `host_token_for_file_name` and `host_object_model_for_token` on the public API.
+
+### Fixed
+
+* Word VBA no longer false-positives against Excel's object model. Analyzing a
+  Word module as a project previously reported four findings on legal code:
+  `ActiveDocument` twice and `wdOrientPortrait` as undeclared variables, and
+  `Selection.TypeText` as `member-not-found` against `Excel.Range`. Under the
+  Word host it reports none.
+* Host metadata is per-model throughout, closing the Excel defaults that
+  remained under the seam. Application-member injection is keyed by model
+  (`Volatile` is a known bare call under Excel and unknown under Word), and the
+  four rules that consulted host metadata with a bare Excel default now take the
+  caller's model: undeclared variables, unknown call, ambiguous enum references,
+  and late-bound Friend members. `Me` types host-correctly in a document module:
+  `ThisWorkbook` is `Excel.Workbook` under Excel, `ThisDocument` is
+  `Word.Document` under Word, and nothing is asserted anywhere else.
+* Word's `ThisDocument` classifies as a document module. It declares
+  `VB_Base = "1Normal.ThisDocument"`, naming no CLSID, so GUID matching missed
+  it; the host-generic signature is the `VB_PredeclaredId` + `VB_Exposed` pair
+  that Office gives every document module. A `.bas` extension or the container's
+  own standard-module flag still outranks that signature, since either states
+  outright that the module is standard. Differentialled across 116 modules in 16
+  real workbooks: nothing reclassified.
+* A named host with no object model no longer reports what it cannot know. An
+  empty model is not uniformly quieter than Excel's: member lookups go silent
+  because no type resolves, but the rules that ask whether a bare name is legal
+  would answer no for every global the host injects, turning an Outlook
+  project's own surface into a wall of `undeclared-variable` findings. The four
+  rules that need host knowledge now stay silent under an unmodelled host, for
+  the same reason they already do on a partial project view.
+* The host-model memos no longer key on a bare `id(model)`. Three caches
+  (`_host_model_index`, `_host_constant_index`, and the host-member name set)
+  used a plain `dict[int, ...]` that kept no reference to the model, so entries
+  accumulated one per model object ever seen and a collected model's id could be
+  recycled by a later one, serving one model's index for another. They now use
+  the repo's `IdentityLru`, which holds its keys alive and stays bounded. Latent
+  before this release, since only the permanently-live Excel singleton was ever
+  passed; reachable now that callers choose models.
+
+### Changed
+
+* `analyze_workbook` and `read_workbook_modules` keep their Excel-only contract
+  unchanged. Handed a container the generic reader could open, they now name
+  `analyze_office_file` in the error rather than only rejecting the extension.
+* README, the usage guide, the API reference and agent.md describe the four
+  hosts; agent.md's pyOpenVBA floor was stale at 3.0.1 and now reads 3.4.0.
+
+### Known limits
+
+* Legacy `.ppt` is not readable. pyOpenVBA 3.4.0 lists it but reads it as a
+  plain CFB, while the VBA project lives in a zlib-compressed CFB inside an
+  `ExOleObjStg` record, so every open fails on the missing `dir` stream. The
+  extension is rejected up front rather than failing later with a parse error
+  that reads like file corruption. Reported as pyOpenVBA issue #17.
+* Access is read-only, following pyOpenVBA: Access executes compiled p-code, so
+  a source write would silently change nothing.
+
 ## 1.4.2 - 2026-08-03
 
 ### Fixed

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyvbaanalysis
-Version: 1.4.2
+Version: 2.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
@@ -24,16 +24,18 @@ Requires-Dist: twine>=5; extra == 'build'
 Provides-Extra: dev
 Requires-Dist: mypy==2.3.0; extra == 'dev'
 Requires-Dist: pytest==9.1.1; extra == 'dev'
-Requires-Dist: ruff==0.16.0; extra == 'dev'
+Requires-Dist: ruff==0.16.2; 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.
+Static analysis for Office VBA. It reads your macros and reports likely bugs and the
+errors the VBA compiler would catch, without opening Office 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.
+Point it at an Excel workbook, a Word document, a PowerPoint deck, an Access
+database, or a set of exported module files, and it returns the problems it finds,
+each with the exact line and a plain explanation. Each file is measured against its
+own host's object model, so Word code is never judged by Excel's surface.
 
 ## What it checks
 
@@ -63,9 +65,9 @@ Python 3.10 or later. Nothing else to set up.
 Analyze a workbook:
 
 ```python
-from pyvbaanalysis import analyze_workbook
+from pyvbaanalysis import analyze_office_file
 
-for module, problems in analyze_workbook("Budget.xlsm").items():
+for module, problems in analyze_office_file("Budget.xlsm").items():
     for p in problems:
         print(module, p.severity.value, p.code, p.message)
 ```
@@ -105,8 +107,14 @@ 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.
+This analyzes the VBA inside Office files. It does not run macros and does not need
+Office installed.
+
+Each file is measured against its own host's object model, so a Word document is
+never judged by Excel's surface. Readable containers: Excel (.xlsm, .xlsb, .xlam,
+.xls), Word (.docm, .dotm, .doc), PowerPoint (.pptm, .potm) and Access (.accdb,
+.mdb, read-only). Legacy .ppt is not readable yet, because its VBA project sits in
+a compressed record the reader does not open.
 
 ## Documentation
 

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/README.md

@@ -1,10 +1,12 @@
 # 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.
+Static analysis for Office VBA. It reads your macros and reports likely bugs and the
+errors the VBA compiler would catch, without opening Office 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.
+Point it at an Excel workbook, a Word document, a PowerPoint deck, an Access
+database, or a set of exported module files, and it returns the problems it finds,
+each with the exact line and a plain explanation. Each file is measured against its
+own host's object model, so Word code is never judged by Excel's surface.
 
 ## What it checks
 
@@ -34,9 +36,9 @@ Python 3.10 or later. Nothing else to set up.
 Analyze a workbook:
 
 ```python
-from pyvbaanalysis import analyze_workbook
+from pyvbaanalysis import analyze_office_file
 
-for module, problems in analyze_workbook("Budget.xlsm").items():
+for module, problems in analyze_office_file("Budget.xlsm").items():
     for p in problems:
         print(module, p.severity.value, p.code, p.message)
 ```
@@ -76,8 +78,14 @@ 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.
+This analyzes the VBA inside Office files. It does not run macros and does not need
+Office installed.
+
+Each file is measured against its own host's object model, so a Word document is
+never judged by Excel's surface. Readable containers: Excel (.xlsm, .xlsb, .xlam,
+.xls), Word (.docm, .dotm, .doc), PowerPoint (.pptm, .potm) and Access (.accdb,
+.mdb, read-only). Legacy .ppt is not readable yet, because its VBA project sits in
+a compressed record the reader does not open.
 
 ## Documentation
 

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/docs/api-reference.md

@@ -11,11 +11,14 @@ 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, whole_project=True, inline_suppression=True)` | Analyze a set of `ModuleInput`s with cross-module context; returns `dict[str, list[VbaDiagnostic]]`. `whole_project=False` for a partial set. |
+| `analyze_project(modules, *, only=None, severity_overrides=None, conditional_compilation=None, whole_project=True, inline_suppression=True, host=None)` | Analyze a set of `ModuleInput`s with cross-module context; returns `dict[str, list[VbaDiagnostic]]`. `whole_project=False` for a partial set. `host` names the Office host (absent means Excel). |
 | `analyze_loose_file(path, *, severity_overrides=None, conditional_compilation=None, whole_project=False, inline_suppression=True)` | Analyze one `.bas`/`.cls`/`.frm` file (partial by default; the whole-project checks are skipped). |
 | `analyze_loose_files(paths, *, only=None, severity_overrides=None, conditional_compilation=None, whole_project=True, inline_suppression=True)` | Analyze several loose files as one project. |
 | `analyze_workbook(path, *, only=None, severity_overrides=None, conditional_compilation=None, inline_suppression=True)` | Analyze the VBA in an Excel workbook (via pyOpenVBA). |
-| `analyze_module_options_for(index, name, kind, *, severity_overrides=None, conditional_compilation=None, whole_project=True, inline_suppression=True)` | Build per-module `AnalyzeModuleOptions` from a populated `ProjectIndex`. |
+| `analyze_office_file(path, *, only=None, severity_overrides=None, conditional_compilation=None, inline_suppression=True)` | The same for any readable Office container (Excel, Word, PowerPoint, Access); the extension selects the host model. |
+| `host_token_for_file_name(name)` | The host a container implies (`excel`, `word`, `powerpoint`, `access`), or `None`. |
+| `host_object_model_for_token(host)` | The model a host token selects: `None` for Excel (the default), the host's own model, or the empty model when a named host has none. |
+| `analyze_module_options_for(index, name, kind, *, severity_overrides=None, conditional_compilation=None, whole_project=True, inline_suppression=True, host=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`). |
@@ -69,7 +72,7 @@ them directly, but they are public and stable.
 | `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.host` | The Excel, Word, PowerPoint and Access host object models and the host registry (`get_excel_object_model`, `host_object_model_for_token`, `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-1.4.2 → pyvbaanalysis-2.0.0}/docs/usage.md

@@ -136,21 +136,53 @@ analyze_loose_files(["Module1.bas", "Widget.cls"])     # several, as one project
 skipped for it (see "Whole project vs a single file" below). Use `analyze_loose_files`
 to analyze several files together with shared cross-module context.
 
-### Excel workbooks (.xlsm / .xlsb / .xlam / .xls)
+### Office macro containers
 
-The workbook reader reads VBA directly out of an Excel file via pyOpenVBA (the one
+The container reader reads VBA directly out of an Office file via pyOpenVBA (the one
 runtime dependency). pyOpenVBA is imported lazily, so `import pyvbaanalysis` stays
-light. The analyzer targets Excel VBA; Word and PowerPoint are out of scope.
+light.
+
+| Host | Extensions |
+| --- | --- |
+| Excel | `.xlsm`, `.xlsb`, `.xlam`, `.xls` |
+| Word | `.docm`, `.dotm`, `.doc` |
+| PowerPoint | `.pptm`, `.potm` |
+| Access | `.accdb`, `.mdb` (read-only) |
 
 ```python
-from pyvbaanalysis import analyze_workbook
+from pyvbaanalysis import analyze_office_file
 
-analyze_workbook("Book.xlsm")                  # dict: module name -> diagnostics
-analyze_workbook("Book.xlsm", only=["Sheet1"]) # one module by name, full context
+analyze_office_file("Book.xlsm")                  # dict: module name -> diagnostics
+analyze_office_file("Report.docm")                # resolved against Word's model
+analyze_office_file("Book.xlsm", only=["Sheet1"]) # one module by name, full context
 ```
 
-A path that is not an Excel workbook, or a container with no readable VBA, raises
-`WorkbookReadError`.
+The extension selects the host, so Word code is measured against Word's object model
+and never against Excel's. Analyzing a Word module under Excel's model reports
+members and constants that are perfectly legal in Word (`Selection.TypeText`,
+`ActiveDocument`, `wdOrientPortrait`), which is the false positive this avoids.
+
+`analyze_workbook` remains the Excel-only entry point and is unchanged.
+
+A path that is not a readable container, or a container with no readable VBA, raises
+`WorkbookReadError`. Legacy `.ppt` is not readable: pyOpenVBA reads it as a plain
+CFB, but its VBA project sits inside a compressed record, so the extension is
+rejected rather than failing later with a parse error
+([pyOpenVBA #17](https://github.com/WilliamSmithEdward/pyOpenVBA/issues/17)).
+
+### Choosing the host yourself
+
+When you already have the module text, name the host directly. Absent means Excel,
+so existing calls are unchanged; a named host with no model asserts no host
+knowledge at all rather than falling back to Excel's.
+
+```python
+from pyvbaanalysis import analyze_project
+
+analyze_project(modules, host="word")      # Word's object model
+analyze_project(modules, host="outlook")   # no model yet: stays quiet, never Excel's
+analyze_project(modules)                   # Excel, exactly as before
+```
 
 The reader loads the workbook and its VBA into memory and does not bound the input
 size, so impose your own limit (for example a maximum file size) before pointing it
@@ -227,8 +259,9 @@ pyvbaanalysis Book.xlsm --format json
 ```
 
 A path may be a loose file, a folder of loose files (analyzed together as one
-project), or an Excel workbook. `pyvbaanalysis --version` prints the version, and
-`python -m pyvbaanalysis` is equivalent to the `pyvbaanalysis` command.
+project), or an Office macro container, whose extension selects the host model.
+`pyvbaanalysis --version` prints the version, and `python -m pyvbaanalysis` is
+equivalent to the `pyvbaanalysis` command.
 
 Flags:
 

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/pyproject.toml

@@ -38,7 +38,7 @@ dependencies = ["pyOpenVBA>=3.4.0"]
 # underneath main (ruff 0.16 broke a green tree with zero repo commits).
 # Dependabot's weekly pip updates turn each tool upgrade into its own gated
 # PR, where a red CI run blocks the bump instead of breaking main.
-dev = ["pytest==9.1.1", "ruff==0.16.0", "mypy==2.3.0"]
+dev = ["pytest==9.1.1", "ruff==0.16.2", "mypy==2.3.0"]
 build = ["build>=1.2", "twine>=5"]
 
 [project.scripts]

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/pyvbaanalysis/__init__.py

@@ -9,6 +9,8 @@ The headline entry points are re-exported here for convenience:
 * analyze_project(modules): analyze a set of modules with cross-module context.
 * analyze_workbook(path): analyze the VBA in an Excel workbook (read via pyOpenVBA,
   the one external runtime dependency).
+* analyze_office_file(path): the same for any Office macro container (Excel, Word,
+  PowerPoint, or read-only Access), resolving against that host's object model.
 * analyze_loose_file(path) / analyze_loose_files(paths): analyze loose
   .bas / .cls / .frm export files.
 
@@ -30,10 +32,16 @@ from .diagnostics import (
     validate_severity_overrides,
 )
 from .project import analyze_module_options_for, analyze_project, build_project_index
-from .reader import analyze_loose_file, analyze_loose_files, analyze_workbook
+from .host import host_object_model_for_token, host_token_for_file_name
+from .reader import (
+    analyze_loose_file,
+    analyze_loose_files,
+    analyze_office_file,
+    analyze_workbook,
+)
 from .symbols import ModuleInput, ModuleSymbolKind, ProjectIndex, ProjectIndexOptions
 
-__version__ = "1.4.2"
+__version__ = "2.0.0"
 
 __all__ = [
     "AnalyzeModuleOptions",
@@ -50,9 +58,12 @@ __all__ = [
     "analyze_loose_files",
     "analyze_module",
     "analyze_module_options_for",
+    "analyze_office_file",
     "analyze_project",
     "analyze_workbook",
     "build_project_index",
+    "host_object_model_for_token",
+    "host_token_for_file_name",
     "line_col",
     "rule_metadata_by_code",
     "validate_severity_overrides",

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.0.0}/pyvbaanalysis/cli.py

@@ -30,13 +30,14 @@ from .diagnostics import (
     validate_severity_overrides,
 )
 from .project import analyze_project
+from .host import host_token_for_file_name
 from .reader import (
-    EXCEL_EXTENSIONS,
     LOOSE_EXTENSIONS,
+    OFFICE_EXTENSIONS,
     LooseFileReadError,
     WorkbookReadError,
     load_loose_module,
-    read_workbook_modules,
+    read_office_modules,
 )
 from .symbols import ModuleInput
 
@@ -151,7 +152,7 @@ def _analyze_workbook_group(
     errors: list[str] = []
     for path in paths:
         try:
-            modules = read_workbook_modules(path)
+            modules = read_office_modules(path)
         except WorkbookReadError as exc:
             errors.append(f"{path}: {exc}")
             continue
@@ -163,6 +164,7 @@ def _analyze_workbook_group(
             only=only or None,
             severity_overrides=severity_overrides or None,
             inline_suppression=inline_suppression,
+            host=host_token_for_file_name(path.name),
         )
         sources = {m.name: m.source for m in modules}
         results.append(_ProjectResult(str(path), diagnostics, sources))
@@ -332,7 +334,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         print("error: unknown diagnostic code(s): " + ", ".join(unknown_codes), file=sys.stderr)
         return 2
 
-    workbook_paths = [p for p in paths if p.is_file() and p.suffix.lower() in EXCEL_EXTENSIONS]
+    workbook_paths = [p for p in paths if p.is_file() and p.suffix.lower() in OFFICE_EXTENSIONS]
     other_paths = [p for p in paths if p not in workbook_paths]
     loose_paths = _gather_loose_paths(other_paths)
     unknown = [p for p in loose_paths if p.suffix.lower() not in LOOSE_EXTENSIONS]