fix(sync): gate collection rebuilds on the info fields the converter reads

The canonical fingerprint now includes title, description, and contact name
and email alongside paths and components, matching what the collection name
and description read from info.

Adds scripts/sync.test.ts covering the gate, including a case where only the
description changes. CI and the pre-push hook now run bun test alongside
typecheck, lint, and the dry run sync.

Author: ph33nx

.github/workflows/ci.yml

@@ -24,5 +24,8 @@ jobs:
       - name: Typecheck
         run: bun typecheck
 
+      - name: Test
+        run: bun test
+
       - name: Validate discovery and conversion (no Postman writes)
         run: bun run sync --dry-run

lefthook.yml

@@ -20,3 +20,6 @@ pre-push:
     sync-dry-run:
       run: bun run sync --dry-run
       priority: 3
+    test:
+      run: bun test
+      priority: 4

package.json

@@ -7,7 +7,8 @@
 	"scripts": {
 		"sync": "bun run scripts/sync.ts",
 		"check": "biome check . --fix",
-		"typecheck": "tsc --noEmit"
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
 	},
 	"license": "MIT",
 	"repository": {

scripts/sync.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'bun:test';
+import { canonical, fingerprint } from './sync';
+
+/** Minimal spec shape the fingerprint reads from. Extra `info` fields (version, license, contact.url) are included where a case needs them. */
+function spec(overrides: {
+	title?: string;
+	description?: string;
+	contact?: { name?: string; email?: string; url?: string };
+	version?: string;
+	paths?: Record<string, unknown>;
+	components?: Record<string, unknown>;
+}) {
+	return {
+		info: {
+			title: overrides.title ?? 'Forecast API',
+			description:
+				overrides.description ?? 'Merges transits into one timeline.',
+			contact: overrides.contact,
+			version: overrides.version,
+		},
+		paths: overrides.paths ?? { '/forecast': { get: {} } },
+		components: overrides.components ?? { schemas: {} },
+	};
+}
+
+describe('fingerprint', () => {
+	test('is stable when nothing changes', () => {
+		expect(fingerprint(spec({}))).toBe(fingerprint(spec({})));
+	});
+
+	test('changes when only info.description changes and paths/components are identical', () => {
+		const before = spec({ description: '14 domains, 209+ endpoints.' });
+		const after = spec({ description: '18 domains, 258+ endpoints.' });
+		expect(fingerprint(before)).not.toBe(fingerprint(after));
+	});
+
+	test('changes when only info.title changes', () => {
+		const before = spec({ title: 'Forecast API' });
+		const after = spec({ title: 'Forecast API v2' });
+		expect(fingerprint(before)).not.toBe(fingerprint(after));
+	});
+
+	test('changes when only contact.name or contact.email changes', () => {
+		const before = spec({ contact: { name: 'RoxyAPI Support' } });
+		const after = spec({ contact: { name: 'Someone Else' } });
+		expect(fingerprint(before)).not.toBe(fingerprint(after));
+
+		const beforeEmail = spec({ contact: { name: 'RoxyAPI Support' } });
+		const afterEmail = spec({
+			contact: { name: 'RoxyAPI Support', email: 'support@roxyapi.com' },
+		});
+		expect(fingerprint(beforeEmail)).not.toBe(fingerprint(afterEmail));
+	});
+
+	test('does not change for info fields the collection never surfaces (version, contact.url)', () => {
+		const before = spec({
+			version: '1.0.0',
+			contact: { url: 'https://roxyapi.com/contact' },
+		});
+		const after = spec({
+			version: '2.0.0',
+			contact: { url: 'https://roxyapi.com/other' },
+		});
+		expect(fingerprint(before)).toBe(fingerprint(after));
+	});
+
+	test('changes when paths or components change', () => {
+		const before = spec({ paths: { '/forecast': { get: {} } } });
+		const after = spec({
+			paths: { '/forecast': { get: {} }, '/forecast/digest': { get: {} } },
+		});
+		expect(fingerprint(before)).not.toBe(fingerprint(after));
+
+		const beforeSchema = spec({ components: { schemas: { Forecast: {} } } });
+		const afterSchema = spec({
+			components: { schemas: { Forecast: {}, Digest: {} } },
+		});
+		expect(fingerprint(beforeSchema)).not.toBe(fingerprint(afterSchema));
+	});
+
+	test('is insensitive to key order, matching the canonical semantic diff', () => {
+		const a = {
+			info: { title: 'X', description: 'd' },
+			paths: { '/a': {}, '/b': {} },
+			components: { schemas: {} },
+		};
+		const b = {
+			info: { description: 'd', title: 'X' },
+			components: { schemas: {} },
+			paths: { '/b': {}, '/a': {} },
+		};
+		expect(fingerprint(a)).toBe(fingerprint(b));
+	});
+});
+
+describe('canonical', () => {
+	test('sorts object keys recursively so JSON.stringify output is order independent', () => {
+		const a = canonical({ b: 1, a: { d: 2, c: 3 } });
+		const b = canonical({ a: { c: 3, d: 2 }, b: 1 });
+		expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+	});
+});

scripts/sync.ts

@@ -6,7 +6,7 @@
  *
  * Pipeline per run:
  *  1. Discover domains: read the combined spec, take every distinct first path segment, keep the ones that serve their own per-domain spec (a 200 at `/api/v2/{slug}/openapi.json`). App utility routes (languages, usage) return 401 and drop out, so no exclusion list is needed.
- *  2. Change-gate: compare the canonical `{ paths, components }` of each live per-domain spec against the vendored baseline in `specs/{slug}.json`. Unchanged and already-published domains are skipped (zero Postman writes).
+ *  2. Change-gate: compare the canonical `{ paths, components, info }` of each live per-domain spec against the vendored baseline in `specs/{slug}.json`, where `info` is only the slice openapi-to-postmanv2 actually reads (title, description, contact name/email; see `collectionInfo`). Unchanged and already-published domains are skipped (zero Postman writes).
  *  3. Build: rewrite the spec server to the absolute domain base so request URLs resolve correctly, convert with openapi-to-postmanv2, stamp a `roxySlug` provenance variable plus an empty `apiKey` so a forked collection is self-contained.
  *  4. Publish: resolve the existing collection UID (cache, then workspace name match), then PUT it; create + capture the UID when it does not exist yet.
  *  5. Persist: write `specs/{slug}.json` (next run's diff baseline), `collections/{slug}.json` (browsable artifact), and the auto-written `collections.json` UID cache. The workflow commits these back.
@@ -38,7 +38,13 @@ const COLLECTIONS_DIR = join(ROOT, 'collections');
 const CACHE_PATH = join(ROOT, 'collections.json');
 
 interface OpenAPISpec {
-	info: { title: string };
+	info: {
+		title: string;
+		description?: string;
+		version?: string;
+		contact?: { name?: string; email?: string; url?: string };
+		license?: unknown;
+	};
 	servers?: unknown[];
 	paths: Record<string, unknown>;
 	components?: Record<string, unknown>;
@@ -71,14 +77,14 @@ const PRUNE = args.has('--prune');
 const POSTMAN_API_KEY = process.env.POSTMAN_API_KEY;
 const DRY_RUN = args.has('--dry-run') || !POSTMAN_API_KEY;
 
-if (!POSTMAN_API_KEY && !args.has('--dry-run')) {
+if (import.meta.main && !POSTMAN_API_KEY && !args.has('--dry-run')) {
 	console.error(
 		'POSTMAN_API_KEY is not set. Export it to publish, or pass --dry-run to validate without writing.',
 	);
 	process.exit(1);
 }
 
-function canonical(value: unknown): unknown {
+export function canonical(value: unknown): unknown {
 	if (Array.isArray(value)) return value.map(canonical);
 	if (value && typeof value === 'object') {
 		const source = value as Record<string, unknown>;
@@ -90,10 +96,29 @@ function canonical(value: unknown): unknown {
 	return value;
 }
 
+/**
+ * The only `info` fields openapi-to-postmanv2 surfaces in the published collection: `title`
+ * becomes the collection name (`getCollectionName`), `description` plus `contact.name` /
+ * `contact.email` become its description (`getCollectionDescription`). `version`, `license`, and
+ * `contact.url` never reach the output, so they stay out of the fingerprint on purpose.
+ */
+export function collectionInfo(spec: OpenAPISpec): Record<string, unknown> {
+	return {
+		title: spec.info.title,
+		description: spec.info.description ?? '',
+		contactName: spec.info.contact?.name ?? null,
+		contactEmail: spec.info.contact?.email ?? null,
+	};
+}
+
 /** Stable fingerprint of the parts of a spec that affect the generated collection. */
-function fingerprint(spec: OpenAPISpec): string {
+export function fingerprint(spec: OpenAPISpec): string {
 	return JSON.stringify(
-		canonical({ paths: spec.paths, components: spec.components ?? null }),
+		canonical({
+			paths: spec.paths,
+			components: spec.components ?? null,
+			info: collectionInfo(spec),
+		}),
 	);
 }
 
@@ -320,4 +345,5 @@ async function main(): Promise<void> {
 	if (removed.length) console.log(`  pruned:    ${removed.join(', ')}`);
 }
 
-await main();
+// Guarded so tests can import fingerprint/canonical/collectionInfo without running the pipeline.
+if (import.meta.main) await main();