dagwick 0.1.0__tar.gz

dagwick-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dev/airflow_home/
+ui/node_modules/
+ui/dist/
+.DS_Store
+.env
+*.pem
+*.key
+dev/*.log
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/

dagwick-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+
+### Added
+
+- **Dagwick tab** on every DAG page: a score from 0 to 100, a grade from A to F,
+  a lantern mascot, the next step to the next grade, the affected tasks, and a
+  fix with a copyable code example for every check that does not pass.
+- **Fleet page** in the Airflow sidebar: every DAG the user can read, ranked by
+  score, with grade filters, search, sort, and the most common issues.
+- 14 built-in checks covering reliability, observability, scheduling,
+  ownership and structure.
+- `dagwick.checks` entry point so other packages can add or override checks.
+- Scores reuse Airflow's own permission checks and are cached per DAG version.

dagwick-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Dagwick Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dagwick-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: dagwick
+Version: 0.1.0
+Summary: The wick that keeps your DAGs lit: DAG quality scores, a fleet view, and fixes you can act on, inside the Airflow 3 UI.
+Project-URL: Homepage, https://github.com/ardalan-jalal/dagwick
+Project-URL: Repository, https://github.com/ardalan-jalal/dagwick
+Project-URL: Issues, https://github.com/ardalan-jalal/dagwick/issues
+Project-URL: Changelog, https://github.com/ardalan-jalal/dagwick/blob/main/CHANGELOG.md
+Author: The Dagwick Authors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: airflow,airflow-plugin,apache-airflow,dag,data-quality,linting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Plugins
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Apache Airflow
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Dagwick
+
+![Dagwick: grade your Airflow DAGs from A to F, right inside the Airflow UI](https://raw.githubusercontent.com/ardalan-jalal/dagwick/main/docs/banner.png)
+
+## Setup
+
+**1. Install** it where Airflow runs:
+
+```bash
+pip install dagwick
+```
+
+Using Docker? Add `dagwick` to your Airflow image's `requirements.txt`.
+
+**2. Restart** the Airflow api-server.
+
+**3. Open Airflow.** You now have:
+
+- a **Dagwick** tab on every DAG page, and
+- a **Dagwick** page in the sidebar that grades all your DAGs.
+
+That's it. There is nothing to configure.
+
+![The Dagwick tab on a DAG](https://raw.githubusercontent.com/ardalan-jalal/dagwick/main/docs/screenshots/dag-tab.png)
+
+![The Dagwick fleet page](https://raw.githubusercontent.com/ardalan-jalal/dagwick/main/docs/screenshots/fleet.png)
+
+## Requirements
+
+- Apache Airflow 3.1 or newer
+- Python 3.10 – 3.15
+
+Dagwick has no dependencies of its own, so installing it never changes your
+other packages. It is read-only and only shows each user the DAGs they can
+already see.
+
+## Remove
+
+```bash
+pip uninstall dagwick
+```
+
+Then restart the api-server.
+
+## More
+
+- [What it checks, and how to add your own checks](https://github.com/ardalan-jalal/dagwick/blob/main/docs/checks.md)
+- [Security](https://github.com/ardalan-jalal/dagwick/blob/main/SECURITY.md) · [Contributing](https://github.com/ardalan-jalal/dagwick/blob/main/CONTRIBUTING.md) · [Changelog](https://github.com/ardalan-jalal/dagwick/blob/main/CHANGELOG.md)
+- License: [MIT](https://github.com/ardalan-jalal/dagwick/blob/main/LICENSE)

dagwick-0.1.0/README.md

@@ -0,0 +1,49 @@
+# Dagwick
+
+![Dagwick: grade your Airflow DAGs from A to F, right inside the Airflow UI](https://raw.githubusercontent.com/ardalan-jalal/dagwick/main/docs/banner.png)
+
+## Setup
+
+**1. Install** it where Airflow runs:
+
+```bash
+pip install dagwick
+```
+
+Using Docker? Add `dagwick` to your Airflow image's `requirements.txt`.
+
+**2. Restart** the Airflow api-server.
+
+**3. Open Airflow.** You now have:
+
+- a **Dagwick** tab on every DAG page, and
+- a **Dagwick** page in the sidebar that grades all your DAGs.
+
+That's it. There is nothing to configure.
+
+![The Dagwick tab on a DAG](https://raw.githubusercontent.com/ardalan-jalal/dagwick/main/docs/screenshots/dag-tab.png)
+
+![The Dagwick fleet page](https://raw.githubusercontent.com/ardalan-jalal/dagwick/main/docs/screenshots/fleet.png)
+
+## Requirements
+
+- Apache Airflow 3.1 or newer
+- Python 3.10 – 3.15
+
+Dagwick has no dependencies of its own, so installing it never changes your
+other packages. It is read-only and only shows each user the DAGs they can
+already see.
+
+## Remove
+
+```bash
+pip uninstall dagwick
+```
+
+Then restart the api-server.
+
+## More
+
+- [What it checks, and how to add your own checks](https://github.com/ardalan-jalal/dagwick/blob/main/docs/checks.md)
+- [Security](https://github.com/ardalan-jalal/dagwick/blob/main/SECURITY.md) · [Contributing](https://github.com/ardalan-jalal/dagwick/blob/main/CONTRIBUTING.md) · [Changelog](https://github.com/ardalan-jalal/dagwick/blob/main/CHANGELOG.md)
+- License: [MIT](https://github.com/ardalan-jalal/dagwick/blob/main/LICENSE)

dagwick-0.1.0/SECURITY.md

@@ -0,0 +1,37 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not open a public issue** for security problems. Report them
+privately through GitHub: open this repository's **Security** tab and choose
+**Report a vulnerability**.
+
+We aim to acknowledge reports within 3 working days and will keep you updated
+until a fix is released.
+
+## Supported versions
+
+Only the latest released minor version receives security fixes.
+
+## Security design
+
+Dagwick runs inside the Airflow api-server. It is designed to add no new attack
+surface beyond what Airflow already exposes:
+
+- **Same permissions as Airflow.** Every endpoint uses Airflow's own security
+  dependencies (`requires_access_dag`, `get_authorized_dag_ids`). A user only
+  sees scores for DAGs they can already read in the Airflow UI.
+- **Read-only.** Dagwick reads serialized DAGs from the metadata database. It
+  never writes to the database, never executes DAG code, and never makes network
+  calls.
+- **No configuration and no secrets.** Dagwick reads no environment variables,
+  Airflow Variables, Connections or credentials.
+- **Safe errors.** Error responses contain only a generic message and a
+  reference id. Details go to the server log, never to the browser.
+- **Same origin only.** No CORS headers are added.
+- **Static files from an allowlist.** The static route never builds file paths
+  from user input.
+- **No third-party code in the browser.** The UI bundle uses the React that
+  Airflow already provides. It loads nothing from a CDN, uses no
+  `innerHTML`, and stores nothing in `localStorage`.
+- **No runtime dependencies.** The package declares no dependencies of its own.

dagwick-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "dagwick"
+dynamic = ["version"]
+description = "The wick that keeps your DAGs lit: DAG quality scores, a fleet view, and fixes you can act on, inside the Airflow 3 UI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "The Dagwick Authors" }]
+keywords = ["airflow", "apache-airflow", "airflow-plugin", "dag", "data-quality", "linting"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Plugins",
+  "Environment :: Web Environment",
+  "Framework :: Apache Airflow",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+# Intentionally empty: Dagwick runs inside an existing Airflow 3.1+ installation and
+# uses the Airflow (and FastAPI) that is already there. Installing it never pulls in,
+# upgrades or downgrades Airflow.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ardalan-jalal/dagwick"
+Repository = "https://github.com/ardalan-jalal/dagwick"
+Issues = "https://github.com/ardalan-jalal/dagwick/issues"
+Changelog = "https://github.com/ardalan-jalal/dagwick/blob/main/CHANGELOG.md"
+
+[project.entry-points."airflow.plugins"]
+dagwick = "dagwick.plugin:DagwickPlugin"
+
+# Development only (never published as a dependency): tests and the local sandbox.
+[dependency-groups]
+dev = [
+  "apache-airflow==3.3.2",
+  "pytest>=8",
+  "pytest-cov>=6",
+  "ruff>=0.14",
+]
+
+[tool.uv]
+# Resolve the dev lockfile (Airflow + test tools) for Python 3.11+ only, so it can
+# use current, patched versions (e.g. dnspython >= 2.9 needs 3.11). This does not
+# change the published package, which has no dependencies and supports 3.10.
+environments = ["python_version >= '3.11'"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/dagwick/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dagwick"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/dagwick",
+  "ui/src",
+  "ui/package.json",
+  "ui/package-lock.json",
+  "ui/tsconfig.json",
+  "ui/vite.config.ts",
+  "tests",
+  "README.md",
+  "LICENSE",
+  "CHANGELOG.md",
+  "SECURITY.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=dagwick --cov-report=term-missing --cov-fail-under=70"
+
+[tool.coverage.run]
+branch = true
+source = ["dagwick"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]

dagwick-0.1.0/src/dagwick/__init__.py

@@ -0,0 +1,6 @@
+"""Dagwick: the wick that keeps your Airflow DAGs lit."""
+
+from dagwick.core import Category, Finding, Status, check, score_dag
+
+__version__ = "0.1.0"
+__all__ = ["Category", "Finding", "Status", "__version__", "check", "score_dag"]

dagwick-0.1.0/src/dagwick/api.py

@@ -0,0 +1,183 @@
+"""HTTP API served inside the Airflow api-server under ``/dagwick``."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import uuid
+from pathlib import Path
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI, HTTPException, Query
+from fastapi.responses import FileResponse, JSONResponse
+
+from dagwick import __version__
+from dagwick.core import registered_checks, score_dag
+
+log = logging.getLogger(__name__)
+STATIC_DIR = Path(__file__).parent / "static"
+FLEET_LIMIT = 2000
+
+
+def _require_dag_read() -> Any:
+    """Reuse Airflow's own DAG permission check (same rules as the REST API)."""
+    from airflow.api_fastapi.core_api.security import requires_access_dag
+
+    return Depends(requires_access_dag(method="GET"))
+
+
+def _require_login() -> Any:
+    from airflow.api_fastapi.core_api.security import requires_authenticated
+
+    return Depends(requires_authenticated())
+
+
+def _user() -> Any:
+    """Airflow's own user resolver: Bearer header, OAuth token, or the UI cookie."""
+    from airflow.api_fastapi.core_api.security import get_user
+
+    return Depends(get_user)
+
+
+class _ScoreCache:
+    """Scores keyed by (dag_id, dag_hash): a DAG is re-scored only when its code changes."""
+
+    def __init__(self, max_entries: int = 5000) -> None:
+        self._data: dict[str, tuple[str, dict[str, Any]]] = {}
+        self._lock = threading.Lock()
+        self._max = max_entries
+
+    def get(self, dag_id: str, dag_hash: str) -> dict[str, Any] | None:
+        with self._lock:
+            hit = self._data.get(dag_id)
+        return hit[1] if hit and hit[0] == dag_hash else None
+
+    def put(self, dag_id: str, dag_hash: str, report: dict[str, Any]) -> None:
+        with self._lock:
+            if dag_id not in self._data and len(self._data) >= self._max:
+                self._data.pop(next(iter(self._data)))
+            self._data[dag_id] = (dag_hash, report)
+
+
+_cache = _ScoreCache()
+
+
+def _score_by_id(dag_id: str) -> dict[str, Any] | None:
+    from airflow.models.serialized_dag import SerializedDagModel
+
+    sdm = SerializedDagModel.get(dag_id)
+    if sdm is None:
+        return None
+    cached = _cache.get(dag_id, sdm.dag_hash)
+    if cached is not None:
+        return cached
+    report = score_dag(sdm.dag)
+    _cache.put(dag_id, sdm.dag_hash, report)
+    return report
+
+
+def _server_error(what: str, exc: BaseException) -> HTTPException:
+    ref = uuid.uuid4().hex[:12]
+    log.error("dagwick: %s (ref %s)", what, ref, exc_info=exc)
+    return HTTPException(status_code=500, detail=f"Something went wrong (ref {ref}).")
+
+
+app = FastAPI(title="Dagwick", version=__version__, docs_url=None, redoc_url=None, openapi_url=None)
+
+
+STATIC_FILES = {"dagwick.js": "application/javascript", "icon.svg": "image/svg+xml"}
+
+
+@app.get("/static/{name}", include_in_schema=False)
+def static(name: str) -> FileResponse:
+    media_type = STATIC_FILES.get(name)  # allowlist: never build paths from user input
+    if media_type is None:
+        raise HTTPException(status_code=404)
+    return FileResponse(
+        STATIC_DIR / name, media_type=media_type, headers={"Cache-Control": "no-cache"}
+    )
+
+
+@app.get("/api/score", dependencies=[_require_dag_read()])
+def score(dag_id: str = Query(..., min_length=1, max_length=250)) -> dict[str, Any]:
+    try:
+        report = _score_by_id(dag_id)
+    except Exception as exc:
+        raise _server_error(f"failed to score DAG {dag_id}", exc) from None
+    if report is None:
+        raise HTTPException(status_code=404, detail="DAG not found or not parsed yet.")
+    return report
+
+
+def fleet_entry(
+    dag_id: str, is_paused: bool, owners: str, report: dict[str, Any]
+) -> dict[str, Any]:
+    """Compact per-DAG summary for the fleet page; issues sorted worst first."""
+    issues = [
+        {
+            "id": c["id"],
+            "title": c["title"],
+            "status": c["status"],
+            "gain": round(c["weight"] - c["points"], 1),
+        }
+        for c in report["checks"]
+        if c["status"] in ("fail", "warn")
+    ]
+    issues.sort(key=lambda i: (i["status"] != "fail", -i["gain"]))
+    return {
+        "dag_id": dag_id,
+        "score": report["score"],
+        "grade": report["grade"],
+        "counts": report["counts"],
+        "is_paused": bool(is_paused),
+        "owners": owners or "",
+        "issues": issues,
+    }
+
+
+@app.get("/api/fleet")
+def fleet(user: Annotated[Any, _user()]) -> dict[str, Any]:
+    """Scores for every active DAG the current user may read."""
+    from airflow.api_fastapi.app import get_auth_manager
+    from airflow.models.dag import DagModel
+    from airflow.utils.session import create_session
+    from sqlalchemy import select
+
+    try:
+        allowed = get_auth_manager().get_authorized_dag_ids(user=user, method="GET")
+        with create_session() as session:
+            rows = session.execute(
+                select(DagModel.dag_id, DagModel.is_paused, DagModel.owners)
+                .where(DagModel.is_stale.is_(False), DagModel.dag_id.in_(allowed))
+                .order_by(DagModel.dag_id)
+                .limit(FLEET_LIMIT)
+            ).all()
+        dags = []
+        for dag_id, is_paused, owners in rows:
+            report = _score_by_id(dag_id)
+            if report is not None:
+                dags.append(fleet_entry(dag_id, is_paused, owners, report))
+    except Exception as exc:
+        raise _server_error("failed to build fleet view", exc) from None
+    return {"dags": dags, "truncated": len(rows) >= FLEET_LIMIT}
+
+
+@app.get("/api/checks", dependencies=[_require_login()])
+def checks() -> list[dict[str, Any]]:
+    return [
+        {
+            "id": c.id,
+            "title": c.title,
+            "category": c.category.value,
+            "weight": c.weight,
+            "fix": c.fix,
+        }
+        for c in registered_checks()
+    ]
+
+
+@app.exception_handler(Exception)
+async def _unhandled(_request: Any, exc: Exception) -> JSONResponse:
+    ref = uuid.uuid4().hex[:12]
+    log.error("dagwick: unhandled error (ref %s)", ref, exc_info=exc)
+    return JSONResponse(status_code=500, content={"detail": f"Internal error (ref {ref})."})

dagwick-0.1.0/src/dagwick/checks/__init__.py

@@ -0,0 +1,5 @@
+"""Built-in checks. Importing this package registers them."""
+
+from dagwick.checks import observability, ownership, reliability, scheduling, structure
+
+__all__ = ["observability", "ownership", "reliability", "scheduling", "structure"]

dagwick-0.1.0/src/dagwick/checks/_util.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from dagwick.core import Finding, Status
+
+
+def coverage(
+    dag: Any,
+    predicate: Callable[[Any], bool],
+    *,
+    noun: str,
+    all_msg: str,
+    none_msg: str,
+) -> Finding:
+    """PASS if every task matches, WARN if some do, FAIL if none do."""
+    tasks = list(dag.tasks)
+    if not tasks:
+        return Finding(Status.SKIP, "The DAG has no tasks.")
+    missing = tuple(sorted(t.task_id for t in tasks if not predicate(t)))
+    if not missing:
+        return Finding(Status.PASS, all_msg)
+    if len(missing) == len(tasks):
+        return Finding(Status.FAIL, none_msg)  # every task: listing them adds nothing
+    ok = len(tasks) - len(missing)
+    return Finding(Status.WARN, f"{ok} of {len(tasks)} tasks {noun}.", missing)
+
+
+def has_schedule(dag: Any) -> bool:
+    timetable = getattr(dag, "timetable", None)
+    return timetable is not None and type(timetable).__name__ != "NullTimetable"

dagwick-0.1.0/src/dagwick/checks/observability.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dagwick.checks._util import coverage
+from dagwick.core import Category, Finding, Status, check
+
+
+@check(
+    id="failure_alerts",
+    title="Someone hears about failures",
+    category=Category.OBSERVABILITY,
+    weight=15,
+    example='default_args={"on_failure_callback": send_slack_alert}',
+    fix="Add on_failure_callback (e.g. a Slack notifier) in default_args.",
+)
+def failure_alerts(dag: Any) -> Finding:
+    if getattr(dag, "has_on_failure_callback", False):
+        return Finding(Status.PASS, "The DAG has an on_failure_callback.")
+    return coverage(
+        dag,
+        lambda t: bool(getattr(t, "has_on_failure_callback", False)),
+        noun="alert on failure",
+        all_msg="Every task alerts on failure.",
+        none_msg="Nothing alerts on failure; it will fail silently.",
+    )
+
+
+@check(
+    id="retry_alerts",
+    title="Retries are visible",
+    category=Category.OBSERVABILITY,
+    weight=3,
+    example='default_args={"on_retry_callback": send_slack_alert}',
+    fix="Add on_retry_callback so flaky tasks surface before they start failing.",
+)
+def retry_alerts(dag: Any) -> Finding:
+    if any(getattr(t, "has_on_retry_callback", False) for t in dag.tasks):
+        return Finding(Status.PASS, "Retries send a notification.")
+    return Finding(Status.WARN, "Retries happen silently.")

dagwick-0.1.0/src/dagwick/checks/ownership.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from dagwick.core import Category, Finding, Status, check
+
+DEFAULT_OWNERS = {"", "airflow"}
+
+
+@check(
+    id="owner",
+    title="Has a real owner",
+    category=Category.OWNERSHIP,
+    weight=8,
+    example='default_args={"owner": "data-team"}',
+    fix="Set owner in default_args to the responsible team (e.g. 'data-team').",
+)
+def owner(dag: Any) -> Finding:
+    owners = {o.strip().lower() for o in (getattr(dag, "owner", "") or "").split(",")}
+    if owners - DEFAULT_OWNERS:
+        return Finding(Status.PASS, "An owner is set.")
+    return Finding(Status.FAIL, "Owner is the default 'airflow'; nobody is accountable.")
+
+
+@check(
+    id="tags",
+    title="Tagged",
+    category=Category.OWNERSHIP,
+    weight=5,
+    example='DAG(..., tags=["sales", "ingest"])',
+    fix="Add tags (domain, layer) so the DAG is easy to find and filter.",
+)
+def tags(dag: Any) -> Finding:
+    found = sorted(getattr(dag, "tags", None) or [])
+    if found:
+        return Finding(Status.PASS, f"Tags: {', '.join(found)}.")
+    return Finding(Status.FAIL, "No tags.")
+
+
+@check(
+    id="docs",
+    title="Documented",
+    category=Category.OWNERSHIP,
+    weight=8,
+    example="DAG(..., doc_md=__doc__)  # reuse the module docstring",
+    fix="Add doc_md explaining what the DAG loads, from where, and who to call.",
+)
+def docs(dag: Any) -> Finding:
+    if str(getattr(dag, "doc_md", None) or "").strip():
+        return Finding(Status.PASS, "doc_md is present.")
+    if str(getattr(dag, "description", None) or "").strip():
+        return Finding(Status.WARN, "Only a one-line description; no doc_md.")
+    return Finding(Status.FAIL, "No documentation.")