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).
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//!
37//! The whole-project scan lifecycle (#2836) layers onto this surface.
38//!
39//! ```
40//! use harn_rules::{Rule, CompiledRule};
41//!
42//! let rule = Rule::from_toml_str(
43//!     r#"
44//!     id = "destructure-default"
45//!     language = "typescript"
46//!     fix = "{ $KEY: $SRC }"
47//!     [rule]
48//!     pattern = "$SRC?.$KEY ?? $DEFAULT"
49//!     "#,
50//! ).unwrap();
51//! let compiled = CompiledRule::compile(&rule).unwrap();
52//! let matches = compiled.run("const a = cfg?.timeout ?? 30;").unwrap();
53//! assert_eq!(matches[0].bindings["KEY"].text, "timeout");
54//! ```
55
56#![forbid(unsafe_code)]
57
58pub mod constraint;
59pub mod engine;
60pub mod error;
61pub mod evaluator;
62pub mod fix;
63pub mod loader;
64pub mod model;
65pub mod pattern;
66pub mod recipe;
67pub mod report;
68pub mod transform;
69
70pub use engine::{Binding, CodemodResult, CompiledRule, Diagnostic, RuleMatch, Span};
71pub use error::RulesError;
72pub use fix::{interpolate, AppliedEdit};
73pub use loader::{load_rule_dir, load_rule_file};
74pub use model::{
75    Applicability, AtomicMatcher, Comparison, Constraint, ConvertOp, Rule, RuleKind, RuleNode,
76    Safety, Severity, StopBy, StopKeyword, Transform,
77};
78pub use pattern::{compile_pattern, CompiledPattern};
79pub use recipe::{run_recipe, FileChange, RecipeRun, RuleRecipe, ScanningRecipe, SourceFile};
80pub use report::{data_table, DataTable, TableRow, TableSummary};
harn_rules/lib.rs

harn_rules/
lib.rs
