ISSUE-266 Replace Black linter with Super-Linter

.checkov.yaml

@@ -0,0 +1,9 @@
+---
+# Checkov skips for intentional local-dev / OpenAPI design choices.
+# Auth is enforced at nginx (basic auth), not in the OpenAPI document.
+skip-check:
+  - CKV_DOCKER_2 # HEALTHCHECK optional for short-lived local compose services
+  - CKV_DOCKER_3 # non-root USER deferred; compose network is private
+  - CKV_OPENAPI_4 # security schemes declared at operation / gateway layer
+  - CKV_OPENAPI_5
+  - CKV2_GHA_1 # workflow permissions set per-job, not write-all globally

.codespellrc

@@ -0,0 +1,3 @@
+[codespell]
+ignore-words-list = connexion,Connexion,etuff,eTUFF,hadolint,tagbase,Tagbase,pgadmin,argos,Argos,teardown,Teardown
+skip = .tox,.git,*.pem,*.zip,pylock.toml

.github/super-linter.env

@@ -0,0 +1,29 @@
+# Shared Super Linter configuration (CI + local Docker).
+# Docs: https://github.com/super-linter/super-linter/blob/main/docs/run-linter-locally.md
+#
+# Keys are alphabetical (dotenv-linter UnorderedKey).
+
+DEFAULT_BRANCH=main
+# Exclude local tox/venv envs, intentional TLS fixtures, staging drops, and
+# pg_dump-style schema SQL (OWNER TO / ROLE / \connect). Hand-written
+# materialized views remain under SQLFluff.
+# (Do not set IGNORE_GITIGNORED_FILES=true — it passes --gitignore to jscpd,
+# which this Super Linter image rejects.)
+FILTER_REGEX_EXCLUDE=\.tox/|\.venv/|venv/|services/nginx/ssl/|test/fixtures/nginx/|staging_data(\.bk)?(/|$)|services/postgis/tagbase_schema(_tables)?\.sql$
+LINTER_RULES_PATH=.
+VALIDATE_ALL_CODEBASE=true
+# Drop Biome; Prettier + ESLint JSON cover the little non-Python surface area.
+VALIDATE_BIOME_FORMAT=false
+VALIDATE_BIOME_LINT=false
+# No commitlint config in-repo.
+VALIDATE_GIT_COMMITLINT=false
+# Soft prose lint; markdownlint + codespell remain.
+VALIDATE_NATURAL_LANGUAGE=false
+# Pre-commit runs on developer machines (Hadolint); keep it out of Super Linter.
+VALIDATE_PRE_COMMIT=false
+# Python style/bugfinding: keep Black + mypy + Ruff; drop overlapping gates.
+VALIDATE_PYTHON_FLAKE8=false
+VALIDATE_PYTHON_ISORT=false
+VALIDATE_PYTHON_PYLINT=false
+# Black remains the Python formatter.
+VALIDATE_PYTHON_RUFF_FORMAT=false

.github/workflows/build.yml

@@ -7,79 +7,65 @@ on:
     branches:
       - main
   pull_request:
-      types: [opened, synchronize, reopened]
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
 jobs:
   lint_openapi:
     name: Lint OpenAPI Specification
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 # Required to mount the Github Workspace to a volume
-      - name: Lint OpenAPI Specification
-        uses: addnab/docker-run-action@v3
         with:
-          image: ibmdevxsdk/openapi-validator:latest
-          options: -v ${{ github.workspace }}:/data -w /data
-          run: |
+          persist-credentials: false
+      - name: Lint OpenAPI Specification
+        run: |
+          docker run --rm \
+            -v "${{ github.workspace }}:/data" \
+            -w /data \
+            ibmdevxsdk/openapi-validator:latest \
             lint-openapi --ruleset /data/.spectral.yaml --warnings-limit 0 openapi.yaml
-            exit $?
-  lint_dockerfiles:
-    name: Lint Dockerfiles
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        dockerfile:
-          - tagbase_server/Dockerfile
-          - services/docker-cron/Dockerfile
-          - services/fswatch/Dockerfile
-          - services/nginx/Dockerfile
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - name: Lint ${{ matrix.dockerfile }}
-        uses: hadolint/hadolint-action@2a66e89f53d0771bb131a7fa31f3136336094aa6 # v3.4.0
-        with:
-          dockerfile: ${{ matrix.dockerfile }}
-          config: .hadolint.yaml
   sonarcloud:
     name: SonarCloud Analysis
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      with:
-        # Disabling shallow clone is recommended for improving relevancy of reporting
-        fetch-depth: 0
-    - name: Setup Python
-      uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
-      with:
-        python-version: "3.14"
-    - name: Install tox and any other packages
-      run: python -m pip install tox
-    - name: Run tox
-      working-directory: tagbase_server
-      run: tox -e py
-    - name: Fix code coverage paths
-      working-directory: tagbase_server/tagbase_server
-      run: |
-        sed -i "s/\/home\/runner\/work\/tagbase-server\/tagbase-server\/tagbase_server\/tagbase_server/\/github\/workspace\/tagbase_server\/tagbase_server\//g" coverage.xml
-    - name: SonarCloud Analysis
-      if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') }}
-      uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      with:
-        projectBaseDir: tagbase_server/tagbase_server
-        args: >
-          -Dsonar.exclusions=test/**
-          -Dsonar.organization=tagbase
-          -Dsonar.projectKey=tagbase_tagbase-server
-          -Dsonar.python.coverage.reportPaths=coverage.xml
-          -Dsonar.python.version=3.10,3.11,3.12,3.13,3.14
-          -Dsonar.sources=.
-          -Dsonar.tests=test
-          -Dsonar.test.inclusions=test/**
-          -Dsonar.verbose=true
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Disabling shallow clone is recommended for improving relevancy of reporting
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Setup Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+      - name: Install tox and any other packages
+        run: python -m pip install tox
+      - name: Run tox
+        working-directory: tagbase_server
+        run: tox -e py
+      - name: SonarCloud Analysis
+        if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]') }}
+        uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        with:
+          projectBaseDir: tagbase_server/tagbase_server
+          args: >
+            -Dsonar.exclusions=test/**
+            -Dsonar.organization=tagbase
+            -Dsonar.projectKey=tagbase_tagbase-server
+            -Dsonar.python.coverage.reportPaths=coverage.xml
+            -Dsonar.python.version=3.10,3.11,3.12,3.13,3.14
+            -Dsonar.sourceEncoding=UTF-8
+            -Dsonar.sources=.
+            -Dsonar.tests=test
+            -Dsonar.test.inclusions=test/**
+            -Dsonar.test.exclusions=test/fixtures/**
+            -Dsonar.verbose=true
   tox_tests:
     name: Tox Testing
     runs-on: ubuntu-latest
@@ -88,6 +74,8 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Setup Python ${{ matrix.python-version }}
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
@@ -105,10 +93,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Start PostGIS
         run: |
           docker compose -f docker-compose.test.yml up -d postgis
-          for i in $(seq 1 60); do
+          for _ in $(seq 1 60); do
             if docker compose -f docker-compose.test.yml exec -T postgis \
               pg_isready -d tagbase -U tagbase ; then
               break
@@ -137,11 +127,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Start stack
         run: |
           mkdir -p staging_data
           docker compose -f docker-compose.test.yml --profile stack up -d --build
-          for i in $(seq 1 90); do
+          for _ in $(seq 1 90); do
             if curl -kf -s -o /dev/null -u testuser:testpass \
               https://localhost/tagbase/api/v0.14.0/tags ; then
               break
@@ -172,5 +164,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
       - name: Run observability smoke
         run: ./scripts/observability-smoke.sh

.github/workflows/super-linter.yml

@@ -0,0 +1,28 @@
+name: Super Linter
+
+on: [push, pull_request]
+
+permissions: {}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      statuses: write
+      packages: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Load Super Linter configuration
+        run: grep -v '^#' .github/super-linter.env >> "$GITHUB_ENV"
+
+      - name: Super-linter
+        uses: super-linter/super-linter@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.htmlhintrc

@@ -0,0 +1,8 @@
+{
+  "doctype-first": true,
+  "title-require": false,
+  "attr-lowercase": true,
+  "tag-pair": true,
+  "space-tab-mixed-disabled": "space",
+  "id-unique": true
+}

.jscpd.json

@@ -0,0 +1,12 @@
+{
+  "threshold": 25,
+  "reporters": ["consoleFull"],
+  "ignore": [
+    "**/__snapshots__/**",
+    "**/node_modules/**",
+    "**/.tox/**",
+    "**/openapi.yaml",
+    "**/docker-compose.test.yml"
+  ],
+  "absolute": true
+}

.markdown-lint.yml

@@ -0,0 +1,13 @@
+---
+# Markdownlint rules tuned for README + agent docs.
+MD013:
+  line_length: 1000
+  code_blocks: false
+  tables: false
+MD009: false
+MD022: false
+MD031: false
+MD032: false
+MD033: false
+MD041: false
+MD047: false

.mypy.ini

@@ -0,0 +1,11 @@
+[mypy]
+python_version = 3.10
+ignore_missing_imports = True
+ignore_errors = True
+warn_unused_ignores = False
+pretty = True
+exclude = (?x)(
+    ^services/
+    | ^tagbase_server/\.tox/
+    | /test/
+  )

.pre-commit-config.yaml

@@ -1,20 +1,6 @@
 repos:
-  - repo: https://github.com/psf/black
-    rev: 26.5.1
-    hooks:
-      - id: black
-        language_version: python3
   - repo: https://github.com/AleksaC/hadolint-py
     rev: v2.14.0
     hooks:
       - id: hadolint
         args: ["--config", ".hadolint.yaml"]
-  - repo: local
-    hooks:
-      - id: pytest-diff-cover
-        name: Coverage on changed lines (≥80%)
-        entry: scripts/check-diff-coverage.sh
-        language: system
-        pass_filenames: false
-        files: ^tagbase_server/tagbase_server/.*\.py$
-        exclude: ^tagbase_server/tagbase_server/test/

.ruff.toml

@@ -0,0 +1,15 @@
+line-length = 120
+exclude = [".tox", ".git", "__pycache__", "tagbase_server/.tox"]
+
+[lint]
+# I = isort-compatible import sorting (replaces PYTHON_ISORT).
+extend-select = ["I"]
+ignore = ["E501", "E721"]
+
+[lint.per-file-ignores]
+"tagbase_server/tagbase_server/models/*" = ["F401", "F811"]
+"tagbase_server/tagbase_server/utils/__init__.py" = ["F401", "F403"]
+"tagbase_server/tagbase_server/util.py" = ["F401", "E721"]
+
+[lint.isort]
+known-first-party = ["tagbase_server"]

.shellcheckrc

@@ -0,0 +1,2 @@
+# ShellCheck config for Super Linter
+disable=SC2034

.sqlfluff

@@ -0,0 +1,20 @@
+[sqlfluff]
+dialect = postgres
+templater = raw
+max_line_length = 120
+# RF04: view output columns intentionally use names like `variable` / `depth`
+# LT02: CREATE MATERIALIZED VIEW … AS SELECT indent rules fight WITH/JOIN layout
+# L031/L034/L044: alias/join-key style noise on analytical views
+exclude_rules = RF04,LT02,L031,L034,L044
+
+[sqlfluff:indentation]
+tab_space_size = 2
+
+[sqlfluff:rules:capitalisation.keywords]
+capitalisation_policy = upper
+
+[sqlfluff:rules:capitalisation.identifiers]
+extended_capitalisation_policy = lower
+
+[sqlfluff:rules:capitalisation.functions]
+extended_capitalisation_policy = lower

.yaml-lint.yml

@@ -0,0 +1,17 @@
+---
+extends: default
+rules:
+  document-start: disable
+  line-length:
+    max: 300
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+  indentation: disable
+  comments: disable
+  comments-indentation: disable
+  truthy: disable
+  new-line-at-end-of-file: enable

AGENTS.md

@@ -12,7 +12,7 @@ Default mattpocock triage vocabulary (`needs-triage`, `needs-info`, `ready-for-a
 
 ### Domain docs
 
-Single-context layout (`CONTEXT.md` + `docs/adr/` at repo root). See `docs/agents/domain.md`.
+Single-context layout (`CONTEXT.md` + `docs/adr/` at repository root). See `docs/agents/domain.md`.
 
 ### Ingest