feat: add Tailwind CSS pipeline, tag-aware cloning & overhaul CI/CD

Frontend

* introduce Tailwind CSS (package.json, tailwind.config.js, input CSS)
* build site.css on-the-fly (removed tracked artefact; added .gitignore)
* new favicon/icon assets & template cleanup
* split JS into modular files

Docker

* replace single-stage image with 3-stage build
  • css-builder (Node 20 alpine) → compiles Tailwind
  • python-builder installs project with PEP 621 metadata
  • runtime image copies site-packages + compiled CSS, runs as uid 1000

CI/CD

* ci.yml: cache by pyproject.toml, install with `pip -e .[dev]`
* new frontend job builds/archives CSS after tests
* publish.yml: build CSS first, then wheel/sdist; trusted OIDC upload
* tidy scorecard workflow

Core library

* clone.py, parser & utils now resolve tags in addition to branches/commits
* fallback branch/tag discovery when `git ls-remote` fails
* compat\_func.py back-ports Path.readlink / str.removesuffix for Py 3.8

Tooling & docs

* add `[dev]` extra, drop requirements-dev.txt & its pre-commit fixer
* refreshed CONTRIBUTING.md with Node/Tailwind instructions
* updated tests for new tag logic

Large squash commit that wires a proper frontend asset pipeline, modernises the container & release workflows, and expands repository-ingest features to understand Git tags.

Author: filipchristiansen

.github/workflows/ci.yml

@@ -30,21 +30,43 @@ jobs:
       uses: actions/cache@v4
       with:
         path: ~/.cache/pip
-        key: ${{ runner.os }}-pip-${{ hashFiles('**/*requirements*.txt') }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
         restore-keys: |
           ${{ runner.os }}-pip-
 
     - name: Install dependencies
       run: |
-        pip install --upgrade pip
-        pip install -r requirements-dev.txt
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[dev]"
 
     - name: Run tests
-      run: |
-        pytest
+      run: pytest
 
     #  Run pre-commit only on Python 3.13 + ubuntu.
     - name: Run pre-commit hooks
       if: ${{ matrix.python-version == '3.13' && matrix.os == 'ubuntu-latest' }}
-      run: |
-        pre-commit run --all-files
+      run: pre-commit run --all-files
+
+  frontend:
+    needs: test # Builds Tailwind CSS only if tests pass
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install Node deps
+        run: npm ci
+
+      - name: Build CSS
+        run: npm run build:css  # Creates src/static/css/site.css
+
+      - name: Upload artefact
+        uses: actions/upload-artifact@v4
+        with:
+          name: static-css
+          path: src/static/css/site.css

.github/workflows/publish.yml

@@ -1,39 +1,89 @@
-name: "Publish to PyPI"
+name: Publish to PyPI
 
 on:
   release:
-    types: [created]
-  workflow_dispatch:
+    types: [created] # Run when you click “Publish release”
+  workflow_dispatch: # ... or run it manually from the Actions tab
 
 permissions:
   contents: read
 
+# ── Build the Tailwind CSS bundle ───────────────────────────────
 jobs:
+  frontend-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install deps + build Tailwind
+        run: |
+          npm ci
+          npm run build:css
+
+      - name: Upload built CSS
+        uses: actions/upload-artifact@v4
+        with:
+          name: frontend-assets
+          path: src/static/css/site.css
+          if-no-files-found: error
+
+# ── Build wheel/sdist (needs CSS) and upload “dist/” ────────────
   release-build:
+    needs: frontend-build
     runs-on: ubuntu-latest
+
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+
+      # Grab site.css produced above
+      - uses: actions/download-artifact@v4
+        with:
+          name: frontend-assets
+          path: src/static/css/
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
         with:
           python-version: "3.13"
-      - name: Build package
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install build backend
         run: |
-          pip install build
           python -m build
-      - uses: actions/upload-artifact@v4
+          python -m pip install twine
+          twine check dist/*
+          ls -R dist/ # List the contents of the dist directory
+
+      - name: Upload dist artefact
+        uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
 
+# ── Publish to PyPI (only if “dist/” succeeded) ─────────────────
   pypi-publish:
-    needs: [release-build]
+    needs: release-build
     runs-on: ubuntu-latest
-    environment: pypi
+    environment: pypi # Creates the “pypi” environment in repo-settings
+
     permissions:
-      id-token: write
+      id-token: write # OIDC token for trusted publishing
+
     steps:
       - uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/
+
       - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

.github/workflows/scorecard.yml

@@ -1,52 +1,39 @@
 name: OSSF Scorecard
 on:
-  # For Branch-Protection check. Only the default branch is supported. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
   branch_protection_rule:
-  # To guarantee Maintained check is occasionally updated. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
   schedule:
     - cron: '33 11 * * 2'
   push:
-    branches: [ "main" ]
+    branches: [ main ]
 
-# Declare default permissions as read only.
-permissions: read-all
+permissions: read-all  # Default for the whole workflow
+
+concurrency:            # (optional) avoid overlapping runs
+  group: scorecard-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   analysis:
     name: Scorecard analysis
     runs-on: ubuntu-latest
     permissions:
-      # Needed to upload the results to code-scanning dashboard.
-      security-events: write
-      # Needed to publish results and get a badge (see publish_results below).
-      id-token: write
+      security-events: write # upload SARIF to code-scanning
+      id-token: write # publish results for the badge
 
     steps:
-      - name: "Checkout code"
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           persist-credentials: false
 
-      - name: "Run analysis"
-        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736
         with:
           results_file: results.sarif
           results_format: sarif
+          publish_results: true  # enables the public badge
 
-          # Public repositories:
-          #   - Publish results to OpenSSF REST API for easy access by consumers
-          #   - Allows the repository to include the Scorecard badge.
-          #   - See https://github.com/ossf/scorecard-action#publishing-results.
-          publish_results: true
-
-      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
-      # format to the repository Actions tab.
-
-      # Upload the results to GitHub's code scanning dashboard (optional).
-      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
-      - name: "Upload to code-scanning"
+      - name: Upload to code-scanning
         uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: results.sarif

.gitignore

@@ -170,6 +170,9 @@ cython_debug/
 # JavaScript tooling
 node_modules/
 
+# CSS
+src/static/css/site.css
+
 # Project specific
 history.txt
 cleanup.py

.pre-commit-config.yaml

@@ -29,8 +29,6 @@ repos:
       # Python
       - id: check-docstring-first
         description: "Check a common error of defining a docstring after code."
-      - id: requirements-txt-fixer
-        description: "Sort entries in requirements.txt."
 
   - repo: https://github.com/MarcoGorelli/absolufy-imports
     rev: v0.3.1

CONTRIBUTING.md

@@ -1,97 +1,110 @@
 # Contributing to Gitingest
 
-Thanks for your interest in contributing to Gitingest! 🚀 Gitingest aims to be friendly for first time contributors, with a simple Python and HTML codebase. We would love your help to make it even better. If you need any help while working with the code, please reach out to us on [Discord](https://discord.com/invite/zerRaGK9EC).
+Thanks for your interest in contributing to **Gitingest** 🚀 Our goal is to keep the codebase friendly to first-time contributors.
+If you ever get stuck, reach out on [Discord](https://discord.com/invite/zerRaGK9EC).
+
+---
 
 ## How to Contribute (non-technical)
 
-- **Create an Issue**: If you find a bug or have an idea for a new feature, please [create an issue](https://github.com/cyclotruc/gitingest/issues/new) on GitHub. This will help us track and prioritize your request.
-- **Spread the Word**: If you like Gitingest, please share it with your friends, colleagues, and on social media. This will help us grow the community and make Gitingest even better.
-- **Use Gitingest**: The best feedback comes from real-world usage! If you encounter any issues or have ideas for improvement, please let us know by [creating an issue](https://github.com/cyclotruc/gitingest/issues/new) on GitHub or by reaching out to us on [Discord](https://discord.com/invite/zerRaGK9EC).
+- **Create an Issue** – found a bug or have a feature idea?
+  [Open an issue](https://github.com/cyclotruc/gitingest/issues/new).
+- **Spread the Word** – tweet, blog, or tell a friend.
+- **Use Gitingest** – real-world usage gives the best feedback. File issues or ping us on [Discord](https://discord.com/invite/zerRaGK9EC) with anything you notice.
+
+---
 
 ## How to submit a Pull Request
 
-1. Fork the repository.
+> **Prereqs**: The project uses **Python 3.9+** and `pre-commit` for development.
+> If you plan to touch the frontend, you’ll also need **Node ≥18** (for Tailwind).
+
+1. **Fork** the repository.
 
-2. Clone the forked repository:
+2. **Clone** your fork:
 
    ```bash
    git clone https://github.com/cyclotruc/gitingest.git
    cd gitingest
    ```
 
-   **Note**: To contribute, ensure you have **Python 3.9 or newer** installed, as some of the `pre-commit` hooks (e.g. `pyupgrade`) require Python 3.9+.
-
-3. Set up the development environment and install dependencies:
+3. **Set up the dev environment**:
 
    ```bash
    python -m venv .venv
    source .venv/bin/activate
-   pip install -r requirements-dev.txt
+   pip install -e ".[dev]"
    pre-commit install
    ```
 
-4. Create a new branch for your changes:
+4. **Create a branch** for your changes:
 
-    ```bash
-    git checkout -S -b your-branch
-    ```
+   ```bash
+   git checkout -b your-branch
+   ```
 
-5. Make your changes. Make sure to add corresponding tests for your changes.
+5. **Make your changes** (and add tests when relevant).
 
-6. Stage your changes:
+6. **Stage** the changes:
 
-    ```bash
-    git add .
-    ```
+   ```bash
+   git add .
+   ```
 
-7. Run the tests:
+7. **Run the backend test suite**:
 
    ```bash
    pytest
    ```
 
-8. Run the local web server
+8. **If you edited templates or CSS** rebuild Tailwind:
 
-   1. Navigate to src folder
-
-        ``` bash
-        cd src
-        ```
-
-   2. Run the local web server:
+   ```bash
+   # one-time install
+   npm ci
 
-      ``` bash
-      uvicorn server.main:app
-      ```
+   # build once
+   npm run build:css
 
-   3. Open your browser and navigate to `http://localhost:8000` to see the app running.
+   # or watch & rebuild on every save
+   npm run dev:css
+   ```
 
-9. Confirm that everything is working as expected. If you encounter any issues, fix them and repeat steps 6 to 8.
+   *Skip this step if your PR only touches Python code.*
 
-10. Commit your changes (signed):
+9. **Run the local server** to sanity-check:
 
-    All commits to Gitingest must be [GPG-signed](https://docs.github.com/en/authentication/managing-commit-signature-verification) so that the project can verify the authorship of every contribution. You can either configure Git globally with:
+   ```bash
+   cd src
+   uvicorn server.main:app
+   ```
 
-    ```bash
-    git config --global commit.gpgSign true
-    ```
+   Open [http://localhost:8000](http://localhost:8000) to confirm everything works.
 
-    or pass the `-S` flag as shown below.
+10. **Commit** (signed):
 
     ```bash
     git commit -S -m "Your commit message"
     ```
 
-    If `pre-commit` raises any issues, fix them and repeat steps 6 to 9.
+    If *pre-commit* complains, fix the problems and repeat **6 – 9**.
 
-11. Push your changes:
+11. **Push** your branch:
 
     ```bash
     git push origin your-branch
     ```
 
-12. Open a pull request on GitHub. Make sure to include a detailed description of your changes.
+12. **Open a pull request** on GitHub with a clear description.
+
+13. **Iterate** on any review feedback—update your branch and repeat **6 – 12** as needed.
+
+*(Optional) Invite a maintainer to your branch for easier collaboration.*
+
+---
+
+## CSS & build artefacts
 
-13. Wait for the maintainers to review your pull request. If there are any issues, fix them and repeat steps 6 to 12.
+- **Do not commit `src/static/css/site.css`.** The CI pipeline runs `npm run build:css` during the container/image build, so the artefact is produced automatically.
 
-    *(Optional) Invite project maintainer to your branch for easier collaboration.*
+- When developing locally you may run the build yourself (see step 8) so you can preview the styles.