Skip to content

validator-cli.md

Latest commit

 

History

History
86 lines (65 loc) · 3.53 KB

validator-cli.md

File metadata and controls

86 lines (65 loc) · 3.53 KB
Raw

Validator CLI

einf-validate is a checker-agnostic CLI for static DSL analysis. It parses Python source, runs einf semantic analysis over call sites, and optionally routes external type-checker output through the same report.

Install

The CLI ships with the base install. To use the richer LibCST parser backend, install the analysis extra:

pip install "einf[analysis] @ git+https://github.com/isty2e/einf.git"

Basic usage

einf-validate path/to/module.py
einf-validate src/
einf-validate src/ --parser ast
einf-validate src/ --parser libcst
einf-validate src/ --checker basedpyright --checker pyrefly
einf-validate src/ --checker basedpyright --checker-timeout-seconds 60

Positional arguments accept any mix of files and directories. Directories are walked recursively for *.py.

Flags

Flag Values Default Purpose
--parser ast, libcst ast Parser backend. libcst needs the analysis extra.
--checker pyright, basedpyright, zuban, ty, pyrefly none External type checker to invoke alongside semantic analysis. Repeatable; repeated names are collapsed.
--checker-timeout-seconds finite positive number 30 Maximum runtime for each checker process.
--checker-cleanup-timeout-seconds finite positive number 1 Maximum time spent cleaning up a checker after timeout or cancellation.
--checker-max-concurrency positive integer 1 Maximum number of checker processes running concurrently.
--checker-max-output-bytes positive integer 8388608 Maximum combined buffered stdout+stderr bytes per checker process; larger output fails closed.
--checker-max-diagnostics positive integer 10000 Maximum diagnostics per checker result and in the merged validator output.
--checker-max-field-length positive integer 4096 Maximum characters in one externally reported diagnostic field (message, path, code).

Exit codes

  1. 0 — no diagnostics, no discovery/parse/read failures, no checker invocation failures.
  2. 1 — any file contains semantic or checker diagnostics, parse failures, or read failures; any target directory cannot be traversed completely; or any configured checker failed to execute.

Output contract

einf-validate writes stable JSON to stdout. Top-level fields:

  • schema_version — output contract version,
  • parser_backend — the parser that produced the report,
  • checker_failures[] — external checker invocation failures (unavailable executable, spawn failure, timeout, malformed output, etc.),
  • discovery_failures[] — directories that could not be traversed completely,
  • files[] — per-file report.

Each file entry:

  • path
  • diagnostics[] — einf semantic diagnostics,
  • checker_diagnostics[] — normalized external checker diagnostics,
  • axis_tokens[] — recognized axis identifier tokens with separate kind, side, relation, and nullable operation role fields,
  • failures[] — validator ingress failures (unreadable files, parse errors).

The current output schema version is 0.3. Axis token kind distinguishes scalar axes from axis packs; relation records whether the same structural symbol appears on both sides of the operation.

CI integration

The CLI is designed for CI gates:

# example: pre-merge lint step
- run: einf-validate src/ --checker basedpyright

The stable JSON + exit-code contract means downstream tooling can pipe stdout into a diff viewer or annotator without parsing unstable text.