@usequeek/theme-check 0.1.0

package/dist/parity/variant-parity.js

@@ -0,0 +1,167 @@
+import ts from 'typescript';
+/**
+ * `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 const FRAMEWORK_OWNED_SUBSCRIBE_VARIANTS = ['inline', 'floating', 'modal'];
+const MAP_NAME = 'variantImplementations';
+const SHAPE_ERROR = `${MAP_NAME} must be a plain nested object literal with component identifier leaves`;
+const CONTENT_FIELD_TYPES = new Set([
+    'string', 'text', 'markdown', 'image', 'url', 'int', 'number', 'boolean',
+    'color', 'string[]', 'image[]', 'object', 'object[]', 'enum',
+]);
+function unwrapExpression(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+function literalPropertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return null;
+}
+function isDirectlyExported(statement) {
+    return statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+function shapeError(fileName) {
+    return new Error(`${fileName}: ${SHAPE_ERROR}`);
+}
+export function parseVariantImplementations(source, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    let initializer = null;
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement) || !isDirectlyExported(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.name.text === MAP_NAME) {
+                initializer = declaration.initializer ?? null;
+            }
+        }
+    }
+    if (!initializer) {
+        throw new Error(`${fileName}: must directly export const ${MAP_NAME}`);
+    }
+    const root = unwrapExpression(initializer);
+    if (!ts.isObjectLiteralExpression(root))
+        throw shapeError(fileName);
+    const parsed = {};
+    for (const scopeProperty of root.properties) {
+        if (!ts.isPropertyAssignment(scopeProperty))
+            throw shapeError(fileName);
+        const scope = literalPropertyName(scopeProperty.name);
+        const scopeValue = unwrapExpression(scopeProperty.initializer);
+        if (!scope || !ts.isObjectLiteralExpression(scopeValue) || parsed[scope])
+            throw shapeError(fileName);
+        const variants = {};
+        const registeredComponents = new Map();
+        for (const variantProperty of scopeValue.properties) {
+            if (!ts.isPropertyAssignment(variantProperty))
+                throw shapeError(fileName);
+            const variantId = literalPropertyName(variantProperty.name);
+            const component = unwrapExpression(variantProperty.initializer);
+            if (!variantId || variants[variantId] || !ts.isIdentifier(component))
+                throw shapeError(fileName);
+            const previousVariant = registeredComponents.get(component.text);
+            if (previousVariant) {
+                throw new Error(`${fileName}: ${scope}.${variantId} reuses ${component.text} already registered by ${scope}.${previousVariant}`);
+            }
+            variants[variantId] = component.text;
+            registeredComponents.set(component.text, variantId);
+        }
+        parsed[scope] = variants;
+    }
+    return parsed;
+}
+export function validateVariantParity(themeSlug, manifestVariants, implementations, frameworkOwned) {
+    const manifestKeys = new Set();
+    for (const [scope, variants] of Object.entries(manifestVariants)) {
+        const ids = new Set();
+        for (const variant of variants) {
+            if (ids.has(variant.id)) {
+                throw new Error(`Theme "${themeSlug}" manifest has duplicate variant id ${scope}.${variant.id}`);
+            }
+            ids.add(variant.id);
+            manifestKeys.add(`${scope}.${variant.id}`);
+        }
+    }
+    const implementedKeys = new Set();
+    for (const [scope, variants] of Object.entries(implementations)) {
+        for (const id of Object.keys(variants))
+            implementedKeys.add(`${scope}.${id}`);
+    }
+    for (const [scope, ids] of Object.entries(frameworkOwned)) {
+        const declaredIds = new Set(manifestVariants[scope]?.map((variant) => variant.id) ?? []);
+        for (const id of ids) {
+            if (declaredIds.has(id))
+                implementedKeys.add(`${scope}.${id}`);
+        }
+    }
+    const manifestOnly = [...manifestKeys].filter((key) => !implementedKeys.has(key)).sort();
+    const implementationOnly = [...implementedKeys].filter((key) => !manifestKeys.has(key)).sort();
+    if (manifestOnly.length > 0 || implementationOnly.length > 0) {
+        throw new Error(`Theme "${themeSlug}" variant parity failed: manifest-only [${manifestOnly.join(', ')}]; implementation-only [${implementationOnly.join(', ')}]`);
+    }
+    const evidence = {};
+    for (const scope of Object.keys(manifestVariants).sort()) {
+        evidence[scope] = manifestVariants[scope].map((variant) => variant.id).sort();
+    }
+    return evidence;
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function validateStructuredContentField(value, path) {
+    if (typeof value.type !== 'string' || !CONTENT_FIELD_TYPES.has(value.type)) {
+        throw new Error(`${path} has unknown type "${String(value.type)}"`);
+    }
+    if (value.type === 'enum' && (!Array.isArray(value.options) || value.options.length === 0 || value.options.some((option) => typeof option !== 'string'))) {
+        throw new Error(`${path} enum fields require non-empty options`);
+    }
+    if (value.type === 'object[]') {
+        if (!isPlainObject(value.of) || Object.keys(value.of).length === 0) {
+            throw new Error(`${path} object[] fields require an of object`);
+        }
+        return 1 + Object.entries(value.of).reduce((count, [key, nested]) => {
+            if (!isPlainObject(nested)) {
+                throw new Error(`${path}.of.${key} must be a structured field object`);
+            }
+            return count + validateStructuredContentField(nested, `${path}.of.${key}`);
+        }, 0);
+    }
+    return 1;
+}
+/**
+ * Checks the content-field migration independently of runtime variant parity.
+ * Legacy strings remain accepted until a theme sets `content_fields: 'structured'`.
+ */
+export function validateContentFieldContract(themeSlug, manifestVariants, contract = undefined) {
+    let legacyFieldCount = 0;
+    let structuredFieldCount = 0;
+    for (const variant of manifestVariants.content ?? []) {
+        for (const [fieldName, field] of Object.entries(variant.fields ?? {})) {
+            const path = `content.${variant.id}.${fieldName}`;
+            if (typeof field === 'string') {
+                if (contract === 'structured') {
+                    throw new Error(`Theme "${themeSlug}" content fields are marked structured but ${path} is still legacy`);
+                }
+                legacyFieldCount += 1;
+                continue;
+            }
+            if (!isPlainObject(field)) {
+                throw new Error(`Theme "${themeSlug}" ${path} must be a legacy string or structured field object`);
+            }
+            structuredFieldCount += validateStructuredContentField(field, path);
+        }
+    }
+    return { legacyFieldCount, structuredFieldCount };
+}

package/dist/rules/analysis.d.ts

@@ -0,0 +1,5 @@
+import { type Rule } from '../types.js';
+export declare const variantParityRule: Rule;
+export declare const fieldParityRule: Rule;
+export declare const designTokensRule: Rule;
+export declare const ANALYSIS_RULES: Rule[];

package/dist/rules/analysis.js

@@ -0,0 +1,105 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { importKit } from '../context.js';
+import { FRAMEWORK_OWNED_SUBSCRIBE_VARIANTS, parseVariantImplementations, validateContentFieldContract, validateVariantParity, } from '../parity/variant-parity.js';
+import { findThemeFieldParityViolations } from '../parity/field-parity.js';
+import { finding } from '../types.js';
+/**
+ * Rules that read the theme's source with the TypeScript compiler rather than
+ * rendering it: the manifest against the components, and the design tokens
+ * against the CSS.
+ */
+function indexPath(context) {
+    return ['index.ts', 'index.tsx'].map((name) => join(context.dir, name)).find(existsSync) ?? null;
+}
+export const variantParityRule = {
+    id: 'theme/variant-parity',
+    summary: 'Every manifest variant has a renderer, and vice versa',
+    kind: 'render',
+    run(context) {
+        if (context.retired)
+            return [];
+        const path = indexPath(context);
+        if (!path || !context.manifest)
+            return [];
+        const manifest = context.manifest;
+        try {
+            const parsed = parseVariantImplementations(readFileSync(path, 'utf8'), path);
+            validateVariantParity(context.slug, manifest.variants, parsed, {
+                content: ['default'],
+                subscribe: FRAMEWORK_OWNED_SUBSCRIBE_VARIANTS,
+            });
+            validateContentFieldContract(context.slug, manifest.variants, manifest.fields_contract?.content);
+            return [];
+        }
+        catch (error) {
+            return [finding(context, 'theme/variant-parity', 'reject', {
+                    where: `${context.env.root}manifest.ts`,
+                    found: error.message,
+                    fix: 'A variant the manifest declares but nothing renders shows a vendor an option that does nothing; a renderer the manifest omits can never be chosen. Both lists must match exactly.',
+                    docs: `${context.env.docs}#manifest`,
+                })];
+        }
+    },
+};
+export const fieldParityRule = {
+    id: 'theme/field-parity',
+    summary: 'Each variant declares exactly the fields its renderer reads',
+    kind: 'render',
+    run(context) {
+        if (context.retired)
+            return [];
+        const path = indexPath(context);
+        if (!path || !context.manifest)
+            return [];
+        const manifest = context.manifest;
+        return findThemeFieldParityViolations(context.slug, manifest.variants, readFileSync(path, 'utf8'), path).map((violation) => finding(context, 'theme/field-parity', 'reject', {
+            where: `${context.env.root}manifest.ts`,
+            found: `${violation.variant}: ${violation.reason}`,
+            fix: 'A declared field the renderer never reads is a control that does nothing when a merchant edits it. A field read but not declared can never be set. Align the manifest with the component.',
+            docs: `${context.env.docs}#manifest`,
+        }));
+    },
+};
+export const designTokensRule = {
+    id: 'theme/design-tokens',
+    summary: 'Declares a complete token set, and its CSS actually consumes it',
+    kind: 'render',
+    async run(context) {
+        if (context.retired)
+            return [];
+        const tokens = context.manifest?.tokens;
+        const at = `${context.env.root}manifest.ts`;
+        const add = (found, fix, where = at) => finding(context, 'theme/design-tokens', 'reject', { where, found, fix, docs: `${context.env.docs}#manifest` });
+        if (!tokens) {
+            return [add('no design-token block', 'Declare `tokens` in manifest.ts. Without it a vendor cannot recolour or restyle the theme at all — it is the whole customisation surface.')];
+        }
+        const findings = [];
+        const missing = [
+            ['color', tokens.color],
+            ['type.heading_font', tokens.type?.heading_font],
+            ['type.scale_ratio', tokens.type?.scale_ratio],
+            ['space.density', tokens.space?.density],
+            ['shape.radius', tokens.shape?.radius],
+            ['elevation', tokens.elevation],
+            ['motion', tokens.motion],
+        ].filter(([, value]) => !value).map(([name]) => name);
+        if (missing.length > 0) {
+            findings.push(add(`tokens missing: ${missing.join(', ')}`, 'Every dimension must be declared — each one is a dial in the vendor’s theme editor.'));
+        }
+        const { expandDesignTokens } = await importKit(context.dir, '@usequeek/theme-kit/utils/brand');
+        const vars = expandDesignTokens(tokens);
+        const unexpanded = ['--brand-primary', '--brand-bg', '--brand-text', '--fs-base', '--fs-3xl', '--space-4', '--radius-md', '--shadow-2', '--duration-base', '--font-heading', '--font-body']
+            .filter((key) => !vars[key]);
+        if (unexpanded.length > 0) {
+            findings.push(add(`tokens do not expand to: ${unexpanded.join(', ')}`, 'Usually a malformed token value. Check it against the starter’s manifest.'));
+        }
+        const css = context.read('theme.css') ?? '';
+        const references = (css.match(/var\(--(fs|space|radius|shadow|duration|fw|tracking|leading|case)-/g) ?? []).length;
+        if (references <= 50) {
+            findings.push(add(`theme.css references design tokens only ${references} time(s)`, 'Hardcoded sizes and colours mean the vendor’s edits never reach the page. Style from var(--fs-*), var(--space-*), var(--radius-*) and friends.', `${context.env.root}theme.css`));
+        }
+        return findings;
+    },
+};
+export const ANALYSIS_RULES = [variantParityRule, fieldParityRule, designTokensRule];

package/dist/rules/static.d.ts

@@ -0,0 +1,41 @@
+import { type Rule } from '../types.js';
+export declare const structureRule: Rule;
+export declare const demoStoreRule: Rule;
+/**
+ * The declaration in theme.config.ts and the files under demos/ are one list.
+ * A declared store with no file 404s in the preview the registry advertises;
+ * a file nobody declared is previewable but never offered; an id that is not
+ * a slug cannot be a URL segment; two stores on one profile.id share a cart.
+ */
+export declare const demoStoresRule: Rule;
+export declare const demoArtRule: Rule;
+export declare const codeQualityRule: Rule;
+export declare const sdkBoundaryRule: Rule;
+/**
+ * The ThemeModule shape (Layout, Header, Footer, blocks, getBlock, pages…) is
+ * enforced by TypeScript, because a theme writes `const theme: ThemeModule`.
+ * The one thing the compiler cannot catch is a theme that drops the annotation
+ * — then nothing checks the shape at all, and core discovers the missing slot
+ * at render time in a vendor's store.
+ *
+ * Checked by reading the source rather than importing it: index.ts pulls the
+ * whole theme graph, which reaches the SDK and will not load outside a bundler.
+ */
+export declare const moduleContractRule: Rule;
+export declare const selectionMetadataRule: Rule;
+export declare const demoCompletenessRule: Rule;
+export declare const subscribeScopeRule: Rule;
+export declare const demoBlockTypesRule: Rule;
+export declare const identityRule: Rule;
+export declare const productMetafieldsRule: Rule;
+export declare const poweredByRule: Rule;
+export declare const templateDescriptionRule: Rule;
+export declare const templateScreenshotRule: Rule;
+export declare const templateChromeRule: Rule;
+export declare const templateStyleRule: Rule;
+export declare const templateBusinessRule: Rule;
+export declare const templateVersionsRule: Rule;
+/** The designed pages every template ships (contract R2.3); versions `-2`… count. */
+export declare const TEMPLATE_PAGES: readonly ["about", "sales", "landing"];
+export declare const templatePagesRule: Rule;
+export declare const STATIC_RULES: Rule[];