story-theme-mcp 1.0.0

package/src/validate/design.js

@@ -0,0 +1,258 @@
+import { plainText, headingLevels } from './richtext.js';
+import { auditSchemes } from './color.js';
+import { normalizeText, templateTypeOf } from '../theme/catalog.js';
+import { EXPECTED_MAIN } from './template.js';
+
+// Design review: what makes a store look amateur even when every file is valid.
+// Levels: important (fix before launch), suggestion (worth doing), info (to know).
+
+const HERO_TYPES = new Set(['banner', 'slideshow', 'video', 'scroll-zoom', 'featured-product']);
+const TEXT_SETTING_TYPES = new Set(['text', 'textarea', 'richtext', 'inline_richtext']);
+const PLACEHOLDER_RE = /lorem ipsum|\[(?:à|a) personnaliser|\btodo\b|\bxxx\b|votre (?:titre|texte) ici|your (?:title|text) here|tell your customers|describe what|add a personal message|parlez de votre|décrivez ici/i;
+// Sample texts that speak to the merchant ("Présentez…", "Tell your customers…").
+const INSTRUCTION_RE = /^(présentez|presentez|dites|racontez|décrivez|decrivez|ajoutez|parlez|invitez|partagez|expliquez|utilisez|indiquez|montrez|mettez|tell|describe|share|add|use|explain|introduce|show|give|invite)\b/i;
+// Blocks whose sample content states facts about the business (reviews, figures, policies).
+const CLAIM_BLOCKS = {
+  testimonial: "témoignage d'exemple : remplacez-le par un vrai avis client, ou supprimez-le",
+  counter: "chiffre d'exemple : uniquement un chiffre réel et vérifiable, sinon supprimez-le",
+  accordion: "réponse d'exemple : elle doit décrire vos vraies conditions (délais, retours, paiement)",
+  checklist: "promesses d'exemple (livraison, retours…) : elles doivent correspondre à vos vraies conditions",
+  _announcement: "annonce d'exemple : elle doit correspondre à une vraie offre ou condition",
+  'marquee-text': "messages d'exemple : ils doivent correspondre à vos vraies conditions",
+};
+const EN_WORDS = new Set(['the', 'and', 'your', 'you', 'with', 'our', 'for', 'shop', 'now', 'free', 'are', 'this', 'that', 'from', 'more', 'what', 'how', 'we', 'all', 'new', 'discover', 'learn', 'about', 'customers', 'products', 'best', 'is', 'it', 'of', 'to', 'in']);
+const FR_WORDS = new Set(['le', 'la', 'les', 'des', 'et', 'vos', 'votre', 'nous', 'pour', 'avec', 'une', 'un', 'du', 'est', 'sur', 'dans', 'nos', 'plus', 'qui', 'que', 'decouvrir', 'livraison', 'offerte', 'produits', 'boutique', 'au', 'aux', 'en', 'de']);
+
+export function looksEnglish(text) {
+  const words = normalizeText(text).split(' ').filter(Boolean);
+  if (words.length < 3) return false;
+  const en = words.filter((word) => EN_WORDS.has(word)).length;
+  const fr = words.filter((word) => FR_WORDS.has(word)).length;
+  return en >= 2 && en > fr * 2;
+}
+
+// Texts shipped as samples: every translated preset string and every shipped template text.
+export function sampleTexts(catalog) {
+  if (catalog._samples) return catalog._samples;
+  const samples = new Set();
+  const addValue = (value) => {
+    if (typeof value !== 'string') return;
+    const text = normalizeText(plainText(value));
+    if (text.length >= 3) samples.add(text);
+  };
+  const walkPreset = (node, languages) => {
+    for (const value of Object.values(node?.settings || {})) {
+      if (typeof value === 'string' && value.startsWith('t:')) languages.forEach((language) => addValue(catalog.resolveKey(value.slice(2), language)));
+      else addValue(value);
+    }
+    const blocks = Array.isArray(node?.blocks) ? node.blocks : Object.values(node?.blocks || {});
+    blocks.forEach((block) => walkPreset(block, languages));
+  };
+  const languages = ['en', 'fr'];
+  for (const map of [catalog.theme.sections, catalog.theme.blocks]) {
+    for (const entry of map.values()) for (const preset of entry.schema?.presets || []) walkPreset(preset, languages);
+  }
+  const walkTemplate = (node) => {
+    for (const value of Object.values(node?.settings || {})) addValue(value);
+    for (const block of Object.values(node?.blocks || {})) walkTemplate(block);
+  };
+  for (const data of [...catalog.theme.templates.values(), ...catalog.theme.groups.values()]) {
+    for (const section of Object.values(data?.sections || {})) walkTemplate(section);
+  }
+  catalog._samples = samples;
+  return samples;
+}
+
+// The colour scheme painting a section's background: frame_palette on hero-frame sections
+// (banner, slideshow, scroll sections), else color_palette, else color_scheme.
+export function sectionPalette(catalog, section) {
+  const settings = catalog.section(section.type)?.schema?.settings || [];
+  for (const id of ['frame_palette', 'color_palette', 'color_scheme']) {
+    const setting = settings.find((item) => item.id === id && item.type === 'color_scheme');
+    if (setting) return section.settings?.[id] ?? setting.default ?? null;
+  }
+  return null;
+}
+
+function* walkBlocks(node, path) {
+  for (const [id, block] of Object.entries(node?.blocks || {})) {
+    const blockPath = `${path}/${id}`;
+    yield { id, block, path: blockPath };
+    yield* walkBlocks(block, blockPath);
+  }
+}
+
+function settingType(catalog, kind, type, key) {
+  const entry = kind === 'section' ? catalog.section(type) : catalog.block(type);
+  return (entry?.schema?.settings || []).find((setting) => setting.id === key)?.type;
+}
+
+export function lintTemplate(catalog, file, data, { language = 'fr' } = {}) {
+  const findings = [];
+  const add = (level, path, message) => findings.push({ level, file, path, message });
+  if (!data?.sections) return findings;
+  const templateType = file.startsWith('templates/') ? templateTypeOf(file) : null;
+  const order = (data.order || []).filter((id) => data.sections[id] && !data.sections[id].disabled);
+  const samples = sampleTexts(catalog);
+  let h1Count = 0;
+  let faqSchemas = 0;
+  let popups = 0;
+  let autoplayMedia = 0;
+
+  const checkTexts = (kind, type, settings, path) => {
+    for (const [key, value] of Object.entries(settings || {})) {
+      if (typeof value !== 'string' || !value) continue;
+      const settingKind = settingType(catalog, kind, type, key);
+      if (!TEXT_SETTING_TYPES.has(settingKind)) continue;
+      const text = plainText(value);
+      if (!text) continue;
+      h1Count += headingLevels(value).filter((level) => level === 1).length;
+      const english = language !== 'en' && looksEnglish(text);
+      const quoted = `« ${text.length > 60 ? text.slice(0, 57) + '…' : text} »`;
+      if (/\*\*[^*\s][^*]*\*\*/.test(text)) {
+        add('important', `${path}.${key}`, `gras écrit en markdown, affiché tel quel avec ses étoiles : ${quoted}. Écrivez <strong>mot</strong> (ou passez par compose_page, qui convertit **mot**)`);
+      }
+      if (PLACEHOLDER_RE.test(text) || INSTRUCTION_RE.test(text)) {
+        add('important', `${path}.${key}`, `texte provisoire (consigne du thème) à remplacer : ${quoted}`);
+      } else if (samples.has(normalizeText(text))) {
+        // Short labels ("Nos collections", "Entretien") can stay; claims and copy cannot.
+        const words = text.split(/\s+/).length;
+        // Years and plain numbers (timeline labels) are the merchant's; sample figures are not.
+        const label = (words <= 3 && !/\d/.test(text)) || (/^[\d\s.,/-]+$/.test(text) && type !== 'counter');
+        if (english) add('important', `${path}.${key}`, `texte d'exemple du thème en anglais : ${quoted}`);
+        else if (label) continue;
+        else if (CLAIM_BLOCKS[type]) add('important', `${path}.${key}`, `${CLAIM_BLOCKS[type]} : ${quoted}`);
+        else if (words > 4 || /\d/.test(text)) add('important', `${path}.${key}`, `texte d'exemple du thème, à écrire pour la marque : ${quoted}`);
+      } else if (english) add('important', `${path}.${key}`, `texte en anglais sur une boutique en ${language} : ${quoted}`);
+    }
+  };
+
+  for (const [position, id] of order.entries()) {
+    const section = data.sections[id];
+    const settings = section.settings || {};
+    checkTexts('section', section.type, settings, id);
+    if (settings.structured_data) faqSchemas += 1;
+    if (section.type === 'popup') popups += 1;
+    if ((section.type === 'banner' && settings.media_type === 'video') || section.type === 'video') autoplayMedia += 1;
+    if (settings.hide_desktop && settings.hide_mobile) add('info', id, 'section masquée sur ordinateur et sur mobile');
+    if (section.type === 'custom-liquid') add('suggestion', id, 'code Liquid personnalisé : le marchand ne pourra pas le modifier sans développeur');
+    if (position === 0 && templateType === 'index' && !HERO_TYPES.has(section.type)) {
+      add('suggestion', id, `la page d'accueil commence par « ${section.type} » : un héro (banner, slideshow, video) pose la promesse de la marque dès l'arrivée`);
+    }
+    if (section.type === 'banner' && !settings.image && !settings.video && !settings.video_url && settings.media_type !== 'none') {
+      add('important', id, "héro sans photo : il s'affiche comme un aplat vide. Donnez une photo (build_store images.hero, ou image: shopify://shop_images/…) ou passez en héro typographique (media_type none, color_palette = frame_palette)");
+    }
+    if (section.type === 'banner' && settings.media_type === 'none' && (settings.color_palette ?? 'inverse') !== (settings.frame_palette ?? 'background-1')) {
+      add('important', id, 'héro sans photo : le texte suit la palette prévue pour être posé sur une image et devient illisible sur le fond. Mettez color_palette égal à frame_palette');
+    }
+
+    for (const { block, path } of walkBlocks(section, id)) {
+      const blockSettings = block.settings || {};
+      if (block.disabled) continue;
+      checkTexts('block', block.type, blockSettings, path);
+      if (block.type === 'button' && blockSettings.button_text && plainText(blockSettings.button_text)) {
+        const label = plainText(blockSettings.button_text);
+        if (!blockSettings.button_link) add('important', path, `bouton « ${label} » sans lien`);
+        if (label.length > 28) add('suggestion', path, `libellé de bouton long (${label.length} caractères) : visez 2 à 4 mots`);
+      }
+      if (block.type === 'heading' && HERO_TYPES.has(section.type)) {
+        const title = plainText(blockSettings.title);
+        if (title.length > 70) add('suggestion', path, `titre de héro long (${title.length} caractères) : une promesse courte se lit en une seconde`);
+      }
+      if (block.type === 'countdown' && blockSettings.renew && blockSettings.renew !== '0') {
+        add('important', path, 'compte à rebours qui redémarre tout seul : urgence artificielle, pratique commerciale trompeuse (et contraire au positionnement premium). Visez une vraie date de fin.');
+      }
+      if (block.type === 'product-stock' && blockSettings.source === 'simulated') {
+        add('important', path, 'stock simulé : afficher un faux stock est une pratique commerciale trompeuse. Utilisez le stock Shopify.');
+      }
+      if (block.type === 'image' && !blockSettings.image) add('important', path, "image vide : un carré gris « image manquante » s'affiche. Placez une photo ou retirez le bloc");
+      if (block.type === 'rating' || (block.type === 'product-rating' && blockSettings.source === 'manual')) {
+        add('suggestion', path, 'note saisie à la main : elle doit refléter vos avis réels (sinon supprimez le bloc)');
+      }
+    }
+  }
+
+  // Page-level rules
+  if (templateType === 'index') {
+    if (order.length > 14) add('suggestion', '', `${order.length} sections sur l'accueil : au-delà d'une douzaine, le visiteur décroche. Gardez ce qui sert la vente.`);
+    if (order.length > 0 && order.length < 7) add('important', '', `accueil trop court (${order.length} sections) : visez 8 à 10. Remplacez chaque section retirée par une section honnête (bénéfices, FAQ, liste de produits, bandeau défilant, collections)`);
+    const types = order.map((id) => data.sections[id].type);
+    if (!types.some((type) => ['product-list', 'featured-product', 'collection-list', 'bundle-builder'].includes(type))) {
+      add('important', '', "aucune section produit sur l'accueil : montrez au moins vos meilleures ventes (product-list)");
+    }
+    if (!types.some((type) => ['testimonials', 'reviews', 'ugc', 'logo-list', 'stats'].includes(type))) {
+      add('suggestion', '', "pas de preuve sociale sur l'accueil (avis, témoignages, logos presse, photos clients)");
+    }
+  }
+  for (let index = 2; index < order.length; index++) {
+    const [a, b, c] = [order[index - 2], order[index - 1], order[index]].map((id) => data.sections[id].type);
+    if (a === b && b === c) add('suggestion', order[index], `trois sections « ${a} » d'affilée : variez les formats pour garder le rythme`);
+  }
+  // Hero sections are covered by their media: their own palette does not show as a background.
+  const palettes = order
+    .filter((id) => !HERO_TYPES.has(data.sections[id].type))
+    .map((id) => ({ id, palette: sectionPalette(catalog, data.sections[id]) }))
+    .filter((entry) => entry.palette);
+  if (templateType === 'index' && palettes.length >= 6 && new Set(palettes.map((entry) => entry.palette)).size <= 1) {
+    add('suggestion', '', 'toutes les sections sur la même palette : alternez avec background-2 ou inverse pour rythmer la page');
+  }
+  for (let index = 1; index < palettes.length; index++) {
+    const [previous, current] = [palettes[index - 1], palettes[index]];
+    if (current.palette === previous.palette && current.palette !== 'background-1' && order.indexOf(current.id) === order.indexOf(previous.id) + 1) {
+      add('suggestion', current.id, `même palette « ${current.palette} » que la section précédente : les deux fonds se confondent (passez l'une en background-1)`);
+    }
+  }
+  if (h1Count > 1) add('important', '', `${h1Count} titres <h1> sur la page : gardez-en un seul (SEO et accessibilité)`);
+  if (templateType === 'index' && h1Count === 0) add('suggestion', '', "aucun <h1> sur l'accueil : le titre du héro devrait l'être (<h1>…</h1> dans le bloc heading)");
+  if (faqSchemas > 1) add('important', '', 'plusieurs FAQ avec données structurées sur la même page : une seule FAQPage par page');
+  if (popups > 1) add('important', '', `${popups} pop-ups sur la même page : une seule, sinon le visiteur part`);
+  if (autoplayMedia > 2) add('suggestion', '', `${autoplayMedia} sections vidéo : chaque vidéo pèse sur le chargement, gardez les plus utiles`);
+
+  if (templateType === 'product') {
+    const main = order.map((id) => data.sections[id]).find((section) => section.type === EXPECTED_MAIN.product);
+    if (main) {
+      const types = new Set([...walkBlocks(main, 'main')].filter(({ block }) => !block.disabled).map(({ block }) => block.type));
+      for (const [type, label] of [['product-title', 'titre'], ['product-price', 'prix'], ['product-buy', "bouton d'achat"], ['product-media', 'galerie']]) {
+        if (!types.has(type)) add('important', 'main', `fiche produit sans ${label} (${type})`);
+      }
+      if (!['checklist', 'trust-badges', 'accordion', 'product-delivery', 'product-spin-message'].some((type) => types.has(type))) {
+        add('suggestion', 'main', 'aucune réassurance près du bouton (livraison, retours, paiement sécurisé) : ajoutez checklist, trust-badges ou product-delivery');
+      }
+      if (types.has('product-offers') || types.has('product-addons') || types.has('bundle-builder')) {
+        add('info', 'main', "offres présentes : le thème affiche les remises, mais c'est Shopify qui les facture. Créez la réduction automatique (ou le code) correspondant à chaque offre.");
+      }
+      if (types.has('product-rating') || types.has('review-summary')) {
+        add('info', 'main', "les notes produit lisent les métachamps d'avis (reviews.rating) : une application d'avis doit les remplir");
+      }
+    }
+    if (!order.some((id) => ['testimonials', 'reviews', 'ugc'].includes(data.sections[id].type))) {
+      add('suggestion', '', "pas d'avis clients sur la fiche produit : c'est le premier levier de conversion");
+    }
+  }
+  return findings;
+}
+
+export function lintSettings(catalog, settingsData) {
+  const findings = [];
+  const add = (level, path, message) => findings.push({ level, file: 'config/settings_data.json', path, message });
+  const current = typeof settingsData?.current === 'string' ? settingsData.presets?.[settingsData.current] : settingsData?.current;
+  if (!current) return findings;
+  const buttons = { 1: current.button_1_palette || 'accent-1', 2: current.button_2_palette || 'text-outline', 3: current.button_3_palette || 'text' };
+  for (const finding of auditSchemes(current.color_schemes || {}, buttons)) {
+    if (finding.level === 'ok') continue;
+    add(finding.level === 'error' ? 'important' : 'suggestion', `color_schemes.${finding.scheme}`, `contraste insuffisant — ${finding.message}`);
+  }
+  // Unknown and deprecated fonts are reported by the validator.
+  if (current.headings_font && current.headings_font === current.body_font) {
+    add('suggestion', 'headings_font', 'même police et même graisse pour les titres et le texte : donnez du contraste aux titres (graisse 5 à 7, ou une autre famille)');
+  }
+  const socials = Object.keys(current).filter((key) => /^social_.*_link$/.test(key) && current[key]);
+  const sampleSocial = socials.filter((key) => /shopify|example\.com/i.test(current[key]));
+  if (sampleSocial.length) add('important', 'social', `liens réseaux sociaux d'exemple : ${sampleSocial.join(', ')}`);
+  if (!socials.length) add('info', 'social', 'aucun réseau social renseigné (réglages du thème > Réseaux sociaux)');
+  if (!current.favicon) add('info', 'favicon', 'favicon à fournir (image carrée 32 × 32 px ou plus)');
+  if (current.disable_right_click || current.disable_selection_text) {
+    add('suggestion', 'security', "blocage du clic droit / de la sélection : gêne les clients (copier une référence, un code promo) sans protéger vraiment les images");
+  }
+  return findings;
+}

package/src/validate/richtext.js

@@ -0,0 +1,103 @@
+const BLOCK_TAGS = new Set(['p', 'ul', 'ol', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+const RICHTEXT_TAGS = new Set([...BLOCK_TAGS, 'li', 'br', 'strong', 'b', 'em', 'i', 'u', 'span', 'a', 's', 'sub', 'sup']);
+const INLINE_TAGS = new Set(['strong', 'b', 'em', 'i', 'u', 'span', 'a', 's', 'sub', 'sup']);
+const VOID_TAGS = new Set(['br']);
+const TAG_RE = /<\/?([a-zA-Z][a-zA-Z0-9]*)\b[^>]*?(\/?)>/g;
+const LIQUID_RE = /\{\{[\s\S]*?\}\}|\{%[\s\S]*?%\}/g;
+
+function scan(html) {
+  const tokens = [];
+  let last = 0;
+  for (const match of html.matchAll(TAG_RE)) {
+    if (match.index > last) tokens.push({ text: html.slice(last, match.index) });
+    tokens.push({ tag: match[1].toLowerCase(), closing: match[0].startsWith('</'), selfClosing: match[2] === '/', raw: match[0] });
+    last = match.index + match[0].length;
+  }
+  if (last < html.length) tokens.push({ text: html.slice(last) });
+  return tokens;
+}
+
+// Checks a `richtext` value: only Shopify's rich text tags, every top-level node a block tag.
+export function checkRichtext(value) {
+  const problems = [];
+  if (value === '' || value == null) return problems;
+  const html = String(value).replace(LIQUID_RE, 'x');
+  const stack = [];
+  for (const token of scan(html)) {
+    if (token.text !== undefined) {
+      if (!stack.length && token.text.trim()) {
+        problems.push({ level: 'error', message: `du texte hors balise en premier niveau (« ${token.text.trim().slice(0, 30)} ») : chaque paragraphe doit être dans <p>, <ul>, <ol> ou <h1>-<h6>` });
+      }
+      continue;
+    }
+    if (!RICHTEXT_TAGS.has(token.tag)) {
+      problems.push({ level: 'error', message: `balise <${token.tag}> refusée dans un texte riche (autorisées : p, h1-h6, ul, ol, li, br, strong, em, u, a, span)` });
+      continue;
+    }
+    if (VOID_TAGS.has(token.tag) || token.selfClosing) continue;
+    if (!token.closing) {
+      if (!stack.length && !BLOCK_TAGS.has(token.tag)) {
+        problems.push({ level: 'error', message: `<${token.tag}> en premier niveau : entourez-le d'un <p>` });
+      }
+      stack.push(token.tag);
+    } else {
+      const index = stack.lastIndexOf(token.tag);
+      if (index === -1) problems.push({ level: 'error', message: `</${token.tag}> fermé sans avoir été ouvert` });
+      else {
+        if (index !== stack.length - 1) problems.push({ level: 'error', message: `balises mal imbriquées autour de </${token.tag}>` });
+        stack.length = index;
+      }
+    }
+  }
+  if (stack.length) problems.push({ level: 'error', message: `balise(s) non fermée(s) : ${stack.map((tag) => `<${tag}>`).join(', ')}` });
+  return dedupe(problems);
+}
+
+// Checks an `inline_richtext` value: bold, italic, links; no paragraphs.
+export function checkInlineRichtext(value) {
+  const problems = [];
+  if (value === '' || value == null) return problems;
+  const html = String(value).replace(LIQUID_RE, 'x');
+  const stack = [];
+  for (const token of scan(html)) {
+    if (token.text !== undefined) continue;
+    if (token.tag === 'br') {
+      problems.push({ level: 'warning', message: 'les retours à la ligne (<br>) ne sont pas pris en charge dans un texte riche en ligne' });
+      continue;
+    }
+    if (!INLINE_TAGS.has(token.tag)) {
+      problems.push({ level: 'error', message: `balise <${token.tag}> refusée dans un texte riche en ligne (autorisées : strong, em, u, a, span)` });
+      continue;
+    }
+    if (token.selfClosing) continue;
+    if (!token.closing) stack.push(token.tag);
+    else {
+      const index = stack.lastIndexOf(token.tag);
+      if (index === -1) problems.push({ level: 'error', message: `</${token.tag}> fermé sans avoir été ouvert` });
+      else stack.length = index;
+    }
+  }
+  if (stack.length) problems.push({ level: 'error', message: `balise(s) non fermée(s) : ${stack.map((tag) => `<${tag}>`).join(', ')}` });
+  return dedupe(problems);
+}
+
+export function plainText(value) {
+  return String(value ?? '')
+    .replace(/<br\s*\/?>/gi, ' ')
+    .replace(/<\/(p|h[1-6]|li)>/gi, ' ')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&#39;|&rsquo;/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function headingLevels(value) {
+  return [...String(value ?? '').matchAll(/<h([1-6])\b/gi)].map((match) => Number(match[1]));
+}
+
+function dedupe(problems) {
+  const seen = new Set();
+  return problems.filter((problem) => (seen.has(problem.message) ? false : seen.add(problem.message)));
+}