feat(catalog): let declarative Catalog advertise source_url

The metadata-quality linter's VGI004 rule expects catalogs to advertise a
source_url (repo/docs homepage) via the catalog_catalogs discovery record
(CatalogInfo.source_url / duckdb_databases()). The declarative Catalog
descriptor had no way to set it, and the default catalogs() serializer
always emitted source_url=None.

Add a settable source_url field to the Catalog descriptor and thread it
through ReadOnlyCatalogInterface.catalogs() so it flows into CatalogInfo.
Schema-level vgi.description_llm / vgi.description_md tags (VGI116/VGI118)
were already wired: Schema.tags flows through Schema.to_schema_info() into
SchemaInfo.tags, so no change was needed there.

Mirrors the vgi-rust fix (CatalogModel.source_url + serializer emit).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

tests/catalog/test_declarative.py

@@ -1207,6 +1207,20 @@ def test_catalog_multiple_schemas(self) -> None:
         catalog = Catalog(name="myapp", schemas=[main, analytics])
         assert len(catalog.schemas) == 2
 
+    def test_catalog_source_url_defaults_to_none(self) -> None:
+        """Catalog source_url is None unless set."""
+        catalog = Catalog(name="myapp", schemas=[Schema(name="main")])
+        assert catalog.source_url is None
+
+    def test_catalog_source_url_settable(self) -> None:
+        """Catalog source_url can advertise the repo/docs homepage."""
+        catalog = Catalog(
+            name="myapp",
+            schemas=[Schema(name="main")],
+            source_url="https://github.com/example/myapp",
+        )
+        assert catalog.source_url == "https://github.com/example/myapp"
+
 
 class TestCatalogValidation:
     """Tests for Catalog validation."""
@@ -1311,6 +1325,25 @@ def test_catalogs_returns_catalog_name(self, catalog_interface: ReadOnlyCatalogI
         infos = catalog_interface.catalogs()
         assert [i.name for i in infos] == ["testapp"]
 
+    def test_catalogs_omits_source_url_when_unset(self, catalog_interface: ReadOnlyCatalogInterface) -> None:
+        """catalogs() yields source_url=None when the Catalog doesn't set one."""
+        infos = catalog_interface.catalogs()
+        assert infos[0].source_url is None
+
+    def test_catalogs_serializes_source_url(self, users_table: Table) -> None:
+        """catalogs() surfaces the Catalog.source_url into CatalogInfo."""
+
+        class SourcedCatalog(ReadOnlyCatalogInterface):
+            catalog = Catalog(
+                name="sourced",
+                default_schema="main",
+                schemas=[Schema(name="main", tables=[users_table])],
+                source_url="https://github.com/example/sourced",
+            )
+
+        infos = SourcedCatalog().catalogs()
+        assert infos[0].source_url == "https://github.com/example/sourced"
+
     def test_catalog_attach(self, catalog_interface: ReadOnlyCatalogInterface) -> None:
         """catalog_attach returns result with correct defaults."""
         result = catalog_interface.catalog_attach(

tests/catalog/test_example_worker_catalog.py

@@ -78,6 +78,13 @@ def test_catalogs_returns_example(self) -> None:
         catalogs = client.catalogs()
         assert "example" in [c.name for c in catalogs]
 
+    def test_catalogs_advertises_source_url(self) -> None:
+        """The declarative catalog's source_url round-trips through discovery."""
+        client = Client(EXAMPLE_WORKER)
+        catalogs = client.catalogs()
+        example = next(c for c in catalogs if c.name == "example")
+        assert example.source_url == "https://github.com/query-farm/vgi-python"
+
     def test_catalog_attach_works(self) -> None:
         """Can attach to the 'example' catalog."""
         client = Client(EXAMPLE_WORKER)

uv.lock

@@ -320,6 +320,7 @@ def _build_enum_stats() -> dict[str, ColumnStatisticsInput]:
     default_schema="main",
     comment="Example VGI catalog for testing",
     tags={"source": "vgi-fixture-worker", "version": "1"},
+    source_url="https://github.com/query-farm/vgi-python",
     schemas=[
         Schema(
             name="main",

vgi/_test_fixtures/worker.py

@@ -2319,6 +2319,7 @@ def catalogs(self) -> list[CatalogInfo]:
                 implementation_version=None,
                 data_version_spec=None,
                 attach_option_specs=[spec.serialize() for spec in self.attach_option_specs],
+                source_url=self.catalog.source_url if self.catalog is not None else None,
             )
         ]
 

vgi/catalog/catalog_interface.py

@@ -873,6 +873,10 @@ class Catalog:
         schemas: Sequence of Schema objects defining the catalog contents.
         comment: Optional comment describing the catalog.
         tags: Optional key-value tags associated with the catalog.
+        source_url: Where this worker's code lives — repo, build, or docs
+            homepage. ``None`` (the default) when the worker doesn't advertise
+            a source location. Surfaced via the ``catalog_catalogs()`` discovery
+            record (``CatalogInfo.source_url``).
 
     """
 
@@ -881,6 +885,7 @@ class Catalog:
     schemas: Sequence[Schema] = ()
     comment: str | None = None
     tags: dict[str, str] = field(default_factory=dict)
+    source_url: str | None = None
 
     def __post_init__(self) -> None:
         """Validate catalog configuration."""