Metadata-Version: 2.4
Name: maid-validator-solidity
Version: 0.1.0
Summary: Solidity language validator plugin for MAID Runner, backed by tree-sitter-solidity.
Author-email: "Mamerto Fabian Jr." <mamerto@codefrost.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mamertofabian/maid-validator-solidity
Project-URL: Repository, https://github.com/mamertofabian/maid-validator-solidity
Project-URL: Issues, https://github.com/mamertofabian/maid-validator-solidity/issues
Project-URL: Changelog, https://github.com/mamertofabian/maid-validator-solidity/blob/main/CHANGELOG.md
Keywords: maid,maid-runner,solidity,validator,tree-sitter,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: maid-runner<3,>=2.24
Requires-Dist: tomli>=2; python_version < "3.11"
Requires-Dist: tree-sitter<0.26,>=0.25
Requires-Dist: tree-sitter-solidity<2,>=1.2.13
Dynamic: license-file

# maid-validator-solidity

Solidity (`.sol`) language validator for MAID Runner, backed by
[`tree-sitter-solidity`](https://github.com/JoranHonig/tree-sitter-solidity).
This separate Python package uses the same `maid_runner.validators` entry-point
mechanism as `maid-validator-csharp`. Version 0.1.0 is a prepared release
candidate; publication is pending the release workflow.

Collection reads supplied source without invoking a compiler, downloading
dependencies, or reading generated build artifacts. Tests can therefore refer to
contracts and methods that have not been implemented yet.

## Install

After publication, install from PyPI in the same environment as MAID:

```sh
uv add --dev maid-validator-solidity
# or use an isolated tool environment:
uv tool install --with maid-validator-solidity 'maid-runner>=2.24,<3'
maid validators
```

See [CHANGELOG.md](CHANGELOG.md) for history and [RELEASING.md](RELEASING.md)
for the C#-style GitHub Actions and PyPI Trusted Publisher release checklist.

### Install locally

Install the plugin in the **same Python environment** as the MAID executable.
For a project managed with uv:

```sh
uv add --dev /path/to/maid-validator-solidity
uv run maid validators
```

For an isolated MAID tool installation:

```sh
uv tool install --with /path/to/maid-validator-solidity 'maid-runner>=2.24,<3'
maid validators
```

The registry lists `SolidityValidator`, extension `.sol`, and status `active`.
Development within this directory uses `uv sync` and `uv run maid validators`.

## Supported declarations

| Solidity construct | MAID artifact |
| --- | --- |
| Contract, abstract contract, library | `class`, including declared bases |
| Interface | `interface` |
| Struct | `class`, with `attribute` fields |
| Enum | `enum` |
| User-defined value type | `type`, with its underlying primitive type |
| Public state variable | `attribute`, with its declared type |
| Public/external contract function | `method` |
| Non-private library function, including internal functions | `method` |
| Constructor, receive, fallback | `method`, named `constructor`, `receive`, `fallback` |
| Free function | `function` |

Nested types use names such as `Vault.Position`; their fields have
`of: Vault.Position`. Callable artifacts retain argument names, raw types and
data locations. Return types are `void`, a single declared type, or a parenthesized
list such as `(uint256, address)`.

Definition signatures such as `deposit(uint256,bytes)` normalize `uint`, `int`,
and `byte`, and omit data locations. They distinguish source overload definitions;
they are not ABI selectors or compiler-resolved identities. Type comparison
normalizes these aliases and whitespace, but preserves widths, array dimensions,
custom names, data locations, and `address payable`.

## Foundry reference collection

The behavioral collector recognizes public/external `test*` and `invariant*`
methods, including `testFuzz*`. It also reads `setUp` and state initializers when
the same contract declares tests. It collects constructor uses, named import
aliases, direct library calls, and method calls on explicitly typed receivers.
Bindings are isolated by contract, method, and lexical block, including primitive
variables that shadow imported names. Imports alone, comments, string literals,
and uninvoked helper bodies do not establish method coverage.

Behavioral references deliberately have no overload signature. A manifest asking
for exact overload coverage will need compiler evidence that this version does
not provide. Use representative callable declarations (omit `signature`) when
appropriate; snapshots include definition signatures, so review them before using
them as behavioral contracts.

Malformed syntax returns a `CollectionResult` with errors and no artifacts.
The parser does not establish semantic validity or prove runtime execution;
continue running Foundry and security checks such as Slither.

## Limits and Runner integration

MAID Runner 2.27.6 recognizes neither Foundry's `*.t.sol` filenames as behavioral
test files nor `forge test` as a supported test runner. This package supplies
language collection, snapshots, and plugin discovery. Full Foundry manifest
validation needs separate Runner integration; installing the plugin alone does
not remove that prerequisite.

Local MAID Runner 2.27.7 adds `.sol` discovery, `*.t.sol` behavioral test
classification, and `forge test` command support. It was verified with this
plugin against `snider-launch`: all 16 source and 7 test files collected without
errors, representative behavioral/implementation contracts passed, a missing
method failed behavioral validation, and MAID executed all 59 Foundry tests.
Runner 2.27.7 is not yet published; the package API floor remains `>=2.24,<3`.
Full Foundry validation needs 2.27.7 or newer, while plugin collection and
discovery work with the published dependency. See RELEASING.md before releasing.

Version 0.1 does not model event, custom-error, or modifier artifacts. It does not
resolve inherited fields from other files, `using for` bindings, generated getter
calls back to state-variable artifacts, namespace/wildcard imports, array-element
receivers, arbitrary helper call graphs, or Hardhat JavaScript test bindings.
Same-file free-function calls are not yet collected as behavioral references.
Unresolved uses can consequently leave a manifest artifact without behavioral
coverage. Cross-file names and imports have source-local identity only; no compiler
or whole-project import resolver is used.

## Development

```sh
uv sync
uv run python -m pytest tests/ -q
uv run ruff check src/ tests/
uv run black --check src/ tests/
uv run maid validate
uv run maid test
uv build
```

The tests include MAID Runner's public conformance kit. The active implementation
contract is [solidity-validator-plugin.manifest.yaml](manifests/solidity-validator-plugin.manifest.yaml).
Changes follow MAID's plan, red evidence, lock, implementation, review, and Outcome
workflow. Commits and publishing require explicit approval.

## Repository MAID tooling

Repo-local Claude and Codex skills, guidance, and hooks are installed. Use
`uv run maid init --check` to check the installed payload. For each coding task,
run `uv run maid assess --since <baseline>` and the verify command it recommends.
Git and Claude hooks invoke `scripts/maid`, which runs `uv run --locked maid`
from the repository root so the Solidity plugin is available without manual
environment activation. The pre-commit configuration runs MAID's pre-commit
profile; this machine's existing Git hook dispatcher already invokes it. On a
fresh machine, install pre-commit (for example, `uv tool install pre-commit`) and
run `pre-commit install` when no existing dispatcher is configured.
