harn_rules/
lib.rs

1//! # harn-rules
2//!
3//! The declarative structural rule engine for Harn — the Rust core that
4//! powers `harn rules` / lint / codemod surfaces. A **rule** describes
5//! *what to match* (a pattern snippet, a node kind, or a regex) and
6//! optionally *how to rewrite* it (a `fix`); the engine compiles that rule
7//! against the tree-sitter machinery in [`harn_hostlib::ast`] and produces
8//! [`RuleMatch`]es with metavariable bindings.
9//!
10//! This crate delivers the **atomic matching tier** (#2832), the
11//! **relational + composite algebra** (#2833), the **predicate + rewrite
12//! layer** (#2834), and the **safety + idempotency gate** (#2835):
13//!
14//! - [`model`] — the serde rule data model: the recursive [`RuleNode`]
15//!   (atomic `pattern` / `kind` / `regex`, relational `inside` / `has` /
16//!   `follows` / `precedes`, composite `all` / `any` / `not` / `matches`)
17//!   plus `where` / `transform` / `fix` and `utils`.
18//! - [`pattern`] — the snippet → tree-sitter-query compiler (`$VAR`
19//!   metavariable lifting, unification, literal patterns, and typed
20//!   `$VAR:kind` placeholders).
21//! - [`evaluator`] — the tree-walking match algebra (relational + composite
22//!   + utility-rule reuse).
23//! - [`constraint`] — `where` predicates on captured metavars (regex,
24//!   comparison, recursive sub-pattern, and Harn-only semantic filters).
25//! - [`transform`] — synthesize new metavars (`replace` / `substring` /
26//!   `convert`) before fixing.
27//! - [`fix`] — `fix` template interpolation and format-preserving splice.
28//! - [`engine`] — compile a [`Rule`], run it to produce matches,
29//!   [`CompiledRule::apply`] / [`CompiledRule::auto_apply`] /
30//!   [`CompiledRule::apply_checked`] a codemod (safety-gated, idempotency
31//!   checked), and emit [`Diagnostic`]s.
32//! - [`recipe`] — the whole-project scan → accumulate → edit lifecycle,
33//!   with file create/delete ([`ScanningRecipe`], [`run_recipe`]).
34//! - [`report`] — report-only [`DataTable`]s: columnar findings + metrics.
35//! - [`loader`] — load rules from a TOML file or a directory.
36//! - semantic capture metadata — Harn captures gain resolved binding identity
37//!   and simple static type labels when the local syntax provides them.
38//!
39//! The whole-project scan lifecycle (#2836) layers onto this surface.
40//!
41//! ```
42//! use harn_rules::{Rule, CompiledRule};
43//!
44//! let rule = Rule::from_toml_str(
45//!     r#"
46//!     id = "destructure-default"
47//!     language = "typescript"
48//!     fix = "{ $KEY: $SRC }"
49//!     [rule]
50//!     pattern = "$SRC?.$KEY ?? $DEFAULT"
51//!     "#,
52//! ).unwrap();
53//! let compiled = CompiledRule::compile(&rule).unwrap();
54//! let matches = compiled.run("const a = cfg?.timeout ?? 30;").unwrap();
55//! assert_eq!(matches[0].bindings["KEY"].text, "timeout");
56//! ```
57
58#![forbid(unsafe_code)]
59
60pub mod constraint;
61pub mod engine;
62pub mod error;
63pub mod evaluator;
64pub mod fix;
65pub mod fold;
66pub mod loader;
67pub mod model;
68pub mod pattern;
69pub mod recipe;
70pub mod report;
71mod semantic;
72pub mod testing;
73pub mod transform;
74
75pub use engine::{
76    Binding, BindingMetadata, CodemodResult, CompiledRule, Diagnostic, ResolvedBinding, RuleMatch,
77    Span,
78};
79pub use error::RulesError;
80pub use fix::{interpolate, AppliedEdit};
81pub use loader::{load_rule_dir, load_rule_file};
82pub use model::{
83    Applicability, AtomicMatcher, Comparison, Constraint, ConvertOp, ResolvedBindingConstraint,
84    Rule, RuleKind, RuleNode, Safety, Severity, StopBy, StopKeyword, Transform,
85};
86pub use pattern::{compile_pattern, CompiledPattern};
87pub use recipe::{run_recipe, FileChange, RecipeRun, RuleRecipe, ScanningRecipe, SourceFile};
88pub use report::{data_table, DataTable, TableRow, TableSummary};
89pub use testing::{run_inline_test, Expectation, FailureKind, InlineTestReport, TestFailure};
harn_rules/lib.rs

harn_rules/
lib.rs
