pyvbaanalysis 2.1.1__tar.gz → 2.2.1__tar.gz

{pyvbaanalysis-2.1.1 → pyvbaanalysis-2.2.1}/.gitignore

@@ -34,3 +34,6 @@ 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.
+
+# A pinned XLIDE checkout is a build input, reproducible from its ref at any time.
+artifacts/

{pyvbaanalysis-2.1.1 → pyvbaanalysis-2.2.1}/CHANGELOG.md

@@ -5,6 +5,290 @@ 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.2.1 - 2026-09-23
+
+Sync to XLIDE 10.7.1 (commit 6ead73d), from 10.6.0. Upstream fixed how its
+lexer and parser read a handful of lines the VBE compiles (XLIDE issues #82 to
+#90), and the port takes each fix. XLIDE 10.7.0 changed nothing the port reads.
+
+### Added
+
+* `LoadedModule.designer_block`: the export header a reader stripped ahead of
+  `source`, empty when there was none. `designer_block + source` is the module
+  text as read, so a span in the analyzed body can be placed in the file.
+
+### Changed
+
+* A contextual keyword is a `KEYWORD` token only inside the statement that
+  makes it one: `Text` after `Option Compare`, `Step` in a `For` header,
+  `Output` in an `Open` statement. Elsewhere, as in `Dim text As String`, it is
+  an `IDENTIFIER` (XLIDE issue #86). `PtrSafe` joins these words, as it did
+  upstream with issue #41.
+* A comment ending in ` _` runs on through the next line, so its token can span
+  physical lines (#82). A line continuation may have whitespace after its `_`
+  (#83).
+* `1.` lexes as a float and `&17` as an octal literal. `=>`, `=<` and `><` are
+  one operator token, whose `canonical_text` gives the standard spelling (#87).
+
+### Fixed
+
+False positives 2.2.0 reported on code that compiles, and two errors it missed:
+
+* `unreachable-code` on the line after
+  `If conn Is Nothing Then ACCT = CVErr(xlErrNA): Exit Function`. Every
+  statement a one-line `If` runs after a colon belongs to the If (MS-VBAL
+  5.4.2.9). After a `Set x = Nothing` or an `Erase` there, the next line no
+  longer reports an unset object or an unallocated array. A `Set` inside a
+  one-line `If` no longer leaves the object reported as Nothing after it.
+* Findings on the line after a comment ending in ` _` (#82), and a missing
+  `Then` or a call to a variable on the line after a continuation with spaces
+  after its `_` (#83).
+* `If x Then:` read as a block If (#84), and a one-word `EndIf` read as no
+  closer, so the lines after it reported as unreachable (#88).
+* `invalid-expression-syntax` on `1.`, `&17`, `a => b`, `a < > b` and the other
+  spellings the VBE reads (#87). `s = "a" &1`, which the VBE refuses, is now
+  reported, and `s = "a" &9` is still a concatenation.
+* `argument-count` missed on `Needs, 2`: a comma touching the callee opens its
+  argument list, as the VBE reads it (#85).
+* `assignment-object-type-mismatch` on `Shape.Duplicate` assigned to a `Shape`,
+  on `SparklineGroup.SeriesColor` assigned to a `FormatColor`, and on a
+  `Charts` or `Worksheets` collection assigned to a `Sheets` variable (#90).
+* `Err.LastDllError` is spelled the way the VBE writes it (#89).
+* The command line counted lines in a `.cls` or `.frm` export from the end of
+  its designer header (the `VERSION` line and `Begin ... End` block the reader
+  strips before analysis), so a class module's findings printed four lines
+  early and a UserForm's early by the height of its form block. Lines, and the
+  JSON `start` and `end` offsets, now count the file as saved. Modules read
+  from an Office container are numbered as before, since pyOpenVBA reads them
+  without a designer header. The library's spans still index the code body.
+
+### Verified
+
+* Upstream's own 10.7.1 test suite, recorded and replayed through the port:
+  1081 standalone and 936 project calls, every result identical in code, span
+  and message. Before the port changes 24 of them differed, so the replay sees
+  what this release changes.
+* The oracle corpus (1820 diagnostics), 16 real workbooks, 195 Office files of
+  every host, 693 further projects (948 modules) and 7 VB6 projects: identical
+  diagnostics from both analyzers.
+* Against 2.2.0, the largest module (26,721 lines) takes the same CPU time.
+
+## 2.2.0 - 2026-09-22
+
+Sync to XLIDE 10.6.0 (commit 5682c8f), from 6.2.0: twelve new diagnostics, early
+binding checked against the libraries a project references, and member lookups
+that follow the type library's own extensibility flags. The data is now vendored
+from a pinned upstream commit, which the manifest records.
+
+The sync also closes gaps earlier syncs left open. Replaying upstream's own test
+suite through the port found checks that were never ported (member calls, typing
+through the host model, constants from the host and the VBA library), fixes
+older than 6.2.0 that were never taken, and false positives in 2.1.1 from that
+drift. All of it is listed below.
+
+### Added
+
+* `invalid-option-statement` (error): a malformed Option statement, such as
+  `Option Base 2`, `Option Explicit Foo` or a bare `Option Private`.
+  `Option Compare Database` is reported only when a host other than Access is
+  named: it is an Access directive, and a loose file names no host.
+* `missing-library-reference` (error): a type or constant qualified with another
+  Office application's library the project does not reference, such as
+  `Dim doc As Word.Document` in a workbook with no reference to Word. The VBE
+  refuses it with "User-defined type not defined". Late binding through
+  `CreateObject` names nothing and stays silent. Reported once per library per
+  module, and only against a known reference list (see Changed).
+* Four dead-code checks, all `information`: `unused-variable` (a local, or a
+  module-private variable or constant, that nothing uses), `variable-never-read`
+  (one that is only ever assigned), `unused-procedure` (a private procedure
+  nothing calls), and `unreachable-code` (statements after `Exit`, `End`, `GoTo`
+  or `Resume` that no label or `Case` arm reaches). A name in any module's
+  string literal counts as a use of a private procedure, because
+  `Application.Run "Poll"` reaches a private Sub. `unused-variable` and
+  `unreachable-code` findings carry the edit that removes the declaration or the
+  dead run.
+* Six doc-comment checks, all `warning`: `doc-param-missing`,
+  `doc-param-unknown`, `doc-returns-missing`, `doc-returns-unexpected`,
+  `doc-tag-unclosed` and `doc-tag-duplicate` compare the XML tags of a `'''`
+  block with the declaration it documents, each with fixes that add, rename or
+  remove a tag. A `'''` block of plain prose is left alone.
+* `referenced_hosts` on `analyze_project` and `analyze_module_options_for`: the
+  other Office libraries a project references, in declaration order. Their
+  types, constants and globals resolve against their own models, and the
+  project's own host wins a name two libraries share, as VBA resolves it.
+  `None`, the default, means the list is unknown; `[]` means it is known to name
+  nothing else.
+* `read_office_project(path)` in `pyvbaanalysis.reader`, returning an
+  `OfficeProject`: a container's modules, the host its extension implies, and
+  the Office libraries its reference list names. `analyze_office_file` and the
+  CLI pass all three to the analysis.
+* Member calls are checked for arity and argument types against the signature
+  the member resolves to, on host objects and project classes alike:
+  `Application.Calculate(1)`, a bare `Err.Raise`, `Workbooks.Open()`, and
+  `p.Save "bad"` on a class whose `Save` takes a Long. Earlier ports checked
+  calls to procedures only. A keyword before `:=` is a parameter name, so
+  `BreakLink Name:="x", Type:=xlLinkTypeExcelLinks` stays silent. A signature's
+  parameters end at their own closing parenthesis, so a member returning an
+  array, `Function Values() As Long()`, takes an empty argument list.
+* Expressions are typed through the host model, the VBA runtime and the member
+  a chain resolves to, so `Set wb = ActiveSheet.Range("A1")` reports
+  `assignment-object-type-mismatch`, and a constant such as `vbFalse` or
+  `xlAbove` passed or assigned where an object is expected is reported.
+* Constant expressions fold VBA and host constants: `1 / vbFalse` reports
+  `division-by-zero`, and `Left$(s, xlAbove - 1)` a negative length. A constant
+  qualified with a host (`Word.wdMainTextStory`) answers only in that host.
+* A `vb6` host token and the VB6 object model: App, Screen, Printer, Form and
+  the intrinsic controls. It offers and describes, and never proves a member
+  absent.
+* A UserForm's surface carries the MSForms UserForm members and the ones VBA
+  adds (Show, Hide, Name, ...). When the form's control list is authoritative,
+  supplied as `implicit_members` or spelled out by a `.frm` designer header, it
+  proves a member absent: `EntryForm.NoSuchControl` reports `member-not-found`
+  (XLIDE issue #26). A form nobody read the designer of proves nothing.
+* The public pieces behind these: `classify_reference_kinds` in the new
+  `pyvbaanalysis.references`, the doc-comment grammar in `pyvbaanalysis.docs`,
+  `host_object_model_for_tokens`, `get_vb6_object_model` and the libid helpers
+  in `pyvbaanalysis.host`, the forms metadata in `pyvbaanalysis.host.msforms`,
+  `implicit_members`, `predeclared_id` and `designer_class` on `ModuleInput`
+  (with `ImplicitMember`), and the code-action payloads
+  `VbaAddLibraryReferenceData`, `VbaRemoveDeclarationData`,
+  `VbaRemoveUnreachableCodeData` and `VbaDocCommentFix`.
+* `tools/vendor_data.py` vendors every data file from one pinned XLIDE commit,
+  after `tools/pin_analyzer.py` copies that commit out of the sibling checkout
+  (see CONTRIBUTING.md). The manifest gains `xlideCommit`.
+* `tools/differential/harness.py` compares the port with the upstream analyzer
+  of the same pin. It records every `analyzeModule` call of upstream's own test
+  suite and replays each through the port, and it runs the oracle corpus, Office
+  files and folders of exported modules through both analyzers (see
+  CONTRIBUTING.md). It stays out of the published packages.
+
+### Changed
+
+* `member-not-found` reports an absent member only on a closed Excel interface.
+  Upstream now reads each interface's TYPEFLAGS from the type library, and
+  Application, Workbook and Range are extensible: VBA compiles a member they do
+  not list and resolves it at run time. `Application.Match` and the other
+  worksheet functions reached through Application were reported and are now
+  silent. In a workbook, `ThisWorkbook` is the project's own document class,
+  which the VBE closes, so a member it lacks is still reported. Analyzed with no
+  ThisWorkbook module, as the oracle corpus runs its cases, it falls back to the
+  library's open Workbook, and three cases the VBE rejects go unreported by both
+  analyzers. `Worksheets` stays closed: the type library returns the closed
+  `Sheets` from it, so `Worksheets.NoSuchMemberXyz` is still reported and
+  `Worksheets(1)` is still a Worksheet (XLIDE issue #79, found by this sync).
+* The host models carry the members each type library marks hidden, which the
+  reference documentation leaves out: 405 more in Excel's model, 332 in Word's
+  and 200 in PowerPoint's, each with `hidden` set. They resolve like any other
+  member (see Fixed). Where a Global interface answers for bare names, as in
+  Excel, Word and PowerPoint, Application's hidden members stay out of bare
+  scope, so a bare `Save` in Excel is still `unknown-call`.
+* The project's own types outrank the host library's, as they do in VBA: a class
+  named `Font` or `Point` resolves to its own members rather than Excel's
+  (XLIDE issue #11). A project Enum is a value type, never an object receiver.
+* The rules that read a statement's structure also read the statements a
+  single-line `If` carries: `If ok Then K = 2` reports `const-assignment`, and
+  `If ok Then Helper 1, 2, 3` its arity (XLIDE issue #46).
+* The arms of one `#If` chain are alternatives, and a repeat inside one arm is a
+  repeat: two `Case Else`, two `Option Explicit`, or a duplicated Enum member or
+  Type field in the same arm are reported, where every undecidable branch used
+  to be skipped. A call that no arm's declaration accepts reports
+  `argument-count`, where a name declared once per arm used to turn the check
+  off (XLIDE issue #58).
+* A module's own `Type` shadows another module's `Type` of the same name, as it
+  does in the VBE. A class with a private `Type JsonTextBuilder` was resolved
+  against a public one elsewhere, and its fields reported missing (oracle case
+  `private_type_shadows_public_type_compile`).
+* A procedure closer ends the open procedure even from inside a block left open
+  in it, as the VBE does and upstream's parser now does too (XLIDE issue #81,
+  found by this sync). After `If x Then` with no `End If`, an `End Function`
+  reports the If as missing its `End If` and closes the procedure. It used to
+  read as an unmatched closer and leave the procedure open.
+* `analyze_workbook` returns exactly what `analyze_office_file` returns for the
+  same file. It now reads the workbook's reference list and names Excel as the
+  host, so it can report `missing-library-reference` and
+  `Option Compare Database`, which it could not before.
+* `missing-library-reference` is reported only against a known reference list:
+  one read from a container, or passed as `referenced_hosts`. Upstream treats an
+  absent list as "nothing referenced"; a loose `.bas` file has no list, and a
+  missing reference cannot be proven there.
+* The four dead-code checks report at `information`, and the CLI's default
+  `--fail-level information` fails on any diagnostic, so a workbook with one
+  unused variable now exits 1. Pass `--fail-level warning` to gate on warnings
+  and errors only. Each of 16 real workbooks reports at least one of these.
+* The vendored data moves to 10.6.0: 443 oracle cases (from 418), 134 audited
+  codes (from 122) and 131 catalogue rules (from 119). Two data files join it,
+  both extracted from the same commit: the VB6 object model and the Microsoft
+  Forms members.
+
+### Fixed
+
+False positives 2.1.1 reported on code that compiles, each from a fix an earlier
+sync did not carry over:
+
+* `undeclared-variable` on a qualifier that names an enumeration or a VBA module
+  of constants: `XlDirection.xlUp`, `VbMsgBoxResult.vbYes`, `Strings.Left`,
+  `Constants.vbCrLf`.
+* `undeclared-variable` on a UserForm's own controls in its code-behind, on a
+  bracketed name Excel evaluates (`[A1]`), on the field after `!` (`rs!Field`),
+  on `Line` in `Line Input #f, s`, and on a module name used as a qualifier
+  (`Module1.Limit`).
+* `object-variable-not-set` on a variable declared `As New`, which VBA creates
+  on first use.
+* `unallocated-dynamic-array-access` on an array read after a call that received
+  it, and may have allocated it: `If Fill(a) Then Debug.Print a(0)` (XLIDE issue
+  #70).
+* `event-handler-module-scope` on each Document event handler in Word's
+  `ThisDocument`, such as `Document_Open`. The module was taken for a worksheet,
+  where upstream knows it as Word's document.
+
+Three more, fixed upstream in 10.6.0:
+
+* `readonly-member-assignment` on a comparison with a read-only property: in an
+  `ElseIf` or `Case` header, a single-line `If`'s condition, or a call given the
+  comparison, such as `Debug.Print w.Part = "a"`. The target of a member
+  assignment must be one receiver chain, which a keyword or a call before the
+  receiver breaks (XLIDE issue #78, found by this sync). An assignment that a
+  single-line `If` carries is still reported, named `w.Part` rather than
+  `If ok Then w.Part`.
+* `member-not-found` on a member the type library hides, such as
+  `ThisWorkbook.Title` or `ws.OnEntry` on a Worksheet. Both compile, but the
+  models were built from the reference documentation, which leaves such members
+  out.
+* `undeclared-variable` on a hidden global called bare, such as `Assistant` in
+  Word and PowerPoint, or PowerPoint's `Dialogs`.
+
+### Verified
+
+* Upstream's own test suite, recorded: every `analyzeModule` call its 10.6.0
+  tests make, with the options they pass and the modules of any project index
+  behind them, replayed through the port: 1055 standalone calls and 929 with
+  project context, every result identical in code, span and message. With two
+  of the 10.6.0 fixes undone in the port, 7 of them differ, so the replay sees
+  what those fixes change.
+* The oracle corpus, standalone and with project context: all 1818 diagnostics
+  identical in code, span and message. That is with the reference list given as
+  known and empty to both analyzers. Left unknown, the port stays silent on the
+  one case the upstream analyzer reports, the reference-list gate above.
+* The 116 modules of 16 real workbooks: identical diagnostics from both
+  analyzers.
+* 693 further projects, 627 of them the VBA blocks of upstream's syntax corpus
+  and 66 folders of exported modules: identical diagnostics from both analyzers
+  across 948 modules. The seven VB6 projects among them are identical under the
+  `vb6` host too.
+* 195 distinct Office files from the same repositories, from Excel, Word,
+  PowerPoint and Access: identical diagnostics across 965 modules, once the
+  `ThisDocument` fix above was in. That fix is what this comparison found.
+* Each new rule compared case by case with upstream 10.5.0, fix payloads
+  included: option statements 23, library references 11, reference kinds 18,
+  dead code 33 plus 8 removal edits, doc comments 21 with 25 fixes.
+* Against 2.1.1, in interleaved runs measuring CPU time: a real workbook's
+  analysis takes about 3 percent longer, and the largest module (26,721 lines)
+  about 15 percent. The 10.6.0 changes measure under 2 points of that.
+* The differential harness behind the 2.1.0 and 2.1.1 figures read each module's
+  kind from the wrong corpus field, so class and document modules were compared
+  as standard modules. It is corrected, and the figures above come from the
+  corrected harness, now `tools/differential/`.
+
 ## 2.1.1 - 2026-09-05
 
 Follows XLIDE 6.2.0. The vendored data is byte-identical to 6.1.2, so only the

{pyvbaanalysis-2.1.1 → pyvbaanalysis-2.2.1}/CONTRIBUTING.md

@@ -14,8 +14,8 @@ 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.
+dependency, used to read VBA out of Office files) is installed with the base
+package, so the container reader is exercised by the test suite.
 
 ## Local checks
 
@@ -34,19 +34,73 @@ mypy pyvbaanalysis
 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.
+* The XLIDE source is expected as a sibling checkout at `../xlide_vscode`, to read
+  while porting.
 * 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
+* The vendored data lives in `pyvbaanalysis/data/` (the host object models, 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.
+  checksums). It is never hand-edited. A sync regenerates all of it from one XLIDE
+  commit:
+
+  ```
+  python tools/vendor_data.py --ref vX.Y.Z
+  ```
+
+  The commit is pinned first. `tools/pin_analyzer.py` copies the sibling
+  repository's history into `artifacts/analyzer-pin/<commit>` (not in source
+  control) and checks that commit out, so neither uncommitted work in the sibling
+  checkout nor the branch it happens to be on reaches the data. The
+  `tools/extract_*.mjs` scripts then read the pin through `XLIDE_ROOT`, and stop
+  rather than fall back to the sibling when it does not name an XLIDE checkout. The
+  manifest records both the version label and the full commit (`xlideVersion`,
+  `xlideCommit`).
 
 The build plan, parity inventory, and module-by-module port map are in
 [agent.md](agent.md).
 
+## Checking a sync against upstream
+
+The port's own tests encode the behavior it had, so they stay green while upstream
+widens a rule the port never took. A sync is checked by running both analyzers on
+the same inputs, upstream from the pin of the vendored commit:
+
+```
+python tools/differential/harness.py record
+python tools/differential/harness.py replay
+python tools/differential/harness.py corpus
+python tools/differential/harness.py cases artifacts/differential/cases/mine.json PATH ...
+python tools/differential/harness.py projects artifacts/differential/cases/mine.json
+```
+
+* `record` runs upstream's own test suite with a recorder appended to its
+  `analyzeModule` and `ProjectIndex`, writing every call to
+  `artifacts/differential/<commit>/calls.jsonl`. `replay` runs each call through
+  the port, rebuilding the project index behind a call made with project context,
+  and compares the diagnostics by code, span and message. It finds the gaps
+  nothing else exercises: whole checks never ported, fixes older than the last
+  sync point.
+* `corpus` runs the oracle corpus through both analyzers, each module standalone
+  and with its case's modules as a project.
+* `cases` turns Office files, and folders searched for them and for exported
+  `.bas`/`.cls`/`.frm` modules, into project cases. `--markdown` adds every VBA
+  block of upstream's syntax corpus, and `--host` names a host for the cases no
+  file implies one for. `projects` runs a cases file through both analyzers.
+
+`replay`, `corpus` and `projects` exit 1 when anything differs and print what only
+one side reports. Where the port reports more, the port is wrong. Where upstream
+reports more it may be an upstream false positive, so check before porting it.
+
+The upstream halves (`tools/differential/upstream/*.mjs`) read the pin through
+`tools/xlide_source.mjs`, as the extractors do, and need nothing installed. Only
+`record` runs upstream's vitest suite, which needs the sibling checkout's
+dependencies installed. The pin gets a `node_modules` folder of its own with one
+link per package, so the caches Vite writes stay in the pin, and the run fails if
+the sibling's folder changed. The recorder is removed with `git checkout` when the
+run ends. `harness.py unpatch` restores a pin a run left patched, and
+`tools/pin_analyzer.py` will not reuse a pin with local changes.
+
 ## Adding or changing a rule
 
 * Port the rule from its XLIDE source; match the behavior, not just the shape.

{pyvbaanalysis-2.1.1 → pyvbaanalysis-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyvbaanalysis
-Version: 2.1.1
+Version: 2.2.1
 Summary: Pure-Python static analysis for Excel VBA
 Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyVBAanalysis
 Project-URL: Repository, https://github.com/WilliamSmithEdward/pyVBAanalysis
@@ -22,9 +22,9 @@ Provides-Extra: build
 Requires-Dist: build>=1.2; extra == 'build'
 Requires-Dist: twine>=5; extra == 'build'
 Provides-Extra: dev
-Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: mypy==2.3.1; extra == 'dev'
 Requires-Dist: pytest==9.1.1; extra == 'dev'
-Requires-Dist: ruff==0.16.2; extra == 'dev'
+Requires-Dist: ruff==0.16.8; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # pyVBAanalysis
@@ -46,8 +46,13 @@ It looks for more than a hundred kinds of problem, including:
 - Undeclared variables and calls to procedures or members that do not exist.
 - Code the VBA compiler rejects: duplicate declarations, malformed statements, or a `Declare` that lacks `PtrSafe` on 64-bit
   Office.
+- A type from another Office application's library the project does not
+  reference, such as `Dim doc As Word.Document` in a workbook with no reference to
+  Word.
 - Likely run-time failures, such as dividing by a constant zero or a type mismatch
   from a bad conversion.
+- Dead code: variables nothing uses or nothing reads, private procedures nothing
+  calls, and statements no path reaches.
 
 It only reports a problem when it can prove one, and stays quiet otherwise, so the
 output does not bury you in false alarms.
@@ -122,6 +127,14 @@ a compressed record the reader does not open.
 - [API reference](docs/api-reference.md)
 - [Diagnostic catalogue](docs/diagnostics-catalogue.md)
 
+## Built with this
+
+[xlide-mcp](https://github.com/WilliamSmithEdward/xlide_mcp)
+is an MCP server built on this. The diagnostics here are its build gate:
+an agent that changes a macro runs them afterwards and treats an error
+as a failure rather than a suggestion, which is most of what stops a
+model shipping VBA that does not compile.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{pyvbaanalysis-2.1.1 → pyvbaanalysis-2.2.1}/README.md

@@ -17,8 +17,13 @@ It looks for more than a hundred kinds of problem, including:
 - Undeclared variables and calls to procedures or members that do not exist.
 - Code the VBA compiler rejects: duplicate declarations, malformed statements, or a `Declare` that lacks `PtrSafe` on 64-bit
   Office.
+- A type from another Office application's library the project does not
+  reference, such as `Dim doc As Word.Document` in a workbook with no reference to
+  Word.
 - Likely run-time failures, such as dividing by a constant zero or a type mismatch
   from a bad conversion.
+- Dead code: variables nothing uses or nothing reads, private procedures nothing
+  calls, and statements no path reaches.
 
 It only reports a problem when it can prove one, and stays quiet otherwise, so the
 output does not bury you in false alarms.
@@ -93,6 +98,14 @@ a compressed record the reader does not open.
 - [API reference](docs/api-reference.md)
 - [Diagnostic catalogue](docs/diagnostics-catalogue.md)
 
+## Built with this
+
+[xlide-mcp](https://github.com/WilliamSmithEdward/xlide_mcp)
+is an MCP server built on this. The diagnostics here are its build gate:
+an agent that changes a macro runs them afterwards and treats an error
+as a failure rather than a suggestion, which is most of what stops a
+model shipping VBA that does not compile.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{pyvbaanalysis-2.1.1 → pyvbaanalysis-2.2.1}/docs/api-reference.md

@@ -11,18 +11,18 @@ 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, 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_project(modules, *, only=None, severity_overrides=None, conditional_compilation=None, whole_project=True, inline_suppression=True, host=None, referenced_hosts=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). `referenced_hosts` names the other Office libraries the project references, in declaration order; `None` means the reference list is unknown, `[]` that it is known to name nothing else. |
 | `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_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. |
+| `analyze_workbook(path, *, only=None, severity_overrides=None, conditional_compilation=None, inline_suppression=True)` | The Excel-only form of `analyze_office_file`: refuses any other extension, and otherwise returns exactly what it does. |
+| `analyze_office_file(path, *, only=None, severity_overrides=None, conditional_compilation=None, inline_suppression=True)` | Analyze the VBA in any readable Office container (Excel, Word, PowerPoint, Access, via pyOpenVBA); the extension selects the host model, and the project's reference list is read with its modules. |
 | `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`. |
+| `host_object_model_for_token(host)` | The model a host token selects: `None` for Excel (the default), the host's own model (`word`, `powerpoint`, `access`, `vb6`), 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, referenced_hosts=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`). |
+| `ModuleInput` | One module fed into a project (`module_name`, `module_kind`, `source`), plus what a caller that read the module's designer or attribute header knows: `implicit_members` (a UserForm's controls, as `ImplicitMember`s), `predeclared_id` and `designer_class`. Left `None`, the index reads what the source itself carries. |
 | `ModuleSymbolKind` | `STANDARD`, `CLASS`, `DOCUMENT`, `USERFORM`. |
 | `ProjectIndex` | The cross-module symbol/type index. |
 | `__version__` | The package version string. |
@@ -34,6 +34,12 @@ These are re-exported at the package root for convenience:
 * Result model: `VbaDiagnostic`, `VbaDiagnosticData`, `VbaEdit`, and the enums
   `DiagnosticSeverity`, `DiagnosticCategory`, `DiagnosticEvidenceKind`,
   `DiagnosticSuppressionScope`.
+* Code-action payloads, carried on `VbaDiagnosticData`:
+  `VbaMissingRequiredArgumentPlaceholderData`, `VbaCreateProcedureStubData`,
+  `VbaAddLibraryReferenceData` (the library a `missing-library-reference` finding
+  needs), `VbaRemoveDeclarationData` and `VbaRemoveUnreachableCodeData` (the edit
+  that deletes an unused declaration or an unreachable run), and `VbaDocCommentFix`
+  (each way to bring a doc comment in line with its declaration).
 * Registry and metadata: `DIAGNOSTIC_RULE_REGISTRY`, `DiagnosticRuleEntry`,
   `STRUCTURAL_DIAGNOSTIC_RULES`, `DIAGNOSTIC_RULES`, `DiagnosticRuleMetadata`,
   `diagnostic_metadata_for_code`, `rule_metadata_by_code`, `load_rule_metadata`,
@@ -42,15 +48,25 @@ These are re-exported at the package root for convenience:
 ## Readers (`pyvbaanalysis.reader`)
 
 * High level: `analyze_loose_file`, `analyze_loose_files`, `analyze_workbook`,
-  `load_loose_module`, `read_workbook_modules`.
+  `analyze_office_file`, `load_loose_module`, `read_workbook_modules`,
+  `read_office_modules`, `read_office_project`.
+* `read_office_project(path)` returns an `OfficeProject`: the container's
+  `modules`, the `host` its extension implies, and `referenced_hosts`, the other
+  Office libraries its project references (`None` when the reference list could
+  not be read).
+* A `LoadedModule` carries a module's `name`, `kind`, and `source` (the code body
+  the analyzer reads), plus `designer_block`, the export header the reader stripped
+  ahead of `source` (empty when there was none).
 * Building blocks: `LoadedModule`, `strip_export_header`, `classify_module_kind`,
   `module_name_from_text`, `loaded_module_from_text`, `WorkbookReadError`,
-  `LOOSE_EXTENSIONS`, `EXCEL_EXTENSIONS`.
+  `LooseFileReadError`, and the extension sets `LOOSE_EXTENSIONS`,
+  `EXCEL_EXTENSIONS`, `WORD_EXTENSIONS`, `POWERPOINT_EXTENSIONS`,
+  `ACCESS_EXTENSIONS`, `OFFICE_EXTENSIONS`.
 
 ## Project model (`pyvbaanalysis.symbols`)
 
-* Index: `ProjectIndex`, `ProjectIndexOptions`, `ModuleInput`, `ReferenceScope`,
-  `ShadowedSpan`.
+* Index: `ProjectIndex`, `ProjectIndexOptions`, `ModuleInput`, `ImplicitMember`,
+  `ReferenceScope`, `ShadowedSpan`.
 * Module symbols: `build_module_symbols`, `BuildModuleSymbolsOptions`,
   `ModuleSymbols`, `ModuleSymbolKind`, `SymbolVisibility`, `VbaSymbol`,
   `VbaSymbolKind`, `VbaSymbolAttribute`, `VbaProcedureSignature`,
@@ -72,7 +88,9 @@ 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, Word, PowerPoint and Access host object models and the host registry (`get_excel_object_model`, `host_object_model_for_token`, `resolve_host_alias`, ...). |
+| `pyvbaanalysis.host` | The Excel, Word, PowerPoint, Access and VB6 object models and the host registry (`get_excel_object_model`, `get_vb6_object_model`, `host_object_model_for_token`, `resolve_host_alias`, ...). `host_object_model_for_tokens` merges the models for a project and its references, the first token winning a shared name; `host_token_for_libid`, `host_tokens_for_project` and `referenced_host_tokens` map a project's reference libids to host tokens. `pyvbaanalysis.host.msforms` carries the Microsoft Forms members of a UserForm and its controls (`msforms_control_members`, `resolve_msforms_type_name`). |
+| `pyvbaanalysis.references` | `classify_reference_kinds`: whether each mention of a name reads it, writes it, or modifies it in place. |
+| `pyvbaanalysis.docs` | The `'''` doc-comment grammar: `leading_doc_lines`, `scan_doc_tags`, `attached_comments_start`. |
 | `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-2.1.1 → pyvbaanalysis-2.2.1}/docs/diagnostics-catalogue.md

@@ -1,12 +1,12 @@
 # Diagnostic catalogue
 
-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.
+The diagnostic codes pyVBAanalysis can emit, generated from the rule metadata (`tools/generate_diagnostics_catalogue.py`). This table lists the 131 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 134 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.
 
 Override a code's severity with `AnalyzeModuleOptions.severity_overrides` (or the `severity_overrides` argument of `analyze_project` / the reader functions), keyed by code. Use `"off"`, `"information"`, `"warning"`, or `"error"`; the allowed values per code are constrained by policy (some codes can be downgraded but not disabled). See [docs/usage.md](usage.md).
 
-## Declaration (41)
+## Declaration (42)
 
 | Code | Title | Default | Kind | Spec reference |
 | --- | --- | --- | --- | --- |
@@ -29,6 +29,7 @@ Override a code's severity with `AnalyzeModuleOptions.severity_overrides` (or th
 | `invalid-identifier-character` | Invalid character in identifier | error | compile error | MS-VBAL 3.3.5 (identifier) / VBE compiler |
 | `invalid-identifier-start` | Invalid identifier start | error | compile error | MS-VBAL 3.3.5 |
 | `invalid-new-type-name` | Type cannot be created with New | error | compile error | MS-VBAL 5.2.3.1 / 5.6.9 |
+| `invalid-option-statement` | Malformed Option statement | error | compile error | MS-VBAL 5.2.1 (module options) / VBE compiler |
 | `invalid-proc-header` | Invalid procedure declaration | error | compile error | MS-VBAL 5.3.1 |
 | `module-declaration-after-procedure` | Module-level declaration after procedure | error | compile error | MS-VBAL 5.2 / 5.3 |
 | `module-declaration-in-procedure` | Module-level declaration inside procedure | error | compile error | MS-VBAL 5.2 / 5.3 |
@@ -57,7 +58,7 @@ Override a code's severity with `AnalyzeModuleOptions.severity_overrides` (or th
 | Code | Title | Default | Kind | Spec reference |
 | --- | --- | --- | --- | --- |
 | `event-declaration-module-kind` | Event declaration is not valid in this module | error | compile error | MS-VBAL 5.2.5: Event declarations belong to object modules |
-| `event-handler-module-scope` | Event handler is not wired in this module | information | style-policy | Excel document-module event binding |
+| `event-handler-module-scope` | Event handler is not wired in this module | information | style-policy | Office document-module event binding |
 | `friend-declaration` | Invalid Friend declaration | error | compile error | MS-VBAL Friend procedure visibility: object-module procedures only |
 | `implements-statement-placement` | Invalid Implements statement | error | compile error | MS-VBAL Implements statement: module-level object-module declaration |
 | `withevents-declaration` | Invalid WithEvents declaration | error | compile error | MS-VBAL 5.2.3: WithEvents object variable declarations |
@@ -69,7 +70,7 @@ 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 (51)
+## Semantic (52)
 
 | Code | Title | Default | Kind | Spec reference |
 | --- | --- | --- | --- | --- |
@@ -105,6 +106,7 @@ Override a code's severity with `AnalyzeModuleOptions.severity_overrides` (or th
 | `member-access-outside-with` | Leading member access outside With block | error | compile error | MS-VBAL 5.4.2.6 |
 | `member-not-found` | Object member not found | error | compile error | VBE compiler: Method or data member not found |
 | `mid-statement-literal-target` | Mid statement target must be a writable String variable | error | compile error | MS-VBAL 5.4.3.4 (Mid/MidB statement) |
+| `missing-library-reference` | Type library not referenced | error | compile error | VBE compiler: User-defined type not defined |
 | `missing-return-assignment` | Function has no return assignment | warning | runtime risk | VBA Function return variable semantics |
 | `next-variable-mismatch` | Next variable does not match active For loop | error | compile error | MS-VBAL 5.4.2.5 |
 | `non-callable-call` | Identifier is not callable | error | compile error | MS-VBAL 5.4.2.1 |
@@ -125,12 +127,22 @@ Override a code's severity with `AnalyzeModuleOptions.severity_overrides` (or th
 | `unallocated-dynamic-array-access` | Dynamic array is not allocated | error | runtime error | VBE runtime error 9: Subscript out of range |
 | `undefined-label` | Label not defined | error | compile error | MS-VBAL 5.4.1 / VBE compiler: Label not defined |
 
-## Style (3)
+## Style (13)
 
 | Code | Title | Default | Kind | Spec reference |
 | --- | --- | --- | --- | --- |
 | `analysis-suppression-directive` | Invalid analysis suppression directive | warning | style-policy | Analysis suppression directive comment syntax |
+| `doc-param-missing` | Doc comment does not describe a parameter | warning | style-policy | Doc comment syntax |
+| `doc-param-unknown` | Doc comment describes a parameter the declaration does not have | warning | style-policy | Doc comment syntax |
+| `doc-returns-missing` | Doc comment does not describe the return value | warning | style-policy | Doc comment syntax |
+| `doc-returns-unexpected` | Doc comment describes a return value the declaration does not have | warning | style-policy | Doc comment syntax |
+| `doc-tag-duplicate` | Doc comment repeats a tag | warning | style-policy | Doc comment syntax |
+| `doc-tag-unclosed` | Doc comment tag is not closed | warning | style-policy | Doc comment syntax |
 | `option-explicit-missing` | Option Explicit is not specified | warning | style-policy | MS-VBAL 5.2.4.1.1 |
+| `unreachable-code` | Code is never reached | information | style-policy | MS-VBAL 5.4.1.3 (Exit), 5.4.1.4 (GoTo), 5.4.4 (Resume) plus dead-code policy |
+| `unused-procedure` | Private procedure is never called | information | style-policy | MS-VBAL 5.3.1.1 (Private procedure visibility) plus dead-code policy |
+| `unused-variable` | Variable or constant is never used | information | style-policy | MS-VBAL 5.2.3 / 5.4.3.1 (declaration scope) plus dead-code policy |
+| `variable-never-read` | Variable is assigned but never read | information | style-policy | MS-VBAL 5.4.3 (assignment) plus dead-code policy |
 | `vba-test-directive` | Invalid VBA test directive | warning | style-policy | VBA test directive comment syntax |
 
 ## Syntax (17)