@usequeek/theme-check 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Queek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @usequeek/theme-check
+
+The rules a [Queek](https://usequeek.com) storefront theme is checked against, as a library.
+Most people want the command line instead: `npx queek-theme check` from
+[`@usequeek/theme-cli`](https://www.npmjs.com/package/@usequeek/theme-cli).
+
+```bash
+npm install --save-dev @usequeek/theme-check
+```
+
+```ts
+import { checkTheme, formatStylish, rejects } from '@usequeek/theme-check';
+
+const result = await checkTheme('theme');          // the folder with manifest.ts
+console.log(formatStylish(result, { color: true }));
+process.exitCode = rejects(result.findings).length > 0 ? 1 : 0;
+```
+
+Each finding: `rule` (a stable id), `severity` (`reject` blocks submission, `warn` is advice),
+`where`, `found`, `fix` and `docs` (a link into the
+[theme contract](https://github.com/usequeek/theme-starter/blob/main/docs/THEME.md)).
+`AT_SUBMISSION` lists the checks only Queek can run — against its other themes, with a server
+render, or on its storage.
+
+Theme modules (`theme.config.ts`, `manifest.ts`) load through jiti from the theme's own
+project, so the project must have `@usequeek/theme-kit` installed.
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,19 @@
+import type { CheckEnv, ThemeContext } from './types.js';
+/** The contract every theme is checked against, as published with the starter. */
+export declare const CONTRACT_URL = "https://github.com/usequeek/theme-starter/blob/main/docs/THEME.md";
+/** The environment a developer's own repo gets: paths relative to where they run, public links. */
+export declare function localEnv(dir: string, cwd?: string): CheckEnv;
+/**
+ * Everything the rules read about one theme folder. Its TypeScript modules
+ * (theme.config.ts, manifest.ts) load through jiti, resolving imports from
+ * the theme's own project — the kit the developer installed, not ours.
+ */
+export declare function loadContext(themeDir: string, env?: Partial<CheckEnv>): Promise<ThemeContext>;
+/** Every .ts/.tsx under a theme, for the whole-tree scans. */
+export declare function themeSourceFiles(dir: string): string[];
+/**
+ * Load a module of the kit the theme's project installed. The kit ships
+ * TypeScript source, which Node will not execute from node_modules, so it goes
+ * through jiti — resolved from the theme, never bundled with this package.
+ */
+export declare function importKit<T>(themeDir: string, specifier: string): Promise<T>;

package/dist/context.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { createJiti } from 'jiti';
+import { demoFilesOf } from './utils/theme-demos.js';
+/** The contract every theme is checked against, as published with the starter. */
+export const CONTRACT_URL = 'https://github.com/usequeek/theme-starter/blob/main/docs/THEME.md';
+/**
+ * Page-block scopes. A theme declaring none of them is chrome-only — it renders
+ * one page and lets core supply the rest. The page-based structure
+ * requirements do not apply to it, derived from what the theme declares.
+ */
+const PAGE_BLOCK_SCOPES = ['gallery', 'products', 'categories', 'content'];
+/** The environment a developer's own repo gets: paths relative to where they run, public links. */
+export function localEnv(dir, cwd = process.cwd()) {
+    const shown = relative(cwd, dir).replace(/\\/g, '/');
+    return {
+        root: shown === '' ? '' : `${shown.startsWith('..') ? dir.replace(/\\/g, '/') : shown}/`,
+        docs: CONTRACT_URL,
+        vocabulary: 'the business vocabulary (docs/business-vocabulary.json in the starter)',
+        scaffold: '`npm create @usequeek/theme`',
+        preview: (templateId) => `http://localhost:3000/${templateId}`,
+        submission: false,
+    };
+}
+/**
+ * Everything the rules read about one theme folder. Its TypeScript modules
+ * (theme.config.ts, manifest.ts) load through jiti, resolving imports from
+ * the theme's own project — the kit the developer installed, not ours.
+ */
+export async function loadContext(themeDir, env = {}) {
+    const dir = resolve(themeDir);
+    const file = (path) => join(dir, path);
+    const exists = (path) => existsSync(file(path));
+    const read = (path) => (exists(path) ? readFileSync(file(path), 'utf8') : null);
+    const jiti = createJiti(file('theme.config.ts'), { moduleCache: false, fsCache: false, interopDefault: true });
+    // A file that will not parse is kept, with null data, so the demo-store rule
+    // can name it instead of the theme looking like it has one store fewer.
+    const demos = demoFilesOf(dir).map(({ id, path }) => {
+        const shown = relative(dir, path).replace(/\\/g, '/');
+        try {
+            return { id, file: shown, data: JSON.parse(readFileSync(path, 'utf8')) };
+        }
+        catch {
+            return { id, file: shown, data: null };
+        }
+    });
+    let config = null;
+    try {
+        config = await jiti.import(file('theme.config.ts'), { default: true });
+    }
+    catch {
+        config = null;
+    }
+    let manifest = null;
+    try {
+        manifest = await jiti.import(file('manifest.ts'), { default: true });
+    }
+    catch {
+        manifest = null;
+    }
+    const variants = (manifest?.variants ?? {});
+    const declared = config?.demos;
+    const primary = config?.default_demo;
+    return {
+        env: { ...localEnv(dir), ...env },
+        slug: typeof config?.slug === 'string' ? config.slug : basename(dir),
+        dir,
+        retired: config?.active === false,
+        demo: demos.find((store) => store.id === 'default')?.data ?? null,
+        demos,
+        declaredDemos: config === null ? null : Array.isArray(declared) ? declared : [],
+        defaultDescription: typeof primary?.description === 'string' ? primary.description : null,
+        defaultFor: primary?.for ?? null,
+        manifest,
+        pageBased: PAGE_BLOCK_SCOPES.some((scope) => (variants[scope] ?? []).length > 0),
+        file,
+        exists,
+        read,
+    };
+}
+/** Every .ts/.tsx under a theme, for the whole-tree scans. */
+export function themeSourceFiles(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            return entry.name === 'node_modules' ? [] : themeSourceFiles(full);
+        return /\.tsx?$/.test(entry.name) ? [full] : [];
+    });
+}
+/**
+ * Load a module of the kit the theme's project installed. The kit ships
+ * TypeScript source, which Node will not execute from node_modules, so it goes
+ * through jiti — resolved from the theme, never bundled with this package.
+ */
+export async function importKit(themeDir, specifier) {
+    const jiti = createJiti(join(resolve(themeDir), 'theme.config.ts'), { interopDefault: true });
+    return jiti.import(specifier);
+}

package/dist/format.d.ts

@@ -0,0 +1,20 @@
+import type { CheckResult } from './run.js';
+import type { Finding } from './types.js';
+/** Severity as developers' tools spell it (ESLint, SARIF, GitHub). */
+export type Level = 'error' | 'warning';
+export declare const levelOf: (finding: Finding) => Level;
+/** The file part of a finding's location: `theme/demo.json → pages.home` → `theme/demo.json`. */
+export declare function fileOf(finding: Finding): string | undefined;
+export interface Summary {
+    errors: number;
+    warnings: number;
+}
+export declare function summarize(findings: Finding[]): Summary;
+/** Machine-readable output: stable keys, one object per run. */
+export declare function formatJson(result: CheckResult): string;
+/** GitHub Actions workflow commands — annotations on the pull request's diff. */
+export declare function formatGithubActions(result: CheckResult): string;
+/** The default, for people: findings grouped by file, each with its fix and docs. */
+export declare function formatStylish(result: CheckResult, options: {
+    color: boolean;
+}): string;

package/dist/format.js

@@ -0,0 +1,75 @@
+import { AT_SUBMISSION } from './run.js';
+export const levelOf = (finding) => (finding.severity === 'reject' ? 'error' : 'warning');
+/** The file part of a finding's location: `theme/demo.json → pages.home` → `theme/demo.json`. */
+export function fileOf(finding) {
+    const where = finding.where?.split(' → ')[0]?.trim();
+    return where ? where.replace(/:\d+$/, '') : undefined;
+}
+export function summarize(findings) {
+    return {
+        errors: findings.filter((finding) => levelOf(finding) === 'error').length,
+        warnings: findings.filter((finding) => levelOf(finding) === 'warning').length,
+    };
+}
+/** Machine-readable output: stable keys, one object per run. */
+export function formatJson(result) {
+    return JSON.stringify({
+        theme: result.context.slug,
+        summary: summarize(result.findings),
+        findings: result.findings.map((finding) => ({
+            rule: finding.rule,
+            level: levelOf(finding),
+            file: fileOf(finding) ?? null,
+            where: finding.where ?? null,
+            message: finding.found,
+            fix: finding.fix,
+            docs: finding.docs ?? null,
+            fixable: finding.fixable ?? false,
+        })),
+        atSubmission: AT_SUBMISSION,
+    }, null, 2);
+}
+/** GitHub Actions workflow commands — annotations on the pull request's diff. */
+export function formatGithubActions(result) {
+    // https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands
+    const data = (text) => text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+    const property = (text) => data(text).replace(/:/g, '%3A').replace(/,/g, '%2C');
+    return result.findings.map((finding) => {
+        const file = fileOf(finding);
+        const props = [file ? `file=${property(file)}` : null, `title=${property(finding.rule)}`].filter(Boolean).join(',');
+        return `::${levelOf(finding)} ${props}::${data(`${finding.found} — ${finding.fix}${finding.docs ? ` (${finding.docs})` : ''}`)}`;
+    }).join('\n');
+}
+const paint = (on) => (code, text) => (on ? `\u001B[${code}m${text}\u001B[0m` : text);
+/** The default, for people: findings grouped by file, each with its fix and docs. */
+export function formatStylish(result, options) {
+    const c = paint(options.color);
+    const byFile = new Map();
+    for (const finding of result.findings) {
+        const key = fileOf(finding) ?? result.context.env.root ?? '.';
+        byFile.set(key, [...(byFile.get(key) ?? []), finding]);
+    }
+    const lines = [];
+    for (const [file, findings] of byFile) {
+        lines.push('', c(4, file));
+        for (const finding of findings) {
+            const level = levelOf(finding);
+            const detail = finding.where && finding.where.includes(' → ') ? ` ${c(2, finding.where.split(' → ').slice(1).join(' → '))}` : '';
+            lines.push(`  ${level === 'error' ? c(31, 'error  ') : c(33, 'warning')}  ${finding.found}${detail}  ${c(2, finding.rule)}`);
+            lines.push(`           ${c(2, 'Fix:')} ${finding.fix}`);
+            if (finding.docs)
+                lines.push(`           ${c(2, 'Docs:')} ${finding.docs}`);
+        }
+    }
+    const { errors, warnings } = summarize(result.findings);
+    lines.push('');
+    if (errors + warnings === 0) {
+        lines.push(c(32, `✔ ${result.context.slug}: no problems.`));
+    }
+    else {
+        const parts = [`${errors} error${errors === 1 ? '' : 's'}`, `${warnings} warning${warnings === 1 ? '' : 's'}`];
+        lines.push(c(errors > 0 ? 31 : 33, `${errors > 0 ? '✖' : '!'} ${result.context.slug}: ${parts.join(', ')}.`) + (errors > 0 ? ' Errors block submission.' : ''));
+    }
+    lines.push(c(2, `Also checked when you submit: ${AT_SUBMISSION.map((check) => check.summary).join('; ')}.`));
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @usequeek/theme-check — the rules a Queek storefront theme is checked
+ * against, as a library. The `queek-theme check` command of
+ * @usequeek/theme-cli is its command-line front end.
+ */
+export { checkTheme, rejects, RULES, AT_SUBMISSION, type CheckOptions, type CheckResult } from './run.js';
+export { loadContext, localEnv, CONTRACT_URL } from './context.js';
+export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf, type Level, type Summary } from './format.js';
+export type { CheckEnv, Finding, Rule, Severity, ThemeContext, DemoStore, DeclaredDemo } from './types.js';
+export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
+export { PRIMARY_DEMO_ID, DEMO_ID_FORMAT, demoFilesOf } from './utils/theme-demos.js';
+export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @usequeek/theme-check — the rules a Queek storefront theme is checked
+ * against, as a library. The `queek-theme check` command of
+ * @usequeek/theme-cli is its command-line front end.
+ */
+export { checkTheme, rejects, RULES, AT_SUBMISSION } from './run.js';
+export { loadContext, localEnv, CONTRACT_URL } from './context.js';
+export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf } from './format.js';
+export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
+export { PRIMARY_DEMO_ID, DEMO_ID_FORMAT, demoFilesOf } from './utils/theme-demos.js';
+export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';

package/dist/parity/field-parity.d.ts

@@ -0,0 +1,11 @@
+import { type ManifestVariants } from './variant-parity.js';
+export interface FieldParityViolation {
+    variant: string;
+    reason: string;
+}
+/** Extracts direct field reads from one concrete variant component. */
+export declare function extractComponentFieldReads(source: string, componentName: string, fileName: string): string[];
+/** Enforces equality after removing the explicit fields rendered by PageRenderer. */
+export declare function validateFieldParity(themeSlug: string, variantKey: string, declaredFields: string[], componentReads: string[]): void;
+export declare function findThemeFieldParityViolations(themeSlug: string, manifestVariants: ManifestVariants, indexSource: string, indexFile: string): FieldParityViolation[];
+export declare function assertThemeFieldParity(themeSlug: string, manifestVariants: ManifestVariants, indexSource: string, indexFile: string): void;

package/dist/parity/field-parity.js

@@ -0,0 +1,240 @@
+import ts from 'typescript';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { parseVariantImplementations } from './variant-parity.js';
+/** Rendered by PageRenderer/preview hydration, never merchant-authored block data. */
+const FRAMEWORK_PROVIDED_FIELDS = new Set([
+    'bg_color', 'bg_image', 'bg_overlay', 'anchor_id',
+    'products', 'categories', 'posts',
+]);
+/** `fields` is merchant-authored page-block data, written per section. */
+const PAGE_BLOCK_SCOPES = new Set(['content', 'products', 'categories', 'gallery', 'contact', 'faq', 'table', 'blog']);
+/**
+ * Theme chrome — set once per store through `manage_theme`, not per page block.
+ * A different write path, but the same contract: a chrome variant declares
+ * exactly what its component renders, so ManageThemeTool's per-variant gate
+ * (`chromeSupports()`, queek_backend) refuses an edit that would render nothing
+ * instead of confirming a silent no-op.
+ */
+const CHROME_SCOPES = new Set(['header', 'footer', 'subscribe']);
+/**
+ * Variants whose configured values never arrive as component props, so a
+ * props-read scan cannot see them. Each set is the field list read from the
+ * real source, verified against the renderer named beside it — never a guess.
+ */
+const NON_PROP_VARIANT_READS = {
+    // PageRenderer routes the default content block to CoreContentDefaultBlock.
+    'content.default': ['markdown'],
+    // vendor-shell.tsx mounts the core subscribe app from `config.apps.subscribe`.
+    'subscribe.inline': ['heading', 'tagline', 'cta'],
+    'subscribe.floating': ['heading', 'tagline', 'cta'],
+    'subscribe.modal': ['heading', 'tagline', 'cta', 'trigger'],
+    // Theme-bespoke subscribe panels live INSIDE the theme's own footer component
+    // and read the same `config.apps.subscribe` off context rather than props —
+    // see themes/allure/footers/atelier.tsx and themes/glow/footers/columns.tsx.
+    'subscribe.atelier-hero': ['heading', 'tagline', 'cta'],
+    'subscribe.glow-benefits': ['heading', 'tagline', 'cta'],
+};
+/**
+ * Read-side prop names that resolve to a canonical snake_case manifest field.
+ * Manifest fields are snake_case everywhere (they name the stored config/block
+ * key), and `HeaderProps` (@usequeek/theme-kit/types/theme) re-exposes
+ * `config.header.show_*` as camelCase React props — so every theme header reads
+ * `showCart` for the field the merchant and the backend both call `show_cart`.
+ *
+ * The `cta*` pair is migration debt, not a boundary: allure's
+ * `gallery/tab-collage` stored `ctaLabel`/`ctaLink` before the snake_case
+ * rename, and its component still reads both so already-saved blocks keep
+ * their button. Drop those two entries once that stored data is migrated.
+ */
+const FIELD_READ_ALIASES = {
+    showSearch: 'show_search',
+    showCart: 'show_cart',
+    showAccount: 'show_account',
+    showOffers: 'show_offers',
+    ctaLabel: 'cta_label',
+    ctaLink: 'cta_link',
+};
+function componentError(fileName, componentName, detail) {
+    return new Error(`${fileName}: ${componentName} ${detail}`);
+}
+function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return null;
+}
+function findComponent(sourceFile, componentName) {
+    for (const statement of sourceFile.statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name?.text === componentName)
+            return statement;
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== componentName)
+                continue;
+            if (declaration.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer))) {
+                return declaration.initializer;
+            }
+        }
+    }
+    throw componentError(sourceFile.fileName, componentName, 'must be declared as a function or arrow function in its imported module');
+}
+function fieldsFromBindingPattern(pattern, fileName, componentName) {
+    const fields = [];
+    for (const element of pattern.elements) {
+        if (element.dotDotDotToken) {
+            throw componentError(fileName, componentName, 'uses a rest props binding; field reads are not statically provable');
+        }
+        const field = element.propertyName
+            ? propertyName(element.propertyName)
+            : ts.isIdentifier(element.name) ? element.name.text : null;
+        if (!field || !ts.isIdentifier(element.name)) {
+            throw componentError(fileName, componentName, 'uses an unsupported props binding; field reads are not statically provable');
+        }
+        fields.push(field);
+    }
+    return fields;
+}
+/** Extracts direct field reads from one concrete variant component. */
+export function extractComponentFieldReads(source, componentName, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const component = findComponent(sourceFile, componentName);
+    const firstParam = component.parameters[0];
+    if (!firstParam)
+        return [];
+    const fields = new Set();
+    let propsIdentifier = null;
+    if (ts.isObjectBindingPattern(firstParam.name)) {
+        for (const field of fieldsFromBindingPattern(firstParam.name, fileName, componentName))
+            fields.add(field);
+    }
+    else if (ts.isIdentifier(firstParam.name)) {
+        propsIdentifier = firstParam.name.text;
+    }
+    else {
+        throw componentError(fileName, componentName, 'uses an unsupported props parameter; field reads are not statically provable');
+    }
+    if (!propsIdentifier || !component.body)
+        return [...fields].sort();
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer && ts.isIdentifier(node.initializer) && node.initializer.text === propsIdentifier) {
+            for (const field of fieldsFromBindingPattern(node.name, fileName, componentName))
+                fields.add(field);
+        }
+        if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === propsIdentifier) {
+            fields.add(node.name.text);
+        }
+        if (ts.isElementAccessExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === propsIdentifier) {
+            if (!node.argumentExpression || !ts.isStringLiteral(node.argumentExpression)) {
+                throw componentError(fileName, componentName, 'uses dynamic props access; field reads are not statically provable');
+            }
+            fields.add(node.argumentExpression.text);
+        }
+        if ((ts.isJsxSpreadAttribute(node) || ts.isSpreadElement(node))
+            && ts.isIdentifier(node.expression)
+            && node.expression.text === propsIdentifier) {
+            throw componentError(fileName, componentName, 'forwards props through a spread; field reads are not statically provable');
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(component.body, visit);
+    return [...fields].sort();
+}
+/** Enforces equality after removing the explicit fields rendered by PageRenderer. */
+export function validateFieldParity(themeSlug, variantKey, declaredFields, componentReads) {
+    const declared = new Set(declaredFields.filter((field) => !FRAMEWORK_PROVIDED_FIELDS.has(field)));
+    const reads = new Set(componentReads
+        .map((field) => FIELD_READ_ALIASES[field] ?? field)
+        .filter((field) => !FRAMEWORK_PROVIDED_FIELDS.has(field)));
+    const declaredOnly = [...declared].filter((field) => !reads.has(field)).sort();
+    const readOnly = [...reads].filter((field) => !declared.has(field)).sort();
+    if (declaredOnly.length > 0 || readOnly.length > 0) {
+        const reasons = [
+            declaredOnly.length > 0 ? `declares ${declaredOnly.join(', ')} but the component never reads ${declaredOnly.length === 1 ? 'it' : 'them'}` : null,
+            readOnly.length > 0 ? `reads ${readOnly.join(', ')} but the manifest does not declare ${readOnly.length === 1 ? 'it' : 'them'}` : null,
+        ].filter(Boolean).join('; ');
+        throw new Error(`Theme "${themeSlug}" ${variantKey} ${reasons}`);
+    }
+}
+/** The nearest folder above `from` with a tsconfig.json or package.json — what `@/` means in a theme's project. */
+function projectRootOf(from) {
+    let dir = from;
+    while (dirname(dir) !== dir) {
+        if (existsSync(resolve(dir, 'tsconfig.json')) || existsSync(resolve(dir, 'package.json')))
+            return dir;
+        dir = dirname(dir);
+    }
+    return from;
+}
+function resolveModule(importPath, indexFile) {
+    const projectRoot = projectRootOf(dirname(dirname(indexFile)));
+    const base = importPath.startsWith('.')
+        ? resolve(dirname(indexFile), importPath)
+        : importPath.startsWith('@/')
+            ? resolve(projectRoot, importPath.slice(2))
+            : null;
+    if (!base)
+        throw new Error(`${indexFile}: cannot statically resolve component import ${importPath}`);
+    for (const candidate of [base, `${base}.ts`, `${base}.tsx`, resolve(base, 'index.ts'), resolve(base, 'index.tsx')]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`${indexFile}: cannot find component module ${importPath}`);
+}
+function parseComponentImports(indexSource, indexFile) {
+    const sourceFile = ts.createSourceFile(indexFile, indexSource, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const imports = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !statement.importClause || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (!statement.moduleSpecifier.text.startsWith('.') && !statement.moduleSpecifier.text.startsWith('@/'))
+            continue;
+        const bindings = statement.importClause.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        const moduleFile = resolveModule(statement.moduleSpecifier.text, indexFile);
+        for (const specifier of bindings.elements)
+            imports.set(specifier.name.text, moduleFile);
+    }
+    return imports;
+}
+export function findThemeFieldParityViolations(themeSlug, manifestVariants, indexSource, indexFile) {
+    const implementations = parseVariantImplementations(indexSource, indexFile);
+    const imports = parseComponentImports(indexSource, indexFile);
+    const violations = [];
+    for (const [scope, variants] of Object.entries(manifestVariants)) {
+        if (!PAGE_BLOCK_SCOPES.has(scope) && !CHROME_SCOPES.has(scope))
+            continue;
+        for (const variant of variants) {
+            const variantKey = `${scope}.${variant.id}`;
+            const nonPropReads = NON_PROP_VARIANT_READS[variantKey];
+            const componentName = implementations[scope]?.[variant.id];
+            try {
+                const reads = nonPropReads ?? (() => {
+                    if (!componentName) {
+                        throw new Error(`${indexFile}: ${variantKey} has no declared non-prop read-set or mapped component`);
+                    }
+                    const componentFile = imports.get(componentName);
+                    if (!componentFile) {
+                        throw new Error(`${indexFile}: cannot resolve mapped component ${componentName} for ${variantKey}`);
+                    }
+                    return extractComponentFieldReads(readFileSync(componentFile, 'utf8'), componentName, componentFile);
+                })();
+                validateFieldParity(themeSlug, variantKey, Object.keys(variant.fields ?? {}), reads);
+            }
+            catch (error) {
+                violations.push({
+                    variant: variantKey,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    return violations;
+}
+export function assertThemeFieldParity(themeSlug, manifestVariants, indexSource, indexFile) {
+    const violations = findThemeFieldParityViolations(themeSlug, manifestVariants, indexSource, indexFile);
+    if (violations.length > 0) {
+        throw new Error(`Theme "${themeSlug}" field parity failed:\n${violations.map(({ variant, reason }) => `- ${variant}: ${reason}`).join('\n')}`);
+    }
+}

package/dist/parity/variant-parity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `subscribe` variants rendered by vendor-shell.tsx itself (theme-agnostic,
+ * every theme gets them for free) rather than by a per-theme component in
+ * that theme's own `variantImplementations` — see subscribe-{inline,
+ * floating,modal}. A theme's OWN bespoke subscribe variant (e.g. glow's
+ * `glow-benefits`) is NOT framework-owned; it must appear in that theme's
+ * `variantImplementations.subscribe` map instead. One shared list so the
+ * registry generator and the parity test can't drift out of sync.
+ */
+export declare const FRAMEWORK_OWNED_SUBSCRIBE_VARIANTS: string[];
+export type ParsedVariantImplementations = Record<string, Record<string, string>>;
+export type ManifestVariants = Record<string, Array<{
+    id: string;
+    fields?: Record<string, unknown>;
+}>>;
+export type ImplementedVariants = Record<string, string[]>;
+export type ContentFieldContract = 'structured' | undefined;
+export interface ContentFieldContractReport {
+    legacyFieldCount: number;
+    structuredFieldCount: number;
+}
+export declare function parseVariantImplementations(source: string, fileName: string): ParsedVariantImplementations;
+export declare function validateVariantParity(themeSlug: string, manifestVariants: ManifestVariants, implementations: ParsedVariantImplementations, frameworkOwned: Record<string, string[]>): ImplementedVariants;
+/**
+ * Checks the content-field migration independently of runtime variant parity.
+ * Legacy strings remain accepted until a theme sets `content_fields: 'structured'`.
+ */
+export declare function validateContentFieldContract(themeSlug: string, manifestVariants: ManifestVariants, contract?: ContentFieldContract): ContentFieldContractReport;