@shortlink-org/portolan 0.3.0 → 0.4.0

package/plugins/extract-csharp-ddd/options.schema.json

@@ -0,0 +1,55 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "modules": {
+      "type": "string",
+      "description": "The directory the modules are in, relative to the input root: one directory per module, `Domain`, `Application`, `Infrastructure` and `IntegrationEvents` under it. Each module is a bounded context with one service.",
+      "default": "src/Modules"
+    },
+    "api": {
+      "type": "string",
+      "description": "The directory the HTTP host is in, relative to the input root. Controllers under a `Modules/<Module>` directory beneath it are that module's HTTP edge.",
+      "default": "src/API"
+    },
+    "database": {
+      "type": "string",
+      "description": "The directory the database project is in, relative to the input root: `Structure/<schema>/Tables/*.sql` and `Structure/<schema>/Views/*.sql` beneath it, one schema per module.",
+      "default": "src/Database"
+    },
+    "repo": {
+      "type": "string",
+      "description": "Where the source lives, as `host/owner/name`. Nothing in a .NET tree says, so the manifest does.",
+      "examples": ["github.com/kgrzybek/modular-monolith-with-ddd"]
+    },
+    "bus": {
+      "type": "string",
+      "description": "The address of the bus integration events cross modules on. The code names the class, `InMemoryEventBus`, and nothing else, so the manifest says.",
+      "default": "integration-events"
+    },
+    "storeKind": {
+      "enum": ["postgres", "mysql", "sqlite", "other"],
+      "description": "What the schemas live in. SQL Server is `other`.",
+      "default": "other"
+    },
+    "classification": {
+      "enum": ["core", "supporting", "generic"],
+      "description": "Whether the modules are core to the business, support it, or are generic and could be bought. One value for every module the tree declares."
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "domain.json"
+    },
+    "openapiOut": {
+      "type": "string",
+      "description": "Name of the inferred OpenAPI 3.1 document, inside the step's output directory, one per module with controllers; `{service}` is replaced with the module's slug.",
+      "default": "openapi.{service}.yaml"
+    },
+    "storesOut": {
+      "type": "string",
+      "description": "Name of the store fragment, inside the step's output directory. Written when the database project declares a schema a module maps to.",
+      "default": "stores.json"
+    }
+  }
+}

package/plugins/extract-django/README.md

@@ -61,8 +61,19 @@ the matching extraction step. Regenerate to apply it; other options are kept.
 **Field.** Each model attribute assigned a field, with the type as written:
 `CharField`, `DateTimeField`, and a relation as `ForeignKey[Invoice]`. The doc
 is the field's own `help_text`, which is the one place a Django model already
-writes down what a column means. Value objects are the frozen dataclasses in
-`values.py`, their fields the annotations as written.
+writes down what a column means. What the field call says a value must
+satisfy is read into the catalog's own words (portolan.0015): `max_length`
+is `max_len`, `unique=True` is `unique`, `choices` is `in` with the stored
+values — read off a `Choices` class, a literal list of pairs or a module-level
+constant, and left out when they come from a call — an `EmailField`,
+`URLField` or `UUIDField` is `format`, a `PositiveIntegerField` is `gte 0`,
+and `MinValueValidator`, `MaxValueValidator`, `MinLengthValidator`,
+`MaxLengthValidator` and `RegexValidator` are the bounds they were given. The
+model is the source of truth for `required`: a field must be given unless
+the model fills it (`default`, `auto_now`, an auto id) or excuses it (`blank`,
+`null`); what a serializer adds is that layer's word and is not read here.
+Value objects are the frozen dataclasses in `values.py`, their fields the
+annotations as written.
 
 **Event.** `events.py`, in either of the two ways a Django project says it. A
 dataclass with `name = "billing.InvoiceIssued"` is an event, its payload the

package/plugins/extract-django/choices.py

@@ -0,0 +1,47 @@
+"""The `Choices` classes a model keeps, read as the values the column holds.
+
+`class Status(models.TextChoices): DRAFT = "draft", "Draft"` says two things:
+the states a lifecycle moves between, and the values a `status` field may
+take. Both readers want the same table, member name to stored value, and
+neither wants the label.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Dict
+
+from source import assigned, bases, inner_class
+
+
+def is_choices(node: ast.AST) -> bool:
+    return isinstance(node, ast.ClassDef) and any(b.split(".")[-1].endswith("Choices") for b in bases(node))
+
+
+def choices_of(model, name: str) -> Dict[str, str]:
+    """A Choices class, as member name to the value stored in the column. Looked
+    up inside the model first, then among the module's own classes."""
+    node = inner_class(model.node, name)
+    if node is None:
+        for other in model.module.classes():
+            if other.name == name:
+                node = other
+                break
+    if node is None or not is_choices(node):
+        return {}
+    out = {}
+    for member, value, _ in assigned(node):
+        if isinstance(value, ast.Constant) and not isinstance(value.value, bool):
+            out[member] = str(value.value)
+        elif isinstance(value, ast.Tuple) and value.elts and isinstance(value.elts[0], ast.Constant):
+            out[member] = str(value.elts[0].value)
+    return out
+
+
+def choice_tables(model) -> Dict[str, Dict[str, str]]:
+    """Every Choices class in reach of the model, by class name."""
+    out = {}
+    for node in list(model.node.body) + list(model.module.tree.body):
+        if is_choices(node):
+            out[node.name] = choices_of(model, node.name)
+    return out

package/plugins/extract-django/domain.py

@@ -16,6 +16,7 @@ from typing import Dict, List, Optional
 import catalog
 from apps import App
 from ids import aggregate_id, block_id, pascal, singular, slug
+from rules import rules_of
 from source import (
     Module,
     Project,
@@ -315,7 +316,7 @@ def read_aggregates(
                     slug(model.name),
                     model.name,
                     doc(model.node),
-                    [catalog.field(f.name, f.type(), f.help()) for f in model.fields],
+                    [catalog.field(f.name, f.type(), f.help(), **rules_of(f, model)) for f in model.fields],
                 )
             )
         for module, node in value_objects(app):

package/plugins/extract-django/extract_test.py

@@ -303,6 +303,19 @@ class Reading(unittest.TestCase):
         self.assertEqual([b["name"] for b in self.aggregate["entities"]], ["Invoice", "InvoiceLine"])
         self.assertEqual([b["name"] for b in self.aggregate["valueObjects"]], ["Money"])
 
+    def test_a_model_field_states_its_rules_and_whether_it_must_be_given(self):
+        invoice = next(b for b in self.aggregate["entities"] if b["name"] == "Invoice")
+        fields = {f["name"]: f for f in invoice["fields"]}
+        self.assertEqual(fields["number"].get("rules"), [{"name": "max_len", "value": "32"}, {"name": "unique"}])
+        self.assertNotIn("required", fields["number"])  # null=True: the model lets it be absent
+        self.assertEqual(fields["currency"], {"name": "currency", "type": "CharField", "doc": "", "required": True, "rules": [{"name": "max_len", "value": "3"}]})
+        self.assertEqual(
+            fields["status"].get("rules"),
+            [{"name": "max_len", "value": "16"}, {"name": "in", "value": "draft, issued, paid, void"}],
+        )
+        self.assertNotIn("required", fields["status"])  # a default fills it
+        self.assertEqual(fields["id"].get("rules"), [{"name": "format", "value": "uuid"}])
+
     def test_a_service_function_is_an_operation_and_a_write_makes_it_a_command(self):
         kinds = {o["id"]: o["kind"] for o in self.aggregate["operations"]}
         self.assertEqual(kinds["IssueInvoice"], "command")

package/plugins/extract-django/lifecycle.py

@@ -15,8 +15,9 @@ from dataclasses import dataclass, field as dc_field
 from typing import Dict, List, Optional, Tuple
 
 import catalog
+from choices import choice_tables
 from domain import Aggregate, ModelDef
-from source import assigned, bases, const_str, dotted, inner_class, keyword, methods
+from source import assigned, const_str, dotted, keyword, methods
 
 
 @dataclass
@@ -28,25 +29,6 @@ class Move:
     sources: List[str] = dc_field(default_factory=list)  # the states it may be made from, when the decorator says
 
 
-def choices_of(model: ModelDef, name: str) -> Dict[str, str]:
-    """A TextChoices class, as member name to the value stored in the column."""
-    node = inner_class(model.node, name)
-    if node is None:
-        for other in model.module.classes():
-            if other.name == name:
-                node = other
-                break
-    if node is None or not any(b.split(".")[-1].endswith("Choices") for b in bases(node)):
-        return {}
-    out = {}
-    for member, value, _ in assigned(node):
-        if isinstance(value, ast.Constant) and isinstance(value.value, str):
-            out[member] = value.value
-        elif isinstance(value, ast.Tuple) and value.elts and isinstance(value.elts[0], ast.Constant):
-            out[member] = value.elts[0].value
-    return out
-
-
 def state_of(node: ast.AST, choices: Dict[str, Dict[str, str]]) -> str:
     """`Status.DRAFT` or `"draft"`, either way the value in the column."""
     literal = const_str(node)
@@ -71,14 +53,6 @@ def status_field(model: ModelDef) -> Optional[str]:
     return "status" if model.field("status") else None
 
 
-def choice_tables(model: ModelDef) -> Dict[str, Dict[str, str]]:
-    out = {}
-    for node in list(model.node.body) + list(model.module.tree.body):
-        if isinstance(node, ast.ClassDef) and any(b.split(".")[-1].endswith("Choices") for b in bases(node)):
-            out[node.name] = choices_of(model, node.name)
-    return out
-
-
 def declared_table(model: ModelDef, choices: Dict[str, Dict[str, str]]) -> Dict[str, List[str]]:
     """`TRANSITIONS = {Status.DRAFT: [Status.ISSUED], ...}`, in the order written."""
     for name, value, _ in assigned(model.node):

package/plugins/extract-django/main.py

@@ -25,6 +25,7 @@ HERE = os.path.dirname(os.path.abspath(__file__))
 DESCRIPTOR = {
     "name": "extract-django",
     "summary": "Reads a Django service by its applications - models, events, services, DRF views, receivers, clients - into a catalog fragment, and its models into the store they are the schema of.",
+    "category": "code",
     "phases": ["extract"],
 }
 

package/plugins/extract-django/rules.py

@@ -0,0 +1,154 @@
+"""What a model field says a value must satisfy, in the catalog's words.
+
+A Django model states its rules in the field call: `CharField(max_length=3,
+unique=True, choices=Status.choices, validators=[MinValueValidator(0)])`. The
+catalog has one vocabulary for these across every source (portolan.0015), so
+`max_length` is `max_len` here as `minLength` is in an OpenAPI document and
+`min_len` in a proto, and the page says all three the same way.
+
+The model is the source of truth for `required`: a field must be given when a
+row is made unless the class fills it in (`default`, `auto_now`, an auto id),
+lets it be empty (`blank`) or lets it be absent (`null`). What a serializer or
+a form adds on top is that layer's word, not the model's, and is not read here.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Dict, List, Optional
+
+import catalog
+from choices import choice_tables
+from source import assigned, dotted, keyword, keyword_bool
+
+# The field classes whose name is itself a rule on the value.
+FORMATS = {
+    "EmailField": "email",
+    "URLField": "uri",
+    "UUIDField": "uuid",
+    "GenericIPAddressField": "ip",
+}
+NON_NEGATIVE = {"PositiveIntegerField", "PositiveBigIntegerField", "PositiveSmallIntegerField"}
+
+# Never required: the database numbers an auto id, a bool is False when not
+# given, and a many-to-many is a table of its own with no row to be missing.
+NEVER_REQUIRED = {"AutoField", "BigAutoField", "SmallAutoField", "BooleanField", "ManyToManyField"}
+
+# Options under which the model itself fills or excuses the value.
+FILLED_OR_EXCUSED = ("blank", "null", "auto_now", "auto_now_add")
+
+VALIDATORS = {
+    "MinValueValidator": "gte",
+    "MaxValueValidator": "lte",
+    "MinLengthValidator": "min_len",
+    "MaxLengthValidator": "max_len",
+    "RegexValidator": "pattern",
+}
+
+
+def rules_of(f, model) -> Dict[str, object]:
+    """`required` and `rules` for `catalog.field`, as keyword arguments; an
+    empty dict when the field says nothing about its value."""
+    out: Dict[str, object] = {}
+    if required(f):
+        out["required"] = True
+    found = rules(f, model)
+    if found:
+        out["rules"] = found
+    return out
+
+
+def required(f) -> bool:
+    if f.kind in NEVER_REQUIRED:
+        return False
+    if any(keyword_bool(f.call, option) for option in FILLED_OR_EXCUSED):
+        return False
+    return keyword(f.call, "default") is None
+
+
+def rules(f, model) -> List[Dict[str, str]]:
+    """The rules in the order the source states them: what the field class
+    says first, then the options as written."""
+    out = []
+    if f.kind in FORMATS:
+        out.append(catalog.rule("format", FORMATS[f.kind]))
+    if f.kind in NON_NEGATIVE:
+        out.append(catalog.rule("gte", "0"))
+    for kw in f.call.keywords:
+        if kw.arg == "max_length":
+            length = f.integer("max_length")
+            if length is not None:
+                out.append(catalog.rule("max_len", str(length)))
+        elif kw.arg == "unique" and keyword_bool(f.call, "unique"):
+            out.append(catalog.rule("unique"))
+        elif kw.arg == "choices":
+            values = choice_values(kw.value, model)
+            if values:
+                out.append(catalog.rule("in", ", ".join(values)))
+        elif kw.arg == "validators":
+            out.extend(validator_rules(kw.value))
+    return out
+
+
+def choice_values(node: ast.AST, model, depth: int = 0) -> List[str]:
+    """The values a `choices=` option allows, in the order it lists them.
+
+    `Status.choices` reads the Choices class; a literal list of pairs or of
+    bare values reads the value of each pair, descending into a group's own
+    list; a name reads the module-level constant it is assigned. Anything
+    else - a call, an import the module does not define - yields nothing, and
+    nothing is what the field then says, rather than an empty `in`.
+    """
+    if depth > 3:
+        return []
+    if isinstance(node, ast.Attribute) and node.attr == "choices":
+        table = choice_tables(model).get(dotted(node.value).split(".")[-1], {})
+        return list(table.values())
+    if isinstance(node, (ast.List, ast.Tuple)):
+        out: List[str] = []
+        for item in node.elts:
+            if isinstance(item, ast.Constant) and not isinstance(item.value, bool):
+                out.append(str(item.value))
+            elif isinstance(item, (ast.List, ast.Tuple)) and item.elts:
+                first = item.elts[0]
+                second = item.elts[1] if len(item.elts) > 1 else None
+                if isinstance(second, (ast.List, ast.Tuple)):
+                    out.extend(choice_values(second, model, depth + 1))  # a group: (label, [pairs])
+                elif isinstance(first, ast.Constant) and not isinstance(first.value, bool):
+                    out.append(str(first.value))
+                elif isinstance(first, ast.Attribute):
+                    value = choice_member(first, model)
+                    if value:
+                        out.append(value)
+        return out
+    if isinstance(node, ast.Name):
+        for name, value, _ in assigned(model.module.tree):
+            if name == node.id:
+                return choice_values(value, model, depth + 1)
+    return []
+
+
+def choice_member(node: ast.Attribute, model) -> Optional[str]:
+    """`Status.DRAFT` in a literal list of pairs: the member's stored value."""
+    table = choice_tables(model).get(dotted(node.value).split(".")[-1], {})
+    return table.get(node.attr)
+
+
+def validator_rules(node: ast.AST) -> List[Dict[str, str]]:
+    """`validators=[MinValueValidator(0), RegexValidator(r"^[A-Z]+$")]`: the
+    validators the catalog has words for, with the bound they were given. A
+    validator built from a name the module computes, or a regex meant to be
+    NOT matched, is left out rather than guessed."""
+    if not isinstance(node, (ast.List, ast.Tuple)):
+        return []
+    out = []
+    for item in node.elts:
+        if not isinstance(item, ast.Call):
+            continue
+        rule = VALIDATORS.get(dotted(item.func).split(".")[-1])
+        if rule is None or keyword_bool(item, "inverse_match"):
+            continue
+        given = item.args[0] if item.args else keyword(item, "limit_value") or keyword(item, "regex")
+        if isinstance(given, ast.Constant) and not isinstance(given.value, bool):
+            out.append(catalog.rule(rule, str(given.value)))
+    return out

package/plugins/extract-django/rules_test.py

@@ -0,0 +1,158 @@
+"""The rules a model field states, read one option at a time."""
+
+import ast
+import unittest
+
+from domain import FieldDef
+from rules import rules_of
+
+
+class Module:
+    """The slice of a Module the rules reader touches: the tree and its classes."""
+
+    def __init__(self, tree: ast.Module):
+        self.tree = tree
+
+    def classes(self):
+        return [node for node in self.tree.body if isinstance(node, ast.ClassDef)]
+
+
+class Model:
+    def __init__(self, node: ast.ClassDef, module: Module):
+        self.node = node
+        self.module = module
+
+
+def fields(source: str):
+    """Every field of the last class in `source`, as the extractor reads it,
+    with the integer options it resolves ahead of time."""
+    tree = ast.parse(source)
+    node = [n for n in tree.body if isinstance(n, ast.ClassDef)][-1]
+    model = Model(node, Module(tree))
+    out = {}
+    for stmt in node.body:
+        if isinstance(stmt, ast.Assign) and isinstance(stmt.value, ast.Call):
+            name = stmt.targets[0].id
+            call = stmt.value
+            kind = call.func.attr if isinstance(call.func, ast.Attribute) else call.func.id
+            integers = {}
+            for kw in call.keywords:
+                if kw.arg == "max_length" and isinstance(kw.value, ast.Constant):
+                    integers["max_length"] = kw.value.value
+            out[name] = rules_of(FieldDef(name=name, kind=kind, call=call, node=stmt, integers=integers), model)
+    return out
+
+
+class Options(unittest.TestCase):
+    def test_the_options_become_rules_in_the_order_written(self):
+        got = fields(
+            "class Invoice(models.Model):\n"
+            "    number = models.CharField(max_length=32, unique=True, null=True)\n"
+            "    currency = models.CharField(unique=True, max_length=3)\n"
+        )
+        self.assertEqual(got["number"], {"rules": [{"name": "max_len", "value": "32"}, {"name": "unique"}]})
+        self.assertEqual(got["currency"], {"required": True, "rules": [{"name": "unique"}, {"name": "max_len", "value": "3"}]})
+
+    def test_the_field_class_speaks_first(self):
+        got = fields(
+            "class Line(models.Model):\n"
+            "    email = models.EmailField(max_length=254)\n"
+            "    quantity = models.PositiveIntegerField()\n"
+            "    site = models.URLField(blank=True)\n"
+            "    owner = models.UUIDField(default=uuid.uuid4)\n"
+        )
+        self.assertEqual(got["email"]["rules"], [{"name": "format", "value": "email"}, {"name": "max_len", "value": "254"}])
+        self.assertEqual(got["quantity"], {"required": True, "rules": [{"name": "gte", "value": "0"}]})
+        self.assertEqual(got["site"], {"rules": [{"name": "format", "value": "uri"}]})
+        self.assertEqual(got["owner"], {"rules": [{"name": "format", "value": "uuid"}]})
+
+    def test_validators_carry_their_bound(self):
+        got = fields(
+            "class Line(models.Model):\n"
+            "    rate = models.DecimalField(validators=[MinValueValidator(0), MaxValueValidator(limit_value=1)])\n"
+            "    code = models.CharField(validators=[RegexValidator(r'^[A-Z]{3}$'), RegexValidator('x', inverse_match=True), validators.MinLengthValidator(2)])\n"
+            "    other = models.CharField(validators=[custom(), MinValueValidator(LIMIT)])\n"
+        )
+        self.assertEqual(got["rate"]["rules"], [{"name": "gte", "value": "0"}, {"name": "lte", "value": "1"}])
+        self.assertEqual(got["code"]["rules"], [{"name": "pattern", "value": "^[A-Z]{3}$"}, {"name": "min_len", "value": "2"}])
+        self.assertEqual(got["other"], {"required": True})
+
+
+class Choices(unittest.TestCase):
+    def test_a_choices_class_is_read_by_its_stored_values(self):
+        got = fields(
+            "class Invoice(models.Model):\n"
+            "    class Status(models.TextChoices):\n"
+            "        DRAFT = 'draft', 'Draft'\n"
+            "        PAID = 'paid', 'Paid'\n"
+            "    status = models.CharField(max_length=16, choices=Status.choices, default=Status.DRAFT)\n"
+        )
+        self.assertEqual(got["status"], {"rules": [{"name": "max_len", "value": "16"}, {"name": "in", "value": "draft, paid"}]})
+
+    def test_a_module_level_class_and_an_integer_choices_read_the_same(self):
+        got = fields(
+            "class Priority(models.IntegerChoices):\n"
+            "    LOW = 1\n"
+            "    HIGH = 2, 'High'\n"
+            "class Ticket(models.Model):\n"
+            "    priority = models.IntegerField(choices=Priority.choices)\n"
+        )
+        self.assertEqual(got["priority"], {"required": True, "rules": [{"name": "in", "value": "1, 2"}]})
+
+    def test_literal_lists_bare_values_and_groups(self):
+        got = fields(
+            "SIZES = [('s', 'Small'), ('m', 'Medium')]\n"
+            "class Shirt(models.Model):\n"
+            "    size = models.CharField(choices=SIZES)\n"
+            "    fit = models.CharField(choices=['slim', 'regular'])\n"
+            "    colour = models.CharField(choices=[('Warm', [('red', 'Red')]), ('Cold', [('blue', 'Blue')])])\n"
+            "    made = models.CharField(choices=load_choices())\n"
+        )
+        self.assertEqual(got["size"]["rules"], [{"name": "in", "value": "s, m"}])
+        self.assertEqual(got["fit"]["rules"], [{"name": "in", "value": "slim, regular"}])
+        self.assertEqual(got["colour"]["rules"], [{"name": "in", "value": "red, blue"}])
+        self.assertEqual(got["made"], {"required": True})
+
+    def test_a_pair_naming_a_member_reads_its_value(self):
+        got = fields(
+            "class Kind(models.TextChoices):\n"
+            "    ORDER = 'order', 'Order'\n"
+            "class Invoice(models.Model):\n"
+            "    kind = models.CharField(choices=[(Kind.ORDER, 'An order')])\n"
+        )
+        self.assertEqual(got["kind"]["rules"], [{"name": "in", "value": "order"}])
+
+
+class Required(unittest.TestCase):
+    def test_the_model_fills_or_excuses_the_value(self):
+        got = fields(
+            "class Invoice(models.Model):\n"
+            "    id = models.BigAutoField(primary_key=True)\n"
+            "    order_id = models.UUIDField()\n"
+            "    number = models.CharField(max_length=32, null=True)\n"
+            "    note = models.TextField(blank=True)\n"
+            "    created = models.DateTimeField(auto_now_add=True)\n"
+            "    status = models.CharField(max_length=8, default='draft')\n"
+            "    paid = models.BooleanField()\n"
+            "    tags = models.ManyToManyField('Tag')\n"
+            "    invoice = models.ForeignKey('Invoice', on_delete=models.CASCADE)\n"
+        )
+        required = {name: value.get("required", False) for name, value in got.items()}
+        self.assertEqual(
+            required,
+            {
+                "id": False,
+                "order_id": True,
+                "number": False,
+                "note": False,
+                "created": False,
+                "status": False,
+                "paid": False,
+                "tags": False,
+                "invoice": True,
+            },
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/plugins/extract-go-sqs/options.schema.json

@@ -0,0 +1,21 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context this service belongs to. Defaults to the name of the input directory.",
+      "examples": ["shop"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service. Defaults to the name of the input directory.",
+      "examples": ["fulfillment"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "sqs.json"
+    }
+  }
+}

package/plugins/extract-http-clients/describe.go

@@ -11,9 +11,10 @@ var optionsSchema []byte
 
 func descriptor() plugin.Descriptor {
 	return plugin.Descriptor{
-		Name:    "extract-http-clients",
-		Summary: "Reads outbound HTTP/SOAP calls and joins Go routes, handlers, factories, and providers into source-backed flows.",
-		Phases:  []string{plugin.PhaseExtract},
-		Options: optionsSchema,
+		Name:     "extract-http-clients",
+		Summary:  "Reads outbound HTTP/SOAP calls and joins Go routes, handlers, factories, and providers into source-backed flows.",
+		Category: plugin.CategoryCode,
+		Phases:   []string{plugin.PhaseExtract},
+		Options:  optionsSchema,
 	}
 }

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

@@ -0,0 +1,32 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context this service belongs to. Defaults to the name of the input directory.",
+      "examples": ["shop"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service. Defaults to the name of the input directory. The workload is found by this name: a Deployment, StatefulSet, DaemonSet, Job or CronJob called so, or labelled so with `app` or `app.kubernetes.io/name`; when the tree holds exactly one workload, that one.",
+      "examples": ["pricing"]
+    },
+    "paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Directories under the input root that hold the manifests, so a repository's other YAML - compose files, CI, buf - is not walked. Left out, the whole root is read and anything without `apiVersion` and `kind` is passed over.",
+      "examples": [["deploy/k8s"]]
+    },
+    "namespace": {
+      "type": "string",
+      "description": "Read only the objects in this namespace. An object that names no namespace is read either way. Left out, every namespace.",
+      "examples": ["shop"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "k8s.json"
+    }
+  }
+}