resolvescript 0.1.2__tar.gz

resolvescript-0.1.2/LICENSE

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

resolvescript-0.1.2/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: resolvescript
+Version: 0.1.2
+Summary: CLI framework for building, coding, testing, packaging and installing DaVinci Resolve scripts.
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# resolvescript
+
+Build, test, package and install [DaVinci Resolve](https://www.blackmagicdesign.com/products/davinciresolve) Python scripts and plugins: a small CLI with an npm-style workflow for the Resolve `Scripts/` tree.
+
+- `create` scaffolds a project with a `manifest.json` and smoke tests
+- `dev` / `test` run against a mock `DaVinciResolveScript` API - no Resolve needed
+- `build` consolidates the multi-file package into a single `.py` for distribution
+- `add` / `install` / `update` resolve dependencies from GitHub, URLs, archives or local folders and record them in `resolvescript.json`
+- `package` emits `dist/<name>-<version>.tar.gz` plus `SHA256SUMS.txt`
+
+Install with pip: `pip install resolvescript` (Python 3.12+).
+
+## Quickstart
+
+```console
+$ resolvescript create my-cool-tool
+$ cd my-cool-tool
+$ resolvescript dev        # sandboxed dev loop against the mock API
+$ resolvescript test       # run the smoke tests
+$ resolvescript build      # single-file build -> dist/my_cool_tool.py
+$ resolvescript analyze    # static checks (imports, manifest, API usage)
+$ resolvescript package    # dist/my-cool-tool-0.1.0.tar.gz + SHA256SUMS.txt
+
+# elsewhere, consume it:
+$ resolvescript add github:example/my-cool-tool
+$ resolvescript install    # materialize all recorded deps into Resolve
+```
+
+## Authoring
+
+### Directory
+
+```
+my-cool-tool/
+  manifest.json        # project manifest (or manifest.xml)
+  my_cool_tool/        # your Python package (module name from manifest.name/python)
+    __init__.py
+    export.py
+  tests/
+    test_smoke.py
+```
+
+### Commands
+
+| Command | Purpose |
+| --- | --- |
+| `create <name>` | Scaffold a new project (`--json`/`--xml`, `--template minimal\|toolkit`, `--dir`) |
+| `dev` | Sandboxed dev loop / REPL against the mock Resolve API (`--built` for the consolidated file, `--repl`, `--editor`) |
+| `test` | Run the project's pytest suite against the mock API (`--built`, `-k pattern`, `--api-coverage`) |
+| `analyze` | Static checks: missing entrypoint/module, syntax, unused imports, unmocked API methods, attribute typing (`--json`) |
+| `build` | Consolidate into a single file (`--output`, or the manifest `consolidate.output`) |
+| `package` | Assemble `dist/<name>-<version>.tar.gz` + `SHA256SUMS.txt` (`--dist DIR`) |
+| `add <spec>` | Resolve, install a dependency and record it (`--no-save`, `--target`, `--scripts-root`) |
+| `install [<spec>]` | One-off install, local project, **or** materialize recorded deps (`--locked`, `--dry-run`) |
+| `update [<name>]` | Re-resolve recorded deps within their ranges (`--precise X.Y.Z`, `--fix`) |
+| `remove <name>` | Uninstall and unrecord (`--no-save`) |
+| `search <query>` | Search the known sources table |
+| `manage list\|remove` | Low-level registry operations (`--json`, `--all`) |
+
+Exit codes: `0` ok, `1` error, `2` usage.
+
+### Specifiers
+
+`add` / `install <spec>` accept:
+
+- `name` - a name from the built-in known-sources table (`resolvescript search`)
+- `owner/repo` or `github:owner/repo[#ref]` - GitHub repo (ref = branch/tag/commit, or `#semver:^1.2` for a range)
+- `https://...tar.gz` / `.zip` - direct archive URL
+- `https://...` - a URL whose root carries a `manifest.json` (GitHub Pages-style hosting)
+- `file:path`, `./dir`, an absolute path - local directory or archive
+- `.tar.gz` / `.zip` files and local directories
+
+Recorded specs live in `resolvescript.json`; use `resolvescript install --locked` for a CI/npm-ci style check that recorded artifacts still satisfy the recorded ranges.
+
+### Manifest reference
+
+`manifest.json` (or `manifest.xml`, same shape):
+
+```jsonc
+{
+  "name": "my-cool-tool",          // required
+  "version": "0.1.0",              // required, semver
+  "author": "You",
+  "description": "...",
+  "python": "my_cool_tool",        // package/module name (defaults to "name")
+  "entrypoint": "export.py",       // recommended CLI/bootstrap module
+  "kind": "script",                 // "script" (default) | "extension" (plugin)
+  "targets": ["Comp"],              // Scripts subfolders: Comp, Utility, Tool, Render,
+                                    //   Deliver, Edit, WorkflowIntegrations, Fusion, root
+  "compat": { "resolve": "18.6.4", "python": "3.12" },
+  "release": { "owner": "you", "repo": "my-cool-tool" },  // for `add` discovery
+  "scripts_root": "",               // per-OS override for the Resolve Scripts root
+  "consolidate": { "enabled": true, "output": "dist/my_tool.py", "exclude": [], "no_comment": [] },
+  "install": { "as_directory": true, "include": [], "exclude": [], "to": "resolve" },
+  "dependencies": ["github:example/dep"]   // resolved on install
+}
+```
+
+### Install model
+
+Installs drop into each OS's Resolve Scripts root under the manifest `targets`. Directories install as a single folder; `.py`-only packages can opt into `install.as_directory: false` multi-file installs. Every install is recorded in `<ScriptsRoot>/.resolvescript/install.json` (schema v1):
+
+- keys are `<name>:<target>` (directory) or `<name>:<target>:<relpath>` (file-based)
+- each entry carries `version`, `targets`, `as_directory`, `files`, `source`, `resolved` and `integrity`
+- `install --locked` verifies registry entries against recorded specs before reusing them
+
+`--scripts-root` (or `RESOLVESCRIPT_SCRIPTS_ROOT`) overrides OS detection.
+
+## Frameworks
+
+`resolvescript` ships a mock `DaVinciResolveScript` module with a faithful-enough Resolve color/editing/page object model for testing, plus `resolvescript test --api-coverage` to report which mock methods your tests actually exercise.
+
+## Development
+
+```console
+python -m venv .venv
+.\.venv\Scripts\activate        # Windows; source .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+Milestones and the full plan live in [`TODO.md`](TODO.md). CI runs the shared `OseMine/workflows` action; cutting a `vX.Y.Z` tag runs the release pipeline (sdist+wheel, checksums, GitHub release, optional PyPI publishing).

resolvescript-0.1.2/README.md

@@ -0,0 +1,123 @@
+# resolvescript
+
+Build, test, package and install [DaVinci Resolve](https://www.blackmagicdesign.com/products/davinciresolve) Python scripts and plugins: a small CLI with an npm-style workflow for the Resolve `Scripts/` tree.
+
+- `create` scaffolds a project with a `manifest.json` and smoke tests
+- `dev` / `test` run against a mock `DaVinciResolveScript` API - no Resolve needed
+- `build` consolidates the multi-file package into a single `.py` for distribution
+- `add` / `install` / `update` resolve dependencies from GitHub, URLs, archives or local folders and record them in `resolvescript.json`
+- `package` emits `dist/<name>-<version>.tar.gz` plus `SHA256SUMS.txt`
+
+Install with pip: `pip install resolvescript` (Python 3.12+).
+
+## Quickstart
+
+```console
+$ resolvescript create my-cool-tool
+$ cd my-cool-tool
+$ resolvescript dev        # sandboxed dev loop against the mock API
+$ resolvescript test       # run the smoke tests
+$ resolvescript build      # single-file build -> dist/my_cool_tool.py
+$ resolvescript analyze    # static checks (imports, manifest, API usage)
+$ resolvescript package    # dist/my-cool-tool-0.1.0.tar.gz + SHA256SUMS.txt
+
+# elsewhere, consume it:
+$ resolvescript add github:example/my-cool-tool
+$ resolvescript install    # materialize all recorded deps into Resolve
+```
+
+## Authoring
+
+### Directory
+
+```
+my-cool-tool/
+  manifest.json        # project manifest (or manifest.xml)
+  my_cool_tool/        # your Python package (module name from manifest.name/python)
+    __init__.py
+    export.py
+  tests/
+    test_smoke.py
+```
+
+### Commands
+
+| Command | Purpose |
+| --- | --- |
+| `create <name>` | Scaffold a new project (`--json`/`--xml`, `--template minimal\|toolkit`, `--dir`) |
+| `dev` | Sandboxed dev loop / REPL against the mock Resolve API (`--built` for the consolidated file, `--repl`, `--editor`) |
+| `test` | Run the project's pytest suite against the mock API (`--built`, `-k pattern`, `--api-coverage`) |
+| `analyze` | Static checks: missing entrypoint/module, syntax, unused imports, unmocked API methods, attribute typing (`--json`) |
+| `build` | Consolidate into a single file (`--output`, or the manifest `consolidate.output`) |
+| `package` | Assemble `dist/<name>-<version>.tar.gz` + `SHA256SUMS.txt` (`--dist DIR`) |
+| `add <spec>` | Resolve, install a dependency and record it (`--no-save`, `--target`, `--scripts-root`) |
+| `install [<spec>]` | One-off install, local project, **or** materialize recorded deps (`--locked`, `--dry-run`) |
+| `update [<name>]` | Re-resolve recorded deps within their ranges (`--precise X.Y.Z`, `--fix`) |
+| `remove <name>` | Uninstall and unrecord (`--no-save`) |
+| `search <query>` | Search the known sources table |
+| `manage list\|remove` | Low-level registry operations (`--json`, `--all`) |
+
+Exit codes: `0` ok, `1` error, `2` usage.
+
+### Specifiers
+
+`add` / `install <spec>` accept:
+
+- `name` - a name from the built-in known-sources table (`resolvescript search`)
+- `owner/repo` or `github:owner/repo[#ref]` - GitHub repo (ref = branch/tag/commit, or `#semver:^1.2` for a range)
+- `https://...tar.gz` / `.zip` - direct archive URL
+- `https://...` - a URL whose root carries a `manifest.json` (GitHub Pages-style hosting)
+- `file:path`, `./dir`, an absolute path - local directory or archive
+- `.tar.gz` / `.zip` files and local directories
+
+Recorded specs live in `resolvescript.json`; use `resolvescript install --locked` for a CI/npm-ci style check that recorded artifacts still satisfy the recorded ranges.
+
+### Manifest reference
+
+`manifest.json` (or `manifest.xml`, same shape):
+
+```jsonc
+{
+  "name": "my-cool-tool",          // required
+  "version": "0.1.0",              // required, semver
+  "author": "You",
+  "description": "...",
+  "python": "my_cool_tool",        // package/module name (defaults to "name")
+  "entrypoint": "export.py",       // recommended CLI/bootstrap module
+  "kind": "script",                 // "script" (default) | "extension" (plugin)
+  "targets": ["Comp"],              // Scripts subfolders: Comp, Utility, Tool, Render,
+                                    //   Deliver, Edit, WorkflowIntegrations, Fusion, root
+  "compat": { "resolve": "18.6.4", "python": "3.12" },
+  "release": { "owner": "you", "repo": "my-cool-tool" },  // for `add` discovery
+  "scripts_root": "",               // per-OS override for the Resolve Scripts root
+  "consolidate": { "enabled": true, "output": "dist/my_tool.py", "exclude": [], "no_comment": [] },
+  "install": { "as_directory": true, "include": [], "exclude": [], "to": "resolve" },
+  "dependencies": ["github:example/dep"]   // resolved on install
+}
+```
+
+### Install model
+
+Installs drop into each OS's Resolve Scripts root under the manifest `targets`. Directories install as a single folder; `.py`-only packages can opt into `install.as_directory: false` multi-file installs. Every install is recorded in `<ScriptsRoot>/.resolvescript/install.json` (schema v1):
+
+- keys are `<name>:<target>` (directory) or `<name>:<target>:<relpath>` (file-based)
+- each entry carries `version`, `targets`, `as_directory`, `files`, `source`, `resolved` and `integrity`
+- `install --locked` verifies registry entries against recorded specs before reusing them
+
+`--scripts-root` (or `RESOLVESCRIPT_SCRIPTS_ROOT`) overrides OS detection.
+
+## Frameworks
+
+`resolvescript` ships a mock `DaVinciResolveScript` module with a faithful-enough Resolve color/editing/page object model for testing, plus `resolvescript test --api-coverage` to report which mock methods your tests actually exercise.
+
+## Development
+
+```console
+python -m venv .venv
+.\.venv\Scripts\activate        # Windows; source .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+Milestones and the full plan live in [`TODO.md`](TODO.md). CI runs the shared `OseMine/workflows` action; cutting a `vX.Y.Z` tag runs the release pipeline (sdist+wheel, checksums, GitHub release, optional PyPI publishing).

resolvescript-0.1.2/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "resolvescript"
+version = "0.1.2"
+description = "CLI framework for building, coding, testing, packaging and installing DaVinci Resolve scripts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+resolvescript = "resolve_script.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["resolve_script*"]
+
+[tool.setuptools.package-data]
+"resolve_script" = ["templates/**/*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+extend-exclude = [
+    "src/resolve_script/templates",  # placeholders (@NAME@) are not valid Python
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM", "W", "RET", "PTH"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ARG001"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

resolvescript-0.1.2/setup.cfg

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

resolvescript-0.1.2/src/resolve_script/__init__.py

@@ -0,0 +1,3 @@
+"""ResolveScript — CLI framework for DaVinci Resolve scripts."""
+
+__version__ = "0.1.2"

resolvescript-0.1.2/src/resolve_script/analyze.py

@@ -0,0 +1,277 @@
+"""Static analyzer (M6): syntax, unused imports, manifest + API coverage.
+
+``analyze_project()`` scans an extension directory and reports:
+
+- MANIFEST     validation errors (reuses ``manifest/validation.py``)
+- SYNTAX       compile failures per .py file
+- UNUSED_IMPORT imports bound but never referenced afterwards
+- API_UNMOCKED calls to methods missing from the mock sandbox
+- ATTR_KEY     ``GetAttrs()``-style keys that the mock does not define
+- TARGET       target-name problems (already covered by MANIFEST)
+
+The API surfaces are introspected from the mock itself (``sandbox/api.py``), so
+the checker stays in sync with what ``dev``/``test`` actually provide.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .manifest.validation import validate_manifest
+from .sandbox.api import (
+    FakeClip,
+    FakeComp,
+    FakeFolder,
+    FakeFusion,
+    FakeKey,
+    FakeMediaPool,
+    FakeMediaPoolItem,
+    FakeProject,
+    FakeProjectManager,
+    FakeResolve,
+    FakeSpline,
+    FakeStroke,
+    FakeTimeline,
+    FakeTool,
+)
+
+# Conventional names practitioners use for Resolve API root objects.
+KNOWN_ROOTS = {
+    "resolve",
+    "project",
+    "projectManager",
+    "timeline",
+    "clip",
+    "mediaPool",
+    "mediaPoolItem",
+    "mediapoolitem",
+    "folder",
+    "fusion",
+    "comp",
+    "tool",
+    "stroke",
+    "spline",
+    "key",
+    "currentComp",
+    "currentTool",
+}
+
+_SKIP_PARTS = {"__pycache__", ".venv", "venv", "build", "dist", ".git", "node_modules"}
+_ATTR_KEY_RE = re.compile(r"^(TOOLS|COMPS|SPLINES|STROKES|INPOINT|OUTPOINT|EDIT|FRAME)_[A-Z0-9_]+$")
+
+
+@dataclass
+class Issue:
+    code: str
+    severity: str  # "error" | "warning" | "info"
+    file: str
+    line: int
+    message: str
+
+
+@dataclass
+class Analysis:
+    issues: list[Issue] = field(default_factory=list)
+    api_used: set[str] = field(default_factory=set)
+    api_mocked: set[str] = field(default_factory=set)
+    attr_keys_used: set[str] = field(default_factory=set)
+    attr_keys_mocked: set[str] = field(default_factory=set)
+
+    def api_report(self) -> list[str]:
+        lines = [
+            f"API coverage: {len(self.api_used & self.api_mocked)} of "
+            f"{len(self.api_mocked)} mocked methods used",
+        ]
+        missing = sorted(self.api_used - self.api_mocked)
+        unused = sorted(self.api_mocked - self.api_used)
+        if missing:
+            lines.append(f"  called but not mocked: {', '.join(missing)}")
+        if unused:
+            lines.append(f"  mocked but unused: {', '.join(unused)}")
+        attr_missing = sorted(self.attr_keys_used - self.attr_keys_mocked)
+        if attr_missing:
+            lines.append(f"  attr keys not in mock: {', '.join(attr_missing)}")
+        return lines
+
+
+def _mocked_api_surface() -> set[str]:
+    classes = (
+        FakeResolve,
+        FakeProjectManager,
+        FakeProject,
+        FakeTimeline,
+        FakeClip,
+        FakeMediaPoolItem,
+        FakeFolder,
+        FakeMediaPool,
+        FakeKey,
+        FakeSpline,
+        FakeStroke,
+        FakeTool,
+        FakeComp,
+        FakeFusion,
+    )
+    return {
+        name
+        for cls in classes
+        for name in dir(cls)
+        if not name.startswith("_") and callable(getattr(cls, name, None))
+    }
+
+
+def _mock_attr_keys() -> set[str]:
+    """Extract keys from ``self._attrs = {...}`` in sandbox/api.py (stays in sync)."""
+    source = Path(__file__).resolve().parent / "sandbox" / "api.py"
+    tree = ast.parse(source.read_text("utf-8"))
+    keys: set[str] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign):
+            continue
+        for target in node.targets:
+            if not (isinstance(target, ast.Attribute) and target.attr == "_attrs"):
+                continue
+            if not (isinstance(target.value, ast.Name) and target.value.id == "self"):
+                continue
+            if isinstance(node.value, ast.Dict):
+                keys.update(
+                    key.value
+                    for key in node.value.keys
+                    if isinstance(key, ast.Constant) and isinstance(key.value, str)
+                )
+    return keys
+
+
+def _is_skip(rel: Path) -> bool:
+    return any(part in _SKIP_PARTS for part in rel.parts)
+
+
+def _unused_imports(tree: ast.AST, rel: Path, analysis: Analysis) -> None:
+    names_used = {
+        node.id
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Name)
+    }
+    names_used.update(
+        node.attr
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Attribute)
+        if isinstance(node.value, ast.Name)
+    )
+    for node in ast.walk(tree):
+        aliases: list[ast.alias] = []
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            aliases = node.names
+        for alias in aliases:
+            name = alias.asname or (alias.name.split(".")[0])
+            if name == "*":
+                continue
+            if name in {"__version__"}:
+                continue
+            count = sum(1 for token in names_used if token == name)
+            if count <= 1:  # only the binding itself
+                analysis.issues.append(
+                    Issue(
+                        "UNUSED_IMPORT",
+                        "warning",
+                        rel.as_posix(),
+                        node.lineno,
+                        f"imported name '{name}' is never used",
+                    )
+                )
+
+
+def _collect_api(tree: ast.AST, analysis: Analysis) -> None:
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        attr = node.func
+        if not isinstance(attr, ast.Attribute):
+            continue
+        base = attr.value
+        if isinstance(base, ast.Attribute):
+            while isinstance(base, ast.Attribute):
+                base = base.value
+        if isinstance(base, ast.Name) and base.id in KNOWN_ROOTS:
+            analysis.api_used.add(attr.attr)
+
+
+def _collect_attr_keys(tree: ast.AST, analysis: Analysis) -> None:
+    seen_constants = {
+        node.value
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Constant) and isinstance(node.value, str)
+    }
+    for text in seen_constants:
+        if _ATTR_KEY_RE.match(text) or text in {"TOOLS_RegID", "COMPS_Name"}:
+            analysis.attr_keys_used.add(text)
+
+
+def analyze_project(root: Path, manifest=None) -> Analysis:
+    root = Path(root).resolve()
+    analysis = Analysis()
+    analysis.api_mocked = _mocked_api_surface()
+    analysis.attr_keys_mocked = _mock_attr_keys()
+
+    if manifest is not None:
+        for message in validate_manifest(manifest):
+            analysis.issues.append(
+                Issue("MANIFEST", "error", "manifest.json", 0, message)
+            )
+
+    for py in sorted(root.rglob("*.py")):
+        try:
+            rel = py.relative_to(root)
+        except ValueError:
+            rel = Path(py.name)
+        if _is_skip(rel):
+            continue
+        try:
+            tree = ast.parse(py.read_text("utf-8"), filename=str(py))
+        except SyntaxError as exc:
+            analysis.issues.append(
+                Issue(
+                    "SYNTAX",
+                    "error",
+                    rel.as_posix(),
+                    exc.lineno or 0,
+                    f"syntax error: {exc.msg}",
+                )
+            )
+            continue
+        except UnicodeDecodeError:
+            continue
+        _unused_imports(tree, rel, analysis)
+        _collect_api(tree, analysis)
+        _collect_attr_keys(tree, analysis)
+
+    for name in sorted(analysis.api_used - analysis.api_mocked):
+        analysis.issues.append(
+            Issue(
+                "API_UNMOCKED",
+                "info",
+                "",
+                0,
+                f"'{name}()' is called but not provided by the mock sandbox",
+            )
+        )
+    for key in sorted(analysis.attr_keys_used - analysis.attr_keys_mocked):
+        analysis.issues.append(
+            Issue(
+                "ATTR_KEY",
+                "info",
+                "",
+                0,
+                f"attr key '{key}' is read but not defined by the mock sandbox",
+            )
+        )
+    return analysis
+
+
+def issues_to_json(analysis: Analysis) -> str:
+    return json.dumps(
+        [issue.__dict__ for issue in analysis.issues], indent=2, default=str
+    )