timeleak 0.1.0__py3-none-any.whl

timeleak/__init__.py

@@ -0,0 +1,20 @@
+"""timeleak - a static linter for data leakage in time-series ML code."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .analyzer import analyze_file, analyze_source, iter_python_files
+from .rules import ALL_RULES, RULES_BY_CODE, Finding, Rule, Severity
+
+__all__ = [
+    "__version__",
+    "ALL_RULES",
+    "RULES_BY_CODE",
+    "Finding",
+    "Rule",
+    "Severity",
+    "analyze_file",
+    "analyze_source",
+    "iter_python_files",
+]

timeleak/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

timeleak/analyzer.py

@@ -0,0 +1,247 @@
+"""AST analysis that turns Python source into leakage findings.
+
+The analyzer is deliberately syntactic. It never imports or executes the file
+under test, so it is safe to run on untrusted code and inside pre-commit.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import re
+from typing import Iterator
+
+from .rules import (
+    CV_CONSUMERS,
+    FULL_SAMPLE_REDUCERS,
+    TL001,
+    TL002,
+    TL003,
+    TL004,
+    TL005,
+    TL006,
+    TL007,
+    NON_TIME_AWARE_CV,
+    STATEFUL_TRANSFORMERS,
+    Finding,
+    Rule,
+)
+
+_NOQA = re.compile(r"#\s*noqa(?::\s*(?P<codes>[A-Z0-9,\s]+))?", re.IGNORECASE)
+
+# Reductions chained off one of these are windowed, not whole-sample, so they
+# are legitimate: df["x"].rolling(20).mean() looks backwards by construction.
+_WINDOWED = frozenset({"rolling", "expanding", "ewm", "groupby", "resample"})
+
+_FIT_METHODS = frozenset({"fit", "fit_transform"})
+
+
+def _root_name(node: ast.AST) -> str | None:
+    """Return the identifier at the base of an attribute/subscript/call chain."""
+    while True:
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            node = node.value
+        elif isinstance(node, ast.Subscript):
+            node = node.value
+        elif isinstance(node, ast.Call):
+            node = node.func
+        else:
+            return None
+
+
+def _called_name(call: ast.Call) -> str | None:
+    """Return the final component of the callee, e.g. `fit` or `StandardScaler`."""
+    if isinstance(call.func, ast.Attribute):
+        return call.func.attr
+    if isinstance(call.func, ast.Name):
+        return call.func.id
+    return None
+
+
+def _keyword(call: ast.Call, name: str) -> ast.expr | None:
+    for kw in call.keywords:
+        if kw.arg == name:
+            return kw.value
+    return None
+
+
+def _is_true(node: ast.expr | None) -> bool:
+    return isinstance(node, ast.Constant) and node.value is True
+
+
+def _negative_int(node: ast.expr | None) -> bool:
+    return (
+        isinstance(node, ast.UnaryOp)
+        and isinstance(node.op, ast.USub)
+        and isinstance(node.operand, ast.Constant)
+        and isinstance(node.operand.value, int)
+        and node.operand.value != 0
+    )
+
+
+def _is_full_sample_reduction(call: ast.Call) -> bool:
+    """True for df.mean() but not for df.rolling(20).mean()."""
+    if not isinstance(call.func, ast.Attribute):
+        return False
+    if call.func.attr not in FULL_SAMPLE_REDUCERS:
+        return False
+    receiver = call.func.value
+    if isinstance(receiver, ast.Call) and _called_name(receiver) in _WINDOWED:
+        return False
+    return True
+
+
+class _Analyzer(ast.NodeVisitor):
+    def __init__(self, path: str, lines: list[str]) -> None:
+        self.path = path
+        self.lines = lines
+        self.findings: list[Finding] = []
+        self.transformer_vars: dict[str, str] = {}
+        self.fit_events: list[tuple[ast.Call, str]] = []
+        self.split_lines: list[int] = []
+
+    # -- reporting ---------------------------------------------------------
+    def _suppressed(self, line: int, code: str) -> bool:
+        if not 1 <= line <= len(self.lines):
+            return False
+        match = _NOQA.search(self.lines[line - 1])
+        if match is None:
+            return False
+        codes = match.group("codes")
+        if codes is None:
+            return True
+        return code in {c.strip().upper() for c in codes.split(",") if c.strip()}
+
+    def _report(self, rule: Rule, node: ast.AST, context: str = "") -> None:
+        line = getattr(node, "lineno", 0)
+        if self._suppressed(line, rule.code):
+            return
+        self.findings.append(
+            Finding(
+                rule=rule,
+                path=self.path,
+                line=line,
+                col=getattr(node, "col_offset", 0) + 1,
+                context=context,
+            )
+        )
+
+    # -- passes ------------------------------------------------------------
+    def collect_assignments(self, tree: ast.AST) -> None:
+        """Pre-pass: remember which locals hold a stateful transformer."""
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Assign) or not isinstance(node.value, ast.Call):
+                continue
+            ctor = _called_name(node.value)
+            if ctor not in STATEFUL_TRANSFORMERS:
+                continue
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    self.transformer_vars[target.id] = ctor
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        for target in node.targets:
+            if not isinstance(target, ast.Subscript):
+                continue
+            base = _root_name(target)
+            if base is None:
+                continue
+            for inner in ast.walk(node.value):
+                if (
+                    isinstance(inner, ast.Call)
+                    and _is_full_sample_reduction(inner)
+                    and _root_name(inner) == base
+                ):
+                    self._report(TL007, inner, base + "." + inner.func.attr + "()")
+                    break
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        name = _called_name(node)
+
+        if name == "train_test_split":
+            self.split_lines.append(node.lineno)
+            shuffle = _keyword(node, "shuffle")
+            if shuffle is None or _is_true(shuffle):
+                self._report(TL002, node)
+
+        elif name in _FIT_METHODS and isinstance(node.func, ast.Attribute):
+            receiver = node.func.value
+            label: str | None = None
+            if isinstance(receiver, ast.Name) and receiver.id in self.transformer_vars:
+                label = self.transformer_vars[receiver.id]
+            elif isinstance(receiver, ast.Call) and _called_name(receiver) in STATEFUL_TRANSFORMERS:
+                label = _called_name(receiver)
+            if label is not None:
+                self.fit_events.append((node, label))
+
+        elif name == "shift":
+            periods = node.args[0] if node.args else _keyword(node, "periods")
+            if _negative_int(periods):
+                self._report(TL003, node)
+
+        elif name == "rolling":
+            if _is_true(_keyword(node, "center")):
+                self._report(TL004, node)
+
+        elif name in {"bfill", "backfill"}:
+            self._report(TL005, node, "." + name + "()")
+
+        elif name == "fillna":
+            method = _keyword(node, "method")
+            if isinstance(method, ast.Constant) and method.value in {"bfill", "backfill"}:
+                self._report(TL005, node, "method=" + repr(method.value))
+
+        elif name in NON_TIME_AWARE_CV:
+            self._report(TL006, node, name)
+
+        elif name in CV_CONSUMERS:
+            cv = _keyword(node, "cv")
+            if cv is None or (isinstance(cv, ast.Constant) and isinstance(cv.value, int)):
+                self._report(TL006, node, name + " with default KFold")
+
+        self.generic_visit(node)
+
+    def finalize(self) -> None:
+        """TL001 needs ordering, so it runs once the whole module is walked."""
+        if not self.split_lines:
+            return
+        first_split = min(self.split_lines)
+        for call, label in self.fit_events:
+            if call.lineno < first_split:
+                self._report(TL001, call, label + "." + call.func.attr + "()")
+
+
+def analyze_source(source: str, path: str = "<string>") -> list[Finding]:
+    """Analyze a source string and return findings sorted by position."""
+    try:
+        tree = ast.parse(source, filename=path)
+    except SyntaxError as exc:
+        raise ValueError(path + ": could not parse (" + str(exc.msg) + ")") from exc
+
+    analyzer = _Analyzer(path, source.splitlines())
+    analyzer.collect_assignments(tree)
+    analyzer.visit(tree)
+    analyzer.finalize()
+    return sorted(analyzer.findings, key=lambda f: (f.line, f.col, f.code))
+
+
+def analyze_file(path: str) -> list[Finding]:
+    with open(path, "r", encoding="utf-8") as handle:
+        return analyze_source(handle.read(), path)
+
+
+def iter_python_files(paths: list[str], exclude: frozenset[str] = frozenset()) -> Iterator[str]:
+    """Yield .py files under the given paths, skipping excluded directory names."""
+    for target in paths:
+        if os.path.isfile(target):
+            if target.endswith(".py"):
+                yield target
+            continue
+        for root, dirs, files in os.walk(target):
+            dirs[:] = [d for d in dirs if d not in exclude and not d.startswith(".")]
+            for filename in sorted(files):
+                if filename.endswith(".py"):
+                    yield os.path.join(root, filename)

timeleak/cli.py

@@ -0,0 +1,142 @@
+"""Command line interface for timeleak."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Sequence
+
+from . import __version__
+from .analyzer import analyze_file, iter_python_files
+from .rules import ALL_RULES, RULES_BY_CODE, Finding, Severity
+
+DEFAULT_EXCLUDES = frozenset(
+    {"__pycache__", "node_modules", "venv", "env", "build", "dist", "site-packages"}
+)
+
+_COLORS = {
+    Severity.ERROR: "\033[31m",
+    Severity.WARNING: "\033[33m",
+}
+_RESET = "\033[0m"
+_DIM = "\033[2m"
+
+
+def _supports_color(stream) -> bool:
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def _render_text(findings: list[Finding], color: bool, stream) -> None:
+    for finding in findings:
+        rule = finding.rule
+        location = f"{finding.path}:{finding.line}:{finding.col}"
+        code = rule.code
+        if color:
+            code = f"{_COLORS[rule.severity]}{code}{_RESET}"
+        context = f" [{finding.context}]" if finding.context else ""
+        print(f"{location}: {code} {rule.message}{context}", file=stream)
+        fix = f"    fix: {rule.fix}"
+        print(f"{_DIM}{fix}{_RESET}" if color else fix, file=stream)
+
+
+def _render_json(findings: list[Finding], stream) -> None:
+    payload = [
+        {
+            "path": f.path,
+            "line": f.line,
+            "column": f.col,
+            "code": f.rule.code,
+            "name": f.rule.name,
+            "severity": str(f.rule.severity),
+            "message": f.rule.message,
+            "fix": f.rule.fix,
+            "context": f.context,
+        }
+        for f in findings
+    ]
+    json.dump(payload, stream, indent=2)
+    stream.write("\n")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="timeleak",
+        description="Find data-leakage patterns in time-series machine learning code.",
+    )
+    parser.add_argument("paths", nargs="*", default=["."], help="files or directories (default: .)")
+    parser.add_argument("--format", choices=("text", "json"), default="text")
+    parser.add_argument("--select", metavar="CODES", help="only report these codes, comma separated")
+    parser.add_argument("--ignore", metavar="CODES", help="suppress these codes, comma separated")
+    parser.add_argument(
+        "--exclude",
+        metavar="NAMES",
+        help="extra directory names to skip, comma separated",
+    )
+    parser.add_argument(
+        "--exit-zero",
+        action="store_true",
+        help="always exit 0, even when findings are reported",
+    )
+    parser.add_argument("--list-rules", action="store_true", help="print the rule catalogue and exit")
+    parser.add_argument("--version", action="version", version=f"timeleak {__version__}")
+    return parser
+
+
+def _parse_codes(raw: str | None) -> set[str] | None:
+    if not raw:
+        return None
+    codes = {c.strip().upper() for c in raw.split(",") if c.strip()}
+    unknown = codes - set(RULES_BY_CODE)
+    if unknown:
+        raise SystemExit(f"timeleak: unknown rule code(s): {', '.join(sorted(unknown))}")
+    return codes
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    if args.list_rules:
+        for rule in ALL_RULES:
+            print(f"{rule.code}  {rule.severity.value:<7}  {rule.name}")
+            print(f"          {rule.message}")
+        return 0
+
+    select = _parse_codes(args.select)
+    ignore = _parse_codes(args.ignore) or set()
+    excludes = DEFAULT_EXCLUDES | {
+        name.strip() for name in (args.exclude or "").split(",") if name.strip()
+    }
+
+    findings: list[Finding] = []
+    scanned = 0
+    for path in iter_python_files(list(args.paths), excludes):
+        scanned += 1
+        try:
+            findings.extend(analyze_file(path))
+        except (ValueError, OSError) as exc:
+            print(f"timeleak: skipped {exc}", file=sys.stderr)
+
+    if select is not None:
+        findings = [f for f in findings if f.code in select]
+    findings = [f for f in findings if f.code not in ignore]
+
+    if args.format == "json":
+        _render_json(findings, sys.stdout)
+    else:
+        _render_text(findings, _supports_color(sys.stdout), sys.stdout)
+        errors = sum(1 for f in findings if f.rule.severity is Severity.ERROR)
+        warnings = len(findings) - errors
+        summary = (
+            f"\n{len(findings)} finding(s) in {scanned} file(s) "
+            f"({errors} error, {warnings} warning)"
+        )
+        print(summary if findings else f"clean: no leakage patterns in {scanned} file(s)")
+
+    if args.exit_zero:
+        return 0
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

timeleak/rules.py

@@ -0,0 +1,154 @@
+"""Rule catalogue and the Finding record produced by the analyzer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Severity(str, Enum):
+    """How confident the rule is that it has found a real leak."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+@dataclass(frozen=True)
+class Rule:
+    code: str
+    name: str
+    severity: Severity
+    message: str
+    fix: str
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One rule violation, anchored to a source location."""
+
+    rule: Rule
+    path: str
+    line: int
+    col: int
+    context: str = ""
+
+    @property
+    def code(self) -> str:
+        return self.rule.code
+
+    def format_text(self) -> str:
+        head = f"{self.path}:{self.line}:{self.col}: {self.rule.code} {self.rule.message}"
+        if self.context:
+            head += f" [{self.context}]"
+        return f"{head}\n    fix: {self.rule.fix}"
+
+
+TL001 = Rule(
+    code="TL001",
+    name="fit-before-split",
+    severity=Severity.ERROR,
+    message="transformer fitted before train/test split leaks test statistics into training",
+    fix="move the transform inside a sklearn Pipeline so it is refit on each training fold",
+)
+
+TL002 = Rule(
+    code="TL002",
+    name="shuffled-split",
+    severity=Severity.WARNING,
+    message="train_test_split shuffles by default, which destroys time order",
+    fix="pass shuffle=False for time-ordered data, or split on an explicit date boundary",
+)
+
+TL003 = Rule(
+    code="TL003",
+    name="negative-shift",
+    severity=Severity.ERROR,
+    message="negative .shift() pulls future values into the current row (look-ahead)",
+    fix="if this builds a forward-looking label that is fine, but it must never become a feature",
+)
+
+TL004 = Rule(
+    code="TL004",
+    name="centered-window",
+    severity=Severity.ERROR,
+    message="rolling(center=True) centres the window, so each row sees future rows",
+    fix="use the default center=False so the window only looks backwards",
+)
+
+TL005 = Rule(
+    code="TL005",
+    name="backward-fill",
+    severity=Severity.ERROR,
+    message="backward fill propagates future values into earlier rows",
+    fix="use forward fill (ffill), or drop the leading NaNs instead",
+)
+
+TL006 = Rule(
+    code="TL006",
+    name="non-time-aware-cv",
+    severity=Severity.WARNING,
+    message="K-fold style cross-validation on time series trains on data after the test block",
+    fix="use TimeSeriesSplit, or a purged split with an embargo if labels span several bars",
+)
+
+TL007 = Rule(
+    code="TL007",
+    name="full-sample-statistic",
+    severity=Severity.ERROR,
+    message="column rescaled with a statistic computed over the whole frame, including the test period",
+    fix="compute the statistic on the training slice only, or use a Pipeline",
+)
+
+ALL_RULES: tuple[Rule, ...] = (TL001, TL002, TL003, TL004, TL005, TL006, TL007)
+
+RULES_BY_CODE: dict[str, Rule] = {r.code: r for r in ALL_RULES}
+
+
+# Transformers whose fitted state carries dataset-wide statistics. Fitting any of
+# these on the full frame before splitting is the classic silent leak.
+STATEFUL_TRANSFORMERS: frozenset[str] = frozenset(
+    {
+        "StandardScaler",
+        "MinMaxScaler",
+        "MaxAbsScaler",
+        "RobustScaler",
+        "Normalizer",
+        "QuantileTransformer",
+        "PowerTransformer",
+        "SimpleImputer",
+        "KNNImputer",
+        "IterativeImputer",
+        "LabelEncoder",
+        "OrdinalEncoder",
+        "OneHotEncoder",
+        "TargetEncoder",
+        "PCA",
+        "TruncatedSVD",
+        "FactorAnalysis",
+        "SelectKBest",
+        "SelectPercentile",
+        "VarianceThreshold",
+        "SMOTE",
+        "ADASYN",
+        "RandomOverSampler",
+        "RandomUnderSampler",
+    }
+)
+
+# Cross-validator constructors that ignore time ordering entirely.
+NON_TIME_AWARE_CV: frozenset[str] = frozenset(
+    {"KFold", "StratifiedKFold", "ShuffleSplit", "StratifiedShuffleSplit", "RepeatedKFold"}
+)
+
+# Helpers that silently default to KFold when `cv` is an int or omitted.
+CV_CONSUMERS: frozenset[str] = frozenset(
+    {"cross_val_score", "cross_validate", "cross_val_predict", "GridSearchCV", "RandomizedSearchCV"}
+)
+
+# Whole-frame reductions that must not be computed before the split.
+FULL_SAMPLE_REDUCERS: frozenset[str] = frozenset(
+    {"mean", "std", "var", "min", "max", "median", "quantile", "sum"}
+)

timeleak-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: timeleak
+Version: 0.1.0
+Summary: Static linter that finds data-leakage patterns in time-series machine learning code.
+Author-email: Martex <mvnikolov2009@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/MartexHACK/timeleak
+Project-URL: Issues, https://github.com/MartexHACK/timeleak/issues
+Keywords: data-leakage,linter,static-analysis,time-series,machine-learning,backtesting,quantitative-finance,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# timeleak
+
+**A static linter that finds data leakage in time-series machine learning code.**
+
+[![CI](https://github.com/MartexHACK/timeleak/actions/workflows/ci.yml/badge.svg)](https://github.com/MartexHACK/timeleak/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![No dependencies](https://img.shields.io/badge/dependencies-none-3FB950)](pyproject.toml)
+
+Your backtest shows a Sharpe of 2.4. Live, it is 0.1.
+
+Usually nothing exotic went wrong — a scaler was fitted before the train/test split, a
+window was centred, or a gap was filled backwards. Each of these quietly hands the model
+information it could not have had at prediction time. None of them raise an error. None of
+them fail a unit test. The model just looks brilliant until real money is on it.
+
+`timeleak` reads your source with Python's `ast` module and points at the specific line.
+
+```console
+$ timeleak examples/leaky_pipeline.py
+examples/leaky_pipeline.py:15:6: TL005 backward fill propagates future values into earlier rows [method='bfill']
+    fix: use forward fill (ffill), or drop the leading NaNs instead
+examples/leaky_pipeline.py:18:15: TL004 rolling(center=True) centres the window, so each row sees future rows
+    fix: use the default center=False so the window only looks backwards
+examples/leaky_pipeline.py:22:54: TL007 column rescaled with a statistic computed over the whole frame, including the test period [df.std()]
+    fix: compute the statistic on the training slice only, or use a Pipeline
+examples/leaky_pipeline.py:25:17: TL003 negative .shift() pulls future values into the current row (look-ahead)
+    fix: if this builds a forward-looking label that is fine, but it must never become a feature
+examples/leaky_pipeline.py:33:5: TL001 transformer fitted before train/test split leaks test statistics into training [StandardScaler.fit_transform()]
+    fix: move the transform inside a sklearn Pipeline so it is refit on each training fold
+examples/leaky_pipeline.py:36:36: TL002 train_test_split shuffles by default, which destroys time order
+    fix: pass shuffle=False for time-ordered data, or split on an explicit date boundary
+examples/leaky_pipeline.py:42:10: TL006 K-fold style cross-validation on time series trains on data after the test block [cross_val_score with default KFold]
+    fix: use TimeSeriesSplit, or a purged split with an embargo if labels span several bars
+
+7 finding(s) in 1 file(s) (5 error, 2 warning)
+```
+
+## Install
+
+Not on PyPI yet. Install straight from the repository:
+
+```bash
+pip install git+https://github.com/MartexHACK/timeleak
+```
+
+Once it is published, `pip install timeleak` will work too.
+
+Zero runtime dependencies — it is `ast` and the standard library. It never imports or
+executes the code it analyses, so it is safe to point at a repository you do not trust.
+
+## Usage
+
+```bash
+timeleak                          # scan the current directory
+timeleak src/ notebooks/          # scan specific paths
+timeleak --select TL001,TL003 .   # only these rules
+timeleak --ignore TL002 .         # everything except this one
+timeleak --format json .          # machine-readable, for CI
+timeleak --list-rules             # the catalogue
+```
+
+Exit code is `1` when anything is found and `0` when clean, so it drops straight into CI.
+Use `--exit-zero` if you want the report without failing the build.
+
+## Rules
+
+| Code | Severity | What it catches |
+|---|---|---|
+| `TL001` | error | A stateful transformer (`StandardScaler`, `SimpleImputer`, `PCA`, `SMOTE`, …) fitted **before** `train_test_split`. The fitted state carries the test period's statistics. |
+| `TL002` | warning | `train_test_split` without `shuffle=False`. It shuffles by default, which destroys time order. |
+| `TL003` | error | `.shift(-n)` — a negative shift pulls future values into the current row. Fine for building a label, fatal as a feature. |
+| `TL004` | error | `rolling(center=True)` — a centred window averages bars either side of each row, so every value sees the future. |
+| `TL005` | error | `bfill()` / `fillna(method='bfill')` — backward fill propagates future values into earlier rows. |
+| `TL006` | warning | `KFold`, `StratifiedKFold`, or a `cv=<int>` helper on time series. Later folds train on data that follows the test block. |
+| `TL007` | error | A column rescaled with a whole-frame statistic, e.g. `df['z'] = (df['x'] - df['x'].mean()) / df['x'].std()`. |
+
+### Suppressing a finding
+
+```python
+y = df["close"].shift(-1)          # noqa: TL003   <- intentional label
+y = df["close"].shift(-1)          # noqa          <- suppress everything on this line
+```
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/MartexHACK/timeleak
+    rev: v0.1.0
+    hooks:
+      - id: timeleak
+```
+
+## GitHub Actions
+
+```yaml
+- run: pip install git+https://github.com/MartexHACK/timeleak
+- run: timeleak src/
+```
+
+## What it does not do
+
+Being honest about the boundaries, because a linter that overpromises gets muted:
+
+- **It is syntactic, not semantic.** It cannot follow a leak across function boundaries or
+  through a variable that changes meaning. It finds the common shapes, not every leak.
+- **It does not know whether your data is a time series.** `TL002` and `TL006` are warnings
+  precisely because plain K-fold is correct on i.i.d. data. On a genuinely shuffled
+  cross-sectional dataset, silence them.
+- **A clean run is not a guarantee.** It means the seven known shapes are absent. Walk-forward
+  validation on data the model has never touched is still the real test.
+- **Notebooks are not parsed yet.** `.ipynb` support is planned; today you would export to
+  `.py` first.
+
+If you hit a false positive, that is a bug worth reporting — a noisy linter is a useless one.
+
+## Why these seven
+
+They are the leaks that survive code review because they look like ordinary data preparation.
+Nobody writes `model.fit(X_test)`; people write `scaler.fit_transform(df)` on line 12 and split
+on line 30, and the two lines never appear on screen together.
+
+## Development
+
+```bash
+git clone https://github.com/MartexHACK/timeleak
+cd timeleak
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

timeleak-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+timeleak/__init__.py,sha256=QE6nnjWXrajOheSeilQA5fMg8NfpmVHU9O0xjyXT0Hw,455
+timeleak/__main__.py,sha256=UP0yjf5bUzmplYRElA6c5FuXZNu3sTDMJfOpZsy3Bqg,115
+timeleak/analyzer.py,sha256=sef6o_qKHH8XRBhS1KkrrWNAg0ClsrlW8rqflI75oo8,8710
+timeleak/cli.py,sha256=XKGqoQvn3TzKZkhkac42P70enSyqKqd2budYCcrV1J4,4677
+timeleak/rules.py,sha256=v6QkDIoNcxeaIXSQoDyyKVus-7DP89TBStzqMrdCx7k,4458
+timeleak-0.1.0.dist-info/licenses/LICENSE,sha256=817wU5dhyL6uMmksXNYlT9Xq4MKBI3etZYGpD8LaT4c,1063
+timeleak-0.1.0.dist-info/METADATA,sha256=jSJPezIivAiAGiwN4aWuC1bqY4EfpqDg9PusT4wyjFQ,7637
+timeleak-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+timeleak-0.1.0.dist-info/entry_points.txt,sha256=wsEfuO1-fXEIudoPmr9xMgBpaCH9oJbVDe4BxW006zA,47
+timeleak-0.1.0.dist-info/top_level.txt,sha256=QGmlJKtTNq-FGL2S9CC00x3OcNfpF4vOcpxmLZuHsTo,9
+timeleak-0.1.0.dist-info/RECORD,,

timeleak-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

timeleak-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+timeleak = timeleak.cli:main

timeleak-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martex
+
+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.

timeleak-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+timeleak