@shortlink-org/portolan 0.1.0

package/plugins/extract-celery/extract_test.py

@@ -0,0 +1,192 @@
+"""The reader, held to two fixtures.
+
+`testdata/billing` is a Django project with Celery in it, each shape this
+plugin claims to read present once; `testdata/drift` is the tree where every
+diagnostic the reader is meant to raise is raised once. `expected.json` beside
+each is what it comes out as. Set UPDATE_GOLDEN=1 to write them again after a
+deliberate change, and read the diff.
+"""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(1, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "pyplugin"))
+
+import main  # noqa: E402
+from extract import extract  # noqa: E402
+from options import Options  # noqa: E402
+from protocol import Builder, Input  # noqa: E402
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))
+
+
+def run(fixture, options):
+    b = Builder()
+    extract(
+        Input(root=os.path.relpath(os.path.join(HERE, "testdata", fixture), ROOT), commit="abc1234", generated_at="2026-09-05T00:00:00Z"),
+        Options.of(options),
+        b,
+        cwd=ROOT,
+    )
+    return {f.name: f.contents for f in b.files}, b.warnings
+
+
+def golden(test, fixture, contents):
+    path = os.path.join(HERE, "testdata", fixture, "expected.json")
+    if os.environ.get("UPDATE_GOLDEN"):
+        with open(path, "w", encoding="utf-8") as handle:
+            handle.write(contents)
+    with open(path, "r", encoding="utf-8") as handle:
+        test.assertEqual(json.loads(handle.read()), json.loads(contents))
+
+
+class Billing(unittest.TestCase):
+    def setUp(self):
+        self.files, self.warnings = run("billing", {"context": "shop", "service": "billing"})
+        self.fragment = json.loads(self.files["celery.json"])
+        self.service = self.fragment["contexts"][0]["services"][0]
+        self.channels = {c["address"]: c for c in self.service["channels"]}
+        self.flows = {f["slug"]: f for f in self.fragment["flows"]}
+
+    def test_the_fragment_it_reads(self):
+        golden(self, "billing", self.files["celery.json"])
+
+    def test_a_tree_where_everything_joins_reports_nothing(self):
+        self.assertEqual(self.warnings, [])
+
+    def test_a_queue_is_a_job_channel_with_a_send_and_a_receive_per_task(self):
+        self.assertEqual(sorted(self.channels), ["billing", "billing.mail", "billing.slow"])
+        mail = self.channels["billing.mail"]
+        self.assertEqual(mail["kind"], "job")
+        self.assertEqual([(m["name"], m["direction"]) for m in mail["messages"]], [("invoices.tasks.send_invoice_email", "send"), ("invoices.tasks.send_invoice_email", "receive")])
+        self.assertIn("over redis", mail["doc"])
+
+    def test_a_queue_is_decided_the_way_celery_decides_it(self):
+        receive = {c: [m for m in ch["messages"] if m["direction"] == "receive"][0]["doc"] for c, ch in self.channels.items()}
+        self.assertIn("routed by task_routes", receive["billing.mail"])
+        self.assertIn("named on the task", receive["billing.slow"])
+        self.assertIn("the default queue", receive["billing"])
+
+    def test_a_name_given_on_the_decorator_is_the_wire_name(self):
+        self.assertEqual(self.channels["billing"]["messages"][0]["name"], "billing.archive_invoice")
+
+    def test_an_enqueue_inside_on_commit_is_noted_and_a_countdown_too(self):
+        self.assertTrue(self.flows["billing-celery-send-invoice-email"]["steps"][0]["note"].startswith("Enqueued after the transaction commits."))
+        self.assertTrue(self.flows["billing-celery-remind-unpaid-invoice"]["steps"][0]["note"].startswith("Enqueued for later, with a countdown or an eta."))
+
+    def test_the_partial_form_and_the_module_import_resolve_to_the_task(self):
+        step = self.flows["billing-celery-archive-invoice"]["steps"][0]
+        self.assertTrue(step["line"].endswith("invoices/handlers.py:15"))
+        self.assertIn("Also enqueued at plugins/extract-celery/testdata/billing/invoices/services.py:23.", step["note"])
+
+    def test_the_clock_is_a_producer_and_opens_a_flow_of_its_own(self):
+        # Nothing in the code enqueues close_stale_drafts: add_periodic_task does.
+        flow = self.flows["billing-celery-close-stale-drafts"]
+        self.assertEqual([p["id"] for p in flow["participants"]], ["celery-beat", "shop.billing", "celery-billing"])
+        self.assertEqual([(s["from"], s["to"], s["label"]) for s in flow["steps"]], [("celery-beat", "celery-billing", "enqueue close_stale_drafts"), ("celery-billing", "shop.billing", "close_stale_drafts")])
+        self.assertEqual(flow["trigger"], {"kind": "scheduled", "label": "cron 0 3 * * *", "confidence": "high"})
+        self.assertTrue(flow["steps"][0]["line"].endswith("config/celery.py:22"))
+        self.assertTrue(flow["steps"][0]["note"].startswith("Scheduled cron 0 3 * * * (`close-stale-drafts`)."))
+        sent = [m for m in self.channels["billing"]["messages"] if m["name"] == "invoices.tasks.close_stale_drafts"]
+        self.assertEqual([m["direction"] for m in sent], ["send", "receive"])
+        self.assertTrue(sent[0]["doc"].startswith("Sent by Celery beat, cron 0 3 * * * (`close-stale-drafts`)."))
+        self.assertNotIn("Nothing in this tree enqueues it.", sent[1]["doc"])
+
+    def test_a_task_the_code_and_the_clock_both_enqueue_has_two_flows(self):
+        self.assertIn("billing-celery-remind-unpaid-invoice", self.flows)
+        beat = self.flows["billing-celery-remind-unpaid-invoice-beat"]
+        self.assertEqual(beat["trigger"]["label"], "every 6h")
+        self.assertEqual(beat["steps"][1]["handoff"], self.flows["billing-celery-remind-unpaid-invoice"]["steps"][1]["handoff"])
+
+    def test_the_settings_entries_are_read_too(self):
+        archive = self.flows["billing-celery-archive-invoice-beat"]
+        self.assertEqual(archive["participants"][2]["id"], "celery-billing")
+        self.assertEqual(archive["trigger"]["label"], "cron 30 2 * * *")
+        self.assertTrue(archive["source"].endswith("config/settings.py"))
+
+    def test_a_flow_goes_out_to_the_broker_and_comes_back(self):
+        flow = self.flows["billing-celery-send-invoice-email"]
+        self.assertEqual([p["id"] for p in flow["participants"]], ["shop.billing", "celery-billing-mail"])
+        self.assertEqual([(s["from"], s["to"], s["label"]) for s in flow["steps"]], [("shop.billing", "celery-billing-mail", "enqueue send_invoice_email"), ("celery-billing-mail", "shop.billing", "send_invoice_email")])
+        self.assertTrue(flow["steps"][1]["line"].endswith("invoices/tasks.py:13"))
+        self.assertEqual(flow["trigger"], {"kind": "job", "label": "Celery · billing.mail", "confidence": "high"})
+        self.assertEqual(
+            [(step["handoff"]["direction"], step["handoff"]["message"]) for step in flow["steps"]],
+            [("send", "invoices.tasks.send_invoice_email"), ("receive", "invoices.tasks.send_invoice_email")],
+        )
+        self.assertEqual(flow["steps"][1]["continuesAt"], "python:invoices.tasks:send_invoice_email")
+
+
+class Drift(unittest.TestCase):
+    def setUp(self):
+        self.files, self.warnings = run("drift", {"context": "ops", "service": "reports"})
+        self.fragment = json.loads(self.files["celery.json"])
+        self.channels = {c["address"]: c for c in self.fragment["contexts"][0]["services"][0]["channels"]}
+
+    def test_the_fragment_it_reads(self):
+        golden(self, "drift", self.files["celery.json"])
+
+    def test_every_diagnostic_once(self):
+        self.assertEqual(
+            [(w.ref.split("/")[-1], w.message.split(",")[0].split(":")[0]) for w in self.warnings],
+            [
+                ("ops.reports", "settings module `config.settings` not found"),
+                ("ops.reports", "task_routes pattern `reports.tasks.*` matches no task in this tree"),
+                ("services.py:19", "`mail.tasks.send_receipt` is sent as a task no function in this tree declares; recorded as a send with no handler here"),
+                ("services.py:23", "`helper` is enqueued"),
+                ("celery.py:15", "beat entry `nightly` schedules `reports.tasks.nightly`"),
+                ("celery.py:16", "beat entry `rebuild` has a schedule this reader cannot read as syntax"),
+                ("tasks.py:19", "task `jobs.tasks.orphan` is declared"),
+            ],
+        )
+
+    def test_the_app_module_configures_the_queue_when_the_settings_are_missing(self):
+        self.assertEqual(sorted(self.channels), ["mail", "rebuild", "reports.default"])
+        self.assertIn("over amqp", self.channels["mail"]["doc"])
+
+    def test_a_chain_is_one_enqueue_per_signature_noted_as_such(self):
+        notes = [f["steps"][0]["note"] for f in self.fragment["flows"] if f["trigger"]["kind"] == "job"]
+        self.assertTrue(all(n.startswith("Enqueued in a chain.") for n in notes))
+        self.assertEqual(len(notes), 2)
+
+    def test_a_task_sent_by_name_to_another_tree_is_a_send_with_no_handler(self):
+        self.assertEqual([m["direction"] for m in self.channels["mail"]["messages"]], ["send"])
+        self.assertEqual([f["slug"] for f in self.fragment["flows"]], ["reports-celery-build-report", "reports-celery-build-report-beat", "reports-celery-deliver-report"])
+
+    def test_an_opaque_schedule_is_kept_as_written_and_the_entry_options_place_the_task(self):
+        beat = [f for f in self.fragment["flows"] if f["slug"] == "reports-celery-build-report-beat"][0]
+        self.assertEqual(beat["trigger"], {"kind": "scheduled", "label": "every_other_day()", "confidence": "high"})
+        # The code enqueues build_report on the default queue; the entry's
+        # options put the scheduled run on one of its own.
+        self.assertEqual(beat["participants"][2]["id"], "celery-rebuild")
+        self.assertEqual([m["direction"] for m in self.channels["rebuild"]["messages"]], ["send", "receive"])
+
+    def test_a_task_nothing_enqueues_is_still_worked(self):
+        orphan = [m for m in self.channels["reports.default"]["messages"] if m["name"] == "jobs.tasks.orphan"]
+        self.assertEqual([m["direction"] for m in orphan], ["receive"])
+        self.assertIn("Nothing in this tree enqueues it.", orphan[0]["doc"])
+
+
+class Protocol(unittest.TestCase):
+    def test_describe_answers_with_the_options_schema(self):
+        out = json.loads(main.serve(json.dumps({"portolanVersion": "0.1.0", "kind": "describe"})))
+        self.assertEqual(out["files"], [])
+        self.assertEqual(out["describe"]["name"], "extract-celery")
+        self.assertEqual(out["describe"]["options"]["additionalProperties"], False)
+        self.assertIn("settings", out["describe"]["options"]["properties"])
+
+    def test_an_option_nobody_reads_is_refused_rather_than_dropped(self):
+        with self.assertRaises(ValueError):
+            Options.of({"context": "shop", "setings": "config.settings"})
+
+    def test_no_tasks_is_said_rather_than_an_empty_fragment_nobody_questions(self):
+        _, warnings = run("billing", {"context": "shop", "service": "billing", "source": "config"})
+        self.assertIn("no Celery tasks under", warnings[0].message)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/plugins/extract-celery/main.py

@@ -0,0 +1,66 @@
+"""portolan-extract-celery: a tree with Celery in it in, work queues and job
+flows out.
+
+The same protocol as every other extractor: one JSON request on stdin, one
+JSON response on stdout, and a `describe` that answers with what the plugin is
+and what it can be told. Python 3.9 or newer, and nothing but the standard
+library: the project is never imported, and neither is Celery.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(1, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "pyplugin"))
+
+from extract import extract  # noqa: E402
+from options import Options  # noqa: E402
+from protocol import Builder, Input  # noqa: E402
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+DESCRIPTOR = {
+    "name": "extract-celery",
+    "summary": "Reads Celery task declarations, the calls that enqueue them and the routes that place them into work queues and source-backed job flows.",
+    "phases": ["extract"],
+}
+
+
+def descriptor():
+    with open(os.path.join(HERE, "options.schema.json"), "r", encoding="utf-8") as handle:
+        out = dict(DESCRIPTOR)
+        out["options"] = json.load(handle)
+        return out
+
+
+def serve(raw: str) -> str:
+    request = json.loads(raw)
+    version = request.get("portolanVersion", "")
+    if version and version != "0.1.0":
+        raise ValueError("unsupported portolan protocol %r (plugin supports 0.1.0)" % version)
+    if request.get("kind") == "describe":
+        return json.dumps({"files": [], "describe": descriptor()})
+    input_ = Input.of(request.get("input"))
+    if not input_.root:
+        raise ValueError("no input root: an extractor has nothing to read")
+    builder = Builder()
+    extract(input_, Options.of(request.get("options")), builder)
+    for warning in builder.warnings:
+        sys.stderr.write("warning: %s%s\n" % ((warning.ref + ": ") if warning.ref else "", warning.message))
+    return json.dumps(builder.response(), indent=2)
+
+
+def main() -> int:
+    try:
+        sys.stdout.write(serve(sys.stdin.read()))
+    except Exception as err:  # the host reads a non-zero exit and the message
+        sys.stderr.write("portolan-extract-celery: %s\n" % err)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugins/extract-celery/options.py

@@ -0,0 +1,31 @@
+"""What the manifest tells the extractor: the things a tree with Celery in it
+does not say about the estate it belongs to."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from protocol import read_options
+
+
+@dataclass
+class Options:
+    context: str = ""
+    service: str = ""
+    source: str = "."
+    settings: str = ""
+    out: str = "celery.json"
+
+    # The option as the manifest spells it, against the field that holds it.
+    KEYS = {
+        "context": "context",
+        "service": "service",
+        "source": "source",
+        "settings": "settings",
+        "out": "out",
+    }
+
+    @staticmethod
+    def of(raw: Any) -> "Options":
+        return read_options(Options(), Options.KEYS, raw)

package/plugins/extract-celery/options.schema.json

@@ -0,0 +1,31 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context the service belongs to. Defaults to the name of the input directory.",
+      "examples": ["shop"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service that enqueues and works the tasks. Defaults to the name of the input directory.",
+      "examples": ["billing"]
+    },
+    "source": {
+      "type": "string",
+      "description": "The directory the tasks and their callers are looked for in, relative to the input root.",
+      "default": "."
+    },
+    "settings": {
+      "type": "string",
+      "description": "The Django settings module the Celery app is configured from, as an import spells it. Defaults to what manage.py sets DJANGO_SETTINGS_MODULE to.",
+      "examples": ["config.settings"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "celery.json"
+    }
+  }
+}

package/plugins/extract-celery/producers.py

@@ -0,0 +1,156 @@
+"""The calls that put a task on a queue.
+
+`t.delay(...)` and `t.apply_async(...)` are the two ways a task is enqueued,
+and `t.s(...).apply_async()` is the same call through a signature. A
+`chain`, `group` or `chord` holds several signatures, each of which is an
+enqueue and is recorded as one, noted with the canvas it sits in; the order
+the canvas imposes is not drawn. `app.send_task("name")` enqueues by wire
+name, for a task that may live in another tree. `transaction.on_commit(lambda:
+t.delay(...))` - and the `partial` form - is the same enqueue with a note that
+it waits for the commit, which is the one fact about *when* a message leaves
+that the code states plainly.
+
+Names are resolved by import and by file, so `tasks.send_invoice_email.delay`
+and `send_invoice_email.delay` after `from .tasks import send_invoice_email`
+land on the same function.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+from source import Module, Project, const_str, dotted, keyword, keyword_str
+from celery_tasks import package_of
+
+ENQUEUE = ("delay", "apply_async")
+SIGNATURE = ("s", "si", "signature", "subtask")
+CANVAS = {"chain": "in a chain", "group": "in a group", "chord": "in a chord"}
+AFTER_COMMIT = "after the transaction commits"
+LATER = "for later, with a countdown or an eta"
+
+
+@dataclass
+class Producer:
+    module: Module
+    node: ast.Call
+    key: Optional[Tuple[str, str]]  # the task's, when the call resolves to one
+    wire: str  # the name `send_task` was given, "" otherwise
+    label: str  # the callee as written, last segment
+    queue: str  # `queue=` at the call, "" when none
+    notes: List[str]
+
+    @property
+    def line(self) -> str:
+        return self.module.where(self.node)
+
+
+def read_producers(project: Project) -> List[Producer]:
+    out: List[Producer] = []
+    for module in sorted(project.modules.values(), key=lambda m: m.rel):
+        Visitor(project, module, out).visit(module.tree)
+    return out
+
+
+class Visitor(ast.NodeVisitor):
+    def __init__(self, project: Project, module: Module, out: List[Producer]):
+        self.project = project
+        self.module = module
+        self.out = out
+        self.pending: List[str] = []  # notes the enclosing calls add
+
+    def visit_Call(self, node: ast.Call) -> None:
+        name = dotted(node.func)
+        last = name.split(".")[-1]
+        if last == "on_commit":
+            self.pending.append(AFTER_COMMIT)
+            self.generic_visit(node)
+            self.pending.pop()
+            return
+        if last == "partial" and node.args and isinstance(node.args[0], ast.Attribute) and node.args[0].attr in ENQUEUE:
+            self.enqueue(node.args[0].value, node)
+            for arg in node.args[1:]:
+                self.visit(arg)
+            for kw in node.keywords:
+                self.visit(kw.value)
+            return
+        if last in ENQUEUE and isinstance(node.func, ast.Attribute):
+            self.enqueue(node.func.value, node)
+            self.generic_visit(node)
+            return
+        if last == "send_task" and node.args and const_str(node.args[0]):
+            wire = const_str(node.args[0])
+            self.out.append(Producer(self.module, node, None, wire, wire, keyword_str(node, "queue"), self.notes(node)))
+            self.generic_visit(node)
+            return
+        # A canvas called outright: `chain(a.s(), b.s())()`.
+        if isinstance(node.func, ast.Call) and dotted(node.func.func).split(".")[-1] in CANVAS:
+            self.enqueue(node.func, node)
+            return
+        self.generic_visit(node)
+
+    def enqueue(self, receiver: ast.AST, call: ast.Call, extra: str = "") -> None:
+        """`receiver` is what `.delay` or `.apply_async` was called on: the task,
+        a signature of it, or a canvas of signatures."""
+        if isinstance(receiver, ast.Call) and isinstance(receiver.func, ast.Attribute) and receiver.func.attr in SIGNATURE:
+            self.record(receiver.func.value, call, extra)
+            return
+        if isinstance(receiver, ast.Call) and dotted(receiver.func).split(".")[-1] in CANVAS:
+            how = CANVAS[dotted(receiver.func).split(".")[-1]]
+            for arg in flatten(receiver.args):
+                if isinstance(arg, ast.Call):
+                    self.enqueue(arg, call, how)
+            return
+        self.record(receiver, call, extra)
+
+    def record(self, target: ast.AST, call: ast.Call, extra: str) -> None:
+        name = dotted(target)
+        if not name:
+            return
+        key = resolve(self.project, self.module, name)
+        self.out.append(Producer(self.module, call, key, "", name.split(".")[-1], keyword_str(call, "queue"), self.notes(call, extra)))
+
+    def notes(self, call: ast.Call, extra: str = "") -> List[str]:
+        out = list(self.pending)
+        if extra:
+            out.append(extra)
+        if keyword(call, "countdown") is not None or keyword(call, "eta") is not None:
+            out.append(LATER)
+        return out
+
+
+def flatten(args: List[ast.AST]) -> List[ast.AST]:
+    out: List[ast.AST] = []
+    for arg in args:
+        if isinstance(arg, ast.Starred):
+            arg = arg.value
+        if isinstance(arg, (ast.List, ast.Tuple)):
+            out += arg.elts
+        else:
+            out.append(arg)
+    return out
+
+
+def resolve(project: Project, module: Module, name: str) -> Optional[Tuple[str, str]]:
+    """`send_invoice_email` through the import that brought it here,
+    `tasks.send_invoice_email` through the module import, to (module, function).
+    None when the head of the name is nothing this module imported or defined."""
+    parts = name.split(".")
+    if len(parts) == 1:
+        hit = project.resolve(module, name)
+        if hit is None:
+            return None
+        target, local = hit
+        return package_of(target), local
+    head, rest = parts[0], parts[1:]
+    imported = module.imports.get(head)
+    if imported is None:
+        return None
+    if imported.name == "*":
+        # `import a.b` binds `a` and is used as `a.b.fn`; `import a.b as z` is `z.fn`.
+        base = [head] if imported.module == head or imported.module.startswith(head + ".") else imported.module.split(".")
+    else:
+        base = imported.module.split(".") + [imported.name]
+    full = base + rest
+    return ".".join(full[:-1]), full[-1]

package/plugins/extract-celery/routes_test.py

@@ -0,0 +1,106 @@
+"""The order a queue is decided in, and the configuration it is read from."""
+
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(1, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "pyplugin"))
+
+import celery_conf as conf  # noqa: E402
+import celery_conf as routes  # noqa: E402
+from source import Project  # noqa: E402
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def project(fixture):
+    root = os.path.join(HERE, "testdata", fixture)
+    return Project(root, root, lambda p: os.path.relpath(p, root))
+
+
+class Order(unittest.TestCase):
+    def setUp(self):
+        self.cfg = conf.Config(routes=[("app.tasks.send", "exact"), ("app.tasks.*", "glob")], default_queue="dflt")
+
+    def test_the_call_first_then_the_task_then_the_routes_then_the_default(self):
+        self.assertEqual(routes.queue_for("app.tasks.send", "here", "there", self.cfg), ("here", routes.AT_CALL))
+        self.assertEqual(routes.queue_for("app.tasks.send", "", "there", self.cfg), ("there", routes.ON_TASK))
+        self.assertEqual(routes.queue_for("app.tasks.send", "", "", self.cfg), ("exact", routes.BY_ROUTES))
+        self.assertEqual(routes.queue_for("app.tasks.other", "", "", self.cfg), ("glob", routes.BY_ROUTES))
+        self.assertEqual(routes.queue_for("elsewhere.task", "", "", self.cfg), ("dflt", routes.BY_DEFAULT))
+
+    def test_past_everything_celery_has_a_queue_of_its_own(self):
+        self.assertEqual(routes.queue_for("x", "", "", conf.Config()), ("celery", routes.BY_CELERY))
+
+    def test_a_route_that_names_no_task_is_found(self):
+        self.assertEqual(routes.unmatched(self.cfg, ["app.tasks.send"]), [])
+        self.assertEqual(routes.unmatched(self.cfg, ["other.task"]), ["app.tasks.send", "app.tasks.*"])
+
+
+class Schedules(unittest.TestCase):
+    """A schedule object, as the sentence the page says."""
+
+    def text(self, source):
+        import ast
+
+        from source import Module
+
+        module = Module.__new__(Module)
+        module.tree = ast.parse("x = " + source)
+        return conf.schedule_text(module.tree.body[0].value, module)
+
+    def test_crontab_in_its_own_field_order_with_stars_for_what_is_not_said(self):
+        self.assertEqual(self.text("crontab(minute=0, hour='*/3')"), ("cron 0 */3 * * *", True))
+        self.assertEqual(self.text("crontab(hour=9, minute=30, day_of_week='mon-fri')"), ("cron 30 9 * * mon-fri", True))
+        self.assertEqual(self.text("crontab()"), ("cron * * * * *", True))
+
+    def test_an_interval_in_seconds_or_a_timedelta(self):
+        self.assertEqual(self.text("30.0"), ("every 30s", True))
+        self.assertEqual(self.text("90"), ("every 1m30s", True))
+        self.assertEqual(self.text("timedelta(hours=6)"), ("every 6h", True))
+        self.assertEqual(self.text("timedelta(days=1, hours=12)"), ("every 1d12h", True))
+        self.assertEqual(self.text("schedule(run_every=timedelta(minutes=5))"), ("every 5m", True))
+
+    def test_a_solar_event_and_anything_else_as_written(self):
+        self.assertEqual(self.text("solar('sunset', 59.9, 10.7)"), ("solar sunset", True))
+        self.assertEqual(self.text("crontab(minute=MINUTE)"), ("crontab(minute=MINUTE)", False))
+        self.assertEqual(self.text("every_other_day()"), ("every_other_day()", False))
+
+    def test_the_entries_are_read_off_the_settings_and_the_app_module(self):
+        cfg = conf.read_config(project("billing"), "")
+        self.assertEqual(
+            [(s.name, s.task or s.ref, s.when, s.queue, s.opaque) for s in cfg.schedules],
+            [
+                ("remind-unpaid-invoices", "invoices.tasks.remind_unpaid_invoice", "every 6h", "", False),
+                ("archive-closed-invoices", "billing.archive_invoice", "cron 30 2 * * *", "", False),
+                ("close-stale-drafts", "close_stale_drafts", "cron 0 3 * * *", "", False),
+            ],
+        )
+        self.assertFalse(cfg.beat_in_database)
+
+
+class Reading(unittest.TestCase):
+    def test_the_settings_under_the_namespace_the_app_names(self):
+        cfg = conf.read_config(project("billing"), "")
+        self.assertEqual(cfg.settings, "config.settings")
+        self.assertTrue(cfg.settings_found)
+        self.assertEqual(cfg.routes, [("invoices.tasks.send_invoice_email", "billing.mail")])
+        self.assertEqual(cfg.default_queue, "billing")
+        self.assertEqual(cfg.broker_scheme, "redis")
+        self.assertEqual([a.name for a in cfg.apps], ["app"])
+
+    def test_the_app_module_over_settings_that_are_not_there(self):
+        cfg = conf.read_config(project("drift"), "")
+        self.assertFalse(cfg.settings_found)
+        self.assertEqual(cfg.routes, [("reports.tasks.*", "reports")])
+        self.assertEqual(cfg.default_queue, "reports.default")
+        self.assertEqual(cfg.broker_scheme, "amqp")
+
+    def test_an_environment_lookup_is_its_default_and_no_further(self):
+        cfg = conf.read_config(project("billing"), "")
+        self.assertEqual(cfg.broker, "redis://localhost:6379/0")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/plugins/extract-commands/describe.go

@@ -0,0 +1,19 @@
+package main
+
+import (
+	_ "embed"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+//go:embed options.schema.json
+var optionsSchema []byte
+
+func descriptor() plugin.Descriptor {
+	return plugin.Descriptor{
+		Name:    "extract-commands",
+		Summary: "Reads the make targets, npm scripts, just recipes and task-runner tasks a repository declares onto its service.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-commands/describe_test.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchemaMatchesStruct(t *testing.T) {
+	schematest.Check(t, optionsSchema, Options{})
+}