Implement the FileToLink improvement plan (H1-H10, M1-M14, L1-L10) + review hardening

.dockerignore

@@ -0,0 +1,37 @@
+.git
+.gitignore
+.gitattributes
+.github
+.venv
+.vscode
+__pycache__
+*.py[cod]
+.pytest_cache
+.ruff_cache
+.mypy_cache
+*.session*
+**/logs/
+tests/
+docs/
+htmlcov/
+.coverage
+README.md
+CONTRIBUTING.md
+SECURITY.md
+Makefile
+config.env
+config.env.local
+config.env.bak
+config.env.tmp
+*.tmp
+AGENTS.md
+uv.lock
+requirements.txt
+# build/infra files the runtime image never reads
+pyproject.toml
+scripts/
+config_sample.env
+render.yaml
+app.json
+heroku.yml
+docker-compose.yml

.gitattributes

@@ -0,0 +1,11 @@
+# Normalize all text files to LF in the repository and working tree.
+* text=auto eol=lf
+
+# Binary assets
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.docx binary
+*.session binary

.github/dependabot.yml

@@ -0,0 +1,27 @@
+# Dependabot cannot regenerate uv.lock: after each pip PR, run
+#
+#   uv lock && uv export --frozen --no-dev --hashes -o requirements.lock
+#
+# and push both lockfiles to the PR branch, or CI's `uv lock --check` and the
+# requirements.lock export-diff gate will fail. These PRs are expected to be
+# red until that human step is done -- see the `lockfiles-stale` label.
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    labels:
+      - lockfiles-stale
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: pre-commit
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/quality.yml

@@ -0,0 +1,165 @@
+name: Quality Gates
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quality-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+
+      # pinned: lock/export output format and gate semantics must not drift
+      # between commits (dependabot bumps this like any other dependency)
+      - name: Install uv
+        run: python -m pip install "uv==0.12.5"
+
+      # Install the hash-pinned lockfile (runtime + dev) so CI tests and audits
+      # the exact dependency graph that ships, not a fresh pip resolution.
+      - name: Install dependencies (locked, hash-pinned)
+        run: uv sync --frozen --group dev
+
+      - name: Lockfile is current with pyproject (uv.lock must never drift)
+        run: uv lock --check
+
+      - name: requirements.txt is in sync with pyproject (two sources of truth must agree)
+        run: |
+          uv run --locked python - <<'PY'
+          import sys, tomllib
+          deps = {d.strip() for d in tomllib.load(open("pyproject.toml", "rb"))["project"]["dependencies"]}
+          listed = {l.strip() for l in open("requirements.txt") if l.strip() and not l.startswith("#")}
+          if deps != listed:
+              print("pyproject:", sorted(deps))
+              print("requirements.txt:", sorted(listed))
+              sys.exit("requirements.txt drifted from pyproject [project.dependencies]")
+          PY
+
+      - name: requirements.lock is in sync with uv.lock (Docker consumes this)
+        run: |
+          uv export --frozen --no-dev --hashes -o /tmp/requirements.lock.check
+          # uv embeds the export command in the header; compare content only
+          diff -u <(grep -v '^#' requirements.lock) <(grep -v '^#' /tmp/requirements.lock.check)
+
+      - name: Ruff (lint + format check)
+        run: |
+          uv run ruff check Thunder/ update.py tests/ scripts/
+          uv run ruff format --check Thunder/ update.py tests/ scripts/
+
+      - name: Mypy (blocking)
+        run: uv run mypy Thunder update.py scripts/
+
+      - name: Unit tests
+        run: uv run pytest --cov=Thunder --cov-report=term-missing --cov-fail-under=35
+
+      # addopts = "-m unit" silently deselects any test that forgets its marker:
+      # an unmarked test is collected but never runs, and nothing else notices.
+      #
+      # The counts are grepped out of pytest's own summary rather than taken from
+      # `tail -1 | cut -d' ' -f1`: that pipeline captures whatever happens to be
+      # last on stdout, so any change to pytest's trailing output makes BOTH sides
+      # capture the same garbage, the comparison passes, and the gate silently
+      # stops guarding anything.
+      - name: No test is silently excluded by the marker filter
+        run: |
+          set -o pipefail
+          UNIT=$(uv run pytest -m unit --collect-only -q | grep -oE '[0-9]+/[0-9]+ tests collected' | tail -1)
+          ALL=$(uv run pytest -m "not integration" --collect-only -q | grep -oE '[0-9]+/[0-9]+ tests collected' | tail -1)
+          echo "unit=$UNIT all-non-integration=$ALL"
+          if [ -z "$UNIT" ] || [ -z "$ALL" ]; then
+            echo "::error::Could not parse the collection summary from pytest. Fix this step rather than letting it pass vacuously."
+            exit 1
+          fi
+          if [ "$UNIT" != "$ALL" ]; then
+            echo "::error::A test is missing its @pytest.mark.unit and addopts=-m unit is excluding it. Mark it, or move it to the integration tier."
+            exit 1
+          fi
+
+      # Audit the locked env: `-r requirements.txt` (direct pins only) never covered transitives.
+      - name: pip-audit (locked environment incl. transitives)
+        run: uv run pip-audit
+
+      - name: Bandit (medium-or-higher severity)
+        run: uv run bandit -c pyproject.toml -r Thunder update.py -ll --skip B101
+
+      - name: Vulture (dead-code gate)
+        run: uv run vulture Thunder update.py --min-confidence 80
+
+      - name: Dependency count gate (leanness is permanent)
+        run: |
+          # distinct package names, so a conditional platform marker for the same
+          # package (pyrofork[speedup] / pyrofork) does not inflate the count
+          COUNT=$(grep -vE '^[[:space:]]*(#|$)' requirements.txt \
+            | sed -E 's/[[:space:]]*;.*$//; s/[[:space:]]*\[.*\]//; s/==.*$//' \
+            | tr -d '\r' | sort -u | wc -l)
+          echo "Direct runtime deps: $COUNT"
+          if [ "$COUNT" -gt 7 ]; then
+            echo "::error::Direct dependency count increased beyond the agreed 7; justify in the PR or remove."
+            exit 1
+          fi
+
+  docker:
+    # Smoke-build on PRs (no secrets); publish only from main pushes so a
+    # feature branch can never overwrite fyaz05/thunder:latest.
+    if: github.repository == 'fyaz05/FileToLink' && (github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == 'refs/heads/main'))
+    needs: quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - name: Login to Docker Hub
+        if: github.event_name == 'push'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          username: fyaz05
+          password: ${{ secrets.DOCKER_TOKEN }}
+
+      - name: Build and Push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: .
+          push: ${{ github.event_name == 'push' }}
+          # Attestations stay off: the default docker driver rejects them even
+          # on no-push smoke builds; revisit with a containerd-backed builder.
+          tags: |
+            fyaz05/thunder:latest
+            fyaz05/thunder:${{ github.sha }}
+
+  integration:
+    # token CAS / ingest-claim atomicity is only provable against a real
+    # MongoDB, and this tier never ran in CI before
+    needs: quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        run: python -m pip install "uv==0.12.5"
+
+      - name: Install dependencies (locked, incl. testcontainers)
+        run: uv sync --frozen --group dev
+
+      - name: Integration tests (real MongoDB via testcontainers)
+        run: uv run pytest -m integration
+        env:
+          TEST_INTEGRATION: "1"

.gitignore

@@ -1,28 +1,38 @@
-*.py[cod]
-*$py.class
-*.so
-.venv/
-.Python
-config.env
-log.text
-.vscode/
-**/__pycache__/
-*.session
-*.session-journal
-*.session-shm
-*.session-wal
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
+*.py[cod]
+*$py.class
+*.so
+.venv/
+.Python
+config.env
+config.env.local
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+log.txt
+config.env.tmp
+config.env.bak
+*.tmp
+Thunder/logs/
+.vscode/
+**/__pycache__/
+*.session
+*.session-journal
+*.session-shm
+*.session-wal
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files