Metadata-Version: 2.4
Name: scieqlint
Version: 1.0.0
Summary: Deterministic linter for exact scalar equations and equation references in scientific documents.
Project-URL: Homepage, https://github.com/Kuhai9801/scieqlint
Project-URL: Repository, https://github.com/Kuhai9801/scieqlint
Project-URL: Issues, https://github.com/Kuhai9801/scieqlint/issues
Project-URL: Documentation, https://Kuhai9801.github.io/scieqlint
Author: SciEqLint contributors
License: MIT
License-File: LICENSE
Keywords: ci,equations,lint,markdown,myst,scientific-writing
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: jsonschema>=4.23; extra == 'dev'
Requires-Dist: pyright>=1.1.390; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: notebook
Requires-Dist: nbformat>=5.10; extra == 'notebook'
Provides-Extra: v010
Requires-Dist: lark>=1.2; extra == 'v010'
Requires-Dist: markdown-it-py>=3.0; extra == 'v010'
Requires-Dist: mdit-py-plugins>=0.4; extra == 'v010'
Requires-Dist: pathspec>=0.12; extra == 'v010'
Requires-Dist: sympy>=1.13; extra == 'v010'
Description-Content-Type: text/markdown

# SciEqLint

[![PyPI](https://img.shields.io/pypi/v/scieqlint.svg)](https://pypi.org/project/scieqlint/)
[![Python versions](https://img.shields.io/pypi/pyversions/scieqlint.svg)](https://pypi.org/project/scieqlint/)
[![CI](https://github.com/Kuhai9801/scieqlint/actions/workflows/ci.yml/badge.svg)](https://github.com/Kuhai9801/scieqlint/actions/workflows/ci.yml)
[![Codecov](https://codecov.io/github/Kuhai9801/scieqlint/graph/badge.svg)](https://app.codecov.io/github/Kuhai9801/scieqlint)
[![Docs](https://github.com/Kuhai9801/scieqlint/actions/workflows/docs.yml/badge.svg)](https://github.com/Kuhai9801/scieqlint/actions/workflows/docs.yml)
[![CodeQL](https://github.com/Kuhai9801/scieqlint/actions/workflows/codeql.yml/badge.svg)](https://github.com/Kuhai9801/scieqlint/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Kuhai9801/scieqlint/badge)](https://scorecard.dev/viewer/?uri=github.com/Kuhai9801/scieqlint)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

SciEqLint checks documented scientific document formats for exact scalar algebra
mistakes and broken equation references.

Run it on Markdown/MyST docs before review to catch mistakes like this:

```tex
(a+b)^2 = a^2 + b^2
```

Diagnostic:

```text
ALG001 algebraic identity does not hold
left - right = 2*a*b
```

It also catches supported broken equation references:

```md
See {eq}`missing`.
```

Diagnostic:

```text
REF002 equation reference target not found: missing
```

## Install

```bash
python -m pip install scieqlint
scieqlint check .
```

For local development:

```bash
python -m pip install -e '.[dev]'
scieqlint --help
scieqlint check .
scieqlint check README.md
scieqlint check examples/bad/famous_bad.md --format github
scieqlint demo
```

## Commands

```bash
scieqlint check [PATH_OR_GLOB...]
scieqlint graph [PATH_OR_GLOB...] --output scieqlint-graph.json
scieqlint init
scieqlint init --preset mechanics
scieqlint presets list
scieqlint presets show mechanics
scieqlint demo
scieqlint explain CODE
python -m scieqlint --help
```

## Deterministic output

SciEqLint is deterministic. Given the same files, config, and version, it must emit
the same diagnostics in the same order. Supported math is checked exactly.
Unsupported math is reported as unknown or skipped. The checker must not guess.

## Supported files

SciEqLint checks `.md`, `.markdown`, `.tex`, and `.ipynb` documents. It supports
Markdown/MyST display math, supported LaTeX containers, notebook Markdown cells,
labels and references, simple scalar algebra, text output, deterministic JSON output,
SARIF, and JSON Schema validation. See `docs/limitations.md` for the exact
scanner and grammar coverage.

Current release target: v1.0.0.

## Pull request annotations

```yaml
- name: Check equations
  run: scieqlint check "docs/**/*.md" --format github
```

## Code scanning

```yaml
permissions:
  contents: read
  security-events: write

steps:
  - uses: actions/checkout@v6
  - uses: Kuhai9801/scieqlint@v1.0.0
    with:
      args: check "docs/**/*.md" --format sarif --output scieqlint.sarif
  - uses: github/codeql-action/upload-sarif@v4
    with:
      sarif_file: scieqlint.sarif
      category: scieqlint-docs
```

## For contributors

Start with these files:

- `SPEC.md` for the product and engineering contract.
- `CONTRIBUTING.md` for the local workflow.
- `GOOD_FIRST_ISSUES.md` for scoped starter tasks.
- `ROADMAP.md` for release order and cut rules.
- `docs/contributing/` for deeper guidance.

Keep PRs small and test the behavior they change.

## License

MIT. See `LICENSE`.
