vb6decompiler 0.2.0__tar.gz

vb6decompiler-0.2.0/LICENSE

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

vb6decompiler-0.2.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: vb6decompiler
+Version: 0.2.0
+Summary: Evidence-based recovery of native-compiled VB6 programs: procedures, literals, SQL, form blobs, DataReports
+Author: vb6decompiler authors
+License: MIT
+Project-URL: Homepage, https://github.com/47Hunter47/vb6decompiler
+Keywords: vb6,reverse-engineering,decompiler,pe,sql-server
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pe
+Requires-Dist: pefile>=2023.2.7; extra == "pe"
+Provides-Extra: asm
+Requires-Dist: capstone>=5; extra == "asm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# vb6decompiler
+
+Recovering what a native-compiled VB6 program actually does, with evidence.
+
+Commercial VB6 decompilers stop at one of two walls: they give you forms without
+code, or code without the semantics that make it portable. This toolkit was built
+while recovering a large native-compiled VB6 application (111 MB, ~34,000
+procedures) whose source was lost. Every claim below is a measurement, and every
+measurement has a command that reproduces it.
+
+The point is not another disassembler. VB6 is not plain x86 at the level that
+matters: strings are length-prefixed `BSTR`s stored inside `.text`, procedures are
+entered through a fixed runtime prologue, most calls go through `MSVBVM60` vtable
+dispatch, forms are serialised into the executable as binary property blobs, and
+reports live in separate VB6 DLLs as `DataReport` blobs. Off-the-shelf tools read
+none of that. These modules do.
+
+Nothing here points at the program it was developed against: no target name, no
+host, no database name, no account, no credential, no absolute install path.
+**You supply every path.**
+
+## What it does
+
+| Stage | Command | Evidence it produces |
+|---|---|---|
+| PE surface of an install | `vb6d pe <dir>` | imports, exports, VB6 runtime dependency, ActiveX/COM classification |
+| Procedure inventory | `vb6d procs <exe>` | object table: objects and method counts, entry points verified by prologue |
+| String / SQL harvest | `vb6d literals <exe or listing dir>` | `BSTR` (UTF-16LE) literals the ASCII scanners miss, with code addresses |
+| SQL reconstruction | `vb6d stitch <dir or listing>` | fragments joined into whole statements, with explicit "not provable statically" buckets |
+| Form design | `vb6d frm <dir>` | controls, geometry, `Visible`, control arrays, `SSTab` pages from `.frm` text |
+| Form geometry from binary | `vb6d blob <exe> --validate` | geometry for forms that have no `.frm`, calibrated against `.frm` ground truth |
+| DataReport layout | `vb6d datareport <dll or dir>` | report sections, controls, captions recovered from the runtime blobs |
+| Form icons from `.frx` | `scripts/frx_icon.py <frx dir> <out> [--validate <frm dir>]` | standalone `.ico` per form, extracted from the leading ICON record without the executable; coverage cross-checked against `.frm` Icon references |
+| Credential gate | `vb6d mask <dir>` | files rewritten in place: connection strings redacted, then an audit counting what is still live |
+
+## You fill these in
+
+Every entry point takes a path; nothing is baked in. Real-target tests read five
+variables and skip when they are unset.
+
+| Variable | What you put in it |
+|---|---|
+| `VB6D_TARGET` | your VB6 executable, e.g. `D:/App/App.exe` or `/opt/app/App.exe` |
+| `VB6D_LISTINGS` | a directory of decompiler output: listing text carrying `'VA` address comments (the shape `docs/formats.md` §4 reads), plus `.frm` and `.frx` files |
+| `VB6D_FRM_DIR` | a directory holding `.frm` design text — ground truth for `--validate` |
+| `VB6D_REPORT_DIR` | the install directory holding the report DLLs |
+| `VB6D_SCRUB_DENYLIST` | optional: a private file, one name per line — names you refuse to publish. The hygiene test fails if any of them appears in this repository. |
+
+Set them for one command, or export them for a session:
+
+```bash
+# bash / zsh
+export VB6D_TARGET="/opt/app/App.exe"
+export VB6D_LISTINGS="$HOME/work/decompile"
+export VB6D_FRM_DIR="$HOME/work/decompile"
+export VB6D_REPORT_DIR="/opt/app"
+```
+
+```powershell
+# PowerShell
+$env:VB6D_TARGET     = "D:/App/App.exe"
+$env:VB6D_LISTINGS   = "D:/work/decompile"
+$env:VB6D_FRM_DIR    = "D:/work/decompile"
+$env:VB6D_REPORT_DIR = "D:/App"
+```
+
+## Why not an existing tool
+
+Measured on the same target (`docs/tool-matrix.md` has the full table, including
+how each number was obtained):
+
+* **Semi-VB-Decompiler** — the only free tool that recovers procedure *bodies*. It
+  is single-threaded, overflows its `Integer` procedure counter above 32,767
+  procedures (`Error 6`), needs a PE `LAA` bit patch to use more than 2 GB, and
+  writes one event name for every body in a form. Bodies are pseudo-source
+  (`var_64`, `arg_C`), not compilable code.
+* **VBReFormer** — forms and structure, expression bodies withheld without a
+  licence; cannot even accept the 111 MB executable (transport limit).
+* **Ghidra / Rizin / IDA** — no VB6 knowledge: no `BSTR` literals, no procedure
+  table, no form blobs, no `DataReport` blobs.
+* **Generic RE engines** — correct for C/C++/Rust/Go, blind to VB6 layout. One such
+  engine found 6,875 functions of 34,159 (20 %, stopped at its own instruction cap)
+  and 59 strings with zero SQL, because its string scanner does not read UTF-16LE
+  literals.
+
+None of these is wrong; they are aimed at C/C++/Rust/Go binaries. The gap this
+repository fills is VB6-specific structure, and it fills it with reproducible
+counts rather than vendor percentages.
+
+## Install
+
+```
+git clone <this repo> && cd vb6decompiler
+python -m pip install -e .
+```
+
+Python 3.11+. **Nothing outside the standard library is required** — every parser
+here is hand-written, which is the point (a library wrapper would hide the layout).
+`pefile` and `capstone` are optional and used only as a second opinion while
+developing:
+
+```
+python -m pip install -e ".[pe,asm]"
+```
+
+## Coding agents
+
+The repository ships as a plugin for coding agents as well as a pip package, so
+an agent can drive `vb6d` without a tutorial:
+
+```
+claude plugin marketplace add 47Hunter47/vb6decompiler
+claude plugin install vb6decompiler@vb6decompiler
+```
+
+One skill lives at `.agents/skills/vb6decompiler/SKILL.md` — the location both
+Claude Code and Codex read — and says when the tool applies, how to parse its
+output and which traps to avoid; the plugin manifests point at that single copy.
+Agents editing the repository itself follow `AGENTS.md`.
+
+## Quick start
+
+```
+vb6d pe            <install dir>                 # what is this install made of
+vb6d procs         <app.exe>                     # object table: objects, method counts
+vb6d procs         <app.exe> --validate          # are the entry points real prologues
+vb6d procs         <app.exe> --names <listing dir> # attach decompiler names/addresses
+vb6d literals      <app.exe>                     # BSTR/UTF-16 literals with addresses
+vb6d literals      <listing dir> --sql-only      # literals a decompiler listing produced
+vb6d stitch        <listing dir>                 # join fragments, classify what stayed open
+vb6d frm           <listing dir>                 # .frm controls, geometry, arrays, SSTab
+vb6d blob          <app.exe> --validate --frm-dir <frm dir>
+vb6d datareport    <install dir>                 # report layouts from the report DLLs
+vb6d mask          .                             # mask credentials in your artefacts
+vb6d mask          . --dry-run                   # report only; exit 1 if anything is live
+```
+
+Exit codes: 0 = completed, whatever it found; 1 = mask audit not clean; 2 =
+unusable input (one line on stderr, no traceback — set `VB6D_DEBUG=1` for the
+traceback when reporting a bug).
+
+What the reference build (111 MB, 802 forms) produced while this toolkit was
+developed, so you can tell at a glance whether your own numbers look sane:
+
+| Stage | Result |
+|---|---|
+| object table | 834 objects, 34,415 methods, 0.4 s |
+| literals from the image | 167,564 in 4.6 s (6,171 with a SQL verb) |
+| literals from a listing | 441,607 in 12,480 procedures |
+| statements | 10,691 starts → 8,745 closed in 4,109 procedures, 494 tables |
+| `.frm` design | 369 forms, 30,000 controls, 126 forms with control arrays |
+| form blobs | 801 blobs, 24,967/24,967 controls (100 %), 367/369 forms |
+| DataReports | 437 layouts (413 in report DLLs + 24 embedded in the executable) |
+
+A different program legitimately gives different numbers. The tests assert
+invariants and lower bounds, not these totals.
+
+## Using it well
+
+Run the stages in pipeline order; each one tells you whether the next is worth
+running. `docs/pipeline.md` states what every stage may claim and what it must
+never be used to claim.
+
+1. `vb6d pe <install dir>` first. It costs seconds and says what you have: which
+   binaries carry VB6 code, which are redistributables, where the report DLLs are.
+2. `vb6d procs`, then `--validate` before trusting anything downstream. Method
+   counts are cheap; entry points proven by their runtime prologue are evidence.
+   Addresses and names only exist once a decompiler listing is merged in with
+   `--names`.
+3. `vb6d literals` on the executable gives UTF-16 text with addresses; on a
+   listing it gives procedure ownership, and that ownership is what makes
+   `vb6d stitch` possible at all.
+4. `vb6d stitch` reports what stayed open as open. The gap buckets are not noise:
+   `OPEN_QUOTE` means a run-time value is missing, and no smarter regex closes
+   it.
+5. `vb6d frm` reads the design text; `vb6d blob --validate` calibrates the binary
+   reader against it. Trust blob geometry for forms that have no `.frm` exactly
+   as far as that calibration holds.
+6. Count embedded reports when you run `vb6d datareport`. A scan limited to
+   `rpt*.dll` misses 24 of the 437 layouts the reference build carries inside its
+   own executable.
+7. `vb6d mask . --dry-run` before sharing anything you produced. A non-zero exit
+   means the artefacts are not publishable, not that you should retry quietly.
+
+Things that cost days to learn:
+
+* Procedure names do not exist in a native build. A decompiler's names are
+  guesses and `.frm` event names repeat; treat every name as a hint and every
+  prologue-verified address as the better fact.
+* If a string scanner reports zero SQL on a VB6 binary, ask whether it reads
+  UTF-16LE at all. One engine reported 59 strings and zero SQL on a build that
+  holds 167,564 `BSTR` literals, 6,171 of them with a SQL verb.
+* Compare shapes, not totals: literals per procedure, closed versus open
+  statements, controls per form. Totals scale with the program; the tests assert
+  invariants for the same reason.
+* When a free decompiler refuses a large executable, run `scripts/semi_laa.py`
+  on a copy. The Large Address Aware bit is a property of the file, not of the
+  tool's competence.
+* Three-state flags such as `Visible` and `Locked` have defaults that look like
+  explicit values, and `docs/pitfalls.md` lists that class of trap with the
+  measurement that proved each one.
+
+## Honest limits
+
+* Procedure **names** are not recoverable from a native build; only addresses and
+  the names a decompiler guessed.
+* Bodies recovered by a third-party decompiler are pseudo-source. Expression-level
+  fidelity does not exist in any free tool measured here.
+* SQL that is built at run time (concatenated from variables) cannot be closed
+  statically. `vb6d stitch` reports those gaps as gaps instead of guessing.
+* Geometry recovered from the binary is calibrated, not exact for forms that
+  changed after the `.frm` in hand was written; `--validate` says so per form.
+* The toolkit is calibrated on native-compiled builds; a P-Code build is outside
+  that calibration and was not tested here. If `vb6d procs --validate` reports no
+  real prologues in your build, suspect a P-Code compile before suspecting the
+  toolkit.
+* The parsers know the grammar of the reference build. Another program ships
+  different controls, property sets and report sections, so expect more `unknown`
+  lines than the reference numbers show. An un-calibrated construct is reported as
+  unknown, never guessed (`docs/formats.md` §7), and no stage drops a file
+  silently: failures are counted and named.
+
+## Layout
+
+```
+vb6decompiler/     the library (one module per stage, stdlib only except pefile/capstone)
+scripts/          standalone helpers (semi_laa.py: set the LAA bit on a copy;
+                  frx_icon.py: extract the leading ICON record of a .frx;
+                  win32_gui_probe.py: drive vendor GUI tools headlessly when the
+                  measurement only exists in a window)
+tests/            unit tests + target tests that skip unless VB6D_TARGET is set
+docs/             formats.md (structures), pitfalls.md (traps), tool-matrix.md,
+                  pipeline.md (stages and what each may claim), RULES.md
+.agents/skills/   the vb6decompiler skill — what a coding agent installs
+.claude-plugin/   Claude Code plugin + marketplace manifests (skills point at it)
+.codex-plugin/    Codex plugin manifest (same single skill copy)
+```
+
+Run the tests:
+
+```
+pip install -e ".[dev]"
+pytest -q                                            # unit tests, no target needed
+VB6D_TARGET="C:/path/App.exe" pytest -q              # + real-target invariants
+VB6D_LISTINGS="C:/path/decompile" pytest -q          # + listing/stitching tests
+VB6D_FRM_DIR="C:/path/decompile" pytest -q           # + blob calibration
+VB6D_REPORT_DIR="C:/path/install" pytest -q          # + DataReport parsing
+```
+
+`docs/formats.md` is the structure reference: every offset, every grammar, and the
+fields that look documented but are not what they claim (`lpMethods` in a native
+build, `lpGuiTable`). `docs/pitfalls.md` is the second most useful file: it lists
+the traps that cost days (double-`Integer` overflow, `OriginalFirstThunk` vs
+`FirstThunk`, CP1254 vs UTF-16, `Visible` defaults, blob property sorting) with the
+measurement that
+proved each one.
+
+## Licence
+
+MIT. See `LICENSE`.

vb6decompiler-0.2.0/README.md

@@ -0,0 +1,260 @@
+# vb6decompiler
+
+Recovering what a native-compiled VB6 program actually does, with evidence.
+
+Commercial VB6 decompilers stop at one of two walls: they give you forms without
+code, or code without the semantics that make it portable. This toolkit was built
+while recovering a large native-compiled VB6 application (111 MB, ~34,000
+procedures) whose source was lost. Every claim below is a measurement, and every
+measurement has a command that reproduces it.
+
+The point is not another disassembler. VB6 is not plain x86 at the level that
+matters: strings are length-prefixed `BSTR`s stored inside `.text`, procedures are
+entered through a fixed runtime prologue, most calls go through `MSVBVM60` vtable
+dispatch, forms are serialised into the executable as binary property blobs, and
+reports live in separate VB6 DLLs as `DataReport` blobs. Off-the-shelf tools read
+none of that. These modules do.
+
+Nothing here points at the program it was developed against: no target name, no
+host, no database name, no account, no credential, no absolute install path.
+**You supply every path.**
+
+## What it does
+
+| Stage | Command | Evidence it produces |
+|---|---|---|
+| PE surface of an install | `vb6d pe <dir>` | imports, exports, VB6 runtime dependency, ActiveX/COM classification |
+| Procedure inventory | `vb6d procs <exe>` | object table: objects and method counts, entry points verified by prologue |
+| String / SQL harvest | `vb6d literals <exe or listing dir>` | `BSTR` (UTF-16LE) literals the ASCII scanners miss, with code addresses |
+| SQL reconstruction | `vb6d stitch <dir or listing>` | fragments joined into whole statements, with explicit "not provable statically" buckets |
+| Form design | `vb6d frm <dir>` | controls, geometry, `Visible`, control arrays, `SSTab` pages from `.frm` text |
+| Form geometry from binary | `vb6d blob <exe> --validate` | geometry for forms that have no `.frm`, calibrated against `.frm` ground truth |
+| DataReport layout | `vb6d datareport <dll or dir>` | report sections, controls, captions recovered from the runtime blobs |
+| Form icons from `.frx` | `scripts/frx_icon.py <frx dir> <out> [--validate <frm dir>]` | standalone `.ico` per form, extracted from the leading ICON record without the executable; coverage cross-checked against `.frm` Icon references |
+| Credential gate | `vb6d mask <dir>` | files rewritten in place: connection strings redacted, then an audit counting what is still live |
+
+## You fill these in
+
+Every entry point takes a path; nothing is baked in. Real-target tests read five
+variables and skip when they are unset.
+
+| Variable | What you put in it |
+|---|---|
+| `VB6D_TARGET` | your VB6 executable, e.g. `D:/App/App.exe` or `/opt/app/App.exe` |
+| `VB6D_LISTINGS` | a directory of decompiler output: listing text carrying `'VA` address comments (the shape `docs/formats.md` §4 reads), plus `.frm` and `.frx` files |
+| `VB6D_FRM_DIR` | a directory holding `.frm` design text — ground truth for `--validate` |
+| `VB6D_REPORT_DIR` | the install directory holding the report DLLs |
+| `VB6D_SCRUB_DENYLIST` | optional: a private file, one name per line — names you refuse to publish. The hygiene test fails if any of them appears in this repository. |
+
+Set them for one command, or export them for a session:
+
+```bash
+# bash / zsh
+export VB6D_TARGET="/opt/app/App.exe"
+export VB6D_LISTINGS="$HOME/work/decompile"
+export VB6D_FRM_DIR="$HOME/work/decompile"
+export VB6D_REPORT_DIR="/opt/app"
+```
+
+```powershell
+# PowerShell
+$env:VB6D_TARGET     = "D:/App/App.exe"
+$env:VB6D_LISTINGS   = "D:/work/decompile"
+$env:VB6D_FRM_DIR    = "D:/work/decompile"
+$env:VB6D_REPORT_DIR = "D:/App"
+```
+
+## Why not an existing tool
+
+Measured on the same target (`docs/tool-matrix.md` has the full table, including
+how each number was obtained):
+
+* **Semi-VB-Decompiler** — the only free tool that recovers procedure *bodies*. It
+  is single-threaded, overflows its `Integer` procedure counter above 32,767
+  procedures (`Error 6`), needs a PE `LAA` bit patch to use more than 2 GB, and
+  writes one event name for every body in a form. Bodies are pseudo-source
+  (`var_64`, `arg_C`), not compilable code.
+* **VBReFormer** — forms and structure, expression bodies withheld without a
+  licence; cannot even accept the 111 MB executable (transport limit).
+* **Ghidra / Rizin / IDA** — no VB6 knowledge: no `BSTR` literals, no procedure
+  table, no form blobs, no `DataReport` blobs.
+* **Generic RE engines** — correct for C/C++/Rust/Go, blind to VB6 layout. One such
+  engine found 6,875 functions of 34,159 (20 %, stopped at its own instruction cap)
+  and 59 strings with zero SQL, because its string scanner does not read UTF-16LE
+  literals.
+
+None of these is wrong; they are aimed at C/C++/Rust/Go binaries. The gap this
+repository fills is VB6-specific structure, and it fills it with reproducible
+counts rather than vendor percentages.
+
+## Install
+
+```
+git clone <this repo> && cd vb6decompiler
+python -m pip install -e .
+```
+
+Python 3.11+. **Nothing outside the standard library is required** — every parser
+here is hand-written, which is the point (a library wrapper would hide the layout).
+`pefile` and `capstone` are optional and used only as a second opinion while
+developing:
+
+```
+python -m pip install -e ".[pe,asm]"
+```
+
+## Coding agents
+
+The repository ships as a plugin for coding agents as well as a pip package, so
+an agent can drive `vb6d` without a tutorial:
+
+```
+claude plugin marketplace add 47Hunter47/vb6decompiler
+claude plugin install vb6decompiler@vb6decompiler
+```
+
+One skill lives at `.agents/skills/vb6decompiler/SKILL.md` — the location both
+Claude Code and Codex read — and says when the tool applies, how to parse its
+output and which traps to avoid; the plugin manifests point at that single copy.
+Agents editing the repository itself follow `AGENTS.md`.
+
+## Quick start
+
+```
+vb6d pe            <install dir>                 # what is this install made of
+vb6d procs         <app.exe>                     # object table: objects, method counts
+vb6d procs         <app.exe> --validate          # are the entry points real prologues
+vb6d procs         <app.exe> --names <listing dir> # attach decompiler names/addresses
+vb6d literals      <app.exe>                     # BSTR/UTF-16 literals with addresses
+vb6d literals      <listing dir> --sql-only      # literals a decompiler listing produced
+vb6d stitch        <listing dir>                 # join fragments, classify what stayed open
+vb6d frm           <listing dir>                 # .frm controls, geometry, arrays, SSTab
+vb6d blob          <app.exe> --validate --frm-dir <frm dir>
+vb6d datareport    <install dir>                 # report layouts from the report DLLs
+vb6d mask          .                             # mask credentials in your artefacts
+vb6d mask          . --dry-run                   # report only; exit 1 if anything is live
+```
+
+Exit codes: 0 = completed, whatever it found; 1 = mask audit not clean; 2 =
+unusable input (one line on stderr, no traceback — set `VB6D_DEBUG=1` for the
+traceback when reporting a bug).
+
+What the reference build (111 MB, 802 forms) produced while this toolkit was
+developed, so you can tell at a glance whether your own numbers look sane:
+
+| Stage | Result |
+|---|---|
+| object table | 834 objects, 34,415 methods, 0.4 s |
+| literals from the image | 167,564 in 4.6 s (6,171 with a SQL verb) |
+| literals from a listing | 441,607 in 12,480 procedures |
+| statements | 10,691 starts → 8,745 closed in 4,109 procedures, 494 tables |
+| `.frm` design | 369 forms, 30,000 controls, 126 forms with control arrays |
+| form blobs | 801 blobs, 24,967/24,967 controls (100 %), 367/369 forms |
+| DataReports | 437 layouts (413 in report DLLs + 24 embedded in the executable) |
+
+A different program legitimately gives different numbers. The tests assert
+invariants and lower bounds, not these totals.
+
+## Using it well
+
+Run the stages in pipeline order; each one tells you whether the next is worth
+running. `docs/pipeline.md` states what every stage may claim and what it must
+never be used to claim.
+
+1. `vb6d pe <install dir>` first. It costs seconds and says what you have: which
+   binaries carry VB6 code, which are redistributables, where the report DLLs are.
+2. `vb6d procs`, then `--validate` before trusting anything downstream. Method
+   counts are cheap; entry points proven by their runtime prologue are evidence.
+   Addresses and names only exist once a decompiler listing is merged in with
+   `--names`.
+3. `vb6d literals` on the executable gives UTF-16 text with addresses; on a
+   listing it gives procedure ownership, and that ownership is what makes
+   `vb6d stitch` possible at all.
+4. `vb6d stitch` reports what stayed open as open. The gap buckets are not noise:
+   `OPEN_QUOTE` means a run-time value is missing, and no smarter regex closes
+   it.
+5. `vb6d frm` reads the design text; `vb6d blob --validate` calibrates the binary
+   reader against it. Trust blob geometry for forms that have no `.frm` exactly
+   as far as that calibration holds.
+6. Count embedded reports when you run `vb6d datareport`. A scan limited to
+   `rpt*.dll` misses 24 of the 437 layouts the reference build carries inside its
+   own executable.
+7. `vb6d mask . --dry-run` before sharing anything you produced. A non-zero exit
+   means the artefacts are not publishable, not that you should retry quietly.
+
+Things that cost days to learn:
+
+* Procedure names do not exist in a native build. A decompiler's names are
+  guesses and `.frm` event names repeat; treat every name as a hint and every
+  prologue-verified address as the better fact.
+* If a string scanner reports zero SQL on a VB6 binary, ask whether it reads
+  UTF-16LE at all. One engine reported 59 strings and zero SQL on a build that
+  holds 167,564 `BSTR` literals, 6,171 of them with a SQL verb.
+* Compare shapes, not totals: literals per procedure, closed versus open
+  statements, controls per form. Totals scale with the program; the tests assert
+  invariants for the same reason.
+* When a free decompiler refuses a large executable, run `scripts/semi_laa.py`
+  on a copy. The Large Address Aware bit is a property of the file, not of the
+  tool's competence.
+* Three-state flags such as `Visible` and `Locked` have defaults that look like
+  explicit values, and `docs/pitfalls.md` lists that class of trap with the
+  measurement that proved each one.
+
+## Honest limits
+
+* Procedure **names** are not recoverable from a native build; only addresses and
+  the names a decompiler guessed.
+* Bodies recovered by a third-party decompiler are pseudo-source. Expression-level
+  fidelity does not exist in any free tool measured here.
+* SQL that is built at run time (concatenated from variables) cannot be closed
+  statically. `vb6d stitch` reports those gaps as gaps instead of guessing.
+* Geometry recovered from the binary is calibrated, not exact for forms that
+  changed after the `.frm` in hand was written; `--validate` says so per form.
+* The toolkit is calibrated on native-compiled builds; a P-Code build is outside
+  that calibration and was not tested here. If `vb6d procs --validate` reports no
+  real prologues in your build, suspect a P-Code compile before suspecting the
+  toolkit.
+* The parsers know the grammar of the reference build. Another program ships
+  different controls, property sets and report sections, so expect more `unknown`
+  lines than the reference numbers show. An un-calibrated construct is reported as
+  unknown, never guessed (`docs/formats.md` §7), and no stage drops a file
+  silently: failures are counted and named.
+
+## Layout
+
+```
+vb6decompiler/     the library (one module per stage, stdlib only except pefile/capstone)
+scripts/          standalone helpers (semi_laa.py: set the LAA bit on a copy;
+                  frx_icon.py: extract the leading ICON record of a .frx;
+                  win32_gui_probe.py: drive vendor GUI tools headlessly when the
+                  measurement only exists in a window)
+tests/            unit tests + target tests that skip unless VB6D_TARGET is set
+docs/             formats.md (structures), pitfalls.md (traps), tool-matrix.md,
+                  pipeline.md (stages and what each may claim), RULES.md
+.agents/skills/   the vb6decompiler skill — what a coding agent installs
+.claude-plugin/   Claude Code plugin + marketplace manifests (skills point at it)
+.codex-plugin/    Codex plugin manifest (same single skill copy)
+```
+
+Run the tests:
+
+```
+pip install -e ".[dev]"
+pytest -q                                            # unit tests, no target needed
+VB6D_TARGET="C:/path/App.exe" pytest -q              # + real-target invariants
+VB6D_LISTINGS="C:/path/decompile" pytest -q          # + listing/stitching tests
+VB6D_FRM_DIR="C:/path/decompile" pytest -q           # + blob calibration
+VB6D_REPORT_DIR="C:/path/install" pytest -q          # + DataReport parsing
+```
+
+`docs/formats.md` is the structure reference: every offset, every grammar, and the
+fields that look documented but are not what they claim (`lpMethods` in a native
+build, `lpGuiTable`). `docs/pitfalls.md` is the second most useful file: it lists
+the traps that cost days (double-`Integer` overflow, `OriginalFirstThunk` vs
+`FirstThunk`, CP1254 vs UTF-16, `Visible` defaults, blob property sorting) with the
+measurement that
+proved each one.
+
+## Licence
+
+MIT. See `LICENSE`.

vb6decompiler-0.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vb6decompiler"
+version = "0.2.0"
+description = "Evidence-based recovery of native-compiled VB6 programs: procedures, literals, SQL, form blobs, DataReports"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "vb6decompiler authors" }]
+keywords = ["vb6", "reverse-engineering", "decompiler", "pe", "sql-server"]
+
+[project.urls]
+Homepage = "https://github.com/47Hunter47/vb6decompiler"
+
+[project.optional-dependencies]
+pe = ["pefile>=2023.2.7"]
+asm = ["capstone>=5"]
+dev = ["pytest>=8"]
+
+[project.scripts]
+vb6d = "vb6decompiler.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vb6decompiler*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

vb6decompiler-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+