finefettle 1.0.2__py3-none-any.whl

fettle/__init__.py

@@ -0,0 +1,3 @@
+"""Fettle — quality enforcement for AI-assisted development."""
+
+__version__ = "1.0.2"

fettle/__main__.py

@@ -0,0 +1,7 @@
+"""Run the Fettle CLI with ``python -m fettle``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

fettle/_resources.py

@@ -0,0 +1,45 @@
+"""Runtime resource location for fettle.
+
+Resolves paths to bundled resources (rules/, templates/, etc.) that work in
+both install modes:
+
+1. Clone-into-plugins: rules/ lives at repo root (../rules relative to scripts/)
+2. pip/uvx install: rules/ is copied into the wheel as fettle/_rules/
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_PACKAGE_DIR = Path(__file__).parent
+_REPO_ROOT = _PACKAGE_DIR.parent  # Only valid in clone mode
+
+
+def rules_dir() -> Path:
+    """Return the path to the semgrep/ruff rules directory.
+
+    Resolution order:
+    1. CLAUDE_PLUGIN_ROOT env var (explicit override)
+    2. Clone-mode: repo_root/rules/ (exists when running from git clone)
+    3. Pip-installed: package/_rules/ (bundled inside the wheel)
+    """
+    # 1. Explicit env var
+    env_root = os.environ.get("CLAUDE_PLUGIN_ROOT")
+    if env_root:
+        candidate = Path(env_root) / "rules"
+        if candidate.is_dir():
+            return candidate
+
+    # 2. Clone mode — rules/ at repo root
+    clone_rules = _REPO_ROOT / "rules"
+    if clone_rules.is_dir():
+        return clone_rules
+
+    # 3. Pip-installed — _rules/ inside the package
+    pkg_rules = _PACKAGE_DIR / "_rules"
+    if pkg_rules.is_dir():
+        return pkg_rules
+
+    # Fallback to clone path (will fail gracefully downstream)
+    return clone_rules

fettle/_rules/.ruff.toml

@@ -0,0 +1,10 @@
+line-length = 120
+target-version = "py312"
+
+[lint]
+select = ["E", "F", "BLE", "S110", "S608", "S701", "B", "SIM", "UP"]
+ignore = ["E501"]
+
+[lint.per-file-ignores]
+"tests/*" = ["S", "BLE"]
+"*_generated.py" = ["ALL"]

fettle/_rules/go-antipatterns.yml

@@ -0,0 +1,68 @@
+rules:
+  - id: empty-error-swallow-go
+    metadata:
+      origin: fettle-v0.4.2
+      citation: "Swallowed errors are the Go twin of bare-except-pass — failures vanish silently"
+      fix: 'Handle it: return fmt.Errorf("context: %w", err) or log and recover deliberately'
+    languages: [go]
+    severity: ERROR
+    pattern-either:
+      - pattern: |
+          if $ERR != nil { }
+      - pattern: |
+          if $ERR := $F(...); $ERR != nil { }
+    message: "Error checked but swallowed — empty if-block hides failures."
+
+  - id: debug-print-go
+    metadata:
+      origin: debug-detection
+      citation: "Leftover fmt.Println pollutes service logs — use the structured logger"
+      fix: 'Replace with slog/zap: logger.Info(...) — or remove'
+    languages: [go]
+    severity: WARNING
+    pattern-either:
+      - pattern: fmt.Println(...)
+      - pattern: fmt.Printf(...)
+      - pattern: println(...)
+    paths:
+      exclude:
+        - "cmd/"
+        - "tools/"
+        - "scripts/"
+        - "**/main.go"
+        - "**/*_test.go"
+    message: "Leftover debug print — use the structured logger or remove."
+
+  - id: sql-string-concat-go
+    metadata:
+      origin: security
+      citation: "OWASP: SQL injection via string-built queries"
+      fix: 'Use placeholders: db.Query("SELECT ... WHERE id = $1", id)'
+    languages: [go]
+    severity: ERROR
+    pattern-either:
+      - pattern: $DB.Query("..." + $VAR, ...)
+      - pattern: $DB.QueryRow("..." + $VAR, ...)
+      - pattern: $DB.Exec("..." + $VAR, ...)
+      - pattern: $DB.QueryContext($CTX, "..." + $VAR, ...)
+      - pattern: $DB.QueryRowContext($CTX, "..." + $VAR, ...)
+      - pattern: $DB.ExecContext($CTX, "..." + $VAR, ...)
+      - pattern: fmt.Sprintf("SELECT ...", ...)
+      - pattern: fmt.Sprintf("INSERT ...", ...)
+      - pattern: fmt.Sprintf("UPDATE ...", ...)
+      - pattern: fmt.Sprintf("DELETE ...", ...)
+    message: "SQL built from strings is injection-vulnerable — use parameterized queries."
+
+  - id: http-client-no-timeout-go
+    metadata:
+      origin: fettle-v0.4.2
+      citation: "http.Client zero value has no timeout — hangs on unresponsive servers"
+      fix: 'http.Client{Timeout: 30 * time.Second}'
+    languages: [go]
+    severity: WARNING
+    patterns:
+      - pattern: |
+          http.Client{...}
+      - pattern-not: |
+          http.Client{..., Timeout: $T, ...}
+    message: "http.Client without Timeout can hang forever — set an explicit Timeout."

fettle/_rules/llm-antipatterns.yml

@@ -0,0 +1,261 @@
+rules:
+  - id: regex-llm-output
+    metadata:
+      origin: llm-antipattern
+      citation: "Structured tool_use replaced regex parsing of model output across our agents"
+    languages: [python]
+    severity: ERROR
+    paths:
+      include:
+        - "pipeline/"
+        - "agents/"
+    patterns:
+      - pattern-either:
+          - pattern: re.search($PATTERN, ...)
+          - pattern: re.findall($PATTERN, ...)
+      - metavariable-regex:
+          metavariable: $PATTERN
+          regex: ".*[\\[\\{].*"
+    message: >-
+      Regex parsing of LLM output is fragile and produces invalid results.
+      Fix: Use Anthropic tool_use for structured output, or 'pip install instructor'
+      and use Instructor with Pydantic models.
+      Example: response = client.messages.create(..., tools=[tool_def])
+
+  - id: bare-except-swallow
+    metadata:
+      origin: classic
+      citation: "Swallowed exceptions repeatedly hid real failures in AI-generated code"
+    languages: [python]
+    severity: ERROR
+    patterns:
+      - pattern: |
+          try:
+              ...
+          except:
+              pass
+    message: >-
+      Bare except with pass swallows all errors silently.
+      Fix: Catch specific exceptions: 'except (ValueError, KeyError) as e:
+      logger.warning("Handled: %s", e)'
+
+  - id: broad-except-no-reraise
+    metadata:
+      origin: classic
+      citation: "Broad catches without logging made production failures invisible"
+    languages: [python]
+    severity: ERROR
+    patterns:
+      - pattern-either:
+          - pattern: |
+              try:
+                  ...
+              except Exception as $E:
+                  $BODY
+          - pattern: |
+              try:
+                  ...
+              except BaseException as $E:
+                  $BODY
+      - pattern-not: |
+          try:
+              ...
+          except Exception as $E:
+              ...
+              raise
+      - pattern-not: |
+          try:
+              ...
+          except Exception as $E:
+              ...
+              raise ...
+      - pattern-not: |
+          try:
+              ...
+          except BaseException as $E:
+              ...
+              raise
+      - pattern-not: |
+          try:
+              ...
+          except BaseException as $E:
+              ...
+              raise ...
+      - pattern-not: |
+          try:
+              ...
+          except Exception as $E:
+              ...
+              logging.$METHOD(...)
+      - pattern-not: |
+          try:
+              ...
+          except BaseException as $E:
+              ...
+              logging.$METHOD(...)
+      - pattern-not: |
+          try:
+              ...
+          except Exception as $E:
+              ...
+              logger.$METHOD(...)
+      - pattern-not: |
+          try:
+              ...
+          except BaseException as $E:
+              ...
+              logger.$METHOD(...)
+    message: >-
+      Broad Exception caught without re-raise or logging hides failures.
+      Fix: Add 'logger.error("Failed: %s", e, exc_info=True)' or catch specific exceptions.
+
+  - id: missing-httpx-timeout
+    metadata:
+      origin: llm-antipattern
+      citation: "AI-generated HTTP clients repeatedly shipped without timeouts"
+    languages: [python]
+    severity: ERROR
+    patterns:
+      - pattern-either:
+          - pattern: httpx.AsyncClient(...)
+          - pattern: httpx.Client(...)
+      - pattern-not: httpx.AsyncClient(..., timeout=..., ...)
+      - pattern-not: httpx.Client(..., timeout=..., ...)
+    message: >-
+      httpx client without timeout will hang on unresponsive servers.
+      Fix: httpx.AsyncClient(timeout=httpx.Timeout(30.0))
+
+  - id: sql-fstring
+    metadata:
+      origin: security
+      citation: "OWASP: SQL injection via string-built queries"
+    languages: [python]
+    severity: ERROR
+    patterns:
+      - pattern-regex: "(?i)f[\"'].*(?:SELECT|INSERT|UPDATE|DELETE|DROP)\\s.*\\{.*\\}.*[\"']"
+    message: >-
+      SQL via f-string is injection-vulnerable.
+      Fix: Use parameterized queries: cursor.execute('SELECT * FROM table WHERE id = ?', (user_id,))
+
+  - id: datetime-now-pipeline
+    metadata:
+      origin: pipeline
+      citation: "Wall-clock reads in pipelines broke historical backfills"
+    languages: [python]
+    severity: WARNING
+    paths:
+      include:
+        - "pipeline/"
+        - "sources/"
+    pattern-either:
+      - pattern: datetime.now()
+      - pattern: datetime.datetime.now()
+    message: >-
+      datetime.now() in pipeline code breaks backfill and testing.
+      Fix: Accept a 'clock: Callable[[], datetime] = datetime.now' parameter
+      and call clock() instead.
+
+  - id: health-score-inversion
+    metadata:
+      origin: incident
+      citation: "INC-2026-0501-A: health dimension returned 1.0 on absent data, masking an outage"
+    languages: [python]
+    severity: ERROR
+    pattern-either:
+      - pattern: |
+          if $X <= 0.0:
+              return 1.0
+      - pattern: |
+          if $X <= 0:
+              return 1.0
+      - pattern: |
+          if $X == 0.0:
+              return 1.0
+      - pattern: |
+          if $X == 0:
+              return 1.0
+      - pattern: |
+          if not $X:
+              return 1.0
+      - pattern: return 1.0 if $X <= 0.0 else $Y
+      - pattern: return 1.0 if $X <= 0 else $Y
+      - pattern: return 1.0 if not $X else $Y
+    message: >-
+      Health score returns 1.0 (perfect) when metric is zero or absent.
+      "No data" must never map to the best possible score — it must return
+      None (unmeasured) or 0.0 (degraded), not 1.0.
+      Fix: return None when no measurement is available; let the composite
+      skip unmeasured dimensions and set status=unknown.
+      Incident: incident INC-2026-0501-A.responsiveness,
+      KHI.accuracy, KHI.behavioral_consistency all had this pattern.
+
+  - id: orphaned-queue-flag
+    metadata:
+      origin: incident
+      citation: "INC-2026-0501-B: write-only queue shipped with no verified consumer"
+    languages: [python]
+    severity: ERROR
+    pattern-regex: "(?m)processed\\s*=\\s*0(?!.*#\\s*fettle:queue-consumer-verified)"
+    message: >-
+      Queue flag (processed=0) written without a fettle:queue-consumer-verified
+      annotation. This risks a write-only queue — rows accumulate with no
+      consumer to process them.
+      Fix: ensure a consumer exists that calls get_unprocessed_* and marks
+      rows processed=1, then annotate the write site:
+        # fettle:queue-consumer-verified consumer=<consumer_file.py>
+      Incident: incident INC-2026-0501-B
+      written with processed=0; no consumer ever called get_unprocessed_episodes.
+
+  - id: debug-breakpoint
+    metadata:
+      origin: debug-detection
+      citation: "WP-113: Leftover debug statements leak into production"
+    languages: [python]
+    severity: WARNING
+    pattern: breakpoint()
+    message: "Leftover breakpoint() — remove before shipping."
+
+  - id: debug-pdb
+    metadata:
+      origin: debug-detection
+      citation: "WP-113: Leftover debug statements leak into production"
+    languages: [python]
+    severity: WARNING
+    pattern-either:
+      - pattern: import pdb
+      - pattern: pdb.set_trace()
+    message: "Leftover pdb debugger — remove before shipping."
+
+  - id: debug-print-statement
+    metadata:
+      origin: debug-detection
+      citation: "WP-113: print() in non-CLI code pollutes logs"
+    languages: [python]
+    severity: WARNING
+    pattern: print(...)
+    paths:
+      exclude:
+        - "cli/"
+        - "scripts/"
+        - "**/cli.py"
+        - "**/main.py"
+        - "**/conftest.py"
+        - "tests/"
+    message: "print() in non-CLI code — use logging or remove."
+
+  - id: non-atomic-write-output
+    metadata:
+      origin: pipeline
+      citation: "Partial writes corrupted downstream readers on crash"
+    languages: [python]
+    severity: WARNING
+    paths:
+      include:
+        - "pipeline/"
+        - "output/"
+    patterns:
+      - pattern: $PATH.write_text(...)
+    message: >-
+      Direct file write is not atomic — crash produces corrupt output.
+      Fix: import tempfile, os; fd, tmp = tempfile.mkstemp(dir=path.parent);
+      os.write(fd, content.encode()); os.close(fd); os.replace(tmp, path)

fettle/_rules/ts-antipatterns.yml

@@ -0,0 +1,112 @@
+rules:
+  - id: empty-catch-block
+    pattern-either:
+      - pattern: |
+          catch ($ERR) { }
+      - pattern: |
+          catch { }
+    message: "Empty catch block swallows errors silently. Log or handle the error."
+    languages: [typescript, javascript]
+    severity: ERROR
+    metadata:
+      origin: fettle-v0.4.0
+      citation: "Common AI-generated pattern: try/catch without error handling"
+      fix: "Add error logging: catch (e) { console.error('Context:', e); throw e; }"
+
+  - id: unawaited-promise
+    patterns:
+      - pattern-either:
+          - pattern: fetch(...)
+          - pattern: axios(...)
+          - pattern: axios.$METHOD(...)
+      - pattern-not-inside: await $X
+      - pattern-not-inside: return $X
+      - pattern-not-inside: const $X = $Y
+      - pattern-not-inside: let $X = $Y
+      - pattern-not-inside: var $X = $Y
+      - pattern-not-inside: $X.then(...)
+      - pattern-not-inside: $X.catch(...)
+    message: "Unawaited promise from fetch/axios. Add await or handle the returned promise."
+    languages: [typescript, javascript]
+    severity: WARNING
+    metadata:
+      origin: fettle-v0.4.0
+      citation: "Fire-and-forget async calls lose errors and create race conditions"
+      fix: "Add await: const result = await fetch(url)"
+      note: >-
+        Scoped to known promise-returning APIs. Semgrep OSS has no type
+        inference, so matching arbitrary $FN(...) calls flagged every
+        statement-level call (~9k findings on a 23-file app).
+
+  - id: fetch-without-timeout
+    patterns:
+      - pattern-either:
+          - pattern: |
+              fetch($URL)
+          - pattern: |
+              fetch($URL, { ... })
+      - pattern-not: |
+          fetch($URL, { ..., signal: $SIGNAL, ... })
+    message: "fetch() without AbortSignal timeout. Network calls can hang indefinitely."
+    languages: [typescript, javascript]
+    severity: ERROR
+    metadata:
+      origin: fettle-v0.4.0
+      citation: "AI-generated fetch calls rarely include timeouts — causes hung processes"
+      fix: "Add signal: fetch(url, { signal: AbortSignal.timeout(10000) })"
+
+  - id: string-built-sql-ts
+    # pattern-regex (not template-literal patterns): semgrep's ellipsis does
+    # not match inside template literals, so `SELECT ... ${$VAR} ...` never
+    # fired — caught by the WP-116 integrity suite. The regex also catches
+    # SQL templates assigned to variables, not just call arguments.
+    pattern-regex: "(?i)`\\s*(SELECT|INSERT|UPDATE|DELETE)[^`]*\\$\\{[^`]*`"
+    message: "SQL query built with template literal interpolation — use parameterized queries."
+    languages: [typescript, javascript]
+    severity: ERROR
+    metadata:
+      origin: fettle-v0.4.0
+      citation: "SQL injection via template literals in AI-generated database code"
+      fix: "Use parameterized queries: db.query('SELECT * FROM t WHERE id = $1', [id])"
+
+  - id: debug-console-log
+    metadata:
+      origin: debug-detection
+      citation: "WP-113: Leftover console.log pollutes production logs"
+    languages: [typescript, javascript]
+    severity: WARNING
+    pattern: console.log(...)
+    paths:
+      exclude:
+        - "scripts/"
+        - "**/cli.*"
+        - "**/cli/"
+    message: "Leftover console.log — remove or replace with structured logger."
+
+  - id: debug-debugger-statement
+    metadata:
+      origin: debug-detection
+      citation: "WP-113: debugger statement halts execution in browser"
+    languages: [typescript, javascript]
+    severity: ERROR
+    pattern: debugger
+    message: "Leftover debugger statement — remove before shipping."
+
+  - id: regex-llm-output-ts
+    pattern-either:
+      - pattern: |
+          $X.match($REGEX)
+      - pattern: |
+          $REGEX.exec($X)
+    paths:
+      include:
+        - "agents/"
+        - "pipeline/"
+        - "llm/"
+    message: "Regex parsing of what may be LLM output. Use structured output (JSON, tool_use) instead."
+    languages: [typescript, javascript]
+    severity: WARNING
+    metadata:
+      origin: fettle-v0.4.0
+      citation: "LLM output is non-deterministic; regex parsing breaks on format drift"
+      fix: "Use structured output: JSON.parse() on tool_use response, or response_format: json"

fettle/action_entrypoint.py

@@ -0,0 +1,130 @@
+"""Fettle GitHub Action execution and SARIF output."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+
+
+def main() -> int:
+    mode = os.environ.get("INPUT_MODE", "advisory").lower()
+    if mode not in {"advisory", "enforce"}:
+        print(f"::error::Invalid mode '{mode}'; expected advisory or enforce", file=sys.stderr)
+        return 2
+    sarif_enabled = os.environ.get("INPUT_SARIF", "true").lower() == "true"
+    config_path = os.environ.get("INPUT_CONFIG", "")
+    paths = shlex.split(os.environ.get("INPUT_PATHS", "."))
+    github_output = os.environ.get("GITHUB_OUTPUT", "")
+    runner_temp = os.environ.get("RUNNER_TEMP", "/tmp")
+
+    cmd = [sys.executable, "-m", "fettle", "check", "--json", "--all"]
+    if config_path:
+        os.environ["FETTLE_CONFIG"] = os.path.abspath(config_path)
+
+    all_findings: list[dict] = []
+    scan_failed = False
+    for path in paths:
+        scan_path = os.path.abspath(path)
+        result = subprocess.run(
+            [*cmd, "--root", scan_path],
+            capture_output=True,
+            text=True,
+        )
+        parsed = False
+        if result.stdout.strip():
+            try:
+                data = json.loads(result.stdout)
+                findings = data.get("findings", []) if isinstance(data, dict) else data
+                all_findings.extend(findings)
+                parsed = True
+            except json.JSONDecodeError:
+                print(f"::error::Could not parse fettle output for path '{path}'")
+                print(result.stdout[:500], file=sys.stderr)
+        if result.returncode not in (0, 1) or not parsed:
+            scan_failed = True
+        for line in result.stderr.strip().splitlines()[:10]:
+            print(f"::debug::{line}")
+
+    findings_count = len(all_findings)
+    has_errors = any(str(f.get("severity", "")).lower() == "error" for f in all_findings)
+
+    findings_path = os.path.join(runner_temp, "fettle-findings.json")
+    with open(findings_path, "w") as f:
+        json.dump(all_findings, f)
+
+    sarif_file = ""
+    if sarif_enabled:
+        sarif_file = os.path.join(runner_temp, "fettle.sarif")
+        with open(sarif_file, "w") as f:
+            json.dump(_findings_to_sarif(all_findings), f, indent=2)
+
+    exit_code = 2 if scan_failed else (1 if mode == "enforce" and has_errors else 0)
+    if github_output:
+        with open(github_output, "a") as f:
+            f.write(f"findings_count={findings_count}\n")
+            f.write(f"sarif_file={sarif_file}\n")
+            f.write(f"exit_code={exit_code}\n")
+
+    print(f"Fettle: {findings_count} finding(s), mode={mode}, exit_code={exit_code}")
+    if all_findings:
+        errors = [f for f in all_findings if str(f.get("severity", "")).lower() == "error"]
+        warnings = [f for f in all_findings if str(f.get("severity", "")).lower() != "error"]
+        if errors:
+            print(f"  {len(errors)} error(s), {len(warnings)} warning(s)")
+        for finding in all_findings[:20]:
+            sev = finding.get("severity", "info").upper()
+            loc = f"{finding.get('file', '')}:{finding.get('line', '')}"
+            print(f"  [{sev}] {loc} {finding.get('code', '')} - {finding.get('message', '')}")
+        if findings_count > 20:
+            print(f"  ... and {findings_count - 20} more")
+    return exit_code
+
+
+def _findings_to_sarif(findings: list[dict]) -> dict:
+    """Convert findings to SARIF 2.1.0 format."""
+    results = []
+    rules: dict[str, dict] = {}
+    for finding in findings:
+        rule_id = finding.get("code", finding.get("rule", "unknown"))
+        severity = str(finding.get("severity", "warning")).lower()
+        file_path = finding.get("file", finding.get("path", ""))
+        line = finding.get("line", 1)
+        message = finding.get("message", "")
+        sarif_level = {"error": "error", "warning": "warning", "info": "note"}.get(severity, "warning")
+        rules.setdefault(rule_id, {
+            "id": rule_id,
+            "shortDescription": {"text": message[:100]},
+            "defaultConfiguration": {"level": sarif_level},
+        })
+        results.append({
+            "ruleId": rule_id,
+            "level": sarif_level,
+            "message": {"text": message},
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {"uri": file_path},
+                    "region": {"startLine": line},
+                },
+            }] if file_path else [],
+        })
+    return {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "fettle",
+                    "informationUri": "https://github.com/MilindGaharwar/fettle",
+                    "rules": list(rules.values()),
+                },
+            },
+            "results": results,
+        }],
+    }
+
+
+if __name__ == "__main__":
+    sys.exit(main())