pyvbaanalysis 1.4.2__tar.gz → 2.1.0__tar.gz

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

@@ -5,6 +5,155 @@ 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.1.0 - 2026-09-05
+
+Sync to XLIDE 6.1.2, the analyzer's first re-pin since 3.1.4. Verified by a
+differential against the upstream analyzer over the whole oracle corpus: 418 of
+418 cases identical, in both directions.
+
+### Added
+
+* `ambiguousProjectProcedure`: VBA is content for two modules to export the same
+  public procedure name, but it refuses to compile an UNQUALIFIED call to that
+  name from a module declaring neither. The finding sits at the call site, not
+  the declarations, because a project that exports a name twice and always
+  qualifies its calls is legal VBA and common. Silent when the call is
+  qualified, when the calling module declares the name itself, when a local or
+  parameter shadows it, or when only one module exports it.
+* `ConditionalActivityTracker.mutually_exclusive` and `in_same_branch`, the
+  primitive the arm-aware rules below need, plus
+  `ProjectIndex.implemented_interface_names()` and the
+  `AnalyzeModuleOptions.implemented_interfaces` option it feeds.
+
+### Fixed
+
+* Rules no longer pair declarations from mutually exclusive `#If` arms. Only one
+  arm of a chain is ever built, so two declarations in different arms are
+  alternatives rather than duplicates. With a compiler constant the analyzer
+  cannot evaluate, the ordinary `#If VBA7 / #Else` idiom reported
+  `duplicate-procedure` and `duplicate-module-variable` on legal code. The same
+  reasoning now covers duplicate declarations and labels, undefined labels,
+  `For`/`Next` pairing, `Else` branch order, `Option` placement, and `Implements`
+  placement (XLIDE issue #58).
+* A `#Const` directive may precede `Option Explicit`. A conditional-compilation
+  directive is not a declaration, and the live VBE compiles it there
+  (oracle case `const_directive_before_option_explicit_compile`).
+* Three gaps in return-assignment detection, each of which the widened rule below
+  would otherwise have turned into a false positive:
+  assigning a field of the returned value (`MsToSystemTime.wYear = ...`) is a
+  return assignment; so is an assignment inside a single-line `If`, whose
+  branches the statement walk never entered; and a name that SPELLS a keyword is
+  still an assignment target, so `Function Read()` assigning `Read = True` was
+  read as never assigning its return. Measured on one real workbook these three
+  accounted for nine false findings.
+
+### Changed
+
+* `missingReturnAssignment` now covers every Function and Property Get, not only
+  untyped ones, so a typed Function that never assigns its return reports. An
+  empty member of a module some other module declares with `Implements` stays
+  silent: that is a contract for an implementer to fill in, not unfinished code.
+  A body whose work is to raise stays silent too. **This reports on code that was
+  previously quiet**; the rule is warning severity and can be turned off through
+  `severity_overrides`.
+* The vendored host models grew with upstream's move to the whole documented
+  object model: Excel 229 to 651 types, Word 364 to 627, PowerPoint 201 to 464,
+  Access 188 to 451. The wheel grows from 0.94 MB to 1.84 MB; the models still
+  load lazily, so import cost is unchanged.
+* Data re-pinned to XLIDE 6.1.2: 418 oracle cases (was 415), 122 audited codes
+  (was 121), 119 rules (was 118).
+
+### Known limits
+
+* Upstream's form-control member work is not ported, and the oracle corpus has no
+  UserForm designer cases, so that area is untested here rather than verified.
+
+## 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.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyvbaanalysis
-Version: 1.4.2
+Version: 2.1.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.1.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.1.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.1.0}/docs/diagnostics-catalogue.md

@@ -1,6 +1,6 @@
 # Diagnostic catalogue
 
-The diagnostic codes pyVBAanalysis can emit, generated from the rule metadata (`tools/generate_diagnostics_catalogue.py`). This table lists the 118 rule-metadata codes across 6 categories. A further 3 structural block-balance codes (`mismatched-end-keyword`, `missing-block-closer`, `unmatched-block-closer`) are emitted by the parser pass and are not in the metadata table, for a full set of 121 codes.
+The diagnostic codes pyVBAanalysis can emit, generated from the rule metadata (`tools/generate_diagnostics_catalogue.py`). This table lists the 119 rule-metadata codes across 6 categories. A further 3 structural block-balance codes (`mismatched-end-keyword`, `missing-block-closer`, `unmatched-block-closer`) are emitted by the parser pass and are not in the metadata table, for a full set of 122 codes.
 
 Each code is reported only when it is provably correct; anything unknown or ambiguous stays quiet (the no-false-positive discipline). The **kind** column says what a code means: a *compile error* is rejected by the VBE compiler, a *runtime error* is a deterministic Run-time error, a *runtime risk* is a likely fault, and *style* is advisory.
 
@@ -69,11 +69,12 @@ Override a code's severity with `AnalyzeModuleOptions.severity_overrides` (or th
 | `undeclared-variable` | Variable not defined | error | compile error | MS-VBAL 5.2.4.1.1 |
 | `unknown-call` | Sub or Function not defined | error | compile error | MS-VBAL 5.4.2.1 |
 
-## Semantic (50)
+## Semantic (51)
 
 | Code | Title | Default | Kind | Spec reference |
 | --- | --- | --- | --- | --- |
 | `ambiguous-enum-member` | Ambiguous Enum member reference | error | compile error | VBE compiler: Ambiguous name detected |
+| `ambiguous-project-procedure` | Ambiguous unqualified call to a name two modules export | error | compile error | VBE compiler: Ambiguous name detected |
 | `argument-count` | Wrong number of arguments | error | compile error | MS-VBAL 5.4.2.1 |
 | `argument-object-type-mismatch` | Object argument type mismatch | error | compile error | MS-VBAL 5.3.1 |
 | `argument-shape-mismatch` | Argument shape (array/Type vs scalar) mismatch | error | compile error | MS-VBAL 5.3.1 (argument passing) / VBE compiler: ByRef argument type mismatch; array or user-defined type expected |

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.1.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.1.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.1.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.1.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.1.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]

{pyvbaanalysis-1.4.2 → pyvbaanalysis-2.1.0}/pyvbaanalysis/conditional/conditional_compilation.py

@@ -114,10 +114,42 @@ class _ConditionalFrame:
     seen_unknown: bool
 
 
+@dataclass(frozen=True, slots=True)
+class _ConditionalArm:
+    """One arm of one `#If` chain, as a persistent stack.
+
+    ``parent`` is the enclosing chain's arm. Immutable, so an event can keep the
+    arm that was in effect when it was recorded without copying the stack, and
+    one arm is one object, which makes identity the comparison for
+    ``in_same_branch``.
+    """
+
+    chain: int
+    #: 0 for the `#If`, then one per `#ElseIf` / `#Else`.
+    index: int
+    parent: "_ConditionalArm | None"
+
+
+def _arms_diverge(a: _ConditionalArm | None, b: _ConditionalArm | None) -> bool:
+    """Whether two arm stacks disagree about which arm of a shared chain they are
+    in. The branches then exclude each other whatever the constants are worth.
+    Stacks are as deep as the source nests directives, so the walk is short."""
+    outer = a
+    while outer is not None:
+        inner = b
+        while inner is not None:
+            if outer.chain == inner.chain:
+                return outer.index != inner.index
+            inner = inner.parent
+        outer = outer.parent
+    return False
+
+
 @dataclass(slots=True)
 class _ConditionalActivityEvent:
     start: int
     activity: ConditionalActivity
+    branch: _ConditionalArm | None = None
 
 
 class ConditionalActivityTracker:
@@ -128,7 +160,7 @@ class ConditionalActivityTracker:
     def __init__(self, events: list[_ConditionalActivityEvent]) -> None:
         self._events = events
 
-    def activity_for_span(self, span: Span) -> ConditionalActivity:
+    def _event_for_span(self, span: Span) -> _ConditionalActivityEvent | None:
         # Directives starting at or after the queried offset are not applied.
         lo = -1
         hi = len(self._events) - 1
@@ -138,11 +170,41 @@ class ConditionalActivityTracker:
                 lo = mid
             else:
                 hi = mid - 1
-        return self._events[lo].activity if lo >= 0 else ConditionalActivity.ACTIVE
+        return self._events[lo] if lo >= 0 else None
+
+    def activity_for_span(self, span: Span) -> ConditionalActivity:
+        event = self._event_for_span(span)
+        return event.activity if event is not None else ConditionalActivity.ACTIVE
 
     def is_inactive(self, span: Span) -> bool:
         return self.activity_for_span(span) is ConditionalActivity.INACTIVE
 
+    def mutually_exclusive(self, a: Span, b: Span) -> bool:
+        """Whether the two spans sit in different arms of one `#If` chain, and so
+        are never compiled together however the constants evaluate."""
+        left = self._event_for_span(a)
+        right = self._event_for_span(b)
+        return _arms_diverge(
+            left.branch if left is not None else None,
+            right.branch if right is not None else None,
+        )
+
+    def in_same_branch(self, a: Span, b: Span) -> bool:
+        """Whether the two spans sit under exactly the same arms, so every build
+        either compiles both or neither.
+
+        Stricter than "not mutually exclusive": spans in two SEPARATE chains are
+        neither exclusive nor in the same branch, because a build may take one and
+        not the other. Rules that pair two pieces of one construct need this, since
+        a pairing made across different chains is a guess about a build that may
+        never exist.
+        """
+        left = self._event_for_span(a)
+        right = self._event_for_span(b)
+        return (left.branch if left is not None else None) is (
+            right.branch if right is not None else None
+        )
+
 
 def create_conditional_activity_tracker(
     module: ModuleNode, env: ConditionalCompilationEnvironment | None = None
@@ -162,10 +224,25 @@ def _collect_conditional_activity_events(
     project_constants = _lowercased(effective_env.project_constants)
     stack: list[_ConditionalFrame] = []
     current = ConditionalActivity.ACTIVE
+    branch: _ConditionalArm | None = None
+    chains = 0
     events: list[_ConditionalActivityEvent] = []
     for occ in directives:
         current = _apply_conditional_directive(occ.directive, effective_env, project_constants, stack, current)
-        events.append(_ConditionalActivityEvent(start=occ.directive.span.start, activity=current))
+        kind = occ.directive.directive_kind
+        if kind is ConditionalDirectiveKind.IF:
+            branch = _ConditionalArm(chain=chains, index=0, parent=branch)
+            chains += 1
+        elif kind in (ConditionalDirectiveKind.ELSE_IF, ConditionalDirectiveKind.ELSE):
+            # An `#ElseIf` with no open `#If` is a parse-level error; leave the
+            # stack alone rather than inventing an arm for it.
+            if branch is not None:
+                branch = _ConditionalArm(chain=branch.chain, index=branch.index + 1, parent=branch.parent)
+        elif kind is ConditionalDirectiveKind.END_IF:
+            branch = branch.parent if branch is not None else None
+        events.append(
+            _ConditionalActivityEvent(start=occ.directive.span.start, activity=current, branch=branch)
+        )
     return events