@usequeek/theme-check 0.5.0 → 0.6.0

package/README.md

@@ -25,6 +25,26 @@ 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.
 
+New rule: `theme/markdown-html` (reject) — `renderMarkdown` returns React elements, not an
+HTML string, so passing it to `dangerouslySetInnerHTML` renders "[object Object]".
+
+## Project config
+
+`loadProjectConfig(root)` reads `.queek-theme.yml` at the project root (`null` when there
+is no file; `ConfigError` when invalid), and `applyProjectConfig(findings, config)` applies
+it. The config changes warnings only. Errors are the contract Queek checks when you submit,
+so nothing turns them off. If an error is wrong for your theme, open an issue:
+https://github.com/usequeek/theme-tools/issues
+
+`rules.<id>` is `off` (drop that rule's warnings), `warning` (the default) or `error` (turn
+them into rejects); `ignore` globs, relative to the project root, drop warnings in those
+files. Reject findings are never changed. `checkTheme()` never reads the config.
+
+## Machine-readable report
+
+`jsonReport(result)` builds the object `formatJson(result)` prints (same bytes):
+`{ theme, summary, vocabulary, findings, atSubmission }`.
+
 ## License
 
 MIT

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+import type { Finding } from './types.js';
+/**
+ * The project config: what a theme's own repo may tune. It changes warnings
+ * only — errors are the contract Queek checks on submission, so nothing turns
+ * them off. `checkTheme()` never reads it (the submission check must never
+ * see a developer's config); the CLI `check`/`package` commands load and
+ * apply it.
+ */
+/** The file at the project root (beside package.json). */
+export declare const CONFIG_FILE_NAME = ".queek-theme.yml";
+/** What a rule entry may say: `warning` is the default, a no-op. */
+export type ConfigRuleLevel = 'off' | 'warning' | 'error';
+export interface ProjectConfig {
+    /** The project root the file was read from (globs are relative to it). */
+    root: string;
+    /** The config file itself. */
+    path: string;
+    /** Only `off` and `error` entries are kept — `warning` changes nothing. */
+    rules: Partial<Record<string, Exclude<ConfigRuleLevel, 'warning'>>>;
+    /** Warning findings in these files are not reported. */
+    ignore: string[];
+}
+/** Thrown when the config file exists but is invalid — the CLI exits 2. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read the project config, or null when there is no file. Throws ConfigError
+ * (naming the file and the key) when it is invalid.
+ */
+export declare function loadProjectConfig(root: string): ProjectConfig | null;
+/**
+ * Apply the config to findings: `off` drops a rule's warn findings, `error`
+ * turns them into rejects, and `ignore` globs (relative to the project root,
+ * matched against the file part of `where`) drop warn findings in those
+ * files. A rule's reject findings are never changed.
+ */
+export declare function applyProjectConfig(findings: Finding[], config: ProjectConfig, cwd?: string): Finding[];
+/**
+ * Rule ids that can emit a warning — the only ones a config (or
+ * `check --init`) may name — in RULES order.
+ */
+export declare function warningRuleIds(): string[];
+/** The policy, verbatim: also the first comment of what `check --init` writes. */
+export declare const CONFIG_POLICY = "The config changes warnings only. Errors are the contract Queek checks when you submit, so nothing turns them off. If an error is wrong for your theme, open an issue: https://github.com/usequeek/theme-tools/issues";
+/** What `check --init` writes: the policy, every warnable rule id commented out, and a sample ignore. */
+export declare function renderInitConfig(): string;

package/dist/config.js

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import picomatch from 'picomatch';
+import YAML from 'yaml';
+import { RULES } from './run.js';
+import { closestRuleId } from './utils/closest-id.js';
+/**
+ * The project config: what a theme's own repo may tune. It changes warnings
+ * only — errors are the contract Queek checks on submission, so nothing turns
+ * them off. `checkTheme()` never reads it (the submission check must never
+ * see a developer's config); the CLI `check`/`package` commands load and
+ * apply it.
+ */
+/** The file at the project root (beside package.json). */
+export const CONFIG_FILE_NAME = '.queek-theme.yml';
+/** Thrown when the config file exists but is invalid — the CLI exits 2. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+const KNOWN_TOP_LEVEL = ['rules', 'ignore'];
+/**
+ * Read the project config, or null when there is no file. Throws ConfigError
+ * (naming the file and the key) when it is invalid.
+ */
+export function loadProjectConfig(root) {
+    const path = join(root, CONFIG_FILE_NAME);
+    if (!existsSync(path))
+        return null;
+    let data;
+    try {
+        data = YAML.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: the YAML won't parse (${error.message}).`);
+    }
+    if (data === null || data === undefined)
+        return { root, path, rules: {}, ignore: [] };
+    if (typeof data !== 'object' || Array.isArray(data)) {
+        throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: the file must be a mapping with "rules" and/or "ignore".`);
+    }
+    const record = data;
+    for (const key of Object.keys(record)) {
+        if (!KNOWN_TOP_LEVEL.includes(key)) {
+            throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: unknown top-level key "${key}" (expected "rules" and/or "ignore").`);
+        }
+    }
+    const rules = {};
+    const rawRules = record.rules ?? {};
+    if (rawRules === null) {
+        // An empty `rules:` (as `check --init` writes) means no overrides.
+    }
+    else if (typeof rawRules !== 'object' || Array.isArray(rawRules)) {
+        throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: "rules" must be a mapping of rule id to off, warning or error.`);
+    }
+    else {
+        const known = new Set(RULES.map((rule) => rule.id));
+        for (const [id, value] of Object.entries(rawRules)) {
+            if (!known.has(id)) {
+                const hint = closestRuleId(id, known);
+                throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: unknown rule "${id}" in "rules"${hint ? ` (did you mean "${hint}"?)` : ''}.`);
+            }
+            if (value !== 'off' && value !== 'warning' && value !== 'error') {
+                throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: "rules"."${id}" must be off, warning or error (got ${JSON.stringify(value) ?? String(value)}).`);
+            }
+            if (value !== 'warning')
+                rules[id] = value;
+        }
+    }
+    const rawIgnore = record.ignore ?? [];
+    let ignore = [];
+    if (rawIgnore === null) {
+        // An empty `ignore:` (as `check --init` writes) means no patterns.
+    }
+    else if (!Array.isArray(rawIgnore) || rawIgnore.some((entry) => typeof entry !== 'string')) {
+        throw new ConfigError(`Invalid ${CONFIG_FILE_NAME}: "ignore" must be an array of strings (glob patterns relative to the project root).`);
+    }
+    else {
+        ignore = [...rawIgnore];
+    }
+    return { root, path, rules, ignore };
+}
+/**
+ * Apply the config to findings: `off` drops a rule's warn findings, `error`
+ * turns them into rejects, and `ignore` globs (relative to the project root,
+ * matched against the file part of `where`) drop warn findings in those
+ * files. A rule's reject findings are never changed.
+ */
+export function applyProjectConfig(findings, config, cwd = process.cwd()) {
+    const matchers = config.ignore.map((pattern) => picomatch(pattern, { dot: true }));
+    // A finding's file starts with env.root, which is relative to where `check`
+    // ran — so it only matches project-root-relative globs after resolving it
+    // against that directory and making it relative to the project root again.
+    const ignored = (where) => {
+        const file = where.split(' → ')[0]?.trim().replace(/:\d+$/, '') ?? '';
+        if (!file)
+            return false;
+        const rel = relative(config.root, isAbsolute(file) ? file : resolve(cwd, file)).replace(/\\/g, '/');
+        return matchers.some((matches) => matches(rel));
+    };
+    return findings.flatMap((finding) => {
+        if (finding.severity !== 'warn')
+            return [finding];
+        const override = config.rules[finding.rule];
+        if (override === 'off')
+            return [];
+        if (override === 'error')
+            return [{ ...finding, severity: 'reject' }];
+        if (finding.where && matchers.length > 0 && ignored(finding.where))
+            return [];
+        return [finding];
+    });
+}
+/**
+ * Rule ids that can emit a warning — the only ones a config (or
+ * `check --init`) may name — in RULES order.
+ */
+export function warningRuleIds() {
+    const warnable = new Set([
+        'theme/demo-completeness',
+        'theme/template-business',
+        'theme/template-pages',
+    ]);
+    return RULES.map((rule) => rule.id).filter((id) => warnable.has(id));
+}
+/** The policy, verbatim: also the first comment of what `check --init` writes. */
+export const CONFIG_POLICY = "The config changes warnings only. Errors are the contract Queek checks when you submit, so nothing turns them off. If an error is wrong for your theme, open an issue: https://github.com/usequeek/theme-tools/issues";
+/** What `check --init` writes: the policy, every warnable rule id commented out, and a sample ignore. */
+export function renderInitConfig() {
+    return [
+        `# ${CONFIG_POLICY}`,
+        'rules:',
+        ...warningRuleIds().map((id) => `  #  ${id}: off`),
+        'ignore:',
+        '  #  - theme/vendor/**',
+        '',
+    ].join('\n');
+}

package/dist/context.d.ts

@@ -9,7 +9,7 @@ export declare function localEnv(dir: string, cwd?: string): CheckEnv;
  * 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. */
+/** Every JS/TS source file 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

package/dist/context.js

@@ -1,7 +1,7 @@
 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';
+import { PRIMARY_DEMO_ID, 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';
 /**
@@ -18,7 +18,8 @@ export function localEnv(dir, cwd = process.cwd()) {
         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}`,
+        preview: (templateId) => `http://localhost:7833/${templateId}`,
+        capture: (designId) => designId === PRIMARY_DEMO_ID ? 'npx queek-theme screenshot' : `npx queek-theme screenshot ${designId}`,
         submission: false,
     };
 }
@@ -80,13 +81,13 @@ export async function loadContext(themeDir, env = {}) {
         read,
     };
 }
-/** Every .ts/.tsx under a theme, for the whole-tree scans. */
+/** Every JS/TS source file 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] : [];
+        return /\.[mc]?[jt]sx?$/.test(entry.name) ? [full] : [];
     });
 }
 /**

package/dist/format.d.ts

@@ -1,4 +1,5 @@
 import type { CheckResult } from './run.js';
+import { AT_SUBMISSION } from './run.js';
 import type { Finding } from './types.js';
 /** Severity as developers' tools spell it (ESLint, SARIF, GitHub). */
 export type Level = 'error' | 'warning';
@@ -10,6 +11,26 @@ export interface Summary {
     warnings: number;
 }
 export declare function summarize(findings: Finding[]): Summary;
+export interface JsonFinding {
+    rule: string;
+    level: Level;
+    file: string | null;
+    where: string | null;
+    message: string;
+    fix: string;
+    docs: string | null;
+    fixable: boolean;
+}
+/** Machine-readable report: stable keys, one object per run. */
+export interface JsonReport {
+    theme: string;
+    summary: Summary;
+    vocabulary: CheckResult['vocabulary'];
+    findings: JsonFinding[];
+    atSubmission: typeof AT_SUBMISSION;
+}
+/** The object the machine-readable output is built from. */
+export declare function jsonReport(result: CheckResult): JsonReport;
 /** 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. */

package/dist/format.js

@@ -11,9 +11,9 @@ export function summarize(findings) {
         warnings: findings.filter((finding) => levelOf(finding) === 'warning').length,
     };
 }
-/** Machine-readable output: stable keys, one object per run. */
-export function formatJson(result) {
-    return JSON.stringify({
+/** The object the machine-readable output is built from. */
+export function jsonReport(result) {
+    return {
         theme: result.context.slug,
         summary: summarize(result.findings),
         vocabulary: result.vocabulary,
@@ -28,7 +28,11 @@ export function formatJson(result) {
             fixable: finding.fixable ?? false,
         })),
         atSubmission: AT_SUBMISSION,
-    }, null, 2);
+    };
+}
+/** Machine-readable output: stable keys, one object per run. */
+export function formatJson(result) {
+    return JSON.stringify(jsonReport(result), null, 2);
 }
 /** GitHub Actions workflow commands — annotations on the pull request's diff. */
 export function formatGithubActions(result) {

package/dist/index.d.ts

@@ -6,12 +6,14 @@
 export { checkTheme, rejects, RULES, AT_SUBMISSION, type CheckOptions, type CheckResult, type CheckVocabulary } from './run.js';
 export { resolveVocabulary, vocabularyCacheDir, readCachedVocabulary, bundledVocabulary, bundledVersion, parseEndpointPayload, parseVocabularyData, VOCABULARY_URL, VOCABULARY_CACHE_TTL_MS, type BusinessVocabularyData, type ResolveVocabularyOptions, type ResolvedVocabulary, type VocabularySource, } from './vocabulary.js';
 export { loadContext, localEnv, CONTRACT_URL } from './context.js';
-export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf, type Level, type Summary } from './format.js';
+export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf, jsonReport, type JsonFinding, type JsonReport, type Level, type Summary } from './format.js';
+export { loadProjectConfig, applyProjectConfig, warningRuleIds, renderInitConfig, CONFIG_FILE_NAME, CONFIG_POLICY, ConfigError, type ConfigRuleLevel, type ProjectConfig, } from './config.js';
+export { editDistance, closestRuleId } from './utils/closest-id.js';
 export type { CheckEnv, Finding, Rule, Severity, ThemeContext, DemoStore, DeclaredDemo } from './types.js';
 export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, SUBCATEGORIES, ROOT_SERVICE, BUNDLED_VERSION, bundledVocabularyView, vocabularyViewOf, isBusinessKey, businessRoot, type VocabularyView } from './utils/business-vocabulary.js';
 export { TEMPLATE_COPY_PLACES, copyViolations, isTestimonialSection, storeNameForms } from './utils/template-copy.js';
 export { PRIMARY_DEMO_ID, DEMO_ID_FORMAT, demoFilesOf } from './utils/theme-demos.js';
 export { designsOf, groupTemplates, mainTemplateKey, composeLabel, type DesignDeclaration, type ThemeDesignsConfig, type ThemeDesign, type ThemeTemplate, } from './utils/theme-designs.js';
 export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, declaredFieldsByVariant } from './utils/theme-templates.js';
-export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, compositionVariantsRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templateDesignsRule, TEMPLATE_DESIGNS_MAX, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, frameworkImport, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
+export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, compositionVariantsRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templateDesignsRule, TEMPLATE_DESIGNS_MAX, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, markdownHtmlRule, frameworkImport, moduleSpecifiers, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
 export { ANALYSIS_RULES, variantParityRule, fieldParityRule, designTokensRule } from './rules/analysis.js';

package/dist/index.js

@@ -6,7 +6,9 @@
 export { checkTheme, rejects, RULES, AT_SUBMISSION } from './run.js';
 export { resolveVocabulary, vocabularyCacheDir, readCachedVocabulary, bundledVocabulary, bundledVersion, parseEndpointPayload, parseVocabularyData, VOCABULARY_URL, VOCABULARY_CACHE_TTL_MS, } from './vocabulary.js';
 export { loadContext, localEnv, CONTRACT_URL } from './context.js';
-export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf } from './format.js';
+export { formatJson, formatGithubActions, formatStylish, summarize, levelOf, fileOf, jsonReport } from './format.js';
+export { loadProjectConfig, applyProjectConfig, warningRuleIds, renderInitConfig, CONFIG_FILE_NAME, CONFIG_POLICY, ConfigError, } from './config.js';
+export { editDistance, closestRuleId } from './utils/closest-id.js';
 export { BUSINESS_KEYS, SERVICE_SLUGS, CATALOGUE, SUBCATEGORIES, ROOT_SERVICE, BUNDLED_VERSION, bundledVocabularyView, vocabularyViewOf, isBusinessKey, businessRoot } from './utils/business-vocabulary.js';
 export { TEMPLATE_COPY_PLACES, copyViolations, isTestimonialSection, storeNameForms } from './utils/template-copy.js';
 export { PRIMARY_DEMO_ID, DEMO_ID_FORMAT, demoFilesOf } from './utils/theme-demos.js';
@@ -17,5 +19,5 @@ export { TEMPLATE_DESCRIPTION_MAX, screenshotFile, sectionStyle, sectionCopy, de
 // Per-kind rule arrays and the individual rule constants, for rule-level unit
 // tests that want to run one rule against a hand-built ThemeContext instead
 // of a whole theme directory through checkTheme().
-export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, compositionVariantsRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templateDesignsRule, TEMPLATE_DESIGNS_MAX, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, frameworkImport, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
+export { STATIC_RULES, moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, compositionVariantsRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule, templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule, templateBusinessRule, templateVersionsRule, templateDesignsRule, TEMPLATE_DESIGNS_MAX, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule, markdownHtmlRule, frameworkImport, moduleSpecifiers, STARTER_PLACEHOLDER_IMAGES, } from './rules/static.js';
 export { ANALYSIS_RULES, variantParityRule, fieldParityRule, designTokensRule } from './rules/analysis.js';

package/dist/rules/static.d.ts

@@ -16,6 +16,13 @@ export declare const codeQualityRule: Rule;
  * import Next, a theme may not.
  */
 export declare function frameworkImport(source: string): string | null;
+/**
+ * Every static module specifier in a source file: `import … from`,
+ * `export … from`, side-effect `import '…'`, dynamic `import('…')` and
+ * `require('…')`. Parsed like frameworkImport — regexes, not a bundler — so
+ * a theme whose module graph will not load still gets checked.
+ */
+export declare function moduleSpecifiers(source: string): string[];
 export declare const sdkBoundaryRule: Rule;
 /**
  * The ThemeModule shape (Layout, Header, Footer, blocks, getBlock, pages…) is
@@ -80,4 +87,5 @@ export declare const fontsSelfHostedRule: Rule;
 /** The starter's labelled placeholder images ("Your banner photo", "Category photo", "Product photo") under theme-assets/_bare. */
 export declare const STARTER_PLACEHOLDER_IMAGES: readonly string[];
 export declare const placeholderContentRule: Rule;
+export declare const markdownHtmlRule: Rule;
 export declare const STATIC_RULES: Rule[];

package/dist/rules/static.js

@@ -1,4 +1,4 @@
-import { join, relative } from 'node:path';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { readdirSync, existsSync, readFileSync } from 'node:fs';
 import { foreignImageRefs } from '../utils/theme-demo-images.js';
 import { DEMO_ID_FORMAT, PRIMARY_DEMO_ID } from '../utils/theme-demos.js';
@@ -52,7 +52,7 @@ export const structureRule = {
             findings.push(finding(context, 'theme/structure', 'reject', {
                 where: `${context.env.root}`,
                 found: `no theme screenshot (${SCREENSHOTS.join(' or ')})`,
-                fix: `Capture the homepage at 1280×800 from ${context.env.preview('default')} and save it as theme.jpg.`,
+                fix: `Run \`${context.env.capture('default')}\` — it captures the homepage at 1280×800 into theme.jpg.`,
                 docs: `${context.env.docs}#theme-png`,
             }));
         }
@@ -308,9 +308,29 @@ export function frameworkImport(source) {
     const match = source.match(/(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)['"](next(?:\/[\w./-]+)?)['"]/);
     return match ? match[1] : null;
 }
+/**
+ * Every static module specifier in a source file: `import … from`,
+ * `export … from`, side-effect `import '…'`, dynamic `import('…')` and
+ * `require('…')`. Parsed like frameworkImport — regexes, not a bundler — so
+ * a theme whose module graph will not load still gets checked.
+ */
+export function moduleSpecifiers(source) {
+    const found = [];
+    const patterns = [
+        /(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]/g,
+        /\bimport\s*['"]([^'"]+)['"]/g,
+        /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+        /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+    ];
+    for (const pattern of patterns) {
+        for (const match of source.matchAll(pattern))
+            found.push(match[1]);
+    }
+    return found;
+}
 export const sdkBoundaryRule = {
     id: 'theme/core-boundary',
-    summary: 'No SDK or framework imports, no direct API calls, no store mutations',
+    summary: 'No SDK or framework imports, no app-code imports or escapes, no direct API calls, no store mutations',
     kind: 'static',
     run(context) {
         const findings = [];
@@ -334,6 +354,33 @@ export const sdkBoundaryRule = {
                     docs: `${context.env.docs}#what-themes-must-not-do`,
                 }));
             }
+            // A theme is a self-contained folder: it imports packages and its own
+            // files, never the app around it. `@/` only resolves inside the
+            // storefront repo, and a relative import past the theme root only
+            // resolves there too — both break in a developer's `npm create`
+            // project and in `theme:pull`.
+            const root = resolve(context.dir);
+            for (const spec of moduleSpecifiers(source)) {
+                if (spec.startsWith('@/')) {
+                    findings.push(finding(context, 'theme/core-boundary', 'reject', {
+                        where,
+                        found: `imports app code ('${spec}')`,
+                        fix: "Move the code into the theme's own folder, or import it from '@usequeek/theme-kit'.",
+                        docs: `${context.env.docs}#what-themes-must-not-do`,
+                    }));
+                }
+                else if (spec.startsWith('.')) {
+                    const resolved = resolve(dirname(path), spec);
+                    if (resolved !== root && !resolved.startsWith(root + sep)) {
+                        findings.push(finding(context, 'theme/core-boundary', 'reject', {
+                            where,
+                            found: `relative import '${spec}' escapes the theme (resolves to ${relative(root, resolved)})`,
+                            fix: "Move the code into the theme's own folder, or import it from '@usequeek/theme-kit'.",
+                            docs: `${context.env.docs}#what-themes-must-not-do`,
+                        }));
+                    }
+                }
+            }
             if (/\b(?:fetch|axios)\s*\(\s*['"`]https?:/.test(source)) {
                 findings.push(finding(context, 'theme/core-boundary', 'reject', {
                     where,
@@ -802,7 +849,7 @@ export const templateScreenshotRule = {
                 return [finding(context, 'theme/template-screenshot', 'reject', {
                         where,
                         found: `template "${id}" has no screenshot`,
-                        fix: `Capture the template's first screen at 1280×800 (${context.env.preview(id)}) and save it here. The AI looks at this image before committing to a template — a missing one means a blind pick.`,
+                        fix: `Run \`${context.env.capture(id)}\` — it captures this design's first screen at 1280×800 into ${file}. The AI looks at this image before committing to a template — a missing one means a blind pick.`,
                         docs: `${context.env.docs}#templates`,
                     })];
             }
@@ -1443,7 +1490,53 @@ export const placeholderContentRule = {
         return findings;
     },
 };
+/* ── renderMarkdown returns elements, not an HTML string ────────────── */
+/** The 1-based line of an offset in source. */
+function sourceLineOf(source, offset) {
+    return source.slice(0, offset).split('\n').length;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export const markdownHtmlRule = {
+    id: 'theme/markdown-html',
+    summary: 'renderMarkdown elements render as children, never through dangerouslySetInnerHTML',
+    kind: 'static',
+    run(context) {
+        const findings = [];
+        for (const path of themeSourceFiles(context.dir)) {
+            if (!path.endsWith('.ts') && !path.endsWith('.tsx'))
+                continue;
+            const source = readFileSync(path, 'utf8');
+            const add = (offset) => {
+                findings.push(finding(context, 'theme/markdown-html', 'reject', {
+                    where: `${themePath(context, path)}:${sourceLineOf(source, offset)}`,
+                    found: 'renderMarkdown(…) passed to dangerouslySetInnerHTML — it returns elements, so the page shows "[object Object]"',
+                    fix: 'Render the elements as children: `<div className="…">{renderMarkdown(text, basePath)}</div>`, or use `<Markdown>` from @usequeek/theme-kit/components/markdown.',
+                    docs: `${context.env.docs}#what-themes-must-not-do`,
+                }));
+            };
+            // (a) the call straight in the prop, across any whitespace or newlines.
+            for (const match of source.matchAll(/dangerouslySetInnerHTML\s*=\s*\{\{\s*__html\s*:\s*renderMarkdown\s*\(/g)) {
+                add(match.index + match[0].indexOf('__html'));
+            }
+            // (b) the call assigned to a name first (`const`/`let`/`var`), then used as `__html: name`.
+            const names = new Set();
+            for (const match of source.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?renderMarkdown\s*\(/g)) {
+                if (match[1])
+                    names.add(match[1]);
+            }
+            for (const name of names) {
+                for (const match of source.matchAll(new RegExp(`__html\\s*:\\s*${escapeRegExp(name)}\\b`, 'g'))) {
+                    add(match.index);
+                }
+            }
+        }
+        return findings;
+    },
+};
 export const STATIC_RULES = [moduleContractRule, structureRule, demoStoreRule, demoStoresRule, demoArtRule, codeQualityRule, sdkBoundaryRule, selectionMetadataRule, demoCompletenessRule, subscribeScopeRule, demoBlockTypesRule, compositionVariantsRule, identityRule, productMetafieldsRule, poweredByRule, fontsSelfHostedRule,
     templateDescriptionRule, templateScreenshotRule, templateChromeRule, templateStyleRule,
     templateBusinessRule, templateVersionsRule, templateDesignsRule, templatePagesRule, templateCopyRule, vendorFactsRule, placeholderContentRule,
+    markdownHtmlRule,
 ];

package/dist/run.d.ts

@@ -24,6 +24,8 @@ export interface CheckOptions {
     only?: string[];
     /** The vocabulary the rules read from the context. Default: the bundled snapshot, so existing callers keep working. */
     vocabulary?: CheckVocabulary;
+    /** Called with each rule's elapsed milliseconds (used for `--verbose` per-rule timing). */
+    profile?: (ruleId: string, ms: number) => void;
 }
 export interface CheckResult {
     context: ThemeContext;

package/dist/run.js

@@ -27,6 +27,7 @@ export async function checkTheme(themeDir, options = {}) {
     const rules = RULES.filter((rule) => !options.only || options.only.includes(rule.id));
     const findings = [];
     for (const rule of rules) {
+        const started = Date.now();
         try {
             findings.push(...(await rule.run(context)));
         }
@@ -42,6 +43,9 @@ export async function checkTheme(themeDir, options = {}) {
                 fix: 'Usually a theme module that fails to load. Run `npx tsc --noEmit` and fix the error first.',
             });
         }
+        finally {
+            options.profile?.(rule.id, Date.now() - started);
+        }
     }
     return { context, findings, vocabulary: { source, version: view.version } };
 }

package/dist/types.d.ts

@@ -100,6 +100,8 @@ export interface CheckEnv {
     scaffold: string;
     /** Where a template previews, by template id (`default` is the primary). */
     preview: (templateId: string) => string;
+    /** The command that captures a design's screenshot (`default` is the primary). */
+    capture: (designId: string) => string;
     /**
      * True when Queek is checking a submission. Two checks only mean anything
      * then: demo art on Queek's CDN, and screenshots uploaded — both done by the

package/dist/utils/closest-id.d.ts

@@ -0,0 +1,4 @@
+/** Plain Levenshtein edit distance, for "did you mean" suggestions. */
+export declare function editDistance(a: string, b: string): number;
+/** The known id closest to `id` by edit distance, or null when there are no candidates. */
+export declare function closestRuleId(id: string, known: Iterable<string>): string | null;

package/dist/utils/closest-id.js

@@ -0,0 +1,27 @@
+/** Plain Levenshtein edit distance, for "did you mean" suggestions. */
+export function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = prev[0] ?? 0;
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = prev[j] ?? 0;
+            prev[j] = Math.min(above + 1, (prev[j - 1] ?? 0) + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return prev[b.length] ?? 0;
+}
+/** The known id closest to `id` by edit distance, or null when there are no candidates. */
+export function closestRuleId(id, known) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const candidate of known) {
+        const distance = editDistance(id, candidate);
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-check",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The rules a Queek storefront theme is checked against, as a library.",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,9 @@
   },
   "dependencies": {
     "jiti": "^2.7.0",
-    "typescript": "~5.9.3"
+    "picomatch": "^4.0.7",
+    "typescript": "~5.9.3",
+    "yaml": "^2.9.1"
   },
   "peerDependencies": {
     "@usequeek/theme-kit": ">=0.1.8"
@@ -52,6 +54,9 @@
       "optional": false
     }
   },
+  "devDependencies": {
+    "@types/picomatch": "^4.0.3"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync('src/utils/business-vocabulary.json','dist/utils/business-vocabulary.json')\"",
     "typecheck": "tsc -p tsconfig.json --noEmit"