Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions .github/workflows/version-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ on:
- 'scripts/lib/paths.py'
- 'scripts/lib/version_policy.py'
- 'scripts/ci/check_frozen_policy.py'
- 'scripts/ci/check_consumer_catalog_changes.py'
- 'scripts/ci/ci_version_manager.py'

permissions:
Expand Down Expand Up @@ -172,6 +173,71 @@ jobs:
});
}

- name: Check consumer-significant catalog populations
id: consumer_catalog
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: |
python scripts/ci/check_consumer_catalog_changes.py \
--base-ref "$BASE_SHA" \
--comment-file pr-consumer-catalog-comment.md \
--github-summary
if [ -f pr-consumer-catalog-comment.md ]; then
echo "post_comment=true" >> "$GITHUB_OUTPUT"
else
echo "post_comment=false" >> "$GITHUB_OUTPUT"
fi

- name: Reconcile consumer catalog warning on PR
if: steps.consumer_catalog.outcome == 'success'
uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
with:
script: |
const fs = require('fs');
const marker = '<!-- consumer-catalog-change-check -->';
const commentPath = 'pr-consumer-catalog-comment.md';
const comments = await github.paginate(
github.rest.issues.listComments,
{
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
per_page: 100,
},
);
const existing = comments.find(
(c) =>
c.body &&
c.body.includes(marker) &&
c.user?.login === 'github-actions[bot]',
);
if (!fs.existsSync(commentPath)) {
if (existing) {
await github.rest.issues.deleteComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: existing.id,
});
}
return;
}
const body = fs.readFileSync(commentPath, 'utf8');
if (existing) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: existing.id,
body,
});
} else {
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body,
});
}

- name: Detect release version vs base branch (PyPI comment gate)
id: release_detect
run: |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6324,7 +6324,7 @@
"assets": [
{
"filename": "index.mcp.json",
"sha256": "f969cc0ecd889b0216f936411e01887aec31de7b2b413b390c2cc9a98b5c1299"
"sha256": "e965dff54be7973be20a9bb1191929ff84497520465c85727f1b8026793b9560"
}
],
"cdn": {
Expand Down
97 changes: 97 additions & 0 deletions packages/core/tests/test_consumer_catalog_changes.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import importlib.util
import sys
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[3]
SCRIPT = REPO_ROOT / "scripts" / "ci" / "check_consumer_catalog_changes.py"
SPEC = importlib.util.spec_from_file_location("check_consumer_catalog_changes", SCRIPT)
assert SPEC and SPEC.loader
CHECK = importlib.util.module_from_spec(SPEC)
sys.modules[SPEC.name] = CHECK
SPEC.loader.exec_module(CHECK)


def category(title, templates, *, essential=False, module="default"):
return {
"moduleName": module,
"title": title,
"isEssential": essential,
"templates": templates,
}


@pytest.fixture
def populated_catalog():
return [
category("Getting Started", [{"name": "default"}], essential=True),
category("Image", [{"name": "flux"}]),
category("Partners", [{"name": "partner", "openSource": False}]),
]


@pytest.mark.parametrize(
"replacement",
[
[],
[category("Start Here", [{"name": "default"}], essential=True)],
[category("Getting Started", [{"name": "default"}])],
[category("Getting Started", [], essential=True)],
],
ids=["removed", "renamed", "declassified", "emptied"],
)
def test_flags_disappearance_of_essential_category(populated_catalog, replacement):
after = [*replacement, *populated_catalog[1:]]

impacts = CHECK.detect_impacts(populated_catalog, after)

assert [impact.kind for impact in impacts] == ["essential_category_removed"]


def test_flags_elimination_of_partner_population(populated_catalog):
after = [populated_catalog[0], populated_catalog[1]]

impacts = CHECK.detect_impacts(populated_catalog, after)

assert [impact.kind for impact in impacts] == ["partner_population_removed"]


def test_allows_shrinking_preserved_consumer_populations(populated_catalog):
before = [
category(
"Getting Started",
[{"name": "default"}, {"name": "second"}],
essential=True,
),
category(
"Partners",
[{"name": "a", "openSource": False}, {"name": "b", "openSource": False}],
),
]
after = [
category("Getting Started", [{"name": "default"}], essential=True),
category("Partners", [{"name": "a", "openSource": False}]),
]

assert CHECK.detect_impacts(before, after) == []


def test_allows_removal_or_rename_of_ordinary_category(populated_catalog):
after = [populated_catalog[0], populated_catalog[2], category("Pictures", [{"name": "flux"}])]

assert CHECK.detect_impacts(populated_catalog, after) == []


def test_allows_module_move_when_frontend_category_id_is_unchanged(populated_catalog):
after = [
category(
"Getting Started",
[{"name": "default"}],
essential=True,
module="new-module",
),
*populated_catalog[1:],
]

assert CHECK.detect_impacts(populated_catalog, after) == []
3 changes: 2 additions & 1 deletion scripts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ Also runs workflow I/O extraction via `generate_workflow_io.py` before locale sy
| Doc | Topic |
|-----|-------|
| [`docs/frozen_bundles.md`](docs/frozen_bundles.md) | Frozen legacy `media-*` bundles, inventory, CI, publishing |
| [`docs/consumer_catalog_changes.md`](docs/consumer_catalog_changes.md) | Producer-side warnings for removal of frontend-visible catalog populations |
| [`docs/whitelist.md`](docs/whitelist.md) | `whitelist.json` for link/model/custom-node checks |
| [`docs/check_input_assets.md`](docs/check_input_assets.md) | Input asset validation |

Expand All @@ -68,7 +69,7 @@ Also runs workflow I/O extraction via `generate_workflow_io.py` before locale sy
| `sync-custom-nodes.yml` | `sync/sync_custom_nodes.py` |
| `sync-template-index.yml` | `sync/sync_data.py --index-only` (locale field sync; does not rewrite `usage`) |
| `validate-is-app.yml` | `sync/sync_is_app.py --check` |
| `version-check.yml`, `publish.yml` | `ci/ci_version_manager.py`, `ci/check_frozen_policy.py`, `sync/sync_bundles.py`, `sync/sync_frozen_inventory.py`, `ci/*` |
| `version-check.yml`, `publish.yml` | `ci/ci_version_manager.py`, `ci/check_frozen_policy.py`, `ci/check_consumer_catalog_changes.py`, `sync/sync_bundles.py`, `sync/sync_frozen_inventory.py`, `ci/*` |
| `build-test.yml` | `sync/sync_bundles.py` |

## Maintenance tools (not in CI)
Expand Down
161 changes: 161 additions & 0 deletions scripts/ci/check_consumer_catalog_changes.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
#!/usr/bin/env python3
"""Warn when a catalog diff removes frontend-visible template populations.

This intentionally uses only producer-owned signals already consumed by the
frontend: ``isEssential`` categories and the ``openSource: false`` partner-node
population. It does not attempt to prove that a consumer release is compatible.
"""
from __future__ import annotations

import argparse
import json
import os
import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path

_LIB_DIR = Path(__file__).resolve().parent.parent / "lib"
if str(_LIB_DIR) not in sys.path:
sys.path.insert(0, str(_LIB_DIR))

from paths import REPO_ROOT # noqa: E402

INDEX_PATH = "templates/index.json"
COMMENT_MARKER = "<!-- consumer-catalog-change-check -->"


@dataclass(frozen=True)
class CatalogImpact:
kind: str
detail: str


def _essential_populations(index: list[dict]) -> dict[str, int]:
return {
str(category.get("title", "")): len(category.get("templates", []))
for category in index
if category.get("isEssential") is True and category.get("templates")
}


def _partner_node_count(index: list[dict]) -> int:
return sum(
1
for category in index
for template in category.get("templates", [])
if template.get("openSource") is False
)


def detect_impacts(before: list[dict], after: list[dict]) -> list[CatalogImpact]:
"""Return consumer-visible populations present before but absent after."""
impacts: list[CatalogImpact] = []
old_essential = _essential_populations(before)
new_essential = _essential_populations(after)

for title, old_count in sorted(old_essential.items()):
if title not in new_essential:
impacts.append(
CatalogImpact(
kind="essential_category_removed",
detail=(
f"Essential category `{title}` had {old_count} template(s) and is now "
"removed, renamed, empty, or no longer marked `isEssential`. Frontends "
"may persist or request its generated category identifier."
),
)
)

old_partner_count = _partner_node_count(before)
new_partner_count = _partner_node_count(after)
if old_partner_count and not new_partner_count:
impacts.append(
CatalogImpact(
kind="partner_population_removed",
detail=(
f"The `openSource: false` partner-node population fell from "
f"{old_partner_count} template(s) to zero, removing the frontend's "
"Partner Nodes navigation population."
),
)
)

return impacts


def read_index_at_ref(ref: str) -> list[dict]:
if not ref or ref.startswith("-") or "\0" in ref:
raise ValueError(f"Invalid git ref: {ref!r}")
raw = subprocess.check_output(
["git", "show", f"{ref}:{INDEX_PATH}"], cwd=REPO_ROOT, text=True
)
data = json.loads(raw)
if not isinstance(data, list):
raise ValueError(f"{INDEX_PATH} at {ref} is not a list")
return data


def read_current_index() -> list[dict]:
data = json.loads((REPO_ROOT / INDEX_PATH).read_text(encoding="utf-8"))
if not isinstance(data, list):
raise ValueError(f"{INDEX_PATH} is not a list")
return data


def build_report(impacts: list[CatalogImpact]) -> str:
lines = [
COMMENT_MARKER,
"## Consumer-significant catalog change",
"",
"Frontend-visible template populations changed. Confirm dependent consumers no longer "
"request the removed category or population before publishing this catalog.",
"",
*[f"- {impact.detail}" for impact in impacts],
"",
"<details><summary>Full context for agent readers</summary>",
"",
"This is an informational, producer-only diff check. It detects disappearance of "
"non-empty `isEssential` categories and elimination of all `openSource: false` templates. "
"It cannot verify frontend versions, persisted user selections, rollout order, or "
"arbitrary filters. See `scripts/docs/consumer_catalog_changes.md`.",
"",
"</details>",
"",
"<sub>Generated by `scripts/ci/check_consumer_catalog_changes.py`</sub>",
]
return "\n".join(lines) + "\n"


def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--base-ref", required=True)
parser.add_argument("--comment-file", type=Path)
parser.add_argument("--github-summary", action="store_true")
args = parser.parse_args()

try:
impacts = detect_impacts(read_index_at_ref(args.base_ref), read_current_index())
except Exception as exc:
print(f"Error: consumer catalog change check failed: {exc}", file=sys.stderr)
return 1

if not impacts:
print("No consumer-significant catalog removals detected.")
return 0

report = build_report(impacts)
for impact in impacts:
print(f"::warning file={INDEX_PATH}::{impact.detail}")
if args.comment_file:
args.comment_file.write_text(report, encoding="utf-8")
summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
if args.github_summary and summary_path:
Path(summary_path).write_text(
report.replace(COMMENT_MARKER, "").strip() + "\n", encoding="utf-8"
)
return 0


if __name__ == "__main__":
raise SystemExit(main())
29 changes: 29 additions & 0 deletions scripts/docs/consumer_catalog_changes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Consumer-significant catalog changes

`scripts/ci/check_consumer_catalog_changes.py` compares a pull request's
`templates/index.json` with its base revision and posts an informational warning when:

- a previously non-empty `isEssential` category disappears, is renamed, becomes empty, or loses
`isEssential`; or
- the `openSource: false` population falls to zero, removing the Partner Nodes population.

These are repository-owned fields that the ComfyUI frontend currently uses to build navigation.
The check deliberately does not maintain frontend category IDs or fetch another repository.

## Limitations

This check catches a risky producer-side diff; it cannot distinguish an accidental removal from a
coordinated one. It cannot prove consumer compatibility, inspect released frontend versions,
account for persisted user selections, validate rollout order, or discover arbitrary filters in
consumer code. It is therefore warning-only.

If blocking enforcement becomes necessary, the missing contract is a versioned, consumer-authored
list of catalog selectors/populations that must remain non-empty, plus an explicit compatibility
version or coordinated-removal acknowledgement. That contract should be supplied to this repository
as release input rather than inferred from frontend source or represented as a new catalog ID system.

Run locally against a branch or commit:

```bash
python scripts/ci/check_consumer_catalog_changes.py --base-ref origin/main
```
Loading
Loading