Module tooling 

Workshop-independent tooling APIs: check a project and query the resolved semantic model.

This module is the public tooling surface for Wright and other consumers that want to parse, check, inspect, and reason about OPY projects before any Workshop backend is connected (issue #7):

• check / check_with_overlay run the full frontend pipeline (preprocess → parse → resolve) on a main file plus its includes and return every structured diagnostic together with the file registry, without requiring lowering to any Workshop backend. Resolution stops at the Opy HIR semantic model (hir::Program); Workshop emission, decompilation, and catalog behavior are deliberately out of scope here.
• SemanticModel wraps the resolved program and answers semantic queries: declarations, rule listing, symbol/reference lookup by name or span, custom-enum declarations, macro defines, and source provenance (span → file id, path, line/col).

Diagnostics contract: every Diagnostic carries a stable machine code, a severity, a human message, and — when known — a resolved source location (path:line:col through the file registry). Codes are the same ones the compile pipeline emits (lex-error, parse-error, unknown-identifier, unknown-action, include-not-found, …); see docs/opy/tooling-api.md for the full table.

Parse diagnostics are collected in full (the parser recovers at statement boundaries); semantic-resolution diagnostics follow the compile contract and report the first error, so check never disagrees with compile about whether a project is clean.

Structs

CheckOutcome

The outcome of check: structured diagnostics plus the resolved model.

Diagnostic

A structured, source-attributed diagnostic.

EnumDecl

A custom enum declaration (CST-retained; enums fold to constants in the HIR).

EnumMember

One custom-enum member with its declaration site.

SemanticModel

The resolved program model: the Opy HIR semantic program plus the queryable symbol index and custom-enum declarations.

SourceLocation

A resolved source location: a span’s file id and path (through the file registry) plus its 1-based line/column interval.

Symbol

A program-scope symbol with its declaration site and resolved reference sites.

Enums

DiagnosticSeverity

The severity of a diagnostic. All frontend diagnostics are errors today; the enum is the machine contract for future warning/note severities.

SymbolKind

The kind of a program-scope symbol.

Functions

check

Check one .opy project: preprocess (includes/defines) → parse (CST) → resolve (Opy HIR). main_path is the display path recorded in the file registry; root is the include base. No Workshop backend is required.

check_with_overlay

check with open-document overlays (unsaved editor buffers participate in include resolution, see crate::preprocess::preprocess_with_overlay).