fantasm 0.1.2__tar.gz

fantasm-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  readme-check:
+    # Belt-and-braces against contributors who bypass the pre-commit
+    # hook. Same job is reused by release.yml as a publication gate.
+    uses: ./.github/workflows/readme-check.yml

fantasm-0.1.2/.github/workflows/readme-check.yml

@@ -0,0 +1,28 @@
+name: README check
+
+# Reusable workflow: verifies that README.md is in sync with the
+# generator (scripts/generate_readme.py). Called by ci.yml on push/PR
+# and by release.yml as a publication gate so a v-tag with a stale
+# README is held back from PyPI.
+
+on:
+  workflow_call:
+
+jobs:
+  check:
+    name: README.md is in sync with the generator
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install dev dependencies
+        run: uv sync
+
+      - name: Verify README.md matches the generator's output
+        run: uv run python scripts/generate_readme.py --check

fantasm-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+# Atomic release workflow: on a `v*` tag produced by bump-my-version,
+# runs the full test matrix and the README sync check in parallel as
+# two gates. Only when BOTH gates are green does publish-pypi run.
+#
+# `workflow_dispatch` is enabled so a release can be re-attempted
+# manually if the publish step fails transiently after the gates
+# pass. Individual failed jobs can also be re-run from the Actions UI.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+# Default read-only permissions for the workflow; the publishing job
+# narrows its own permissions to what it actually needs.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    # Reuses the matrix defined in test.yml so CI and Release exercise
+    # the exact same test surface against the built wheel.
+    uses: ./.github/workflows/test.yml
+
+  readme-check:
+    # Same gate ci.yml runs on every push.
+    uses: ./.github/workflows/readme-check.yml
+
+  publish-pypi:
+    name: Publish to PyPI
+    # Both gates must pass before publication. If either fails, this
+    # job does not run.
+    needs: [test, readme-check]
+    runs-on: ubuntu-latest
+    # The `pypi` GitHub deployment environment is the gate for the
+    # PYPI_TOKEN secret (and/or trusted-publishing OIDC config).
+    environment:
+      name: pypi
+      url: https://pypi.org/project/fantasm/
+    permissions:
+      # Required if/when the project opts into PyPI trusted publishing
+      # via OIDC. Harmless when using a token instead.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        # Uses UV_PUBLISH_TOKEN if set; otherwise uv falls back to
+        # PyPI trusted publishing via the OIDC token minted by
+        # GitHub (works when the project is registered as a trusted
+        # publisher under the `pypi` environment).
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

fantasm-0.1.2/.github/workflows/test.yml

@@ -0,0 +1,90 @@
+name: Test
+
+# Reusable workflow: builds a wheel and runs the test suite against the
+# installed wheel (not the source tree) on a matrix of OS x Python
+# version. Called by ci.yml on push/PR so verification always exercises
+# the exact artefact shape users will install -- catching packaging
+# regressions like missing package data, omitted entry points, or an
+# unshipped py.typed marker that an editable install would hide.
+
+on:
+  workflow_call:
+
+jobs:
+  resolve-python-versions:
+    name: Resolve supported Python versions from pyproject classifiers
+    runs-on: ubuntu-latest
+    outputs:
+      versions: ${{ steps.extract.outputs.versions }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: extract
+        name: Pick earliest + latest declared Python version
+        # Reading the supported versions from the classifiers keeps the CI
+        # matrix in sync with the published metadata. ubuntu-latest ships
+        # a stdlib tomllib-capable Python (>=3.11).
+        run: |
+          versions=$(python - <<'PY'
+          import json
+          import re
+          import tomllib
+          from pathlib import Path
+
+          data = tomllib.loads(Path("pyproject.toml").read_text())
+          declared = sorted(
+              (
+                  c.rsplit(" :: ", 1)[-1]
+                  for c in data["project"]["classifiers"]
+                  if re.match(r"^Programming Language :: Python :: 3\.\d+$", c)
+              ),
+              key=lambda v: tuple(map(int, v.split("."))),
+          )
+          if not declared:
+              raise SystemExit("No 'Programming Language :: Python :: 3.x' classifiers found")
+          selected = [declared[0], declared[-1]] if len(declared) >= 2 else declared
+          print(json.dumps(selected))
+          PY
+          )
+          echo "versions=$versions" >> "$GITHUB_OUTPUT"
+
+  test:
+    name: Test on ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    needs: resolve-python-versions
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ${{ fromJson(needs.resolve-python-versions.outputs.versions) }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache-dependency-glob: pyproject.toml
+
+      - name: Install dependency environment (without fantasm itself)
+        # Sync all dev/test deps into the venv but skip installing the
+        # fantasm project. We install it from a freshly built wheel below
+        # so tests exercise the distribution artefact rather than the
+        # source tree.
+        run: uv sync --no-install-project
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Install the built wheel into the test environment
+        # Force bash so dist/*.whl globs on Windows runners too (default
+        # pwsh does not glob the same way).
+        shell: bash
+        run: uv pip install dist/*.whl
+
+      - name: Run tests against the installed wheel
+        # --no-sync keeps the existing venv (with the wheel-installed
+        # fantasm) intact; without it `uv run` would re-sync and
+        # reinstate an editable install of the source tree, defeating
+        # the point. Confirmed locally that the test process imports
+        # fantasm from site-packages.
+        run: uv run --no-sync pytest -v

fantasm-0.1.2/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+share/python-wheels/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+# Fantasm is a library as much as an application; consumers resolve
+# their own dependency versions, so uv.lock stays out of git.
+uv.lock
+
+# Environments / secrets
+.env
+.env.*
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Project-local scratch
+scratch/
+tmp/

fantasm-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: local
+    hooks:
+      - id: generate-readme-check
+        name: README.md is in sync with the generator
+        entry: uv run python scripts/generate_readme.py --check
+        language: system
+        pass_filenames: false
+        files: |
+          (?x)^(
+            README\.md
+            | scripts/generate_readme\.py
+            | scripts/readme_template\.md\.j2
+            | src/fantasm/.*\.py
+          )$

fantasm-0.1.2/CLAUDE.md

@@ -0,0 +1,138 @@
+# Fantasm — guidance for AI assistants
+
+Project goal: consolidate 6502 disassembly tooling from four sibling
+acornaeology repositories (`acorn-6502-tube-client`, `acorn-adfs`,
+`acorn-econet-bridge`, `acorn-nfs`) into a single `fantasm` package with a
+Click CLI and a programmatic `fantasm.api` package.
+
+## Layout
+
+- `src/fantasm/` — package
+- `src/fantasm/cli.py` — Click entrypoint, hierarchical sub-command groups
+- `src/fantasm/api/` — programmatic API; flat re-exports from `__init__.py`
+- `src/fantasm/config.py` — project-root resolution and `fantasm.toml` loading
+- `tests/` — pytest suite with shared fixtures in `conftest.py`
+- `docs/` — user/developer docs
+
+## Testing strategy
+
+The original code being consolidated has **no tests**. As code is ported in
+we add tests, but the approach is constrained by the recovery context:
+
+- We cannot TDD pre-existing behaviour. Instead, write **characterisation
+  tests** that pin down current observable behaviour on representative
+  inputs. These are the safety net that lets us merge the four divergent
+  forks and refactor afterwards.
+- Prefer small hand-crafted fixtures (a few bytes, a tiny `.asm` file) over
+  full ROM dumps — fast, reviewable, and easy to reason about.
+- For modules that emit assembly source, write **round-trip tests** that
+  assemble the output with `beebasm` and compare the resulting bytes to the
+  original input.
+
+See `docs/testing.md` for a fuller treatment.
+
+## README is generated, not hand-written
+
+`README.md` is produced by `scripts/generate_readme.py` from a Jinja2
+template at `scripts/readme_template.md.j2`. The generator imports
+`fantasm.cli.main` and runs it via `click.testing.CliRunner` (inside
+`isolated_filesystem`, with `COLUMNS=80` / `NO_COLOR=1` and
+`FANTASM_PROJECT_ROOT` cleared) to capture deterministic `--help` text
+and a sample `info` table.
+
+```bash
+uv run python scripts/generate_readme.py           # regenerate README.md
+uv run python scripts/generate_readme.py --check   # verify; prints diff + exits 1 on drift
+```
+
+A pre-commit hook (`.pre-commit-config.yaml`) runs the `--check`
+variant whenever `README.md`, the generator, the template, or any
+`src/fantasm/*.py` changes — so editing the public CLI surface forces
+a README regeneration before the commit lands. First-time setup in a
+fresh clone:
+
+```bash
+uv run pre-commit install
+```
+
+A `readme-check` job in `.github/workflows/ci.yml` runs the same
+`--check` on every push and PR as a safety net for contributors who
+bypass the local hook. **Never hand-edit `README.md`** — edit the
+template (or the generator, or the CLI source) and re-run the
+generator.
+
+## External tooling assumed available
+
+- **py8dis** (the disassembler that produces the JSON / ASM /
+  driver-script artefacts fantasm operates on) — a workflow
+  prerequisite, **not** a runtime dependency of fantasm. Users are
+  expected to have it installed in their development environment to
+  generate disassembly output; fantasm consumes the artefacts and
+  never imports the package. Currently a private fork at
+  https://github.com/acornaeology/py8dis; will eventually be
+  published on PyPI as `msabeeb`. Don't list it in `[project]
+  dependencies` — PyPI rejects direct git-URL deps and fantasm
+  doesn't actually link against it.
+- **beebasm** (the BBC Micro 6502 cross-assembler) — assumed on `PATH`.
+  Tests obtain its location via the `beebasm_filepath` fixture in
+  `tests/conftest.py` and skip cleanly when it is absent.
+- **uv** for dependency management. Use `uv sync` and `uv run`.
+
+## Project-root resolution
+
+Three-step lookup, highest priority first:
+
+1. `--project-root` on the top-level `fantasm` group
+2. `FANTASM_PROJECT_ROOT` environment variable
+3. Walk upwards from cwd looking for `fantasm.toml`
+
+Commands that need a project root should check `ctx.obj["project"].has_root`
+and fail with a clear message if unresolved.
+
+## Output formatting
+
+Commands that produce structured results use `asyoulikeit.report_output`,
+which gives them a uniform `--as display|tsv|json` story. See
+`src/fantasm/cli.py::info` for the canonical pattern. When a command needs
+the Click context, use `click.get_current_context()` inside the body
+rather than mixing `@click.pass_context` with `@report_output`.
+
+## Versioning and releases
+
+Version is managed via `bump-my-version` (configured in `pyproject.toml`
+under `[tool.bumpversion]`). The single source of truth is `__version__`
+in `src/fantasm/__init__.py`; hatchling reads it dynamically via
+`[tool.hatch.version]` and exposes it as the wheel's installed version.
+Do not edit the version by hand in more than one place — let
+`bump-my-version` update both the module and the
+`[tool.bumpversion] current_version` copy in lock-step.
+
+Release flow (on a clean working tree, from `master`):
+
+```bash
+uv run bump-my-version bump --dry-run --verbose patch   # preview
+uv run bump-my-version bump patch                       # or `minor` / `major`
+git push --follow-tags                                  # publish commit + v<X.Y.Z> tag
+```
+
+Each real bump produces one commit (`Bump version: X.Y.Z → X.Y.Z+1`) and
+one annotated tag (`vX.Y.Z+1`). bump-my-version refuses to run with a
+dirty tree — that is the intended safety net.
+
+A `release.yml` workflow triggers on `v*` tags (the ones
+`bump-my-version` produces) plus manual `workflow_dispatch`. Two
+parallel gates — the full test matrix from `test.yml` and the
+README-sync check from `readme-check.yml` — feed a single
+`publish-pypi` job. Nothing is published unless **both** gates are
+green. PyPI publication uses `uv publish` with `UV_PUBLISH_TOKEN`
+from the `PYPI_TOKEN` repo secret, scoped to the `pypi` GitHub
+deployment environment. To release: bump the version, push the
+`v<X.Y.Z>` tag, watch the Actions UI. A failed publish can be
+re-attempted via the **Run workflow** button.
+
+## Naming conventions
+
+- Use `_filename`, `_filepath`, `_dirpath`, `_dirname` suffixes; avoid the
+  ambiguous `_dir` / `_file` suffixes.
+- Keep code comments and commit messages free of references to specific AI
+  tools or model providers.

fantasm-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+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.

fantasm-0.1.2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: fantasm
+Version: 0.1.2
+Summary: Fantasm — the Fantastic (dis-/re-)Assembly tools for 6502 code
+Author: Robert Smallshire
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Disassemblers
+Requires-Python: >=3.12
+Requires-Dist: asyoulikeit>=0.1
+Requires-Dist: click>=8.1
+Requires-Dist: networkx>=3.0
+Description-Content-Type: text/markdown
+
+# Fantasm
+
+The Fantastic (dis-/re-)Assembly tools for 6502 code, version `0.1.2`.
+
+Fantasm is a consolidated suite of tools for working on annotated
+disassemblies of 6502-based ROMs (originally those from the Acorn / BBC
+Microcomputer family). It brings together capabilities that previously
+lived in per-project forks under the `acornaeology` umbrella, behind a
+single `fantasm` command and a programmatic `fantasm.api` package.
+
+## Status
+
+Early scaffolding. The CLI shell is in place; the consolidation of
+per-project tools into `fantasm` is in progress.
+
+## Install (development)
+
+```sh
+uv sync
+```
+
+## CLI
+
+```console
+$ fantasm --help
+Usage: fantasm [OPTIONS] COMMAND [ARGS]...
+
+  Fantasm — the Fantastic (dis-/re-)Assembly tools for 6502 code.
+
+Options:
+  --version                 Show the version and exit.
+  --project-root DIRECTORY  Project root directory. Overrides
+                            FANTASM_PROJECT_ROOT. If neither is given, fantasm
+                            searches upwards from the current directory for a
+                            fantasm.toml.
+  -h, --help                Show this message and exit.
+
+Commands:
+  addresses    Address translation across ROM versions.
+  annotations  Cross-version annotation diff and management.
+  asm          Assembly-source extraction and inspection.
+  audit        Subroutine annotation audit.
+  backfill     Propose annotation propagations from SOURCE_VERSION to...
+  cfg          Inter-procedural call-graph queries.
+  comments     Comment / annotation consistency checks.
+  compare      Compare two ROM versions at byte / opcode / full-instruction...
+  context      Code context queries (depth, sub-context, uncommented gaps).
+  fingerprint  Fingerprint each block of a ROM version's bytes and report...
+  info         Show the resolved project context.
+  labels       Auto-generated label classification and renaming.
+  lint         Validate that a driver script's annotation addresses...
+  project      Initialise and manage fantasm projects.
+  promote      Score labelled code items as candidates for promotion to...
+  shared       Find shared 6502 code fragments between a primary ROM and...
+  sub          Subroutine workflow helpers.
+  verify       Verify a disassembly round-trips: assemble its .asm with...
+```
+
+The top-level `fantasm` command accepts a `--project-root` option and
+also reads `FANTASM_PROJECT_ROOT` from the environment. When neither is
+given, fantasm walks upwards from the current working directory looking
+for a `fantasm.toml` to identify the project root.
+
+### `fantasm info`
+
+The `info` sub-command shows the resolved project context for the
+current invocation. Like every fantasm command that produces structured
+output, it inherits a uniform `--as display | tsv | json` story (and
+friends) from
+[asyoulikeit](https://github.com/sixty-north/asyoulikeit):
+
+```console
+$ fantasm info --help
+Usage: fantasm info [OPTIONS]
+
+  Show the resolved project context.
+
+Options:
+  Report Output Options: 
+    --no-reports              Suppress all report output. The handler still runs
+                              (useful for action commands whose reports are
+                              incidental); only rendering is skipped. Mutually
+                              exclusive with --report and --all-reports.
+    --all-reports             Render every report the handler returns,
+                              regardless of the command's default_reports.
+                              Useful for commands whose default is a subset (or
+                              silent) but where you want the full picture this
+                              time. Mutually exclusive with --report and --no-
+                              reports.
+    --report [project]        Report name(s) to display (can be specified
+                              multiple times). Shows all if omitted. Valid
+                              values: project.
+    --header / --no-header    Include column headers in output. Overrides each
+                              report's default. Format-specific: TSV prefixes
+                              first cell with '#', display omits
+                              headers/title/caption, JSON ignores this flag.
+    --detailed / --essential  Include detailed columns or only essential
+                              columns. Auto-detects based on output format if
+                              not specified.
+    --as [display|json|tsv]   Output format for tabular data. Defaults to
+                              'display' for terminals, 'tsv' for pipes.
+  -h, --help                  Show this message and exit.
+```
+
+Sample output (an explicit project root that does not contain a
+`fantasm.toml`):
+
+```console
+$ fantasm --project-root /path/to/your/project info
+              Fantasm project              
+┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Key             ┃ Value                 ┃
+┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
+│ project_root    │ /path/to/your/project │
+│ config_filepath │ (none)                │
+│ config_keys     │ (empty)               │
+└─────────────────┴───────────────────────┘
+ Resolved project context for the current  
+                invocation.
+```
+
+The same invocation through a pipe (or with `--as tsv`) emits
+tab-separated output suitable for downstream tooling:
+
+```console
+$ fantasm --project-root /path/to/your/project info --as tsv
+# Key	Value
+project_root	/path/to/your/project
+config_filepath	(none)
+config_keys	(empty)
+```
+
+## Programmatic API
+
+```python
+from fantasm.api import ...  # surface filled in as modules are ported
+```
+
+## Testing
+
+The codebase fantasm consolidates is untested. As modules are ported in,
+fantasm adds **characterisation tests** that pin down observable
+behaviour on representative inputs — these are the safety net for
+merging the four upstream forks. Modules that emit 6502 assembly source
+are exercised with **round-trip tests** that re-assemble the output with
+`beebasm` and compare bytes; the `beebasm_filepath` pytest fixture skips
+such tests when the assembler is not on `PATH`. See `docs/testing.md`
+for the patterns and `CLAUDE.md` for the project-level guidance.
+
+## Layout
+
+```
+src/fantasm/             the package
+src/fantasm/cli.py       Click entrypoint
+src/fantasm/api/         programmatic API (re-exports the public surface)
+src/fantasm/config.py    project-root resolution + fantasm.toml loading
+tests/                   pytest suite (with shared fixtures in conftest.py)
+docs/                    user and developer documentation
+scripts/                 README generator + Jinja2 template
+```
+
+## Related projects
+
+- [py8dis (fork)](https://github.com/acornaeology/py8dis) — the tracing
+  disassembler fantasm builds on top of (will eventually become
+  `msabeeb`).
+- The four sibling repositories under `acornaeology` from which fantasm
+  draws its initial tooling: `acorn-6502-tube-client`, `acorn-adfs`,
+  `acorn-econet-bridge`, `acorn-nfs`.
+
+---
+
+This README is generated from `scripts/readme_template.md.j2` by
+`scripts/generate_readme.py`. **Do not edit it directly** — edit the
+template (or the generator, or the source files whose output it
+captures) and re-run `uv run python scripts/generate_readme.py`. The
+pre-commit hook and the `readme-check` CI job both run the
+generator's `--check` mode and will refuse stale READMEs.