feat: add --publish-to-uq flag for understand-quickly registry integration by amacsmith · Pull Request #449 · tirth8205/code-review-graph

amacsmith · 2026-05-08T04:35:06Z

Why

looptech-ai/understand-quickly is a public registry of code-knowledge graphs with an MCP server and a stable registry.json API. code-review-graph is one of the first-class formats it already supports (code-review-graph@1). Wiring a --publish-to-uq flag into the existing visualize subcommand means any user who runs code-review-graph can land in the registry with one flag — and AI agents using the registry's MCP server can consume the graph immediately.

Discoverability. Every published artifact appears at https://looptech-ai.github.io/understand-quickly/.
No infrastructure on either side. Graphs stay in the user's repo (.code-review-graph/graph.json) and are fetched from raw.githubusercontent.com; the registry only stores pointers.
Agent-consumable. Schema validation, drift detection (when metadata.commit is set), MCP server out of the box.

What changes

Add json to the existing --format choices on visualize. Runs export_graph_data() (the same dict the other formats are built from) and writes it to <data_dir>/graph.json (i.e. .code-review-graph/graph.json).
Add a --publish-to-uq flag on visualize. Implies --format json. After the JSON is written, fires a repository_dispatch (event_type=sync-entry) at looptech-ai/understand-quickly so the registry resyncs the entry. Owner/repo is derived from git remote get-url origin.
Embed metadata.tool, metadata.tool_version, metadata.generated_at, and (when in a git checkout) metadata.commit = git rev-parse HEAD on the exported dict alongside the existing nodes, edges, stats, flows, communities fields.
Self-contained in a new code_review_graph/publish.py module; the visualize handler delegates to it. Stdlib only (urllib.request) — no new dependencies.
One-line README mention next to the existing --format examples.

No-op default

--publish-to-uq is opt-in. Existing visualize invocations are unaffected. With the flag set but UNDERSTAND_QUICKLY_TOKEN unset, the tool writes the local artifact as usual and prints one informational line — no network call, no exit-1. Same soft-fail behavior on HTTP errors (e.g. an unregistered repo): the JSON is written, a one-liner points at npx @understand-quickly/cli add, exit 0.

Token setup

The user adds a fine-grained GitHub PAT to their environment (or repo secrets, when run from CI):

Repository access: looptech-ai/understand-quickly only.
Permissions: Repository dispatches: write. Nothing else.

A drop-in workflow snippet lives at docs/integrations/sample-publish-workflow.yml.

Test plan

Unit tests added in tests/test_publish.py (9 cases) cover:

visualize without the flag (default --format html) is unchanged — the full existing suite still passes (1245 passed, 1 skipped, 2 xpassed locally).
build_publish_payload() embeds metadata.tool == \"code-review-graph\", metadata.tool_version, and an ISO-8601 metadata.generated_at. metadata.commit is a 40-hex sha when present.
--publish-to-uq with UNDERSTAND_QUICKLY_TOKEN unset writes the JSON and prints UNDERSTAND_QUICKLY_TOKEN not set; skipping repository_dispatch — urlopen is never called.
--publish-to-uq with the token set fires a single POST to https://api.github.com/repos/looptech-ai/understand-quickly/dispatches with body {\"event_type\":\"sync-entry\",\"client_payload\":{\"id\":\"<owner>/<repo>\"}} and an Authorization: Bearer ... header (mocked urlopen).
HTTPError from the dispatch (e.g. unregistered repo, 422) is soft-failed: the run still writes the JSON, prints dispatch failed ... npx @understand-quickly/cli add, and exits 0.
git remote get-url origin parsing handles both https://github.com/owner/repo(.git) and git@github.com:owner/repo(.git) shapes.

Manual smoke (optional): code-review-graph build && code-review-graph visualize --format json writes .code-review-graph/graph.json with metadata.commit matching git rev-parse HEAD.

Notes for the maintainer

The registry is in early adoption; this is opt-in for early users. Nothing in code-review-graph's existing surface needs to break.
Once a few users land in the registry via this path, we can add tirth8205/code-review-graph to the verified-publisher allowlist for auto-merge of registry updates.
Happy to iterate on naming (e.g. --publish vs --publish-to-uq), the JSON output path, or factor the publish module differently if you'd prefer.

Links

Registry: https://github.com/looptech-ai/understand-quickly
Integration protocol: https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
code-review-graph@1 schema: https://github.com/looptech-ai/understand-quickly/blob/main/schemas/code-review-graph@1.json
Sample workflow: https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/sample-publish-workflow.yml
Verified publishers: https://github.com/looptech-ai/understand-quickly/blob/main/docs/verified-publishers.md

…ation Adds a new opt-in publish path on the visualize subcommand: - New --format json choice that runs export_graph_data() and writes a registry-shaped JSON to <data_dir>/graph.json with a metadata block (tool, tool_version, generated_at, commit). - New --publish-to-uq flag that, after the JSON write, fires a repository_dispatch (event_type=sync-entry) at looptech-ai/understand-quickly so the registry resyncs the entry. Implies --format json. Owner/repo is derived from `git remote get-url origin`. Soft-fail behavior: - Without UNDERSTAND_QUICKLY_TOKEN, the JSON is still written and the dispatch is skipped with a one-line informational message — the registry's nightly sync will pick the change up. - HTTP failures (e.g. unregistered repo) print a one-liner pointing at `npx @understand-quickly/cli add`; the visualize run still exits 0. Existing visualize invocations are unchanged. Default format remains html. The new module lives in code_review_graph/publish.py with unit tests in tests/test_publish.py covering metadata embedding, the no-token soft skip, the happy-path dispatch (mocked urlopen), HTTP failure handling, and origin URL parsing for both ssh and https. Background: looptech-ai/understand-quickly is a public registry of code-knowledge graphs that supports code-review-graph as a first-class format (code-review-graph@1). This wires the existing export pipeline into the registry's documented protocol. Refs: https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md

Copilot

Pull request overview

Adds an opt-in integration to publish a code-review-graph@1-compatible JSON artifact and (optionally) trigger an understand-quickly registry resync from the visualize command.

Changes:

Adds json as a visualize --format option and writes .code-review-graph/graph.json.
Introduces --publish-to-uq on visualize to (optionally) fire a repository_dispatch to looptech-ai/understand-quickly.
Adds a new code_review_graph/publish.py module plus unit tests covering payload metadata, JSON output, dispatch behavior, and git remote parsing.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
`tests/test_publish.py`	Adds unit tests for JSON export payload + dispatch soft-fail behavior and git remote parsing.
`README.md`	Documents `--format json` and `--publish-to-uq` usage.
`code_review_graph/publish.py`	Implements JSON export with metadata and optional GitHub `repository_dispatch` publish step.
`code_review_graph/cli.py`	Wires `json` format and the new `--publish-to-uq` flag into the `visualize` command flow.

amacsmith · 2026-05-08T08:26:31Z

+            if publish_to_uq and fmt == "html":
+                fmt = "json"
+
+            if fmt == "json" or publish_to_uq:


Fixed in 314178b. The override is now if publish_to_uq and fmt != "json": and emits a stderr warning when the user explicitly passed a non-json/non-html format (html is the default, so we don't warn for it). Behavior now matches the help text — --publish-to-uq always implies --format json, surprises eliminated.

amacsmith · 2026-05-08T08:26:33Z

+metadata block looptech-ai/understand-quickly expects, writes the result to
+``<data_dir>/graph.json``, and optionally fires a ``repository_dispatch`` so
+the registry resyncs the entry. Gated on ``UNDERSTAND_QUICKLY_TOKEN`` — without
+it, the JSON is still written and the dispatch is skipped silently.


Fixed in 314178b. Aligned the docstring with the actual behavior: the token-missing path prints an informational message pointing at the nightly-sync fallback rather than failing silently. Kept the print() to preserve discoverability for users running --publish-to-uq without a token configured.

amacsmith · 2026-05-08T08:26:35Z

+def write_publish_json(store: GraphStore, repo_root: Path, output_path: Path) -> Path:
+    payload = build_publish_payload(store, repo_root)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(payload, indent=2, default=str))


Fixed in 314178b. write_publish_json() now passes encoding="utf-8" to Path.write_text(), matching the rest of the repo's file-write conventions and avoiding platform-dependent encodings on Windows.

- Force fmt='json' whenever --publish-to-uq is set; warn on explicit --format conflict (Copilot: cli.py:1015 silent override). - Align publish.py module docstring with actual behavior — token-missing branch prints an informational message rather than skipping silently. - Pass encoding='utf-8' to write_text() to match other file outputs and avoid platform-dependent encodings on Windows. Signed-off-by: Alex Macdonald-Smith <alex.macsmith@gmail.com>

amacsmith · 2026-05-08T08:26:36Z

Thanks @copilot — all three review items addressed in 314178b:

File	Issue	Fix
`code_review_graph/cli.py:1012`	`--publish-to-uq` only overrode `fmt` when it was `html`; non-default formats were silently ignored.	Now forces `fmt='json'` on any non-`json` value and emits a stderr warning when `--format` was explicitly set to something else. Help text and behavior match.
`code_review_graph/publish.py:7`	Docstring claimed dispatch was "skipped silently" when token missing, but `publish()` printed an informational message.	Aligned docstring — message stays (it points at the nightly-sync fallback so users running `--publish-to-uq` without a token aren't left guessing).
`code_review_graph/publish.py:99`	`write_text()` lacked `encoding="utf-8"` — inconsistent with other file outputs and risky on Windows.	Added `encoding="utf-8"`.

Tests: tests/test_publish.py — 9/9 passing.

Copilot AI review requested due to automatic review settings May 8, 2026 04:35

Copilot started reviewing on behalf of amacsmith May 8, 2026 04:35 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add --publish-to-uq flag for understand-quickly registry integration#449

feat: add --publish-to-uq flag for understand-quickly registry integration#449
amacsmith wants to merge 2 commits intotirth8205:mainfrom
amacsmith:feat/uq-publish

amacsmith commented May 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

amacsmith May 8, 2026

Uh oh!

amacsmith May 8, 2026

Uh oh!

amacsmith May 8, 2026

Uh oh!

amacsmith commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

amacsmith commented May 8, 2026

Why

What changes

No-op default

Token setup

Test plan

Notes for the maintainer

Links

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

amacsmith May 8, 2026

Choose a reason for hiding this comment

Uh oh!

amacsmith May 8, 2026

Choose a reason for hiding this comment

Uh oh!

amacsmith May 8, 2026

Choose a reason for hiding this comment

Uh oh!

amacsmith commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants