sattlint 1.0.0__tar.gz

sattlint-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Søren H. Johansen
+
+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.

sattlint-1.0.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: sattlint
+Version: 1.0.0
+Summary: Static analysis, validation, and tooling for SattLine projects
+Author: Søren H. Johansen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SorenHJohansen/SattLint
+Project-URL: Repository, https://github.com/SorenHJohansen/SattLint
+Project-URL: Issues, https://github.com/SorenHJohansen/SattLint/issues
+Project-URL: Documentation, https://docs.sattlint.dev
+Project-URL: Support, https://github.com/SorenHJohansen/SattLint/blob/main/SUPPORT.md
+Project-URL: Changelog, https://github.com/SorenHJohansen/SattLint/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/SorenHJohansen/SattLint/security/policy
+Keywords: sattline,static-analysis,plc
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark<2,>=1.3.1
+Requires-Dist: sattline-parser<2027,>=2026.9.1
+Requires-Dist: tomli_w>=1.2.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: textual<9,>=8.2.7
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "test"
+Provides-Extra: dev
+Requires-Dist: sattlint[test]; extra == "dev"
+Requires-Dist: ruff==0.16.5; extra == "dev"
+Requires-Dist: pyright>=1.1.411; extra == "dev"
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Dynamic: license-file
+
+# SattLint
+
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/SorenHJohansen/SattLint/badge)](https://securityscorecards.dev/viewer/?uri=github.com/SorenHJohansen/SattLint)
+
+SattLint is a Python toolkit for SattLine projects. It provides syntax-checking, configurable static analysis, ICF validation and formatting, graphics-rule analysis, and an interactive terminal UI.
+
+---
+
+## What SattLint Does
+
+- Check whether a SattLine file parses correctly
+- Analyze a full program or library together with its dependencies
+- Find issues such as unused variables, written-but-never-read variables, and shadowing
+- Validate and format ICF files and check graphics rules
+- Inspect parser outputs when something looks wrong
+
+---
+
+## Requirements
+
+- **Windows** or **Linux**
+- **Python 3.13 or newer**
+- **pipx** (for clean, isolated installation)
+- A local copy of your SattLine code
+
+---
+
+## Installation
+
+### 1. Get the source
+
+```bash
+git clone https://github.com/SorenHJohansen/SattLint.git
+cd SattLint
+```
+
+### 2. Install pipx
+
+#### Linux
+
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+Restart your terminal after this.
+
+#### Windows
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+```
+
+Restart your terminal after this.
+
+### 3. Install SattLint
+
+```bash
+pipx install .
+```
+
+This installs SattLint globally in an isolated environment.
+
+### 4. Verify
+
+```bash
+sattlint --version
+sattlint syntax-check tests/fixtures/sample_sattline_files/SattLineFullGrammarTest.s
+```
+
+---
+
+## Quick Start
+
+```bash
+sattlint syntax-check path/to/Program.s
+```
+
+Output:
+
+- `OK` — valid file
+- Error message — invalid file
+
+Exit codes:
+
+- `0` — success
+- `1` — a real problem was found (e.g. `syntax-check` found a syntax error)
+- `2` — invalid arguments or configuration
+
+`analyze` reports issues in its output but exits `0` once the analysis runs;
+among the CLI commands, only `syntax-check` uses exit code `1` for findings.
+
+### Available Commands
+
+```bash
+sattlint syntax-check path/to/Program.s
+sattlint init                    # scaffold a .slproj project file
+sattlint analyze --list-checks   # list available analyzers
+sattlint analyze --check naming-consistency
+sattlint validate-config
+sattlint cache-prune
+```
+
+Shared flags for config-driven commands:
+
+```bash
+sattlint --config path/to/config.toml analyze --check naming-consistency
+sattlint --config path/to/config.toml --no-cache analyze --check naming-consistency
+sattlint --project path/to/project.slproj analyze --check naming-consistency
+```
+
+For the full command reference, run `sattlint --help`.
+
+---
+
+## Interactive Shell
+
+```bash
+sattlint
+```
+
+Opens the Textual interactive terminal UI with the following views:
+
+- **Analyze** — queue curated reports and additional analyzers
+- **Setup** — configure paths, targets, mode, and cache settings
+- **Help** — first-time guidance and workflow explanation
+
+---
+
+## Project Files (.slproj)
+
+A `.slproj` project file captures all analysis settings in a single
+checked-in file: targets, directories, mode, and output/cache paths. Paths
+inside a `.slproj` are relative to the file itself, so projects are portable
+across machines.
+
+- `sattlint init` scaffolds a new `.slproj` in the current directory.
+- `sattlint --project PATH <command>` uses an explicit project file.
+- Without `--project` or `--config`, SattLint auto-discovers a `.slproj` by
+  walking up from the current working directory.
+- Project settings merge over `~/.config/sattlint/config.toml` defaults.
+
+Prefer a `.slproj` project file over editing `~/.config/sattlint/config.toml`
+directly.
+
+---
+
+## First-Time Setup
+
+The first time SattLint runs, it creates a config file automatically:
+
+- **Windows:** `%APPDATA%\sattlint\config.toml`
+- **Linux:** `~/.config/sattlint/config.toml`
+
+For a portable, checked-in setup, create a `.slproj` project file with
+`sattlint init` instead; project settings merge over these config defaults
+(see [Project Files](#project-files-slproj)).
+
+### Configuration
+
+1. Start SattLint with `sattlint`
+2. Select **Setup**
+3. Configure the following:
+
+   - `program_dir` — your SattLine program folder
+   - `ABB_lib_dir` — shared or ABB libraries
+   - `other_lib_dirs` — any additional libraries
+   - `analyzed_programs_and_libraries` — what to analyze
+   - `icf_dir` — directory used for ICF validation and formatting
+   - `Edit graphics rules` — define expected module invocation or clipping rules (saved as JSON)
+
+4. Save with **Save configuration**
+5. Select **Analyze** to run checks
+
+> **Note:** Use names without file extensions (e.g. `MyProgram`, not `MyProgram.s`).
+
+---
+
+## Updating
+
+```bash
+pipx install --force .
+```
+
+---
+
+## Graphics Rule Configuration
+
+1. Open **Setup**, then **Edit graphics rules** to add or update expected invocation coordinates, flags, and clipping-related values
+2. Use `unit:` selectors when a module should look the same in every detected unit (e.g. `unit:L1` or `unit:L1.L2.UnitControl`)
+3. Use `equipment:` selectors when a module should look the same inside every equipment module (e.g. `equipment:L1.L2.EquipModPanelShort`)
+4. Open **Analyze**, then run **Validate graphics rules** from **Structure & modules** to report modules that are not to spec
+5. Run `sattlint validate-config` to confirm the graphics rules JSON path is valid
+
+---
+
+## Common Problems
+
+### `sattlint` not found
+
+pipx is not on your PATH. Run `pipx ensurepath` and restart your terminal.
+
+### Python version error
+
+Install Python 3.13+ and reinstall with `pipx install --force .`.
+
+### Targets not found
+
+- Names must not include file extensions
+- Paths in config must be correct
+- Mode (`official` / `draft`) must match your files
+
+### Missing libraries
+
+Add missing folders to `ABB_lib_dir` or `other_lib_dirs`.
+
+### Results look outdated
+
+Use `sattlint --no-cache analyze` to skip the AST cache, or run `sattlint cache-prune` to remove stale cache artifacts before re-analyzing.
+
+---
+
+## For Developers
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and tooling.
+
+---
+
+## License
+
+SattLint is released under the MIT License.

sattlint-1.0.0/README.md

@@ -0,0 +1,232 @@
+# SattLint
+
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/SorenHJohansen/SattLint/badge)](https://securityscorecards.dev/viewer/?uri=github.com/SorenHJohansen/SattLint)
+
+SattLint is a Python toolkit for SattLine projects. It provides syntax-checking, configurable static analysis, ICF validation and formatting, graphics-rule analysis, and an interactive terminal UI.
+
+---
+
+## What SattLint Does
+
+- Check whether a SattLine file parses correctly
+- Analyze a full program or library together with its dependencies
+- Find issues such as unused variables, written-but-never-read variables, and shadowing
+- Validate and format ICF files and check graphics rules
+- Inspect parser outputs when something looks wrong
+
+---
+
+## Requirements
+
+- **Windows** or **Linux**
+- **Python 3.13 or newer**
+- **pipx** (for clean, isolated installation)
+- A local copy of your SattLine code
+
+---
+
+## Installation
+
+### 1. Get the source
+
+```bash
+git clone https://github.com/SorenHJohansen/SattLint.git
+cd SattLint
+```
+
+### 2. Install pipx
+
+#### Linux
+
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+Restart your terminal after this.
+
+#### Windows
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+```
+
+Restart your terminal after this.
+
+### 3. Install SattLint
+
+```bash
+pipx install .
+```
+
+This installs SattLint globally in an isolated environment.
+
+### 4. Verify
+
+```bash
+sattlint --version
+sattlint syntax-check tests/fixtures/sample_sattline_files/SattLineFullGrammarTest.s
+```
+
+---
+
+## Quick Start
+
+```bash
+sattlint syntax-check path/to/Program.s
+```
+
+Output:
+
+- `OK` — valid file
+- Error message — invalid file
+
+Exit codes:
+
+- `0` — success
+- `1` — a real problem was found (e.g. `syntax-check` found a syntax error)
+- `2` — invalid arguments or configuration
+
+`analyze` reports issues in its output but exits `0` once the analysis runs;
+among the CLI commands, only `syntax-check` uses exit code `1` for findings.
+
+### Available Commands
+
+```bash
+sattlint syntax-check path/to/Program.s
+sattlint init                    # scaffold a .slproj project file
+sattlint analyze --list-checks   # list available analyzers
+sattlint analyze --check naming-consistency
+sattlint validate-config
+sattlint cache-prune
+```
+
+Shared flags for config-driven commands:
+
+```bash
+sattlint --config path/to/config.toml analyze --check naming-consistency
+sattlint --config path/to/config.toml --no-cache analyze --check naming-consistency
+sattlint --project path/to/project.slproj analyze --check naming-consistency
+```
+
+For the full command reference, run `sattlint --help`.
+
+---
+
+## Interactive Shell
+
+```bash
+sattlint
+```
+
+Opens the Textual interactive terminal UI with the following views:
+
+- **Analyze** — queue curated reports and additional analyzers
+- **Setup** — configure paths, targets, mode, and cache settings
+- **Help** — first-time guidance and workflow explanation
+
+---
+
+## Project Files (.slproj)
+
+A `.slproj` project file captures all analysis settings in a single
+checked-in file: targets, directories, mode, and output/cache paths. Paths
+inside a `.slproj` are relative to the file itself, so projects are portable
+across machines.
+
+- `sattlint init` scaffolds a new `.slproj` in the current directory.
+- `sattlint --project PATH <command>` uses an explicit project file.
+- Without `--project` or `--config`, SattLint auto-discovers a `.slproj` by
+  walking up from the current working directory.
+- Project settings merge over `~/.config/sattlint/config.toml` defaults.
+
+Prefer a `.slproj` project file over editing `~/.config/sattlint/config.toml`
+directly.
+
+---
+
+## First-Time Setup
+
+The first time SattLint runs, it creates a config file automatically:
+
+- **Windows:** `%APPDATA%\sattlint\config.toml`
+- **Linux:** `~/.config/sattlint/config.toml`
+
+For a portable, checked-in setup, create a `.slproj` project file with
+`sattlint init` instead; project settings merge over these config defaults
+(see [Project Files](#project-files-slproj)).
+
+### Configuration
+
+1. Start SattLint with `sattlint`
+2. Select **Setup**
+3. Configure the following:
+
+   - `program_dir` — your SattLine program folder
+   - `ABB_lib_dir` — shared or ABB libraries
+   - `other_lib_dirs` — any additional libraries
+   - `analyzed_programs_and_libraries` — what to analyze
+   - `icf_dir` — directory used for ICF validation and formatting
+   - `Edit graphics rules` — define expected module invocation or clipping rules (saved as JSON)
+
+4. Save with **Save configuration**
+5. Select **Analyze** to run checks
+
+> **Note:** Use names without file extensions (e.g. `MyProgram`, not `MyProgram.s`).
+
+---
+
+## Updating
+
+```bash
+pipx install --force .
+```
+
+---
+
+## Graphics Rule Configuration
+
+1. Open **Setup**, then **Edit graphics rules** to add or update expected invocation coordinates, flags, and clipping-related values
+2. Use `unit:` selectors when a module should look the same in every detected unit (e.g. `unit:L1` or `unit:L1.L2.UnitControl`)
+3. Use `equipment:` selectors when a module should look the same inside every equipment module (e.g. `equipment:L1.L2.EquipModPanelShort`)
+4. Open **Analyze**, then run **Validate graphics rules** from **Structure & modules** to report modules that are not to spec
+5. Run `sattlint validate-config` to confirm the graphics rules JSON path is valid
+
+---
+
+## Common Problems
+
+### `sattlint` not found
+
+pipx is not on your PATH. Run `pipx ensurepath` and restart your terminal.
+
+### Python version error
+
+Install Python 3.13+ and reinstall with `pipx install --force .`.
+
+### Targets not found
+
+- Names must not include file extensions
+- Paths in config must be correct
+- Mode (`official` / `draft`) must match your files
+
+### Missing libraries
+
+Add missing folders to `ABB_lib_dir` or `other_lib_dirs`.
+
+### Results look outdated
+
+Use `sattlint --no-cache analyze` to skip the AST cache, or run `sattlint cache-prune` to remove stale cache artifacts before re-analyzing.
+
+---
+
+## For Developers
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and tooling.
+
+---
+
+## License
+
+SattLint is released under the MIT License.

sattlint-1.0.0/pyproject.toml

@@ -0,0 +1,130 @@
+[build-system]
+requires = ["setuptools>=82.0.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sattlint"
+dynamic = ["version"]
+description = "Static analysis, validation, and tooling for SattLine projects"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "S\u00f8ren H. Johansen" }]
+requires-python = ">=3.13"
+keywords = ["sattline", "static-analysis", "plc"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "lark>=1.3.1,<2",
+    "sattline-parser>=2026.9.1,<2027",
+    "tomli_w>=1.2.0",
+    "rich>=13.9.0",
+    "textual>=8.2.7,<9",
+]
+
+[project.urls]
+Homepage = "https://github.com/SorenHJohansen/SattLint"
+Repository = "https://github.com/SorenHJohansen/SattLint"
+Issues = "https://github.com/SorenHJohansen/SattLint/issues"
+Documentation = "https://docs.sattlint.dev"
+Support = "https://github.com/SorenHJohansen/SattLint/blob/main/SUPPORT.md"
+Changelog = "https://github.com/SorenHJohansen/SattLint/blob/main/CHANGELOG.md"
+Security = "https://github.com/SorenHJohansen/SattLint/security/policy"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",       # Coverage reporting
+    "pytest-timeout>=2.3.1",   # Fail fast on stalled tests
+]
+
+dev = [
+    "sattlint[test]",
+    "ruff==0.16.5",    # Match pre-commit Ruff to avoid formatter drift
+    "pyright>=1.1.411", # Type checking
+    "build>=1.2.2",    # Build frontend for release validation
+    "twine>=5.1.1",    # Package metadata validation
+    "pre-commit>=4.0", # Git hooks
+]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+timeout = 60
+timeout_method = "thread"
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+    "parser: marks tests related to parser functionality",
+    "analyzer: marks tests related to analyzer functionality",
+    "quarantine: marks flaky tests that should be skipped in CI",
+]
+
+[tool.coverage.report]
+precision = 2
+
+[project.scripts]
+sattlint = "sattlint.cli.startup:cli"
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "F",     # pyflakes
+    "W",     # pycodestyle warnings
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugarith
+    "BLE",   # blind except Exception handlers
+    "C4",    # flake8-comprehensions
+    "PLC0415", # imports outside top-level
+    "PLR0915", # too many statements
+    "S101",  # disallow assert-based error handling
+    "SIM",   # flake8-simplify
+    "RUF",   # ruff-specific rules
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["S101", "F403", "F405"]
+"tests/**/*.py" = ["S101", "F403", "F405"]
+
+[tool.ruff.lint.pylint]
+max-statements = 50
+
+[tool.pyright]
+include = ["src/sattlint"]
+typeCheckingMode = "strict"
+pythonVersion = "3.13"
+venvPath = "."
+venv = ".venv"
+extraPaths = ["src"]
+reportMissingTypeStubs = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "sattlint.__version__.__version__" }

sattlint-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+