Metadata-Version: 2.3
Name: vgi-lint-check
Version: 0.1.0
Summary: A pydoclint-style metadata-quality linter for VGI workers.
Keywords: vgi,duckdb,haybarn,linter,metadata,data-quality,documentation,catalog,data-engineering,cli
Author: Rusty Conover
Author-email: Rusty Conover <rusty@query.farm>
License: Query Farm Source-Available License, Version 1.0
         
         Copyright (c) 2025, 2026 Query Farm LLC. All rights reserved.
         
         ## 1. Definitions
         
         "Licensor" means Query Farm LLC (http://query.farm, hello@query.farm) and its
         affiliates under common control.
         
         "VGI" means the Vector Gateway Interface, the DuckDB extension technology developed
         by the Licensor, also referred to by the Licensor as its "Hyperfederation" database
         technology.
         
         "Licensed Work" means VGI, including its source code, object code, and any
         documentation distributed with it, in each version made available by the Licensor
         under this License.
         
         "You" (or "Your") means the individual or legal entity exercising rights under this
         License, together with all affiliates under common control with that entity.
         
         "Production Use" means any use of the Licensed Work other than for development,
         testing, evaluation, experimentation, or other non-production purposes.
         
         "Hyperfederation Services" means services relating to the federation, gateway,
         integration, querying, or interoperation of data sources using VGI or
         functionally equivalent technology, including services that expose, broker, or
         provide access to such federated or gateway capabilities.
         
         "Commercial Marketplace" means any platform, exchange, or intermediary service,
         whether or not operated for a fee, that connects providers and consumers of
         Hyperfederation Services, or that facilitates the offering, discovery, exchange,
         sale, or licensing of Hyperfederation Services among third parties.
         
         "Competing Offering" means a product or service that You make available to third
         parties, on a paid basis (including through paid support, subscription, or hosting
         arrangements), whose capabilities significantly overlap with those of the Licensor's
         version(s) of the Licensed Work.
         
         ## 2. Grant of Rights
         
         Subject to the terms and limitations of this License, the Licensor grants You a
         worldwide, royalty-free, non-exclusive license to:
         
         (a) use, copy, and run the Licensed Work for any non-production purpose;
         
         (b) modify the Licensed Work and create derivative works of it;
         
         (c) redistribute the Licensed Work and Your derivative works, provided You comply
         with Section 5; and
         
         (d) make Production Use of the Licensed Work, except where such use is restricted by
         Section 3 or reserved to the Licensor by Section 4.
         
         ## 3. Production Use Conditions
         
         The grant of Production Use in Section 2(d) does not extend to, and You may not
         without a separate commercial license from the Licensor:
         
         (a) provide a Competing Offering to third parties; or
         
         (b) offer the Licensed Work, or any derivative work of it, to third parties on a
         hosted, embedded, or as-a-service basis where doing so competes with the Licensor's
         commercial interests in the Licensed Work.
         
         "Embedded" includes incorporating the source or object code of the Licensed Work
         into a Competing Offering, and packaging a Competing Offering such that the Licensed
         Work must be accessed or downloaded for that offering to function.
         
         Hosting or using the Licensed Work for Your own internal purposes is not a Competing
         Offering and is permitted, including across Your affiliates under common control.
         
         ## 4. Reserved Rights
         
         Notwithstanding any other provision of this License, the Licensor reserves to itself
         the exclusive right to build, operate, offer, or authorize a Commercial Marketplace
         that incorporates, integrates, is built upon, or otherwise uses the Licensed Work.
         
         This License grants You no right to construct, operate, or enable a Commercial
         Marketplace using the Licensed Work, whether on a commercial or non-commercial basis,
         and any such use requires a separate written agreement with the Licensor.
         
         ## 5. Redistribution
         
         If You redistribute the Licensed Work or any derivative work of it, in original or
         modified form, You must:
         
         (a) include a complete, unmodified copy of this License with each copy; and
         
         (b) cause any recipient to receive the Licensed Work subject to the terms of this
         License.
         
         The conditions in Sections 3 and 4 apply to every recipient of the Licensed Work,
         whether received directly from the Licensor or through a third party.
         
         ## 6. Conversion to Open Source
         
         For each version of the Licensed Work, on the tenth anniversary of the date the
         Licensor first made that version publicly available (the "Change Date" for that
         version), the Licensor additionally grants You the right to use that version under
         the terms of the Apache License, Version 2.0, and on and after that version's Change
         Date the restrictions in Sections 3 and 4 no longer apply to that version.
         
         This License applies separately to each version of the Licensed Work, and the Change
         Date may differ between versions.
         
         ## 7. Commercial Licensing
         
         If Your intended use is not permitted under this License, You may obtain a separate
         commercial license from the Licensor by contacting hello@query.farm. Absent such a
         license, You must refrain from the restricted use.
         
         ## 8. Trademarks
         
         This License does not grant You any right to use the names, trademarks, service
         marks, or logos of the Licensor, including "Vector Gateway Interface," "VGI," and
         "Hyperfederation," except as required for reasonable and customary use in describing
         the origin of the Licensed Work.
         
         ## 9. Termination
         
         Any use of the Licensed Work in violation of this License automatically terminates
         Your rights under this License for the current and all other versions of the Licensed
         Work. Your rights may be reinstated only by a writing signed by the Licensor.
         
         ## 10. Disclaimer of Warranty and Limitation of Liability
         
         TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
         AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED,
         INCLUDING WITHOUT LIMITATION ANY WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS
         FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE.
         
         TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL THE LICENSOR BE
         LIABLE TO YOU FOR ANY DAMAGES ARISING OUT OF OR RELATING TO THIS LICENSE OR THE USE
         OF THE LICENSED WORK, WHETHER IN CONTRACT, TORT, OR OTHERWISE.
Classifier: License :: Other/Proprietary License
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: haybarn>=1.5.4rc1
Requires-Dist: click>=8.1
Requires-Dist: rich>=13
Requires-Dist: pytz>=2024.1
Maintainer: Query Farm LLC
Maintainer-email: Query Farm LLC <hello@query.farm>
Requires-Python: >=3.11
Project-URL: Homepage, https://query.farm
Project-URL: Repository, https://github.com/Query-farm/vgi-lint-check
Project-URL: Issues, https://github.com/Query-farm/vgi-lint-check/issues
Description-Content-Type: text/markdown

# vgi-lint

A `pydoclint`-style **metadata-quality linter for VGI workers**. It attaches to an
arbitrary VGI worker, reads everything the worker contributes through DuckDB
system tables, and reports quality findings — missing descriptions, undocumented
columns/functions, absent or malformed example queries, untagged objects, and
more — with a quality score, per-data-version baselines, and machine output for
coding agents.

It works with **any** VGI worker regardless of implementation language (Python,
Go, Rust, Java, TypeScript, …): it treats the worker as a black box and inspects
only what surfaces post-attach.

## Install / run

```bash
uv sync                      # haybarn is RC-only; prerelease = "allow" is set
uv run vgi-lint --help
```

## Quick start

```bash
# Lint a local subprocess worker
uv run vgi-lint 'uv run volcano_worker.py'

# Lint a no-auth HTTP worker
uv run vgi-lint http://localhost:9009

# Machine output for a coding agent / CI
uv run vgi-lint http://localhost:9009 --format agent
uv run vgi-lint http://localhost:9009 --format json
```

In a worker's own repo, add a `[tool.vgi-lint-check]` block (see `vgi-lint init`)
with a `location`, then just run `vgi-lint` with no arguments.

> v1 supports **local subprocess** and **no-auth HTTP** workers. Authenticated
> (OAuth) workers are not yet supported.

## What it checks

Object coverage: schemas, tables, views, columns, scalar functions, macros,
settings, and pragmas. Rule families:

| Family | Codes | Examples |
| --- | --- | --- |
| Descriptions | VGI1xx | schema/table/view comment, `vgi.description_llm`, `vgi.description_md` |
| Columns | VGI2xx | column-comment coverage, comment-not-echo |
| Functions | VGI3xx | function/macro description, parameter documentation, macro examples |
| Tags | VGI4xx | required tag keys, reserved-tag validity |
| Examples | VGI5xx | `vgi.example_queries` present, valid JSON, complete entries, **catalog-qualified** |
| Settings | VGI6xx | setting descriptions |
| Pragmas | VGI7xx | pragma descriptions |
| Execution | VGI9xx | example queries bind/execute (opt-in, `--execute`) |

Run `vgi-lint rules` to list every rule, or `vgi-lint explain VGI112` for one.

## Data versions

A VGI worker can publish multiple data versions whose metadata differs. The tool
can lint one or all of them and compare quality across versions:

```bash
uv run vgi-lint versions <location>            # list published versions
uv run vgi-lint <location> --data-version 2.0.0
uv run vgi-lint <location> --all-data-versions # per-version report + comparison
```

## Baselines (grandfathering)

Adopt the linter on an existing worker without a wall of failures: record current
findings as a baseline, then fail CI only on **new** findings. Baselines are
per data version (`<prefix>.<version>.json`).

```bash
uv run vgi-lint <location> --baseline vgi-lint-baseline --update-baseline
uv run vgi-lint <location> --baseline vgi-lint-baseline --fail-on warning
```

## Configuration

`[tool.vgi-lint-check]` in `pyproject.toml` (or a dedicated `vgi-lint.toml`):

```toml
[tool.vgi-lint-check]
location = "uv run worker.py"
select = ["ALL"]
ignore = ["VGI113"]
fail_on = "error"

[tool.vgi-lint-check.severity]
VGI201 = "error"

[tool.vgi-lint-check.options]
required_schema_tags = ["provider", "domain"]
column_comment_min_ratio = 0.8

[tool.vgi-lint-check.per-object]
"volcanos.hans.*" = { ignore = ["VGI112"] }
```

Precedence: defaults < `pyproject.toml` < `vgi-lint.toml` < CLI flags.

## Exit codes

`0` clean (or below `--fail-on`) · `1` config/tool error · `2` findings ≥
`--fail-on` (regressions only when a baseline is set) · `3` connection error.

## Development

```bash
uv run pytest               # unit tests (offline)
uv run pytest --run-live    # also run live tests against real workers
uv build                    # build sdist + wheel into dist/
```

## Releasing (GitHub Actions → PyPI)

Publishing is automated via GitHub Actions using **PyPI Trusted Publishing**
(OIDC — no API token secret to store):

- `.github/workflows/ci.yml` runs the offline test suite (Python 3.11–3.13) and
  a smoke build on every push/PR.
- `.github/workflows/publish.yml` builds, validates (`twine check`), and uploads
  to PyPI when a **GitHub Release is published**. It first checks that the
  release tag matches the `version` in `pyproject.toml`.

One-time setup on PyPI (Trusted Publisher), under the project's *Publishing*
settings (use a "pending publisher" before the first release):

| Field | Value |
| --- | --- |
| Owner | `Query-farm` |
| Repository | `vgi-lint-check` |
| Workflow | `publish.yml` |
| Environment | `pypi` |

Also create a GitHub Environment named `pypi` in the repo settings (it gates the
publish job and is referenced for the OIDC claim).

To cut a release:

```bash
# bump version in pyproject.toml, commit, then tag + create the release
git tag v0.1.0 && git push origin v0.1.0
gh release create v0.1.0 --generate-notes
```

The release publishing event triggers the workflow. (Prefer a token instead of
OIDC? Replace the `publish` job's trusted-publishing step with
`pypa/gh-action-pypi-publish` configured with `password: ${{ secrets.PYPI_API_TOKEN }}`
and add that repository secret.)
