scitex-linter 0.1.0

AST-based linter enforcing SciTeX reproducible research patterns

SciTeX Linter

scitex.ai · docs · pip install scitex-linter

---

AST-based Python linter enforcing SciTeX reproducible research patterns.

Part of the SciTeX ecosystem — guides both human researchers and AI agents toward reproducible science.

Why SciTeX Linter?

SciTeX scripts follow strict patterns for reproducibility: @stx.session decorators, stx.io for provenance-tracked I/O, stx.stats for complete statistical reporting, and relative paths for portability. SciTeX Linter enforces these patterns at the AST level — catching issues before they become irreproducible results.

Quick Start

pip install scitex-linter

# Lint a file
scitex-linter lint script.py

# Lint then execute
scitex-linter python experiment.py --strict

# List all 35 rules
scitex-linter list-rules

Four Interfaces

Interface	For	Description
🖥️ CLI	Terminal users	scitex-linter lint, scitex-linter python
🐍 Python API	Programmatic use	from scitex_linter.checker import lint_file
🔌 flake8 Plugin	CI pipelines	flake8 --select STX
🔧 MCP Server	AI agents	3 tools for Claude/GPT integration

🖥️ CLI Commands

scitex-linter --help                              # Show all commands
scitex-linter --help-recursive                    # Show help for all subcommands

# Lint - Check for SciTeX pattern violations
scitex-linter lint script.py                      # Lint a file
scitex-linter lint ./src/                         # Lint a directory
scitex-linter lint script.py --severity error     # Only errors
scitex-linter lint script.py --category path      # Only path rules
scitex-linter lint script.py --json               # JSON output for CI

# Python - Lint then execute
scitex-linter python experiment.py                # Lint and run
scitex-linter python experiment.py --strict       # Abort on errors
scitex-linter python experiment.py -- --lr 0.001  # Pass script args

# Rules - Browse available rules
scitex-linter list-rules                          # List all 35 rules
scitex-linter list-rules --category stats         # Filter by category
scitex-linter list-rules --json                   # JSON output

# MCP - AI agent server
scitex-linter mcp start                           # Start MCP server (stdio)
scitex-linter mcp list-tools                      # List MCP tools

🐍 Python API

from scitex_linter.checker import lint_file
from scitex_linter.formatter import format_issue

# Lint a file
issues = lint_file("script.py")
for issue in issues:
    print(format_issue(issue, "script.py"))

# Check source code directly
from scitex_linter.checker import lint_source
issues = lint_source("import argparse\npass\n")

🔌 flake8 Plugin

SciTeX Linter registers as a flake8 plugin with the STX prefix:

flake8 --select STX script.py
flake8 --select STX ./src/ --format=json

Integrates with existing flake8 workflows, pre-commit hooks, and CI pipelines.

🔧 MCP Server — 3 Tools for AI Agents

Tool	Description
linter_lint	Lint a Python file for SciTeX compliance
linter_list_rules	List all available rules
linter_check_source	Lint source code string

Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "scitex-linter": {
      "command": "scitex-linter",
      "args": ["mcp", "start"]
    }
  }
}

Install MCP extra: pip install scitex-linter[mcp]

35 Rules Across 7 Categories

Category	Rules	Severity	What It Enforces
S Structure	5	error/warning	@stx.session, __main__ guard, no argparse
I Import	7	warning/info	Use stx.plt, stx.stats, stx.io instead of raw libs
IO I/O Calls	7	warning	Use stx.io.save()/stx.io.load() for provenance
P Plot	5	info	Use stx.plt tracked methods, logger over print()
ST Stats	6	warning	Use stx.stats for auto effect size + CI + power
PA Path	5	warning/info	Relative paths with ./, no open(), no os.chdir()

Example Output

script.py:1   STX-S003  [error]    argparse detected — @stx.session auto-generates CLI
  Suggestion: Remove `import argparse` and define parameters as function arguments:
    @stx.session
    def main(data_path: str, threshold: float = 0.5):
        # Auto-generates: --data-path, --threshold

script.py:5   STX-PA001 [warning]  Absolute path in `stx.io` call — use relative paths
  Suggestion: Use `stx.io.save(obj, './relative/path.ext')` — paths resolve to script_out/.

script.py: 2 issues (1 error, 1 warning)

Full Rules Reference

See Rules Reference for all 35 rules with descriptions and suggestions.

Claude Code Hook

SciTeX Linter works as a post-tool-use hook for Claude Code, automatically linting every Python file Claude writes or edits:

# In ~/.claude/to_claude/hooks/post-tool-use/run_lint.sh
# Errors (exit 2) → Claude must fix
# Warnings (exit 1) → Claude sees feedback

This ensures AI-generated code follows SciTeX patterns from the start.

What a Clean Script Looks Like

import scitex as stx

@stx.session
def main(data_path="./data.csv", threshold=0.5):
    df = stx.io.load(data_path)
    results = stx.stats.ttest_ind(df["group_a"], df["group_b"])
    stx.io.save(results, "./results.csv")
    return 0

if __name__ == "__main__":
    main()

Zero lint issues. Fully reproducible. Auto-CLI from function signature.

Documentation

📚 Full Documentation on Read the Docs

• Installation
• Quick Start
• Rules Reference
• CLI Reference
• Claude Code Hook

---

AGPL-3.0 · [e-mail]