nqf-lint 0.2.0__tar.gz

nqf_lint-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - name: Format
+        run: cargo fmt --check
+      - name: Clippy
+        run: cargo clippy -- -D warnings
+      - name: Test
+        run: cargo test --release
+      - name: Lint the example clusters (self-check)
+        run: |
+          cargo build --release
+          ./target/release/nqf-lint examples/good_hg_cluster.json
+          ! ./target/release/nqf-lint examples/bad_mining_cluster.json

nqf_lint-0.2.0/.gitignore

@@ -0,0 +1,2 @@
+target/
+Cargo.lock

nqf_lint-0.2.0/Cargo.lock

@@ -0,0 +1,243 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "nqf-lint"
+version = "0.2.0"
+dependencies = [
+ "pyo3",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.23.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

nqf_lint-0.2.0/Cargo.toml

@@ -0,0 +1,38 @@
+# Standalone crate — não faz parte do workspace da raiz (é um produto separado,
+# candidato a repositório próprio no GitHub).
+[workspace]
+
+[package]
+name = "nqf-lint"
+version = "0.2.0"
+edition = "2021"
+authors = ["Cleiton Augusto"]
+description = "Pre-flight linter for quantum-chemistry cluster/calculation setups — catches silent garbage-in before an SCF runs for hours and returns a wrong number."
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/cleitonaugusto/nqf-lint"
+homepage = "https://github.com/cleitonaugusto/nqf-lint"
+keywords = ["quantum-chemistry", "linter", "chemistry", "cli", "validation"]
+categories = ["command-line-utilities", "science", "development-tools"]
+
+[[bin]]
+name = "nqf-lint"
+path = "src/main.rs"
+
+[lib]
+name = "nqf_lint"
+path = "src/lib.rs"
+# rlib for the CLI binary and downstream Rust crates; cdylib for the Python
+# extension module built by maturin (only when the `python` feature is on).
+crate-type = ["rlib", "cdylib"]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+# Optional: pulled in only for the Python bindings (feature `python`). A normal
+# `cargo build` / crates.io build never compiles it, keeping the crate light.
+# abi3-py38: one wheel works on CPython 3.8+ (stable ABI), instead of one per version.
+pyo3 = { version = "0.23", features = ["extension-module", "abi3-py38"], optional = true }
+
+[features]
+python = ["dep:pyo3"]

nqf_lint-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cleiton Augusto Correa Bezerra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nqf_lint-0.2.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: nqf-lint
+Version: 0.2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Software Development :: Quality Assurance
+License-File: LICENSE
+Summary: Pre-flight linter for quantum-chemistry setups — catches silent garbage-in (impossible electron count/spin, Bohr/Ångström unit errors, bare atoms, non-reproducible conformers) before an SCF runs for hours. Rust core, Python API.
+Keywords: quantum-chemistry,linter,chemistry,computational-chemistry,validation
+Home-Page: https://github.com/cleitonaugusto/nqf-lint
+Author: Cleiton Augusto
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/cleitonaugusto/nqf-lint
+Project-URL: Repository, https://github.com/cleitonaugusto/nqf-lint
+
+# nqf-lint
+
+**A pre-flight linter for quantum-chemistry cluster setups.**
+
+A quantum-chemistry calculation can run for hours and return a number that *looks*
+fine while the input was silently broken — an oxygen entered with no hydrogens, an
+electron count made impossible by a forgotten pseudopotential core, a metal floating
+with no coordination. The SCF either fails cryptically or, worse, converges to a
+physically meaningless state that becomes a data point in someone's benchmark.
+
+`nqf-lint` reads a declared cluster and runs cheap, deterministic checks that catch
+these failure modes **before** the expensive calculation. It is written in Rust, has
+no runtime dependencies, and exits with a nonzero code on error so it drops straight
+into a `Makefile` or CI.
+
+Every check corresponds to a real bug found in a production pipeline.
+
+## Usage
+
+```
+nqf-lint geometry.xyz      # a standard XYZ geometry
+nqf-lint cluster.json      # the tool's own cluster spec (charge/spin/ECP)
+nqf-lint build_cluster.py  # Python source (conformer determinism)
+```
+
+**XYZ** is the universal format every quantum-chemistry package reads and writes,
+so the linter runs on real inputs, not only its own JSON. XYZ carries no charge or
+spin, so put them on the comment line — either as a bare `<charge> <mult>` pair or
+as `charge=.. mult=..` — to enable the electron-count checks; without them, those
+checks abstain and the geometry checks still run.
+
+```
+3
+charge=0 mult=1
+O   0.000   0.000   0.000
+H   0.757   0.586   0.000
+H  -0.757   0.586   0.000
+```
+
+The **JSON** spec adds what XYZ cannot express — the ECP list and the metal
+oxidation state — for the ECP-aware parity and d¹⁰ spin checks:
+
+```json
+{
+  "atoms": [
+    { "element": "Hg", "x": 0.0, "y": 0.0, "z": 0.0 },
+    { "element": "O",  "x": 2.30, "y": 0.0, "z": 0.0 },
+    { "element": "H",  "x": 2.60, "y": 0.80, "z": 0.0 },
+    { "element": "H",  "x": 2.60, "y": -0.80, "z": 0.0 }
+  ],
+  "charge": 2,
+  "spin_multiplicity": 1,
+  "ecp_elements": ["Hg"]
+}
+```
+
+## What it checks
+
+The geometry checks (bare heteroatom, metal coordination, overlapping atoms) run
+on any input — `.xyz` or `.json`. The electron-count checks need charge/spin, and
+the ECP/d¹⁰ checks need the extra fields only `.json` carries.
+
+**Geometry + electron count:**
+
+| check | catches |
+|---|---|
+| **electron parity** | `(N + M)` must be odd. Forgotten ECP core subtraction or a wrong formal charge silently flips parity — the SCF then fails or converges to nonsense. Counts electrons *with* the ECP core removed. |
+| **bare heteroatom** | a C/N/O/P/S with no bonding partner in covalent range: waters entered as bare oxygens, dropped hydrogens, or a fragment sliced through a bond. |
+| **metal coordination** | a metal center with zero neighbours in range is floating — the fragment was built wrong. |
+| **metal spin state** | a closed-shell d¹⁰ cation (Zn²⁺, Hg²⁺, Cu⁺, …) declared open-shell. Only fires when the oxidation state is given and the ion is unambiguous; abstains for ligand-field-dependent ions like Ni²⁺. |
+| **overlapping atoms** | two nuclei closer than 0.5 Å — below any real bond (H–H is 0.74 Å). A duplicated atom or a coordinate error that blows up the SCF or double-counts electrons. |
+| **unit scale (Å vs Bohr)** | coordinates in Bohr (1 Bohr = 0.529 Å) read as Ångström, inflating every distance ~1.89×. Anchored on hydrogen (an X–H bond is ~1.0 Å in every molecule): if the closest H sits > 1.5 Å from any atom, the geometry is almost certainly Bohr. Reports the converted value. |
+
+**Python source (`.py`):**
+
+| check | catches |
+|---|---|
+| **conformer seed** | `EmbedMolecule` / `EmbedMultipleConfs` with no fixed `randomSeed`. The embedding is nondeterministic: the same SMILES gives a different geometry each run, so any descriptor computed on it is irreproducible. This is the bug that turned a published ρ=0.855 into a lottery. |
+
+It **never guesses**. When it cannot verify something — an unknown ECP core, an
+unknown element — it abstains with a warning rather than emit a false verdict,
+because "cannot verify" is exactly where silent bugs live.
+
+## Design principle
+
+Every check must fail loudly on a known-bad input and pass a known-good one. The test
+suite is built from real bugs: the mining cluster whose "waters" were bare oxygens
+(`{Co:1, O:7, …}`, zero hydrogens), the Hg cluster whose charge was left at the
+all-electron value after switching on an ECP, the metal built with no ligand nearby.
+A check that cannot demonstrate both directions does not ship.
+
+## Build
+
+```
+cargo test    # 26 tests, each a real bug
+cargo build --release
+./target/release/nqf-lint examples/bad_mining_cluster.json   # → 4 errors, exit 4
+./target/release/nqf-lint examples/good_hg_cluster.json      # → clean, exit 0
+./target/release/nqf-lint examples/bad_floating_metal.xyz    # → 2 errors, exit 2
+./target/release/nqf-lint examples/bad_bohr_units.xyz        # → flags Bohr units
+./target/release/nqf-lint examples/water.xyz                 # → clean, exit 0
+```
+
+## Limitations
+
+This tool is deliberately narrow and states what it cannot verify.
+
+- **The electron-parity check assumes LANL2DZ core sizes.** With a different ECP
+  (SDD, def2-ECP, …) the number of replaced core electrons differs, and the parity
+  verdict would be wrong for a *known* element on a non-LANL2DZ ECP. For elements it
+  is unsure about, the tool abstains (a warning) rather than guess. If you use another
+  ECP, treat parity findings on those atoms as advisory and verify by hand.
+- **Bonding is judged by distance, not a real bond-perception model.** A terminal
+  metal-oxo/nitrido with an unusually long M=X bond (> 1.75 Å) could be flagged as a
+  "bare heteroatom". Rare, but possible.
+- **The conformer-seed check is a source-text heuristic, not a Python parser.** It
+  recognises the common seeding patterns (`randomSeed=` kwarg, `params.randomSeed =`);
+  an exotic way of setting the seed could be missed and reported as unseeded.
+
+The guiding rule is the opposite of the bug it exists to catch: when it cannot be
+sure, it says so, instead of emitting a confident wrong answer.
+
+## License
+
+MIT.

nqf_lint-0.2.0/README.md

@@ -0,0 +1,125 @@
+# nqf-lint
+
+**A pre-flight linter for quantum-chemistry cluster setups.**
+
+A quantum-chemistry calculation can run for hours and return a number that *looks*
+fine while the input was silently broken — an oxygen entered with no hydrogens, an
+electron count made impossible by a forgotten pseudopotential core, a metal floating
+with no coordination. The SCF either fails cryptically or, worse, converges to a
+physically meaningless state that becomes a data point in someone's benchmark.
+
+`nqf-lint` reads a declared cluster and runs cheap, deterministic checks that catch
+these failure modes **before** the expensive calculation. It is written in Rust, has
+no runtime dependencies, and exits with a nonzero code on error so it drops straight
+into a `Makefile` or CI.
+
+Every check corresponds to a real bug found in a production pipeline.
+
+## Usage
+
+```
+nqf-lint geometry.xyz      # a standard XYZ geometry
+nqf-lint cluster.json      # the tool's own cluster spec (charge/spin/ECP)
+nqf-lint build_cluster.py  # Python source (conformer determinism)
+```
+
+**XYZ** is the universal format every quantum-chemistry package reads and writes,
+so the linter runs on real inputs, not only its own JSON. XYZ carries no charge or
+spin, so put them on the comment line — either as a bare `<charge> <mult>` pair or
+as `charge=.. mult=..` — to enable the electron-count checks; without them, those
+checks abstain and the geometry checks still run.
+
+```
+3
+charge=0 mult=1
+O   0.000   0.000   0.000
+H   0.757   0.586   0.000
+H  -0.757   0.586   0.000
+```
+
+The **JSON** spec adds what XYZ cannot express — the ECP list and the metal
+oxidation state — for the ECP-aware parity and d¹⁰ spin checks:
+
+```json
+{
+  "atoms": [
+    { "element": "Hg", "x": 0.0, "y": 0.0, "z": 0.0 },
+    { "element": "O",  "x": 2.30, "y": 0.0, "z": 0.0 },
+    { "element": "H",  "x": 2.60, "y": 0.80, "z": 0.0 },
+    { "element": "H",  "x": 2.60, "y": -0.80, "z": 0.0 }
+  ],
+  "charge": 2,
+  "spin_multiplicity": 1,
+  "ecp_elements": ["Hg"]
+}
+```
+
+## What it checks
+
+The geometry checks (bare heteroatom, metal coordination, overlapping atoms) run
+on any input — `.xyz` or `.json`. The electron-count checks need charge/spin, and
+the ECP/d¹⁰ checks need the extra fields only `.json` carries.
+
+**Geometry + electron count:**
+
+| check | catches |
+|---|---|
+| **electron parity** | `(N + M)` must be odd. Forgotten ECP core subtraction or a wrong formal charge silently flips parity — the SCF then fails or converges to nonsense. Counts electrons *with* the ECP core removed. |
+| **bare heteroatom** | a C/N/O/P/S with no bonding partner in covalent range: waters entered as bare oxygens, dropped hydrogens, or a fragment sliced through a bond. |
+| **metal coordination** | a metal center with zero neighbours in range is floating — the fragment was built wrong. |
+| **metal spin state** | a closed-shell d¹⁰ cation (Zn²⁺, Hg²⁺, Cu⁺, …) declared open-shell. Only fires when the oxidation state is given and the ion is unambiguous; abstains for ligand-field-dependent ions like Ni²⁺. |
+| **overlapping atoms** | two nuclei closer than 0.5 Å — below any real bond (H–H is 0.74 Å). A duplicated atom or a coordinate error that blows up the SCF or double-counts electrons. |
+| **unit scale (Å vs Bohr)** | coordinates in Bohr (1 Bohr = 0.529 Å) read as Ångström, inflating every distance ~1.89×. Anchored on hydrogen (an X–H bond is ~1.0 Å in every molecule): if the closest H sits > 1.5 Å from any atom, the geometry is almost certainly Bohr. Reports the converted value. |
+
+**Python source (`.py`):**
+
+| check | catches |
+|---|---|
+| **conformer seed** | `EmbedMolecule` / `EmbedMultipleConfs` with no fixed `randomSeed`. The embedding is nondeterministic: the same SMILES gives a different geometry each run, so any descriptor computed on it is irreproducible. This is the bug that turned a published ρ=0.855 into a lottery. |
+
+It **never guesses**. When it cannot verify something — an unknown ECP core, an
+unknown element — it abstains with a warning rather than emit a false verdict,
+because "cannot verify" is exactly where silent bugs live.
+
+## Design principle
+
+Every check must fail loudly on a known-bad input and pass a known-good one. The test
+suite is built from real bugs: the mining cluster whose "waters" were bare oxygens
+(`{Co:1, O:7, …}`, zero hydrogens), the Hg cluster whose charge was left at the
+all-electron value after switching on an ECP, the metal built with no ligand nearby.
+A check that cannot demonstrate both directions does not ship.
+
+## Build
+
+```
+cargo test    # 26 tests, each a real bug
+cargo build --release
+./target/release/nqf-lint examples/bad_mining_cluster.json   # → 4 errors, exit 4
+./target/release/nqf-lint examples/good_hg_cluster.json      # → clean, exit 0
+./target/release/nqf-lint examples/bad_floating_metal.xyz    # → 2 errors, exit 2
+./target/release/nqf-lint examples/bad_bohr_units.xyz        # → flags Bohr units
+./target/release/nqf-lint examples/water.xyz                 # → clean, exit 0
+```
+
+## Limitations
+
+This tool is deliberately narrow and states what it cannot verify.
+
+- **The electron-parity check assumes LANL2DZ core sizes.** With a different ECP
+  (SDD, def2-ECP, …) the number of replaced core electrons differs, and the parity
+  verdict would be wrong for a *known* element on a non-LANL2DZ ECP. For elements it
+  is unsure about, the tool abstains (a warning) rather than guess. If you use another
+  ECP, treat parity findings on those atoms as advisory and verify by hand.
+- **Bonding is judged by distance, not a real bond-perception model.** A terminal
+  metal-oxo/nitrido with an unusually long M=X bond (> 1.75 Å) could be flagged as a
+  "bare heteroatom". Rare, but possible.
+- **The conformer-seed check is a source-text heuristic, not a Python parser.** It
+  recognises the common seeding patterns (`randomSeed=` kwarg, `params.randomSeed =`);
+  an exotic way of setting the seed could be missed and reported as unseeded.
+
+The guiding rule is the opposite of the bug it exists to catch: when it cannot be
+sure, it says so, instead of emitting a confident wrong answer.
+
+## License
+
+MIT.

nqf_lint-0.2.0/examples/bad_bohr_units.xyz

@@ -0,0 +1,5 @@
+3
+water written in Bohr (atomic units) instead of Angstrom — a classic footgun
+O    0.00000   0.00000   0.0
+H    1.43044   1.10738   0.0
+H   -1.43044   1.10738   0.0

nqf_lint-0.2.0/examples/bad_floating_metal.xyz

@@ -0,0 +1,4 @@
+2
+Zn and O written too far apart to be bonded — a broken fragment build
+Zn   0.000   0.000   0.000
+O    3.000   0.000   0.000

nqf_lint-0.2.0/examples/bad_mining_cluster.json

@@ -0,0 +1,13 @@
+{
+  "_comment": "O bug real da auditoria de mineração: 'águas' entradas como oxigênios NUS, todo H descartado, e carga formal deixada em 0 (paridade impossível). Composição observada em produção: {Co:1, O:7, ...}, zero H.",
+  "atoms": [
+    { "element": "Co", "x": 0.0,  "y": 0.0,  "z": 0.0 },
+    { "element": "O",  "x": 2.10, "y": 0.0,  "z": 0.0 },
+    { "element": "O",  "x": -2.10,"y": 0.0,  "z": 0.0 },
+    { "element": "O",  "x": 0.0,  "y": 2.10, "z": 0.0 },
+    { "element": "O",  "x": 0.0,  "y": -2.10,"z": 0.0 }
+  ],
+  "charge": 0,
+  "spin_multiplicity": 4,
+  "ecp_elements": []
+}

nqf_lint-0.2.0/examples/bad_spin_state.json

@@ -0,0 +1,13 @@
+{
+  "_comment": "Zn2+ é d10 (camada fechada) e DEVE ser singleto (M=1). Aqui foi declarado tripleto (M=3) — erro real de estado de spin, a mesma classe de bug que o benchmark de Ni cometeu ao rodar singleto onde não devia.",
+  "atoms": [
+    { "element": "Zn", "x": 0.0,  "y": 0.0,  "z": 0.0 },
+    { "element": "O",  "x": 2.10, "y": 0.0,  "z": 0.0 },
+    { "element": "H",  "x": 2.40, "y": 0.80, "z": 0.0 },
+    { "element": "H",  "x": 2.40, "y": -0.80,"z": 0.0 }
+  ],
+  "charge": 2,
+  "spin_multiplicity": 3,
+  "ecp_elements": [],
+  "metal_oxidation_state": 2
+}

nqf_lint-0.2.0/examples/good_hg_cluster.json

@@ -0,0 +1,16 @@
+{
+  "_comment": "Cluster Hg2+ bem-formado: duas águas reais (O + 2 H), carga +2, singleto, Hg com ECP LANL2DZ. Deve passar limpo.",
+  "atoms": [
+    { "element": "Hg", "x": 0.0,  "y": 0.0,  "z": 0.0 },
+    { "element": "O",  "x": 2.30, "y": 0.0,  "z": 0.0 },
+    { "element": "H",  "x": 2.60, "y": 0.80, "z": 0.0 },
+    { "element": "H",  "x": 2.60, "y": -0.80,"z": 0.0 },
+    { "element": "O",  "x": -2.30,"y": 0.0,  "z": 0.0 },
+    { "element": "H",  "x": -2.60,"y": 0.80, "z": 0.0 },
+    { "element": "H",  "x": -2.60,"y": -0.80,"z": 0.0 }
+  ],
+  "charge": 2,
+  "spin_multiplicity": 1,
+  "ecp_elements": ["Hg"],
+  "metal_oxidation_state": 2
+}

nqf_lint-0.2.0/examples/water.xyz

@@ -0,0 +1,5 @@
+3
+charge=0 mult=1
+O   0.000   0.000   0.000
+H   0.757   0.586   0.000
+H  -0.757   0.586   0.000