scitex-linter 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

scitex_linter/__init__.py

@@ -1,3 +1,3 @@
 """SciTeX Linter — enforce reproducible research patterns via AST analysis."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

scitex_linter/_cmd_format.py

@@ -0,0 +1,70 @@
+"""CLI handler for the 'format' subcommand."""
+
+import difflib
+import sys
+from pathlib import Path
+
+from .fixer import fix_source
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser(
+        "format",
+        help="Auto-fix SciTeX pattern issues",
+        description="Auto-fix SciTeX pattern issues (e.g. insert missing INJECTED parameters).",
+    )
+    p.add_argument("path", help="Python file or directory to format")
+    p.add_argument(
+        "--check",
+        action="store_true",
+        help="Check if changes needed without writing (exit 1 if changes needed)",
+    )
+    p.add_argument("--diff", action="store_true", help="Show diff of changes")
+    p.set_defaults(func=cmd_format)
+
+
+def cmd_format(args) -> int:
+    from .cli import _collect_files
+    from .config import load_config
+
+    config = load_config(args.path)
+    target = Path(args.path)
+    if not target.exists():
+        print(f"Error: {args.path} not found", file=sys.stderr)
+        return 2
+
+    files = _collect_files(target, config=config)
+    if not files:
+        print(f"No Python files found in {args.path}", file=sys.stderr)
+        return 0
+
+    changed_count = 0
+    for f in files:
+        original = f.read_text(encoding="utf-8")
+        fixed = fix_source(original, filepath=str(f), config=config)
+        if fixed != original:
+            changed_count += 1
+            if args.diff:
+                diff = difflib.unified_diff(
+                    original.splitlines(keepends=True),
+                    fixed.splitlines(keepends=True),
+                    fromfile=str(f),
+                    tofile=str(f),
+                )
+                sys.stdout.writelines(diff)
+            if not args.check:
+                f.write_text(fixed, encoding="utf-8")
+                print(f"Fixed {f}")
+            else:
+                print(f"Would fix {f}")
+
+    if changed_count == 0:
+        print("All files clean")
+        return 0
+
+    if args.check:
+        print(f"\n{changed_count} file(s) would be changed")
+        return 1
+
+    print(f"\n{changed_count} file(s) fixed")
+    return 0

scitex_linter/_mcp/tools/lint.py

@@ -7,15 +7,17 @@ def register_lint_tools(mcp) -> None:
     """Register lint-related MCP tools."""
 
     @mcp.tool()
-    def linter_lint(
+    def linter_check(
         path: str, severity: str = "info", category: Optional[str] = None
     ) -> dict:
-        """[linter] Lint a Python file for SciTeX pattern compliance."""
+        """[linter] Check a Python file for SciTeX pattern compliance."""
         from ...checker import lint_file
+        from ...config import load_config
         from ...formatter import to_json
         from ...rules import SEVERITY_ORDER
 
-        issues = lint_file(path)
+        config = load_config(path)
+        issues = lint_file(path, config=config)
         min_sev = SEVERITY_ORDER.get(severity, 0)
         categories = set(category.split(",")) if category else None
 
@@ -61,7 +63,9 @@ def register_lint_tools(mcp) -> None:
     def linter_check_source(source: str, filepath: str = "<stdin>") -> dict:
         """[linter] Lint Python source code string for SciTeX pattern compliance."""
         from ...checker import lint_source
+        from ...config import load_config
         from ...formatter import to_json
 
-        issues = lint_source(source, filepath=filepath)
+        config = load_config(filepath)
+        issues = lint_source(source, filepath=filepath, config=config)
         return to_json(issues, filepath)

scitex_linter/_server.py

@@ -8,7 +8,7 @@ _INSTRUCTIONS = """\
 SciTeX Linter: AST-based linter enforcing reproducible research patterns.
 
 Tools:
-- linter_lint: Lint a Python file
+- linter_check: Check a Python file
 - linter_list_rules: List all lint rules
 - linter_check_source: Lint source code string
 """

scitex_linter/checker.py

@@ -8,13 +8,8 @@ from . import rules
 from .rules import Rule
 
 # Shortcuts for Phase 1 rules
-S001, S002, S003, S004, S005 = (
-    rules.S001,
-    rules.S002,
-    rules.S003,
-    rules.S004,
-    rules.S005,
-)
+S001, S002, S003 = rules.S001, rules.S002, rules.S003
+S004, S005, S006 = rules.S004, rules.S005, rules.S006
 I001, I002, I003 = rules.I001, rules.I002, rules.I003
 I006, I007 = rules.I006, rules.I007
 
@@ -67,24 +62,42 @@ class Issue:
     source_line: str = ""
 
 
-def is_script(filepath: str) -> bool:
-    """Check if file is a script (not a library module)."""
-    name = Path(filepath).name
-    if name == "__init__.py":
-        return False
-    if name.startswith("test_") or name == "conftest.py":
-        return False
-    if name in ("setup.py", "manage.py"):
+def is_script(filepath: str, config=None) -> bool:
+    """Check if file is a script (not a library module).
+
+    Uses config.library_patterns and config.library_dirs to determine
+    which files are library modules (exempt from script-only rules).
+    """
+    from .config import LinterConfig, matches_library_pattern
+
+    if config is None:
+        config = LinterConfig()
+
+    path = Path(filepath)
+    name = path.name
+
+    # Check filename against library patterns (e.g., __*__.py, test_*.py)
+    if matches_library_pattern(name, config):
         return False
+
+    # Check if file is inside a library directory (e.g., src/)
+    parts = path.parts
+    for lib_dir in config.library_dirs:
+        if lib_dir in parts:
+            return False
+
     return True
 
 
 class SciTeXChecker(ast.NodeVisitor):
     """AST visitor detecting non-SciTeX patterns."""
 
-    def __init__(self, source_lines: list, filepath: str = "<stdin>"):
+    def __init__(self, source_lines: list, filepath: str = "<stdin>", config=None):
+        from .config import LinterConfig
+
         self.source_lines = source_lines
         self.filepath = filepath
+        self.config = config or LinterConfig()
         self.issues: list = []
 
         # Tracking state
@@ -93,7 +106,7 @@ class SciTeXChecker(ast.NodeVisitor):
         self._has_session_decorator = False
         self._session_func_returns_int = False
         self._imports: dict = {}  # alias -> full module path
-        self._is_script = is_script(filepath)
+        self._is_script = is_script(filepath, self.config)
 
     # -----------------------------------------------------------------
     # Import visitors
@@ -343,10 +356,15 @@ class SciTeXChecker(ast.NodeVisitor):
     # Function/decorator visitors
     # -----------------------------------------------------------------
 
+    @property
+    def _REQUIRED_INJECTED(self):
+        return set(self.config.required_injected)
+
     def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
         if self._has_session_deco(node):
             self._has_session_decorator = True
             self._check_session_return(node)
+            self._check_injected_params(node)
         self.generic_visit(node)
 
     visit_AsyncFunctionDef = visit_FunctionDef
@@ -380,6 +398,25 @@ class SciTeXChecker(ast.NodeVisitor):
         line = self._get_source(node.lineno)
         self._add(S004, node.lineno, node.col_offset, line)
 
+    def _check_injected_params(self, node: ast.FunctionDef) -> None:
+        """Check that @stx.session function declares all INJECTED parameters."""
+        declared = {arg.arg for arg in node.args.args}
+        missing = sorted(self._REQUIRED_INJECTED - declared)
+        if missing:
+            line = self._get_source(node.lineno)
+            missing_str = ", ".join(missing)
+            dynamic_rule = Rule(
+                id=S006.id,
+                severity=S006.severity,
+                category=S006.category,
+                message=(
+                    f"@stx.session function missing INJECTED parameters: {missing_str}. "
+                    f"All 5 must be declared: CONFIG, COLORS, logger, plt, rngg"
+                ),
+                suggestion=S006.suggestion,
+            )
+            self._add(dynamic_rule, node.lineno, node.col_offset, line)
+
     # -----------------------------------------------------------------
     # Module-level checks (run after visiting entire tree)
     # -----------------------------------------------------------------
@@ -427,11 +464,12 @@ class SciTeXChecker(ast.NodeVisitor):
         self.issues.sort(key=lambda i: (-SEVERITY_ORDER[i.rule.severity], i.line))
         return self.issues
 
-    # -----------------------------------------------------------------
-    # Helpers
-    # -----------------------------------------------------------------
-
     def _add(self, rule: Rule, line: int, col: int, source_line: str) -> None:
+        if rule.id in self.config.disable:
+            return
+        sev = self.config.per_rule_severity.get(rule.id)
+        if sev:
+            rule = Rule(rule.id, sev, rule.category, rule.message, rule.suggestion)
         self.issues.append(
             Issue(rule=rule, line=line, col=col, source_line=source_line)
         )
@@ -447,7 +485,7 @@ class SciTeXChecker(ast.NodeVisitor):
 # =============================================================================
 
 
-def lint_source(source: str, filepath: str = "<stdin>") -> list:
+def lint_source(source: str, filepath: str = "<stdin>", config=None) -> list:
     """Lint Python source code and return list of Issues."""
     try:
         tree = ast.parse(source, filename=filepath)
@@ -455,15 +493,15 @@ def lint_source(source: str, filepath: str = "<stdin>") -> list:
         return []
 
     lines = source.splitlines()
-    checker = SciTeXChecker(lines, filepath=filepath)
+    checker = SciTeXChecker(lines, filepath=filepath, config=config)
     checker.visit(tree)
     return checker.get_issues()
 
 
-def lint_file(filepath: str) -> list:
+def lint_file(filepath: str, config=None) -> list:
     """Lint a Python file and return list of Issues."""
     path = Path(filepath)
     if not path.exists() or not path.is_file():
         return []
     source = path.read_text(encoding="utf-8")
-    return lint_source(source, filepath=str(path))
+    return lint_source(source, filepath=str(path), config=config)

scitex_linter/cli.py

@@ -1,9 +1,10 @@
 """CLI entry point for scitex-linter.
 
 Usage:
-    scitex-linter lint <path> [--json] [--severity] [--category] [--no-color]
+    scitex-linter check <path> [--json] [--severity] [--category] [--no-color]
+    scitex-linter format <path> [--check] [--diff]
     scitex-linter python <script.py> [--strict] [-- script_args...]
-    scitex-linter list-rules [--json] [--category] [--severity]
+    scitex-linter rule [--json] [--category] [--severity]
     scitex-linter mcp start
     scitex-linter mcp list-tools
     scitex-linter --help-recursive
@@ -15,7 +16,9 @@ import sys
 from pathlib import Path
 
 from . import __version__
+from ._cmd_format import register as _register_format
 from .checker import lint_file
+from .config import load_config
 from .formatter import format_issue, format_summary, to_json
 from .rules import ALL_RULES, SEVERITY_ORDER
 
@@ -24,13 +27,17 @@ from .rules import ALL_RULES, SEVERITY_ORDER
 # =========================================================================
 
 
-def _collect_files(path: Path, recursive: bool = True) -> list:
+def _collect_files(path: Path, recursive: bool = True, config=None) -> list:
     """Collect Python files from a path."""
     if path.is_file():
         return [path]
     if path.is_dir():
         pattern = "**/*.py" if recursive else "*.py"
-        skip = {"__pycache__", ".git", "node_modules", ".tox", "venv", ".venv"}
+        skip = (
+            set(config.exclude_dirs)
+            if config
+            else {"__pycache__", ".git", "node_modules", ".tox", "venv", ".venv"}
+        )
         return sorted(
             p for p in path.glob(pattern) if not any(s in p.parts for s in skip)
         )
@@ -38,17 +45,17 @@ def _collect_files(path: Path, recursive: bool = True) -> list:
 
 
 # =========================================================================
-# Subcommand: lint
+# Subcommand: check
 # =========================================================================
 
 
-def _register_lint(subparsers) -> None:
+def _register_check(subparsers) -> None:
     p = subparsers.add_parser(
-        "lint",
-        help="Lint Python files for SciTeX pattern compliance",
-        description="Lint Python files for SciTeX pattern compliance.",
+        "check",
+        help="Check Python files for SciTeX pattern compliance",
+        description="Check Python files for SciTeX pattern compliance.",
     )
-    p.add_argument("path", help="Python file or directory to lint")
+    p.add_argument("path", help="Python file or directory to check")
     p.add_argument("--json", action="store_true", dest="as_json", help="Output as JSON")
     p.add_argument("--no-color", action="store_true", help="Disable colored output")
     p.add_argument(
@@ -61,10 +68,11 @@ def _register_lint(subparsers) -> None:
         "--category",
         help="Filter by category (comma-separated: structure,import,io,plot,stats)",
     )
-    p.set_defaults(func=_cmd_lint)
+    p.set_defaults(func=_cmd_check)
 
 
-def _cmd_lint(args) -> int:
+def _cmd_check(args) -> int:
+    config = load_config(args.path)
     use_color = not args.no_color and sys.stdout.isatty()
     min_sev = SEVERITY_ORDER[args.severity]
     categories = set(args.category.split(",")) if args.category else None
@@ -74,14 +82,14 @@ def _cmd_lint(args) -> int:
         print(f"Error: {args.path} not found", file=sys.stderr)
         return 2
 
-    files = _collect_files(target)
+    files = _collect_files(target, config=config)
     if not files:
         print(f"No Python files found in {args.path}", file=sys.stderr)
         return 0
 
     all_results = {}
     for f in files:
-        issues = lint_file(str(f))
+        issues = lint_file(str(f), config=config)
         issues = [
             i
             for i in issues
@@ -151,13 +159,13 @@ def _cmd_python(args) -> int:
 
 
 # =========================================================================
-# Subcommand: list-rules
+# Subcommand: rule
 # =========================================================================
 
 
-def _register_list_rules(subparsers) -> None:
+def _register_rule(subparsers) -> None:
     p = subparsers.add_parser(
-        "list-rules",
+        "rule",
         help="List all lint rules",
         description="List all available SciTeX lint rules.",
     )
@@ -171,10 +179,10 @@ def _register_list_rules(subparsers) -> None:
         choices=["error", "warning", "info"],
         help="Filter by severity",
     )
-    p.set_defaults(func=_cmd_list_rules)
+    p.set_defaults(func=_cmd_rule)
 
 
-def _cmd_list_rules(args) -> int:
+def _cmd_rule(args) -> int:
     categories = set(args.category.split(",")) if args.category else None
     rules_list = list(ALL_RULES.values())
 
@@ -272,7 +280,7 @@ def _cmd_mcp_start(args) -> int:
 
 def _cmd_mcp_list_tools(args) -> int:
     tools = [
-        ("linter_lint", "Lint a Python file for SciTeX pattern compliance"),
+        ("linter_check", "Check a Python file for SciTeX pattern compliance"),
         ("linter_list_rules", "List all available lint rules"),
         ("linter_check_source", "Lint Python source code string"),
     ]
@@ -364,7 +372,6 @@ def _cmd_mcp_installation(args) -> int:
 def _print_help_recursive(parser, subparsers_actions) -> None:
     """Print help for all commands recursively."""
     cyan = "\033[96m" if sys.stdout.isatty() else ""
-    bold = "\033[1m" if sys.stdout.isatty() else ""
     reset = "\033[0m" if sys.stdout.isatty() else ""
 
     bar = "\u2501" * 3
@@ -409,9 +416,10 @@ def main(argv: list = None) -> int:
 
     subparsers = parser.add_subparsers(dest="command")
 
-    _register_lint(subparsers)
+    _register_check(subparsers)
+    _register_format(subparsers)
     _register_python(subparsers)
-    _register_list_rules(subparsers)
+    _register_rule(subparsers)
     _register_mcp(subparsers)
 
     # Split on -- to capture script args for the 'python' subcommand

scitex_linter/config.py

@@ -0,0 +1,206 @@
+"""Configuration system for scitex-linter."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomli as tomllib
+    except ImportError:
+        tomllib = None  # type: ignore
+
+
+@dataclass
+class LinterConfig:
+    """Configuration for scitex-linter behavior."""
+
+    severity: str = "info"
+    exclude_dirs: list[str] = field(
+        default_factory=lambda: [
+            "__pycache__",
+            ".git",
+            "node_modules",
+            ".tox",
+            "venv",
+            ".venv",
+        ]
+    )
+    library_patterns: list[str] = field(
+        default_factory=lambda: [
+            "__*__.py",
+            "test_*.py",
+            "conftest.py",
+            "setup.py",
+            "manage.py",
+        ]
+    )
+    library_dirs: list[str] = field(default_factory=lambda: ["src"])
+    disable: list[str] = field(default_factory=list)
+    per_rule_severity: dict[str, str] = field(default_factory=dict)
+    required_injected: list[str] = field(
+        default_factory=lambda: ["CONFIG", "plt", "COLORS", "rngg", "logger"]
+    )
+
+
+# =============================================================================
+# Configuration Loading
+# =============================================================================
+
+
+def load_config(start_path: str | None = None) -> LinterConfig:
+    """
+    Load configuration from defaults, pyproject.toml, and environment variables.
+
+    Priority: env vars > pyproject.toml > defaults
+
+    Args:
+        start_path: Starting directory for pyproject.toml search (defaults to cwd)
+
+    Returns:
+        Merged configuration
+    """
+    # Start with defaults
+    config_dict = {}
+
+    # Load from pyproject.toml
+    start_dir = Path(start_path).resolve() if start_path else Path.cwd()
+    pyproject_config = _load_pyproject(start_dir)
+    config_dict.update(pyproject_config)
+
+    # Load from environment variables (highest priority)
+    env_config = _load_env()
+    config_dict.update(env_config)
+
+    # Build LinterConfig with merged values
+    return LinterConfig(**config_dict)
+
+
+def _load_pyproject(start_dir: Path) -> dict:
+    """
+    Walk up directories to find pyproject.toml with [tool.scitex-linter].
+
+    Args:
+        start_dir: Starting directory for search
+
+    Returns:
+        Configuration dict from [tool.scitex-linter], or empty dict if not found
+    """
+    if tomllib is None:
+        return {}
+
+    current = start_dir
+    while True:
+        pyproject_path = current / "pyproject.toml"
+        if pyproject_path.exists():
+            try:
+                with open(pyproject_path, "rb") as f:
+                    data = tomllib.load(f)
+                    tool_config = data.get("tool", {}).get("scitex-linter", {})
+                    if tool_config:
+                        # Flatten nested sections
+                        config = {}
+                        for key, value in tool_config.items():
+                            if key == "per-rule-severity":
+                                config["per_rule_severity"] = value
+                            elif key == "session":
+                                # Handle [tool.scitex-linter.session]
+                                if "required_injected" in value:
+                                    config["required_injected"] = value[
+                                        "required_injected"
+                                    ]
+                            else:
+                                # Convert kebab-case to snake_case
+                                config[key.replace("-", "_")] = value
+                        return config
+            except Exception:
+                pass
+
+        # Move up one directory
+        parent = current.parent
+        if parent == current:
+            # Reached filesystem root
+            break
+        current = parent
+
+    return {}
+
+
+def _load_env() -> dict:
+    """
+    Load configuration from environment variables with SCITEX_LINTER_ prefix.
+
+    Returns:
+        Configuration dict with snake_case keys
+    """
+    config = {}
+
+    # Simple string values
+    if "SCITEX_LINTER_SEVERITY" in os.environ:
+        config["severity"] = os.environ["SCITEX_LINTER_SEVERITY"]
+
+    # Comma-separated list values
+    if "SCITEX_LINTER_DISABLE" in os.environ:
+        config["disable"] = [
+            x.strip()
+            for x in os.environ["SCITEX_LINTER_DISABLE"].split(",")
+            if x.strip()
+        ]
+
+    if "SCITEX_LINTER_EXCLUDE_DIRS" in os.environ:
+        config["exclude_dirs"] = [
+            x.strip()
+            for x in os.environ["SCITEX_LINTER_EXCLUDE_DIRS"].split(",")
+            if x.strip()
+        ]
+
+    if "SCITEX_LINTER_LIBRARY_DIRS" in os.environ:
+        config["library_dirs"] = [
+            x.strip()
+            for x in os.environ["SCITEX_LINTER_LIBRARY_DIRS"].split(",")
+            if x.strip()
+        ]
+
+    if "SCITEX_LINTER_LIBRARY_PATTERNS" in os.environ:
+        config["library_patterns"] = [
+            x.strip()
+            for x in os.environ["SCITEX_LINTER_LIBRARY_PATTERNS"].split(",")
+            if x.strip()
+        ]
+
+    if "SCITEX_LINTER_REQUIRED_INJECTED" in os.environ:
+        config["required_injected"] = [
+            x.strip()
+            for x in os.environ["SCITEX_LINTER_REQUIRED_INJECTED"].split(",")
+            if x.strip()
+        ]
+
+    return config
+
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+
+def matches_library_pattern(filename: str, config: LinterConfig) -> bool:
+    """
+    Check if filename matches any library pattern in config.
+
+    Args:
+        filename: Filename to check (e.g., "__init__.py", "test_foo.py")
+        config: Linter configuration
+
+    Returns:
+        True if filename matches any pattern
+    """
+    for pattern in config.library_patterns:
+        if fnmatch.fnmatch(filename, pattern):
+            return True
+    return False

scitex_linter/fixer.py

@@ -0,0 +1,333 @@
+"""Auto-fix SciTeX pattern issues in Python source code.
+
+Currently handles:
+  - S006: Insert missing INJECTED parameters into @stx.session functions.
+"""
+
+import ast
+import re
+from pathlib import Path
+
+# The 5 required INJECTED parameters (in canonical order) — default fallback
+REQUIRED_INJECTED = ["CONFIG", "plt", "COLORS", "rngg", "logger"]
+
+# Canonical default value for injected params
+_INJECTED_DEFAULT = "stx.session.INJECTED"
+
+
+# =========================================================================
+# AST helpers
+# =========================================================================
+
+
+def _has_session_decorator(node: ast.FunctionDef) -> bool:
+    """Return True if function has @stx.session or @session decorator."""
+    for deco in node.decorator_list:
+        if isinstance(deco, ast.Attribute):
+            if (
+                isinstance(deco.value, ast.Name)
+                and deco.value.id == "stx"
+                and deco.attr == "session"
+            ):
+                return True
+        if isinstance(deco, ast.Name) and deco.id == "session":
+            return True
+    return False
+
+
+def _declared_params(node: ast.FunctionDef) -> list:
+    """Return list of parameter names declared in the function signature."""
+    return [arg.arg for arg in node.args.args]
+
+
+def _missing_injected(declared: list, required: list = None) -> list:
+    """Return INJECTED param names not yet declared, preserving canonical order."""
+    required = required if required is not None else REQUIRED_INJECTED
+    declared_set = set(declared)
+    return [p for p in required if p not in declared_set]
+
+
+def _is_injected_value(default_node: ast.expr) -> bool:
+    """Check if a default value is stx.session.INJECTED or stx.INJECTED."""
+    # stx.session.INJECTED
+    if isinstance(default_node, ast.Attribute) and default_node.attr == "INJECTED":
+        inner = default_node.value
+        if isinstance(inner, ast.Attribute):
+            if (
+                isinstance(inner.value, ast.Name)
+                and inner.value.id == "stx"
+                and inner.attr == "session"
+            ):
+                return True
+        # stx.INJECTED
+        if isinstance(inner, ast.Name) and inner.id == "stx":
+            return True
+    return False
+
+
+def _is_canonical_injected(default_node: ast.expr) -> bool:
+    """Check if a default value is the canonical stx.session.INJECTED form."""
+    if isinstance(default_node, ast.Attribute) and default_node.attr == "INJECTED":
+        inner = default_node.value
+        if isinstance(inner, ast.Attribute):
+            if (
+                isinstance(inner.value, ast.Name)
+                and inner.value.id == "stx"
+                and inner.attr == "session"
+            ):
+                return True
+    return False
+
+
+def _has_non_canonical_injected(node: ast.FunctionDef, required: list = None) -> bool:
+    """Check if any INJECTED param uses stx.INJECTED instead of stx.session.INJECTED."""
+    args = node.args.args
+    defaults = node.args.defaults
+    n_positional = len(args) - len(defaults)
+    injected_set = set(required if required is not None else REQUIRED_INJECTED)
+
+    for i, arg in enumerate(args):
+        if arg.arg not in injected_set:
+            continue
+        default_idx = i - n_positional
+        if default_idx >= 0:
+            default = defaults[default_idx]
+            if _is_injected_value(default) and not _is_canonical_injected(default):
+                return True
+    return False
+
+
+# =========================================================================
+# Source-level fix for S006
+# =========================================================================
+
+
+def _find_def_line_range(lines: list, func_node: ast.FunctionDef) -> tuple:
+    """Find the line range (0-indexed) of the 'def ...:' signature.
+
+    Returns (start_line_idx, colon_line_idx) where:
+      - start_line_idx is the line containing 'def '
+      - colon_line_idx is the line containing the closing '):'
+    """
+    start = func_node.lineno - 1  # 0-indexed
+
+    # Walk forward from start to find the colon that opens the body
+    # The body starts at func_node.body[0].lineno
+    body_start = func_node.body[0].lineno - 1 if func_node.body else start + 1
+
+    # The colon line is somewhere between start and body_start
+    # Scan backwards from body_start to find the line with ':'
+    colon_line = start
+    for i in range(body_start - 1, start - 1, -1):
+        stripped = lines[i].rstrip()
+        if stripped.endswith(":"):
+            colon_line = i
+            break
+
+    return start, colon_line
+
+
+def _fix_s006_in_source(source: str, filepath: str, config=None) -> str:
+    """Fix S006 violations: add missing INJECTED params to @stx.session functions."""
+    try:
+        tree = ast.parse(source, filename=filepath)
+    except SyntaxError:
+        return source
+
+    required = config.required_injected if config else REQUIRED_INJECTED
+
+    lines = source.splitlines(keepends=True)
+    # Ensure the last line has a newline
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+
+    # Collect all session functions that need fixing (process in reverse order
+    # so line indices remain valid after edits)
+    fixes = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if _has_session_decorator(node):
+                declared = _declared_params(node)
+                missing = _missing_injected(declared, required)
+                needs_normalize = _has_non_canonical_injected(node, required)
+                if missing or needs_normalize:
+                    fixes.append((node, missing))
+
+    # Sort by line number descending so we edit from bottom to top
+    fixes.sort(key=lambda x: x[0].lineno, reverse=True)
+
+    for func_node, missing in fixes:
+        lines = _apply_s006_fix(lines, func_node, missing, required)
+
+    return "".join(lines)
+
+
+def _get_def_indent(line: str) -> str:
+    """Extract the leading whitespace from a 'def' line."""
+    match = re.match(r"^(\s*)", line)
+    return match.group(1) if match else ""
+
+
+def _apply_s006_fix(
+    lines: list,
+    func_node: ast.FunctionDef,
+    missing: list,
+    required_injected: list = None,
+) -> list:
+    """Apply S006 fix to a single function in the source lines.
+
+    Strategy:
+    1. Find the def line range (from 'def' to the closing ':')
+    2. Determine if it's single-line or multi-line
+    3. Extract user params and existing injected params from source text
+    4. Rebuild the signature with all params
+    """
+    if required_injected is None:
+        required_injected = REQUIRED_INJECTED
+    start_idx, colon_idx = _find_def_line_range(lines, func_node)
+    def_indent = _get_def_indent(lines[start_idx])
+    param_indent = def_indent + "    "
+
+    # Determine if async
+    is_async = isinstance(func_node, ast.AsyncFunctionDef)
+    keyword = "async def" if is_async else "def"
+
+    # Extract the function name
+    func_name = func_node.name
+
+    # Get all existing params with their source text
+    # Join the def signature lines
+    sig_text = "".join(lines[start_idx : colon_idx + 1])
+
+    # Extract content between parentheses
+    paren_open = sig_text.index("(")
+    # Find the matching close paren (searching backward from the colon)
+    paren_close = sig_text.rindex(")")
+    params_text = sig_text[paren_open + 1 : paren_close].strip()
+
+    # Parse individual parameter strings from the source text
+    existing_param_strings = _split_params(params_text)
+
+    # Classify params: user params vs injected params
+    injected_names = set(required_injected)
+    user_param_strings = []
+    existing_injected_strings = []
+
+    for ps in existing_param_strings:
+        pname = ps.strip().split("=")[0].split(":")[0].strip()
+        if pname in injected_names:
+            existing_injected_strings.append(ps)
+        elif pname:
+            user_param_strings.append(ps)
+
+    # Build new parameter lines
+    new_param_lines = []
+
+    # User params first (preserve original text)
+    for ps in user_param_strings:
+        new_param_lines.append(f"{param_indent}{ps.strip()},\n")
+
+    # All INJECTED params in canonical order (existing + missing)
+    existing_injected_names = set()
+    for ps in existing_injected_strings:
+        pname = ps.strip().split("=")[0].split(":")[0].strip()
+        existing_injected_names.add(pname)
+
+    for p in required_injected:
+        if p in existing_injected_names or p in missing:
+            new_param_lines.append(f"{param_indent}{p}={_INJECTED_DEFAULT},\n")
+
+    # Build the new def statement
+    new_lines = []
+    new_lines.append(f"{def_indent}{keyword} {func_name}(\n")
+    new_lines.extend(new_param_lines)
+    new_lines.append(f"{def_indent}):\n")
+
+    # Replace old def lines with new ones
+    lines[start_idx : colon_idx + 1] = new_lines
+
+    return lines
+
+
+def _split_params(params_text: str) -> list:
+    """Split a parameter string respecting nested parentheses and brackets.
+
+    Handles cases like:
+      'x=1, y="hello, world"'
+      'x=dict(a=1, b=2), y=3'
+    """
+    if not params_text.strip():
+        return []
+
+    params = []
+    depth = 0
+    current = []
+    in_string = None
+
+    for ch in params_text:
+        if in_string:
+            current.append(ch)
+            if ch == in_string:
+                in_string = None
+            continue
+
+        if ch in ('"', "'"):
+            in_string = ch
+            current.append(ch)
+            continue
+
+        if ch in ("(", "[", "{"):
+            depth += 1
+            current.append(ch)
+        elif ch in (")", "]", "}"):
+            depth -= 1
+            current.append(ch)
+        elif ch == "," and depth == 0:
+            param = "".join(current).strip()
+            if param:
+                params.append(param)
+            current = []
+        else:
+            current.append(ch)
+
+    # Last param
+    param = "".join(current).strip()
+    if param:
+        params.append(param)
+
+    return params
+
+
+# =========================================================================
+# Public API
+# =========================================================================
+
+
+def fix_source(source: str, filepath: str = "<stdin>", config=None) -> str:
+    """Auto-fix SciTeX issues in source code. Returns fixed source."""
+    return _fix_s006_in_source(source, filepath, config=config)
+
+
+def fix_file(filepath: str, write: bool = True, config=None) -> tuple:
+    """Fix a file in place. Returns (fixed_source, changed).
+
+    Args:
+        filepath: Path to the Python file.
+        write: If True, write the fixed source back to the file.
+        config: Optional LinterConfig instance.
+
+    Returns:
+        Tuple of (fixed_source, changed) where changed is a bool.
+    """
+    path = Path(filepath)
+    if not path.exists() or not path.is_file():
+        return ("", False)
+
+    original = path.read_text(encoding="utf-8")
+    fixed = fix_source(original, filepath=str(path), config=config)
+    changed = fixed != original
+
+    if write and changed:
+        path.write_text(fixed, encoding="utf-8")
+
+    return (fixed, changed)

scitex_linter/formatter.py

@@ -1,6 +1,5 @@
 """Output formatting for terminal and JSON."""
 
-
 from .checker import Issue
 
 # ANSI colors

scitex_linter/rules.py

@@ -67,6 +67,25 @@ S005 = Rule(
     suggestion="Add `import scitex as stx` to use SciTeX modules.",
 )
 
+S006 = Rule(
+    id="STX-S006",
+    severity="warning",
+    category="structure",
+    message="@stx.session function missing explicit INJECTED parameters",
+    suggestion=(
+        "Declare auto-injected values explicitly in the function signature:\n"
+        "  @stx.session\n"
+        "  def main(\n"
+        "      CONFIG=stx.session.INJECTED,\n"
+        "      plt=stx.session.INJECTED,\n"
+        "      COLORS=stx.session.INJECTED,\n"
+        "      rngg=stx.session.INJECTED,\n"
+        "      logger=stx.session.INJECTED,\n"
+        "  ):\n"
+        "      return 0"
+    ),
+)
+
 
 # =============================================================================
 # Category I: Imports
@@ -348,6 +367,7 @@ ALL_RULES = {
         S003,
         S004,
         S005,
+        S006,
         I001,
         I002,
         I003,

{scitex_linter-0.1.0.dist-info → scitex_linter-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-linter
-Version: 0.1.0
+Version: 0.1.2
 Summary: AST-based linter enforcing SciTeX reproducible research patterns
 Author: ywatanabe
 License: AGPL-3.0
@@ -70,20 +70,21 @@ pip install scitex-linter
 
 ```bash
 # Lint a file
-scitex-linter lint script.py
+scitex-linter check script.py
 
 # Lint then execute
 scitex-linter python experiment.py --strict
 
 # List all 35 rules
-scitex-linter list-rules
+scitex-linter rule
 ```
 
-## Four Interfaces
+## Five Interfaces
 
 | Interface | For | Description |
 |-----------|-----|-------------|
-| 🖥️ **CLI** | Terminal users | `scitex-linter lint`, `scitex-linter python` |
+| 🖥️ **CLI** | Terminal users | `scitex-linter check`, `scitex-linter python` |
+| ✨ **Format** | Auto-fix | `scitex-linter format` — auto-fix SciTeX issues |
 | 🐍 **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 |
@@ -97,12 +98,18 @@ scitex-linter list-rules
 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
+# Check - Check for SciTeX pattern violations
+scitex-linter check script.py                      # Check a file
+scitex-linter check ./src/                         # Check a directory
+scitex-linter check script.py --severity error     # Only errors
+scitex-linter check script.py --category path      # Only path rules
+scitex-linter check script.py --json               # JSON output for CI
+
+# Format - Auto-fix SciTeX pattern issues
+scitex-linter format script.py                     # Fix in place
+scitex-linter format script.py --check             # Dry run (exit 1 if changes needed)
+scitex-linter format script.py --diff              # Show diff of changes
+scitex-linter format ./src/                        # Format a directory
 
 # Python - Lint then execute
 scitex-linter python experiment.py                # Lint and run
@@ -110,9 +117,9 @@ 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
+scitex-linter rule                          # List all 35 rules
+scitex-linter rule --category stats         # Filter by category
+scitex-linter rule --json                   # JSON output
 
 # MCP - AI agent server
 scitex-linter mcp start                           # Start MCP server (stdio)
@@ -165,7 +172,7 @@ Integrates with existing flake8 workflows, pre-commit hooks, and CI pipelines.
 
 | Tool | Description |
 |------|-------------|
-| `linter_lint` | Lint a Python file for SciTeX compliance |
+| `linter_check` | Check a Python file for SciTeX compliance |
 | `linter_list_rules` | List all available rules |
 | `linter_check_source` | Lint source code string |
 
@@ -238,6 +245,37 @@ SciTeX Linter works as a **post-tool-use hook** for Claude Code, automatically l
 
 This ensures AI-generated code follows SciTeX patterns from the start.
 
+## Configuration
+
+<details>
+<summary><strong>Configure via pyproject.toml or environment variables</strong></summary>
+
+<br>
+
+```toml
+[tool.scitex-linter]
+severity = "info"                    # Minimum severity: error, warning, info
+disable = ["STX-P004", "STX-I003"]   # Disable specific rules
+exclude-dirs = ["venv", ".venv"]     # Directories to skip
+library-dirs = ["src"]               # Exempt from script-only rules
+
+[tool.scitex-linter.per-rule-severity]
+STX-S003 = "warning"                 # Downgrade argparse rule
+
+[tool.scitex-linter.session]
+required-injected = ["CONFIG", "plt", "COLORS", "rngg", "logger"]
+```
+
+Environment variables (highest priority):
+```bash
+SCITEX_LINTER_SEVERITY=error
+SCITEX_LINTER_DISABLE=STX-P004,STX-I003
+```
+
+Priority: CLI flags > env vars > pyproject.toml > defaults
+
+</details>
+
 ## What a Clean Script Looks Like
 
 ```python

scitex_linter-0.1.2.dist-info/RECORD

@@ -0,0 +1,20 @@
+scitex_linter/__init__.py,sha256=le0V8F4gkjD3t20kzA4eF8z-HSkw1DL9Ry0X5pZc3XM,104
+scitex_linter/_cmd_format.py,sha256=pQVVXTzJeBs6ailWfAc9xOl4Pt9IHKOThDFHDKLAWKM,2094
+scitex_linter/_server.py,sha256=hwB1ghS2L9bHtFoPEK2M564Lm-bEAdsGR83DTDMES8o,546
+scitex_linter/checker.py,sha256=jwKaodez8a1bv4qWNSwPm9SBVZ4DUeMwIEKFMprG3ko,18450
+scitex_linter/cli.py,sha256=su5j_lS-RJH4Om0J22GK6UL2lLGuZqdP3MlHYoXOOzI,14143
+scitex_linter/config.py,sha256=8mSdTHhmCGBaM_Xb7GQD8CGuY5divloGADmBLdFwu1s,6117
+scitex_linter/fixer.py,sha256=OVX3TYHf_7FW6bX7zzEQa1_mnF-ykfKrfkYyMTi2pDg,11107
+scitex_linter/flake8_plugin.py,sha256=2FfGpCy8lWNgdkk09jRTYOILMkGIP_EJS6x0l9q-Wvc,1024
+scitex_linter/formatter.py,sha256=NvMIsC23m6zWO6HbVh5khum1dj7eb2nyhi0QyloSlhM,3074
+scitex_linter/rules.py,sha256=ZR8vbElYexQtP5anewuMijrfWbwFhBC35T-WH_qBdHM,11971
+scitex_linter/runner.py,sha256=JcSII85keuhOXxtCM8vS_HSH0FDUr6t48nqoSz8IGRU,2211
+scitex_linter/_mcp/__init__.py,sha256=mrI1dFFxyTRq2F_yxoLYRnyYro2f8CrRNNk2NYLBpWM,41
+scitex_linter/_mcp/tools/__init__.py,sha256=ZggLuukCaOZ2XhfkNQvYMuszY0BX0hDy9I50hUDJ_xo,208
+scitex_linter/_mcp/tools/lint.py,sha256=97o9ypwcOQ_6xPJXScxP7pZ1iRDtLlrWS9XPKe0wbYE,2308
+scitex_linter-0.1.2.dist-info/licenses/LICENSE,sha256=TfPDBt3ar0uv_f9cqCDMZ5rIzW3CY8anRRd4PkL6ejs,34522
+scitex_linter-0.1.2.dist-info/METADATA,sha256=3Pn744Yg-NmzZstHWkm7quOvv5-Xn-4NREpZzuttcn0,10156
+scitex_linter-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+scitex_linter-0.1.2.dist-info/entry_points.txt,sha256=a0bIGVJmB96OPDbcLMn_mO_ZCZpv8SKlHMIhpxjLt5M,131
+scitex_linter-0.1.2.dist-info/top_level.txt,sha256=FVu-yranpm0Bt0QZA7ohavSovYgCAhhh5YqiPB2HTJQ,14
+scitex_linter-0.1.2.dist-info/RECORD,,

scitex_linter-0.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-scitex_linter/__init__.py,sha256=3Jt4Nr1NFo5kd8ctgaTWrQXCfiECWZu32HuNl_SXLIM,104
-scitex_linter/_server.py,sha256=yzhsPDfNZVjDxc0KkrNYqZ9625ZUdPL0820Sk0zfb3Q,544
-scitex_linter/checker.py,sha256=_qDFxPvwUMOhQSAUQv-jT0eApV8uXUSjbhFMGPFVas4,16789
-scitex_linter/cli.py,sha256=1Aau478i6BIxr5q4A8Xbuda8PYZQVw-78U-KxBYhIPk,13888
-scitex_linter/flake8_plugin.py,sha256=2FfGpCy8lWNgdkk09jRTYOILMkGIP_EJS6x0l9q-Wvc,1024
-scitex_linter/formatter.py,sha256=WgFHJCl0rPxdm6e2t0htjFSI5uyPyGVxX4VFtPs6XEs,3075
-scitex_linter/rules.py,sha256=kLxUhb3H-zjeR3M-FRBT5JONhyBoPORCPjEU8qYhT2w,11372
-scitex_linter/runner.py,sha256=JcSII85keuhOXxtCM8vS_HSH0FDUr6t48nqoSz8IGRU,2211
-scitex_linter/_mcp/__init__.py,sha256=mrI1dFFxyTRq2F_yxoLYRnyYro2f8CrRNNk2NYLBpWM,41
-scitex_linter/_mcp/tools/__init__.py,sha256=ZggLuukCaOZ2XhfkNQvYMuszY0BX0hDy9I50hUDJ_xo,208
-scitex_linter/_mcp/tools/lint.py,sha256=cDSzzoCP0XrzVJ72PaeGpE4opz7gmV9jrwwNV2jb8XM,2118
-scitex_linter-0.1.0.dist-info/licenses/LICENSE,sha256=TfPDBt3ar0uv_f9cqCDMZ5rIzW3CY8anRRd4PkL6ejs,34522
-scitex_linter-0.1.0.dist-info/METADATA,sha256=ANqfwltlnFTmqcMHljHoqe7dLwUnWoxjh8415dYjwtY,8921
-scitex_linter-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-scitex_linter-0.1.0.dist-info/entry_points.txt,sha256=a0bIGVJmB96OPDbcLMn_mO_ZCZpv8SKlHMIhpxjLt5M,131
-scitex_linter-0.1.0.dist-info/top_level.txt,sha256=FVu-yranpm0Bt0QZA7ohavSovYgCAhhh5YqiPB2HTJQ,14
-scitex_linter-0.1.0.dist-info/RECORD,,