pyvbaanalysis 2.0.0__tar.gz → 2.1.0__tar.gz

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

@@ -5,6 +5,69 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyvbaanalysis
-Version: 2.0.0
+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

{pyvbaanalysis-2.0.0 → 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-2.0.0 → pyvbaanalysis-2.1.0}/pyvbaanalysis/__init__.py

@@ -41,7 +41,7 @@ from .reader import (
 )
 from .symbols import ModuleInput, ModuleSymbolKind, ProjectIndex, ProjectIndexOptions
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 __all__ = [
     "AnalyzeModuleOptions",

{pyvbaanalysis-2.0.0 → 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