Router that virtually distributes inference across connected devices in the home.
Go
#!/usr/bin/env python3
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
"""Parse and validate PAIR pull request release-intent blocks (v1).
Three numbers, each with one job:
- the **release** version in `desktop/package.json`, which is what users
install. It is never declared in an intent block: it patch-bumps
automatically whenever an intent declares a release, and a minor or major
release is a deliberate manual bump at cut time.
- **services** in `services/versions.json`, the services suite version that
stamps the standalone installer and Go `main.Version`.
- **components.\\*** in `services/versions.json`, per-binary SemVer.
Only the last two are declared, because only they carry SemVer meaning that a
human has to judge.
"""
from __future__ import annotations
import json
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Literal
BumpKind = Literal['none', 'patch', 'minor', 'major']
BUMP_KINDS: tuple[BumpKind, ...] = ('none', 'patch', 'minor', 'major')
BUMP_RANK: dict[BumpKind, int] = {'none': 0, 'patch': 1, 'minor': 2, 'major': 3}
# How hard to be about the block's key set not matching versions.json.
#
# - 'strict' — any mismatch fails. Used on pull requests, where a typo
# should be corrected rather than silently absorbed.
# - 'reject-unknown' — an unknown key fails; a missing key warns and is treated
# as none. Used when applying. An unknown key means the
# block was edited to something a pull request check would
# have rejected, which is worth failing on. A *missing* key
# is the legitimate case of a concurrent pull request having
# added a component since this one was written, and reading
# it as none is what its author meant.
# - 'lenient' — both warn. Local inspection only.
KeyPolicy = Literal['strict', 'reject-unknown', 'lenient']
INTENT_VERSION = 'v1'
# Canonical forms (template / docs). Parsers also accept HTML comments with
# optional internal whitespace — GitLab often collapses `<!-- foo -->` to
# `<!--foo-->` when the description is saved or re-rendered.
INTENT_START = f'<!-- pair-release-intent:{INTENT_VERSION} -->'
INTENT_END = f'<!-- /pair-release-intent:{INTENT_VERSION} -->'
ALLOW_OWNED_FILES_MARKER = '<!-- pair-release-intent-allow-owned-files -->'
_INTENT_START_RE = re.compile(
rf'<!--\s*pair-release-intent:{re.escape(INTENT_VERSION)}\s*-->'
)
_INTENT_END_RE = re.compile(
rf'<!--\s*/pair-release-intent:{re.escape(INTENT_VERSION)}\s*-->'
)
_ALLOW_OWNED_FILES_RE = re.compile(
r'<!--\s*pair-release-intent-allow-owned-files\s*-->'
)
BOT_COMMIT_PREFIX = '[release-intent]'
APPLIES_PR_TRAILER_PREFIX = 'Applies-PR: #'
# Path-granular, and check_forbidden_paths rejects any edit to a listed file.
# desktop/package.json is deliberately absent even though the bot writes its
# `version`: dependency work touches that file constantly, so listing it would
# block ordinary pull requests.
BOT_OWNED_MODIFY_PATHS = (
'services/versions.json',
'CHANGELOG.md',
)
SERVICES_CHANGELOG_PATH = 'services/changelog.md'
REPO_ROOT = Path(__file__).resolve().parents[2]
VERSIONS_PATH = REPO_ROOT / 'services' / 'versions.json'
CHANGELOG_PATH = REPO_ROOT / 'CHANGELOG.md'
PACKAGE_JSON_PATH = REPO_ROOT / 'desktop' / 'package.json'
PACKAGE_LOCK_PATH = REPO_ROOT / 'desktop' / 'package-lock.json'
VERSIONS_COMMENT = (
'Single source of truth for all version numbers. See VERSIONING.md for bump rules.'
)
@dataclass(frozen=True)
class ReleaseIntent:
changelog_title: str
changelog_body: str
bumps: dict[str, BumpKind]
@property
def has_release(self) -> bool:
return any(kind != 'none' for kind in self.bumps.values())
@dataclass(frozen=True)
class VersionsManifest:
services: str
components: dict[str, str]
@property
def bump_keys(self) -> list[str]:
return ['services', *sorted(self.components)]
def parse_versions(text: str, source: str) -> tuple[VersionsManifest, dict[str, Any]]:
"""Parse a versions manifest. `source` names it in errors."""
raw_obj: Any = json.loads(text)
if not isinstance(raw_obj, dict):
raise ValueError(f'{source}: top-level value must be a JSON object')
raw: dict[str, Any] = raw_obj
components_raw = raw.get('components')
if not isinstance(components_raw, dict) or not components_raw:
raise ValueError(f'{source}: missing non-empty components object')
components: dict[str, str] = {}
for key, value in components_raw.items():
if not isinstance(key, str) or not isinstance(value, str):
raise ValueError(f'{source}: component entries must be string→string')
components[key] = value
services = raw.get('services')
if not isinstance(services, str) or not services:
raise ValueError(f'{source}: services must be a non-empty string')
return (VersionsManifest(services=services, components=components), raw)
def read_release_version(text: str, source: str) -> str:
"""The release version from a desktop/package.json body."""
raw: Any = json.loads(text)
if not isinstance(raw, dict):
raise ValueError(f'{source}: top-level value must be a JSON object')
version = raw.get('version')
if not isinstance(version, str) or not version:
raise ValueError(f'{source}: version must be a non-empty string')
return version
def load_release_version(path: Path = PACKAGE_JSON_PATH) -> str:
return read_release_version(path.read_text(encoding='utf-8'), str(path))
_PACKAGE_VERSION_RE = re.compile(r'^(?P<lead>\s*"version"\s*:\s*")[^"]*(?P<tail>")', re.M)
def render_package_json(text: str, version: str) -> str:
"""Replace only the version value, leaving the rest byte-for-byte intact.
desktop/package.json is hand-maintained, so it is rewritten surgically
rather than re-serialized: a json.dumps round trip would reformat the whole
file and bury the one-line bump in an unreviewable diff.
"""
replaced, count = _PACKAGE_VERSION_RE.subn(
lambda m: f'{m.group("lead")}{version}{m.group("tail")}', text, count=1
)
if count != 1:
raise ValueError('Could not locate a single "version" field in package.json')
return replaced
_LOCK_ROOT_PACKAGE_RE = re.compile(r'"packages"\s*:\s*\{\s*""\s*:\s*\{')
def render_package_lock(text: str, version: str) -> str:
"""Set both copies of the release version in desktop/package-lock.json.
npm records the root package's version at the top level and again under
packages[""], and both must match package.json. Each is replaced in place,
as in render_package_json, and the result is compared with a parsed edit so
a layout that puts some other "version" first fails here rather than
committing a lockfile with the wrong entry changed.
"""
expected: Any = json.loads(text)
if not isinstance(expected, dict):
raise ValueError('package-lock.json: top-level value must be a JSON object')
packages = expected.get('packages')
root = packages.get('') if isinstance(packages, dict) else None
if not isinstance(root, dict) or 'version' not in expected or 'version' not in root:
raise ValueError('package-lock.json: missing version or packages[""].version')
expected['version'] = version
root['version'] = version
def substitute(segment: str) -> tuple[str, int]:
return _PACKAGE_VERSION_RE.subn(
lambda m: f'{m.group("lead")}{version}{m.group("tail")}', segment, count=1
)
root_match = _LOCK_ROOT_PACKAGE_RE.search(text)
if root_match is None:
raise ValueError('package-lock.json: could not locate packages[""]')
head, head_count = substitute(text[: root_match.end()])
tail, tail_count = substitute(text[root_match.end() :])
rendered = head + tail
if head_count != 1 or tail_count != 1 or json.loads(rendered) != expected:
raise ValueError(
'package-lock.json: could not set the top-level and packages[""] '
'versions in place'
)
return rendered
def load_versions(path: Path = VERSIONS_PATH) -> tuple[VersionsManifest, dict[str, Any]]:
return parse_versions(path.read_text(encoding='utf-8'), str(path))
def extract_intent_block(description: str) -> str:
start_match = _INTENT_START_RE.search(description)
end_match = _INTENT_END_RE.search(description)
if (
start_match is None
or end_match is None
or end_match.start() <= start_match.start()
):
raise ValueError(
'Pull request body is missing the exact release-intent fences:\n'
f' {INTENT_START}\n'
f' ...\n'
f' {INTENT_END}\n'
'Copy them from the pull request template and fill them in.'
)
return description[start_match.end() : end_match.start()]
def _parse_section(inner: str, heading: str) -> str:
pattern = rf'(?m)^### {re.escape(heading)}\s*\n(.*?)(?=^### |\Z)'
match = re.search(pattern, inner, flags=re.S)
if not match:
raise ValueError(f'Missing required section heading: ### {heading}')
kept = [
line
for line in match.group(1).splitlines()
if not _is_ignorable_line(line.strip())
]
return '\n'.join(kept).strip()
def _parse_bump_kind(key: str, value: str) -> BumpKind:
for kind in BUMP_KINDS:
if value == kind:
return kind
raise ValueError(f'{key}: expected one of {", ".join(BUMP_KINDS)}, got {value!r}')
def _is_ignorable_line(line: str) -> bool:
return line.startswith('#') or (line.startswith('<!--') and line.endswith('-->'))
def _strip_bump_line(line: str) -> str:
if line.startswith(('- ', '* ')):
return line[2:].strip()
return line
def _parse_bumps(
section: str,
expected_keys: list[str],
*,
key_policy: KeyPolicy,
) -> dict[str, BumpKind]:
lines = [
_strip_bump_line(line.strip())
for line in section.splitlines()
if line.strip() and not _is_ignorable_line(line.strip())
]
if not lines:
raise ValueError('### Bumps section is empty')
parsed: dict[str, BumpKind] = {}
for line in lines:
if ':' not in line:
raise ValueError(
f'Bump line must be "- key: none|patch|minor|major", got: {line!r}'
)
key, value = line.split(':', 1)
key = key.strip()
value = value.strip().lower()
if key in parsed:
raise ValueError(f'Duplicate bump key: {key}')
kind = _parse_bump_kind(key, value)
parsed[key] = kind
expected = set(expected_keys)
got = set(parsed)
missing = sorted(expected - got)
extra = sorted(got - expected)
if missing or extra:
fatal_missing = missing if key_policy == 'strict' else []
fatal_extra = extra if key_policy in ('strict', 'reject-unknown') else []
if fatal_missing or fatal_extra:
parts: list[str] = []
if fatal_missing:
parts.append('missing keys: ' + ', '.join(fatal_missing))
if fatal_extra:
parts.append('unknown keys: ' + ', '.join(fatal_extra))
raise ValueError(
'Bump keys must match services/versions.json exactly ('
+ '; '.join(parts)
+ ')'
)
for key in missing:
print(
f'warning: {key} absent from the intent block; treating as none',
flush=True,
)
for key in extra:
print(
f'warning: ignoring unknown bump key {key} (not in versions.json)',
flush=True,
)
return {key: parsed.get(key, 'none') for key in expected_keys}
return {key: parsed[key] for key in expected_keys}
def _is_na(text: str) -> bool:
return text.strip().lower() == 'n/a'
def parse_release_intent(
description: str,
expected_bump_keys: list[str],
*,
key_policy: KeyPolicy = 'strict',
) -> ReleaseIntent:
inner = extract_intent_block(description)
title = _parse_section(inner, 'Changelog title')
body = _parse_section(inner, 'Changelog body')
bumps = _parse_bumps(
_parse_section(inner, 'Bumps'),
expected_bump_keys,
key_policy=key_policy,
)
if not title:
raise ValueError('Changelog title must be non-empty (use n/a when there is no release)')
if not body:
raise ValueError('Changelog body must be non-empty (use n/a when there is no release)')
component_keys = [key for key in expected_bump_keys if key != 'services']
max_component = max((BUMP_RANK[bumps[key]] for key in component_keys), default=0)
services_rank = BUMP_RANK[bumps['services']]
if max_component > 0 and services_rank == 0:
raise ValueError(
'services must be patch|minor|major when any component bump is not none'
)
if services_rank < max_component:
raise ValueError(
'services bump severity must be >= the highest component bump '
f'(services={bumps["services"]}, highest component rank requires >= '
f'{next(k for k, r in BUMP_RANK.items() if r == max_component)})'
)
has_release = services_rank > 0 or max_component > 0
if has_release:
if _is_na(title) or _is_na(body):
raise ValueError(
'Changelog title and body are required when any bump is not none '
'(do not use n/a)'
)
else:
if not _is_na(title) or not _is_na(body):
raise ValueError(
'When every bump is none, Changelog title and body must both be exactly n/a'
)
return ReleaseIntent(changelog_title=title, changelog_body=body, bumps=bumps)
def allows_owned_file_edits(description: str) -> bool:
return _ALLOW_OWNED_FILES_RE.search(description) is not None
def bump_semver(version: str, kind: BumpKind) -> str:
if kind == 'none':
return version
parts = version.split('.')
if len(parts) != 3 or not all(part.isdigit() for part in parts):
raise ValueError(f'Version must be MAJOR.MINOR.PATCH, got {version!r}')
major, minor, patch = (int(parts[0]), int(parts[1]), int(parts[2]))
if kind == 'major':
return f'{major + 1}.0.0'
if kind == 'minor':
return f'{major}.{minor + 1}.0'
return f'{major}.{minor}.{patch + 1}'
def apply_bumps(manifest: VersionsManifest, intent: ReleaseIntent) -> VersionsManifest:
services = bump_semver(manifest.services, intent.bumps['services'])
components = {
name: bump_semver(version, intent.bumps[name])
for name, version in manifest.components.items()
}
return VersionsManifest(services=services, components=components)
def render_versions_json(manifest: VersionsManifest, original: dict[str, Any]) -> str:
doc = dict(original)
doc.pop('product', None)
doc.pop('installer', None)
doc['$comment'] = VERSIONS_COMMENT
doc['services'] = manifest.services
doc['components'] = dict(manifest.components)
return json.dumps(doc, indent=2, ensure_ascii=False) + '\n'
def format_changelog_entry(
release_version: str, title: str, body: str, pr_ref: str
) -> str:
"""One changelog section. `pr_ref` is cited so an entry traces to its PR."""
bullets = '\n'.join(
line
if line.lstrip().startswith(('-', '*'))
else f'- {line}'
for line in body.strip().splitlines()
if line.strip()
)
suffix = f' (#{pr_ref})' if pr_ref else ''
return f'## {release_version} — {title.strip()}{suffix}\n\n{bullets}\n'
def prepend_changelog(existing: str, entry: str) -> str:
match = re.search(r'(?m)^## ', existing)
if not match:
raise ValueError('CHANGELOG.md has no ## release headings to prepend before')
insert_at = match.start()
return existing[:insert_at] + entry + '\n' + existing[insert_at:]
def applies_pr_trailer(pr_number: str) -> str:
return f'{APPLIES_PR_TRAILER_PREFIX}{pr_number}'
def check_forbidden_paths(changed_name_status: list[tuple[str, str]], description: str) -> None:
if allows_owned_file_edits(description):
return
errors: list[str] = []
for status, path in changed_name_status:
status = status.upper()
if path in BOT_OWNED_MODIFY_PATHS and status != 'D':
errors.append(
f'{path} is bot-owned; do not modify it in a pull request '
f'(declare bumps in the release-intent block instead)'
)
if path == SERVICES_CHANGELOG_PATH and status != 'D':
errors.append(
f'{path} is retired; delete it if present, do not add or edit it. '
'Product notes go in root CHANGELOG.md via the release-intent bot.'
)
if errors:
raise ValueError('Forbidden path changes:\n- ' + '\n- '.join(errors))