dbml-sharepoint 0.4.0__tar.gz

dbml_sharepoint-0.4.0/.coderabbit.yaml

@@ -0,0 +1,20 @@
+# CodeRabbit configuration.
+#
+# The whole point of this file is the one setting below. `base_branches`
+# defaults to an empty list, which means CodeRabbit reviews only pull requests
+# targeting the DEFAULT branch -- and `AGENTS.md` prescribes stacking for any
+# change too large to review in one pass, so every PR above the bottom of a
+# stack targets another feature branch and was silently never reviewed.
+#
+# Measured 2026-08-10 across a four-deep stack: the bottom PR got its automatic
+# pass, and the three above it got nothing at all. Nobody noticed, because a
+# review that never runs looks exactly like a review that found nothing.
+#
+# `.*` matches every base branch. Documented at
+# https://docs.coderabbit.ai/reference/yaml-template -- "Base branches (other
+# than the default branch) to review. Accepts regex patterns. Use '.*' to match
+# all branches."
+reviews:
+  auto_review:
+    base_branches:
+      - ".*"

dbml_sharepoint-0.4.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.gif binary

dbml_sharepoint-0.4.0/.github/copilot-instructions.md

@@ -0,0 +1,24 @@
+# Copilot instructions
+
+**Read [`AGENTS.md`](../AGENTS.md) at the repository root.** It is the canonical
+instruction file for all coding agents here, and it is kept current; this file is
+a pointer so that Copilot picks the same instructions up. Do not duplicate its
+contents here. A second copy drifts.
+
+The points that matter most when reviewing a pull request in this repository:
+
+- **Never accept an assertion about SharePoint behaviour that is not backed by a
+  Microsoft Learn citation or a live probe under `test/manual/`.** This project
+  exists to close the failure class where a rule saves, reads back
+  byte-identical, passes every deploy phase, and does nothing on the rendered
+  page. Plausibility is not evidence. Flag any new claim about platform
+  behaviour that cites neither.
+- **Commit messages must be conventional** (`feat:`, `fix:`, `docs:`, ...).
+  `release-please` builds the changelog by parsing them, so a non-conventional
+  commit is silently omitted from the release notes.
+- **A generator must never import from `analysis/checks/`.** Shared facts belong
+  in a module both sides import; `analysis/joins.py` is the worked example.
+- **Anything that writes must read back and verify**, and anything uncertain must
+  fail closed with a named error.
+- Generated files under `website/docs/api/` are committed. Line-ending-only
+  churn there is a known artifact of the generator on Windows, not a real change.

dbml_sharepoint-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,212 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Sync dependencies
+        run: uv sync
+      - name: Lint
+        run: uv run ruff check src test website/scripts scripts
+      - name: Jinja lint (j2lint; indentation/single-line rules are house-style exceptions)
+        run: uv run j2lint --ignore jinja-statements-indentation single-statement-per-line -- src/dbml_sharepoint/templates
+      - name: Type-check
+        run: uv run mypy
+      - name: Tests
+        # Two flags only; everything else is configured in pyproject.toml, so
+        # a local run and this one measure the same thing.
+        #
+        # `--cov` is off by default locally because it roughly doubles the
+        # suite. `--check-finding-reachability` is off by default because it is
+        # only meaningful over a WHOLE run -- on `pytest test/test_joins.py` it
+        # would report almost every rule unreached, which is noise, not a
+        # finding. The two are not redundant: coverage is an aggregate floor
+        # and cannot see one rule stop firing (measured -- deleting the only
+        # test that fires `display_title_too_long` leaves coverage at 95.21%,
+        # over the floor, while the reachability gate names the rule).
+        run: uv run pytest --cov --check-finding-reachability
+      - name: Build both examples end-to-end
+        run: |
+          uv run dbml-sharepoint build --schema examples/minimal/schema.dbml --mapping examples/minimal/mapping.yaml --release examples/minimal/release.yaml --site-url https://example.sharepoint.com/sites/ci --site-role default --out examples/minimal/build
+          uv run dbml-sharepoint build --schema examples/project-tracker/schema.dbml --mapping examples/project-tracker/mapping.yaml --release examples/project-tracker/release.yaml --site-url https://example.sharepoint.com/sites/ci --site-role default --out examples/project-tracker/build
+      - name: Syntax-check the generated scripts
+        shell: bash
+        # `node --check <file>` cannot read these: the scripts ship as
+        # `.js.txt` so an operator can open them instead of Windows Script
+        # Host executing them, and node refuses an unknown extension with
+        # ERR_UNKNOWN_FILE_EXTENSION before it ever parses the file. Feed
+        # them on stdin and name the dialect instead -- same parse, same
+        # non-zero exit on a syntax error, no dependence on the filename.
+        run: |
+          set -euo pipefail
+          found=0
+          for f in examples/minimal/build/*.js.txt \
+                   examples/project-tracker/build/*.js.txt; do
+            node --check --input-type=commonjs < "$f"
+            found=$((found + 1))
+          done
+          echo "Syntax-checked $found script(s)."
+          # A glob that matches nothing would otherwise pass silently --
+          # which is precisely how a rename like this ships broken.
+          test "$found" -gt 0
+      - name: Generate reporting queries end-to-end
+        run: uv run dbml-sharepoint report --schema examples/project-tracker/schema.dbml --mapping examples/project-tracker/mapping.yaml --release examples/project-tracker/release.yaml --site-role default --out examples/project-tracker/reports
+      - name: Build every solution template end-to-end
+        shell: bash
+        # Discovered, never listed. A hardcoded roster fails open: a new
+        # template is simply never built, and CI stays green saying so.
+        run: |
+          set -euo pipefail
+          # The solution templates live inside the package so the wizard can
+          # offer them to somebody who never cloned this repository.
+          sol=src/dbml_sharepoint/solutions
+          found=0
+          for schema in "$sol"/*/10-design/schema.dbml; do
+            t="$(basename "$(dirname "$(dirname "$schema")")")"
+            found=$((found + 1))
+            echo "::group::$t"
+            # Build OUTSIDE the package. In-place output would write into the
+            # installable tree, where a stray build/ directory can be picked
+            # up by the wheel.
+            uv run dbml-sharepoint build \
+              --schema "$schema" \
+              --mapping "$sol/$t/20-configure/mapping.yaml" \
+              --release "$sol/$t/20-configure/release.yaml" \
+              --site-url https://example.sharepoint.com/sites/ci \
+              --site-role default \
+              --out "build/$t"
+            echo "::endgroup::"
+          done
+          echo "Built $found template(s)."
+          # A glob that matches nothing would otherwise pass silently.
+          test "$found" -gt 0
+      - name: Build every seeded bundle (discovered, never listed)
+        shell: bash
+        # A hardcoded roster fails open: a new demo_items consumer is simply
+        # never seeded, and CI stays green saying so.
+        run: |
+          set -euo pipefail
+          # The library's own size, counted the same way the build step
+          # above counts it, so neither side of the assertion below is a
+          # number somebody has to remember to update.
+          sol=src/dbml_sharepoint/solutions
+          expected=0
+          for schema in "$sol"/*/10-design/schema.dbml; do
+            expected=$((expected + 1))
+          done
+          found=0
+          for mapping in "$sol"/*/20-configure/mapping.yaml; do
+            grep -q '^demo_items:' "$mapping" || continue
+            t="$(basename "$(dirname "$(dirname "$mapping")")")"
+            found=$((found + 1))
+            echo "::group::$t"
+            uv run dbml-sharepoint build \
+              --schema "$sol/$t/10-design/schema.dbml" \
+              --mapping "$mapping" \
+              --release "$sol/$t/20-configure/release.yaml" \
+              --site-url https://example.sharepoint.com/sites/ci \
+              --site-role default \
+              --seed \
+              --out "build/$t-seed"
+            node --check --input-type=commonjs < "build/$t-seed/demo-data.js.txt"
+            echo "::endgroup::"
+          done
+          echo "Seeded $found of $expected template(s)."
+          # Every template ships demo_items. It is part of the family
+          # standard, not a feature some of them happen to use, so the
+          # honest assertion is equality, not a floor. A floor written when
+          # two templates seeded stays green while twenty-seven stop, which
+          # is the same open failure a hardcoded roster gives you, spelled
+          # as a number instead of a list.
+          test "$found" -eq "$expected"
+
+  mutate-limits:
+    # A ceiling nothing enforces moves without any test noticing, which is what
+    # the #259 sweep measured over the whole module. This runs the same
+    # experiment on whichever ceilings the branch touches, so it costs nothing
+    # on a pull request that leaves limits.py alone.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    # Two full suites per ceiling, so a pull request touching all fourteen
+    # declarations runs twenty-eight of them. Bounded rather than left on the
+    # six-hour default, since a hung suite would otherwise hold a runner.
+    timeout-minutes: 60
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # The script diffs against the merge base, which does not exist in a
+          # shallow clone.
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Sync dependencies
+        run: uv sync
+      - name: Mutate every ceiling this pull request changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: uv run python scripts/mutate_limits.py --base-ref "$BASE_SHA"
+
+  markdown:
+    # Style of the hand-written markdown -- the whole tree, not just
+    # website/, since the solution templates ship READMEs and guides that an
+    # adopter reads. Scope, exclusions and rule configuration all live in
+    # .markdownlint-cli2.yaml, shared with the prek hook.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - name: Lint markdown (markdownlint-cli2)
+        # The version here and the `rev:` of the markdownlint-cli2 hook in
+        # .pre-commit-config.yaml are the same number written twice, because
+        # this is a node tool and cannot be pinned by pyproject.toml the way
+        # ruff/mypy/j2lint are. test/test_markdownlint_version.py fails if
+        # they drift, so the hook can still never disagree with CI.
+        #
+        # The repo-wide glob is passed here rather than set as `globs:` in the
+        # config, because markdownlint-cli2 APPENDS config globs to
+        # command-line ones -- putting it there would make the pre-commit hook
+        # lint all 162 files on every commit instead of the ones staged.
+        run: npx --yes markdownlint-cli2@0.23.2 "**/*.md"
+
+  docs:
+    # onBrokenLinks/onBrokenMarkdownLinks are 'throw', so this build is
+    # the cross-link integrity gate for the whole docs site.
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - name: Build docs site
+        working-directory: website
+        run: |
+          npm ci
+          npm run build

dbml_sharepoint-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+# Docs site deploy (GitHub Pages). Manual by design: run it when the
+# docs are worth republishing (workflow_dispatch), not on every push.
+# The API reference pages under website/docs/api/ are generated and
+# COMMITTED (deterministic; drift shows as a git diff), so the build
+# here needs Node only.
+name: Docs
+
+on:
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+      - name: Build site
+        working-directory: website
+        run: |
+          npm ci
+          npm run build
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: website/build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

dbml_sharepoint-0.4.0/.github/workflows/pr-title.yml

@@ -0,0 +1,64 @@
+# The PR title becomes the commit subject on `main`, because this repository
+# squash-merges and `squash_merge_commit_title` is set to PR_TITLE. release-please
+# builds the changelog by parsing those subjects, so a non-conventional title is
+# silently dropped from the release notes. The release still happens and only the
+# notes are wrong. That failure cost four PRs in 0.4.0 (#41, #42, #45, #51) and had
+# to be back-filled by hand in #57.
+#
+# Enforcing the title is sufficient *only* under squash merging. If merge commits
+# are ever re-enabled, the branch commits reach `main` instead and this check stops
+# covering anything, so enforce per-commit then (`cz check --rev-range`).
+name: PR title
+
+on:
+  pull_request:
+    # `edited` matters: a title fixed after the fact must re-run the check.
+    types: [opened, edited, reopened, synchronize]
+
+permissions: {}
+
+jobs:
+  conventional:
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - name: Check the title is a conventional commit
+        env:
+          # Passed as an environment variable, never interpolated into the script.
+          # `${{ }}` inside a run block is a template-injection sink: a PR title is
+          # attacker-controlled text, and zizmor fails the build on that pattern.
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+
+          types='build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test'
+          pattern="^(${types})(\([a-z0-9._/-]+\))?!?: .+"
+
+          if printf '%s' "$TITLE" | grep -Eq "$pattern"; then
+            printf 'OK: %s\n' "$TITLE"
+            exit 0
+          fi
+
+          cat >&2 <<EOF
+          The pull request title is not a conventional commit.
+
+            title: $TITLE
+
+          This repository squash-merges, so the title becomes the commit subject on
+          main, and release-please builds the changelog by parsing it. A title that
+          does not match is dropped from the release notes silently.
+
+          Expected:  type(optional-scope)!: subject
+          Types:     ${types//|/, }
+
+          Examples:
+            feat: refuse a view that performs more joins than SPO serves
+            fix(deploy): a URL column aborted the paste it appeared in
+            docs: cross-reference hide_from_all_items from the views section
+            feat!: refuse any base_template but the generic list
+
+          Note the changelog has no Tests section, so a 'test:' title is invisible in
+          release notes. Pick the type from what the change does, not from which
+          directory it touches.
+          EOF
+          exit 1

dbml_sharepoint-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+# Release + publish pipeline. The PyPI trusted publisher is bound to THIS
+# workflow filename (publish.yml) and the `pypi` environment, so the publish
+# job must live here.
+#
+# Flow: conventional commits land on main -> release-please maintains a
+# release PR -> merging it makes release-please (in that push's run) create
+# the vX.Y.Z tag + GitHub release and set release_created=true -> the build
+# and publish jobs run in the SAME workflow run. They must: releases created
+# with the default GITHUB_TOKEN cannot trigger other workflows, so a separate
+# on:release publish workflow would never fire.
+#
+# First-release bootstrap (v0.1.0): the manifest already records 0.1.0, so
+# release-please only manages releases AFTER it. Create the first tag and
+# release by hand, then publish that build with a manual dispatch:
+#   gh release create v0.1.0 --title v0.1.0 --notes "Initial release"
+#   gh workflow run publish.yml
+name: Publish
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write        # create the release tag + GitHub release
+      pull-requests: write   # maintain the release PR
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name || github.ref }}
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false  # release artifacts are never built from a cache
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: [release-please, build]
+    if: needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/dbml-sharepoint/
+    permissions:
+      id-token: write  # OIDC trusted publishing; no API token anywhere
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

dbml_sharepoint-0.4.0/.github/workflows/zizmor.yml

@@ -0,0 +1,26 @@
+# Static security audit of the workflows themselves (zizmor). Fails the run
+# on any finding: unpinned actions, excessive permissions, credential
+# persistence, template injection, cache poisoning in release paths, etc.
+name: Workflow security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Audit workflows
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uvx zizmor .github/workflows

dbml_sharepoint-0.4.0/.gitignore

@@ -0,0 +1,77 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# Example / template build output
+examples/**/build/
+examples/**/reports/
+src/dbml_sharepoint/solutions/**/build/
+src/dbml_sharepoint/solutions/**/reports/
+
+# A consumer's build defaults, which can carry their tenant's
+# enterprise-reader UPN. Not ours to commit.
+dbml-sharepoint.env
+
+# Generated fixture data for the threshold index probe.
+test/manual/rows/
+
+# Probe run transcripts. A probe is pasted into a LIVE tenant, so its console
+# output carries the site URL, the operator's UPN and real item ids. Keep them
+# on disk, quote findings into code comments, never commit the raw output.
+# test_probes.py::test_no_tracked_file_under_manual_names_a_tenant enforces the
+# same rule against anything that gets past this.
+#
+# The whole directory's .txt, not a `transcript-*` prefix: an operator names the
+# file after the run, not after the ignore rule. No .txt here is tracked.
+test/manual/*.txt
+
+# Captured network traffic, which is a different order of hazard from a console
+# transcript. A HAR records REQUEST HEADERS: the auth cookie and bearer token
+# for a live tenant, plus every URL and response body. Committing one hands over
+# a working session, not just a site name. Nothing here is ever tracked, and
+# these should be deleted once whatever they were captured for is answered.
+test/manual/*.har
+test/manual/*.log
+test/manual/*.json
+!test/manual/probe-catalog.json
+test/manual/captures/
+
+# Manual extraction runs. extract.js.txt is pasted into a LIVE tenant, so the
+# browser log and the JSON it downloads carry the site URL and the operator's
+# UPN. The script itself is a local build artifact (extract-script writes it
+# by default). Zone.Identifier is the Windows mark a browser leaves on every
+# download; WSL materialises it as `<file>:Zone.Identifier`, and git's `*`
+# will not cross the colon, so the colon is in the pattern. Nothing here is
+# tracked.
+extract.js.txt
+*:Zone.Identifier
+human-run/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local process artifacts: specs and plans from the superpowers workflow.
+# Deliberately untracked: they are working notes, not part of the shipped
+# repository, and they dominated PR diffs (9,062 lines across 8 files).
+# Kept on disk so the reasoning survives; `git clean -x` WOULD delete them.
+docs/superpowers/
+
+# Worktrees created for parallel agent work.
+.claude/worktrees/
+
+# Hypothesis example database (machine-local; not shared).
+.hypothesis/
+
+# Pickles are never source. A stray empty sites.pkl was once committed by accident.
+*.pkl

dbml_sharepoint-0.4.0/.markdownlint-cli2.yaml

@@ -0,0 +1,94 @@
+# markdownlint-cli2 configuration. Read by the `markdownlint-cli2` prek hook
+# in .pre-commit-config.yaml and by the `markdown` job in
+# .github/workflows/ci.yml, so both sides lint exactly the same files under
+# exactly the same rules.
+
+# The ruleset is markdownlint's default, unmodified. Disabling a rule needs a
+# reason written here; "it fires a lot" is not one. What each rule means:
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# There is deliberately no `globs:` key here. markdownlint-cli2 APPENDS the
+# config's globs to any given on the command line rather than replacing them
+# (measured on v0.23.2: passing one filename still reported "Linting: 162
+# files"), so a `globs: ["**/*.md"]` here would make the prek hook lint the
+# whole repository on every commit that touches any markdown at all.
+
+# The repo-wide glob lives in the CI invocation instead; the hook keeps
+# pre-commit's normal changed-files-only behaviour. `ignores` below applies to
+# both, because command-line filenames are themselves treated as globs.
+
+# Honour .gitignore. Build output is the reason: `examples/**/build/`,
+# `src/dbml_sharepoint/solutions/**/build/` and the docs site's own
+# `website/build/` all contain emitted markdown (index.md, deploy-manifest.md,
+# assess-manifest.md, data-dictionary.md...) that exists only in a working
+# tree. Without this, a developer who has run a build lints different files
+# from CI, which is the worst kind of lint config.
+gitignore: true
+
+ignores:
+  # node_modules is gitignored under website/, but a stray install anywhere
+  # else would otherwise pull in every dependency's README.
+  - "**/node_modules/**"
+
+  # GENERATED AND COMMITTED, excluded because a violation here cannot be
+  # fixed in the file. The file is overwritten wholesale by its generator on
+  # the next run, so the only real fix is in the generator's Python, and a
+  # lint error pointing at the artefact sends the reader to the wrong place.
+  # A currency test already fails if either page drifts from its source.
+
+  # Written by website/scripts/generate_api.py (`write_page`), which emits the
+  # whole tree: index.md, templates.md, conditions.md and python/**.
+  - "website/docs/api/**"
+
+  # Written by website/scripts/generate_findings.py, which renders the
+  # FindingCode catalogue and analysis/finding_help.py into one page. The page
+  # itself carries a "Do not edit by hand" banner.
+  - "website/docs/reference/findings.md"
+
+config:
+  # MD013 (line-length) is KEPT ON, deliberately. The obvious reason to turn
+  # it off does not apply here: this repository's committed markdown is hard
+  # wrapped, 698 of 19,547 non-generated lines exceed 80 columns, so the
+  # convention is real and the exceptions are exceptions.
+
+  # Its sub-options were left at their defaults until an inventory existed, so
+  # what follows is a decision made on numbers rather than a rule narrowed
+  # before anyone had seen what it reports. MEASURED over the whole tree,
+  # 2026-08-14, once the mechanical rules were fixed: 490 findings, of which
+  # 452 were a table row, 21 prose, 16 a line inside a fenced code block, and
+  # 1 a heading.
+
+  # TABLES ARE OFF, and that is a syntax constraint rather than a preference.
+  # A GFM table row must occupy exactly one line and there is no continuation,
+  # so a long row cannot be wrapped at all and the only way to satisfy the
+  # rule is to delete words from a cell. That is information loss dressed up
+  # as formatting, across 452 rows of documentation an adopter reads.
+
+  # CODE BLOCKS ARE OFF for the same reason one step removed. A fenced line is
+  # content the reader copies and runs. Wrapping it either changes what they
+  # run or adds continuation backslashes that change what they see, and the
+  # longest offenders are the commands AGENTS.md tells people to paste.
+
+  # Both meet the test this file already applies to its `ignores` list: a
+  # violation that cannot be fixed in the file. Headings stay ON, because the
+  # one over-long heading is a real finding. That leaves 22 findings genuinely
+  # about prose being too wide, which is what the rule was kept on to catch.
+  MD013:
+    tables: false
+    code_blocks: false
+
+  # MD025 counts a Docusaurus front matter `title:` as a top-level heading, so
+  # a page carrying both that and a body `# Heading` reads as having two. This
+  # tells it to count real headings only.
+
+  # MEASURED across website/docs, 2026-08-14, excluding the generated api
+  # tree: 23 pages carry a front matter title, all 23 also carry a body H1,
+  # and none carries a front matter title alone. The pairing is the site's
+  # universal convention rather than drift on a few pages.
+
+  # Deleting the 22 body headings the rule flagged was rejected on that
+  # evidence. Docusaurus uses the front matter title for the sidebar, the
+  # browser tab and search; it does not inject a heading into the page body.
+  # Removing the body H1 would leave those pages with no visible heading.
+  MD025:
+    front_matter_title: ""