@stechquick/studio-cli 4.2.0-0 → 4.2.0-1

package/dist/common/agentic/qjsonBuild/validateStyles.js

@@ -0,0 +1,644 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatStyleReport = exports.validateStyles = void 0;
+// ── locate the kit root (the dir holding reference/). Resolves from the FILE being validated,
+// walking up until a candidate layout matches, so it finds the kit in the user's workspace.
+// Returns null when no reference data is found — the S-param checks then no-op. ────────────
+//
+// Reference data lives under the ui-kit package (`.ai-kit/ui-kit/reference/`). The flat
+// `.ai-kit/reference/` form is still accepted so workspaces pulled by an older CLI keep working.
+const KIT_CANDIDATES = [".", ".ai-kit/ui-kit", ".ai-kit"];
+async function findKitRoot(env, startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 8; i++) {
+        for (const candidate of KIT_CANDIDATES) {
+            const root = env.path.resolve(dir, candidate);
+            const hasStyles = await env.fs.exists(env.path.join(root, "reference", "component-styles.json"));
+            if (hasStyles)
+                return root;
+        }
+        const parent = env.path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+// ── reference data. Loaded lazily and cached per kit root, so one process can validate files
+// across different workspaces. Both files are optional: without them the S-param/prop checks
+// simply degrade to no-ops (styleParams/contractProps return null) rather than crashing. ──────
+let contracts = {};
+let styles = {};
+let loadedRoot; // undefined = never loaded
+async function loadReference(env, startDir) {
+    const root = (await findKitRoot(env, startDir)) ?? await findKitRoot(env, env.fallbackKitDir);
+    if (root === loadedRoot)
+        return; // already loaded for this root
+    loadedRoot = root;
+    const refFile = (name) => env.path.join(root ?? "", "reference", name);
+    try {
+        const contractsRaw = await env.fs.readFile(refFile("component-contracts.json"));
+        contracts = JSON.parse(contractsRaw).components ?? {};
+    }
+    catch {
+        contracts = {};
+    }
+    try {
+        const stylesRaw = await env.fs.readFile(refFile("component-styles.json"));
+        styles = JSON.parse(stylesRaw).components ?? {};
+    }
+    catch {
+        styles = {};
+    }
+}
+// ── reference lookups ──────────────────────────────────────────────────────────
+function contractProps(T) {
+    const c = contracts[T];
+    return c && c.props ? new Set(Object.keys(c.props)) : null; // null = unknown component
+}
+// Props the contract marks cssProp:"true" — legacy CSS/styling props. Always usable on a legacy
+// page, never on the S track (there, styling belongs in S). null = no contract for this component.
+function cssProps(T) {
+    const c = contracts[T];
+    if (!c || !c.props)
+        return null;
+    return new Set(Object.entries(c.props).filter(([, m]) => m?.cssProp === "true").map(([k]) => k));
+}
+function styleParams(T) {
+    const s = styles[T];
+    if (!s)
+        return null;
+    // "inheritedChildList" is the component's SC mapping data, not an S param.
+    return new Set(Object.keys(s).filter((k) => k !== "inheritedChildList"));
+}
+// the component's SC mapping template ({ styleParam: { ChildType: childParam } }), if any
+function inheritedChildList(T) {
+    const m = styles[T]?.inheritedChildList;
+    return m && typeof m === "object" && !Array.isArray(m) ? m : null;
+}
+// Params whose editor "default" does NOT match the runtime-unset behavior — auto-adding them
+// would change how existing pages render (a VCol with no flexDirection lays out as a ROW at
+// runtime; the editor suggestion says "column"). These stay explicit design decisions:
+// never flagged missing, never auto-added.
+const S_DEFAULT_EXCEPTIONS = { VCol: new Set(["flexDirection"]) };
+// the component's default-valued S params (rule S3: a placed component's S must include all of
+// these — the default value, or the design's override)
+function defaultSParams(T) {
+    const s = styles[T];
+    if (!s)
+        return null;
+    const skip = S_DEFAULT_EXCEPTIONS[T];
+    const out = {};
+    for (const [k, m] of Object.entries(s)) {
+        if (k === "inheritedChildList" || (skip && skip.has(k)))
+            continue;
+        if (m && typeof m === "object" && m.default !== undefined && m.default !== "")
+            out[k] = m.default;
+    }
+    return Object.keys(out).length ? out : null;
+}
+// component-styles.json contains a legacy typo `bacgroundColor`; treat it as backgroundColor.
+function supportsS(T, param) {
+    const s = styleParams(T);
+    if (!s)
+        return false;
+    if (s.has(param))
+        return true;
+    if (param === "backgroundColor" && s.has("bacgroundColor"))
+        return true;
+    return false;
+}
+// Vuetify 2 default theme palette — used only as a *suggested* value; the real page
+// theme may override these, so any fix derived from a theme name is flagged needsValue.
+const THEME_HEX = {
+    primary: "#1976D2", secondary: "#424242", accent: "#82B1FF",
+    error: "#FF5252", info: "#2196F3", success: "#4CAF50",
+    warning: "#FB8C00", white: "#FFFFFF", black: "#000000",
+};
+// ── qjson parsing ────────────────────────────────────────────────────────────────
+// qjson files are pure JSON, or a JS module (`let pjson = {...}; export default pjson`),
+// optionally preceded by a `---studio-metadata---` header. Extract the object literal by
+// brace-matching (string-aware) so H values containing braces/brackets don't confuse it.
+function extractLiteral(raw, start) {
+    let depth = 0, inStr = false, esc = false;
+    for (let i = start; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === "\\")
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+            continue;
+        }
+        if (ch === '"')
+            inStr = true;
+        else if (ch === "{" || ch === "[")
+            depth++;
+        else if (ch === "}" || ch === "]") {
+            depth--;
+            if (depth === 0)
+                return raw.slice(start, i + 1);
+        }
+    }
+    return raw.slice(start);
+}
+async function loadQjson(env, file) {
+    const raw = (await env.fs.readFile(file)).trim();
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        const assign = raw.match(/(?:let|const|var)\s+\w+\s*=\s*/);
+        const from = assign ? assign.index + assign[0].length : 0;
+        let start = -1;
+        for (let i = from; i < raw.length; i++)
+            if (raw[i] === "{" || raw[i] === "[") {
+                start = i;
+                break;
+            }
+        if (start < 0)
+            throw new Error("no object/array literal found");
+        return JSON.parse(extractLiteral(raw, start));
+    }
+}
+// unwrap a prop H value: "'primary'" → "primary", "true" → "true", "'12'" → "12"
+function hVal(h) {
+    const s = String(h ?? "");
+    const m = s.match(/^'(.*)'$/s);
+    return m ? m[1] : s;
+}
+function nodeId(node) {
+    return node?.P?.ID?.H ?? node?._Editor?.eID ?? "(no id)";
+}
+// walk every node in a pJson tree (children live in C.<slot>.c arrays)
+function* walk(nodes) {
+    for (const node of nodes ?? []) {
+        if (!node || typeof node !== "object")
+            continue;
+        yield node;
+        const C = node.C;
+        if (C && typeof C === "object") {
+            for (const slot of Object.values(C)) {
+                if (slot && Array.isArray(slot.c))
+                    yield* walk(slot.c);
+            }
+        }
+    }
+}
+// A page is on the S track when opt.V >= 2.0 OR any node actually carries a (non-empty) S
+// object — the latter is the ground truth per AGENT_GUIDE.md Step 0 (S renders ⇔ S track).
+// Legacy pages (opt.V missing/<2 and no S) don't render S, so style checks don't apply.
+function isStyleTrackPage(doc, roots) {
+    const v = Number(doc?.opt?.V);
+    if (Number.isFinite(v) && v >= 2)
+        return true;
+    for (const node of walk(roots))
+        if (node.S && typeof node.S === "object" && Object.keys(node.S).length > 0)
+            return true;
+    return false;
+}
+const FONT_WEIGHT = {
+    thin: "100", light: "300", regular: "400", medium: "500", bold: "700", black: "900",
+};
+function px(n) { return `${n * 4}px`; }
+function mapClassToken(tok) {
+    // structural / container classes with no S meaning
+    if (tok === "container" || tok === "container--fluid" || tok === "row" || tok === "spacer")
+        return "structural";
+    // responsive breakpoint variants are handled via S ranges, not a single token — leave as-is
+    if (/-(xs|sm|md|lg|xl)-/.test(tok) || /-(sm|md|lg|xl)$/.test(tok.replace(/^col-/, "")))
+        // col-md-6 style — flag separately below; other -bp- variants: no single S target
+        if (!/^col-/.test(tok))
+            return "no-s";
+    // spacing: pa/px/py/pt/pb/pl/pr/ps/pe + ma/mx/my/mt/mb/ml/mr  (+ negative n, + auto)
+    const sp = tok.match(/^([pm])([axytblrse])-(n?)(\d+|auto)$/);
+    if (sp) {
+        const [, pm, side, neg, num] = sp;
+        const base = pm === "p" ? "padding" : "margin";
+        const val = num === "auto" ? "auto" : (neg ? "-" : "") + px(Number(num));
+        const sides = side === "a" ? ["Top", "Right", "Bottom", "Left"]
+            : side === "x" || side === "s" || side === "e" ? (side === "s" ? ["Left"] : side === "e" ? ["Right"] : ["Left", "Right"])
+                : side === "y" ? ["Top", "Bottom"]
+                    : side === "t" ? ["Top"] : side === "b" ? ["Bottom"]
+                        : side === "l" ? ["Left"] : ["Right"];
+        return { params: sides.map((s) => ({ sParam: base + s, value: val })) };
+    }
+    // flex direction / justify / align (flex containers only)
+    const flexDir = {
+        "flex-row": "row", "flex-column": "column",
+        "flex-row-reverse": "row-reverse", "flex-column-reverse": "column-reverse",
+    };
+    if (flexDir[tok])
+        return { params: [{ sParam: "flexDirection", value: flexDir[tok] }], needsFlexContainer: true };
+    const j = tok.match(/^justify-(start|center|end|space-between|space-around|space-evenly)$/);
+    if (j)
+        return { params: [{ sParam: "justifyContent", value: j[1] === "start" ? "flex-start" : j[1] === "end" ? "flex-end" : j[1] }], needsFlexContainer: true };
+    const a = tok.match(/^align-(start|center|end|baseline|stretch)$/);
+    if (a)
+        return { params: [{ sParam: "alignItems", value: a[1] === "start" ? "flex-start" : a[1] === "end" ? "flex-end" : a[1] }], needsFlexContainer: true };
+    if (tok === "d-flex" || tok === "d-inline-flex")
+        return { params: [], needsFlexContainer: true }; // implied by flexDirection
+    // typography
+    const fw = tok.match(/^font-weight-(thin|light|regular|medium|bold|black)$/);
+    if (fw)
+        return { params: [{ sParam: "fontWeight", value: FONT_WEIGHT[fw[1]] }] };
+    if (tok === "font-italic")
+        return { params: [{ sParam: "fontStyle", value: "italic" }] };
+    const ta = tok.match(/^text-(left|center|right|justify)$/);
+    if (ta)
+        return { params: [{ sParam: "textAlign", value: ta[1] }] };
+    const td = tok.match(/^text-decoration-(none|underline|line-through)$/);
+    if (td)
+        return { params: [{ sParam: "textDecorationLine", value: td[1] }] };
+    if (/^text-(h[1-6]|subtitle-[12]|body-[12]|button|caption|overline)$/.test(tok))
+        return { params: [{ sParam: "fontSize", needsValue: true }] }; // typography scale → font size/weight/lineHeight
+    const textColor = tok.match(/^([a-z]+)--text$/);
+    if (textColor)
+        // theme-named color → suggest the Vuetify default but flag it (page theme may override)
+        return { params: [{ sParam: "fontColor", value: THEME_HEX[textColor[1]], needsValue: true }] };
+    // appearance
+    if (/^elevation-\d+$/.test(tok))
+        return { params: [{ sParam: "boxShadow", needsValue: true }] };
+    if (/^rounded(-.+)?$/.test(tok))
+        return { params: [{ sParam: "borderTopLeftRadius", needsValue: true }] };
+    // grid column: col-N / col-auto  (VCol only — checked by caller)
+    const col = tok.match(/^col(?:s)?-(\d{1,2}|auto)$/);
+    if (col)
+        return { params: [{ sParam: "col", value: col[1] }] };
+    // single theme-color token used as a background class (e.g. 'warning', 'primary')
+    // theme-named → suggest the Vuetify default but flag it (page theme may override)
+    if (THEME_HEX[tok])
+        return { params: [{ sParam: "backgroundColor", value: THEME_HEX[tok], needsValue: true }] };
+    // explicit no-S tokens
+    if (/^(text-uppercase|text-lowercase|text-capitalize|text-truncate|text-no-wrap|d-none|d-block|d-inline|d-inline-block)$/.test(tok))
+        return "no-s";
+    if (/^(flex-grow|flex-shrink|order|overflow)-/.test(tok))
+        return "no-s";
+    return "no-s"; // unknown token — leave it in class, don't touch
+}
+// ── prop → S mapping (styling props that should live in S) ───────────────────────
+// Only the props with a clean, deterministic S destination. Behavioral/variant props
+// (outlined, dense, depressed, block-as-variant, loading, disabled, type, href…) are left alone.
+// components where the Vuetify `color` prop means foreground, not background fill
+const COLOR_TARGET = { VIcon: "iconColor", QIcon: "iconColor" };
+function mapStyleProp(T, prop, value) {
+    switch (prop) {
+        case "color": {
+            // color means foreground on icon/text components, background on buttons/surfaces.
+            const pref = COLOR_TARGET[T];
+            const target = (pref && supportsS(T, pref)) ? pref
+                : supportsS(T, "backgroundColor") ? "backgroundColor"
+                    : supportsS(T, "fontColor") ? "fontColor"
+                        : supportsS(T, "iconColor") ? "iconColor"
+                            : null;
+            if (!target)
+                return null;
+            // a literal (#hex / rgb) is deterministic; a theme name (primary…) may be overridden by the page theme
+            const isLiteral = /^#|^rgb/i.test(value);
+            return { sParam: target, value: isLiteral ? value : THEME_HEX[value], needsValue: !isLiteral, removeProp: "color" };
+        }
+        case "elevation":
+            return supportsS(T, "boxShadow") ? { sParam: "boxShadow", needsValue: true, removeProp: "elevation" } : null;
+        case "block":
+            return supportsS(T, "width") ? { sParam: "width", value: "100%", removeProp: "block" } : null;
+        // VCol responsive grid props → S.col ranges
+        case "cols": return { sParam: "col", value: value, range: "xs-xl", removeProp: "cols" };
+        case "sm": return { sParam: "col", value: value, range: "sm-xl", removeProp: "sm" };
+        case "md": return { sParam: "col", value: value, range: "md-xl", removeProp: "md" };
+        case "lg": return { sParam: "col", value: value, range: "lg-xl", removeProp: "lg" };
+        case "xl": return { sParam: "col", value: value, range: "xl-xl", removeProp: "xl" };
+        default:
+            return null;
+    }
+}
+// props that are always fine even if a contract is missing/loose
+const UNIVERSAL_PROPS = new Set(["ID", "Render", "DiscardSettings", "class", "visible", "qValue", "text", "style"]);
+// common wrong S-param names → the real one (component-specific). Kept small and exact.
+const S_PARAM_ALIASES = {
+    VIcon: { fontColor: "iconColor", color: "iconColor", fontSize: "iconSize", size: "iconSize" },
+};
+// suggest the intended S param for an unknown one: exact alias, then a valid param whose
+// name ends with the unknown one (e.g. VTextField `borderTopLeftRadius` → `innerBorderTopLeftRadius`).
+function suggestSParam(T, param) {
+    const alias = S_PARAM_ALIASES[T]?.[param];
+    if (alias && supportsS(T, alias))
+        return alias;
+    const valid = styleParams(T);
+    if (!valid)
+        return undefined;
+    // Only suggest a rename on a strong match: the unknown name is a camelCase-boundary suffix
+    // of a real param (e.g. `borderTopLeftRadius`→`innerBorderTopLeftRadius`). Short names like
+    // `top`/`right` are ambiguous (usually stray positioning props) → no guess, advise removal.
+    if (param.length < 6)
+        return undefined;
+    const lc = param.toLowerCase();
+    for (const v of valid) {
+        if (v === param || v.length <= param.length || !v.toLowerCase().endsWith(lc))
+            continue;
+        const boundary = v[v.length - param.length];
+        if (boundary === boundary.toUpperCase() && /[A-Za-z]/.test(boundary))
+            return v;
+    }
+    return undefined;
+}
+// collect every S param already set on a node (across all ranges)
+function existingSParams(node) {
+    const out = new Set();
+    const S = node.S;
+    if (S && typeof S === "object")
+        for (const range of Object.values(S))
+            if (range && typeof range === "object")
+                for (const k of Object.keys(range))
+                    out.add(k);
+    return out;
+}
+// ── validate one node ────────────────────────────────────────────────────────────
+function validateNode(file, node, out) {
+    const T = node.T;
+    if (!T)
+        return;
+    const id = nodeId(node);
+    const cProps = contractProps(T); // null → unknown component
+    const cssPropSet = cssProps(T); // contract props that are legacy CSS props (illegal on the S track)
+    const hasSBlock = styleParams(T) !== null; // component has an S block in component-styles.json
+    const knownComponent = hasSBlock || cProps !== null;
+    const sAlready = existingSParams(node);
+    // legacy O.layout / dOpt
+    if (node.O && (node.O.layout || node.O.dOpt)) {
+        out.push({ file, nodeId: id, component: T, kind: "legacy-layout", severity: "error",
+            detail: "O.layout/dOpt present", suggestion: "Migrate dOpt tokens to S and remove O.layout (keep only O.cType)." });
+    }
+    // props: styling prop with an S equivalent, legacy CSS prop (cssProp), unknown prop
+    const P = node.P ?? {};
+    for (const [prop, def] of Object.entries(P)) {
+        if (prop === "ID")
+            continue;
+        const value = hVal(def?.H);
+        // styling prop that should move to S?
+        const styleFix = mapStyleProp(T, prop, value);
+        if (styleFix) {
+            out.push({ file, nodeId: id, component: T, kind: "prop-to-S", severity: "warn",
+                detail: `prop "${prop}"=${value} is styling; component has S param "${styleFix.sParam}"`,
+                suggestion: styleFix.needsValue
+                    ? `Move to S.${styleFix.range ?? "xs-xl"}.${styleFix.sParam} (value needed${THEME_HEX[value] ? `; Vuetify default ${THEME_HEX[value]}` : ""}) and remove prop "${prop}".`
+                    : `Move to S.${styleFix.range ?? "xs-xl"}.${styleFix.sParam} = "${styleFix.value}" and remove prop "${prop}".`,
+                fix: styleFix });
+            continue;
+        }
+        // cssProp:"true" — a legacy CSS styling prop. This validator only runs on S-track pages, where
+        // such a prop is not part of the component's prop surface at all. Components with no
+        // component-styles.json block are exempt: with no S params there is no legal alternative, so
+        // the prop stays the only way to style them (same spirit as the class-token "last resort" rule).
+        if (hasSBlock && cssPropSet?.has(prop)) {
+            out.push({ file, nodeId: id, component: T, kind: "css-prop-in-S", severity: "error",
+                detail: `prop "${prop}"=${value} is a CSS styling prop (cssProp) — not usable in the S style system`,
+                suggestion: `Remove "${prop}" and set the equivalent styling in S (see ${T}'s block in component-styles.json).` });
+            continue;
+        }
+        // unknown prop (only when we actually have a contract for this component)
+        if (cProps && !cProps.has(prop) && !UNIVERSAL_PROPS.has(prop)) {
+            out.push({ file, nodeId: id, component: T, kind: "unknown-prop", severity: "warn",
+                detail: `prop "${prop}" is not in the ${T} contract`,
+                suggestion: `Verify "${prop}" exists for ${T}; if it is a styling intent, express it via S or a Vuetify class.` });
+        }
+    }
+    // class tokens
+    const classDef = P.class;
+    if (classDef && typeof classDef.H === "string") {
+        const tokens = hVal(classDef.H).split(/\s+/).filter(Boolean);
+        for (const tok of tokens) {
+            const m = mapClassToken(tok);
+            if (m === "structural" || m === "no-s")
+                continue; // keep — no S target
+            // col-N on a non-VCol is a grid class on the wrong component
+            if (/^col(s)?-/.test(tok) && T !== "VCol") {
+                const isFull = /^col(s)?-12$/.test(tok);
+                out.push({ file, nodeId: id, component: T, kind: "class-token-misuse", severity: "warn",
+                    detail: `grid class "${tok}" on ${T} (col-* is VCol-only)`,
+                    suggestion: isFull && supportsS(T, "width")
+                        ? `Replace "${tok}" with S.xs-xl.width = "100%" (full-width) and remove the token.`
+                        : `"${tok}" has no S target on ${T}; move this element into a VCol or drop the token.`,
+                    fix: isFull && supportsS(T, "width")
+                        ? { sParam: "width", value: "100%", removeClassToken: tok }
+                        : { removeClassToken: tok } });
+                continue;
+            }
+            // flex tokens only migrate on a flex container that has the S param
+            const anyUnsupported = m.needsFlexContainer && m.params.some((p) => !supportsS(T, p.sParam));
+            const supported = m.params.filter((p) => supportsS(T, p.sParam));
+            if (supported.length === 0) {
+                // component has no S param for this token → keep as class (last resort), note only if it *looked* migratable
+                if (m.params.length > 0)
+                    out.push({ file, nodeId: id, component: T, kind: "class-token-kept", severity: "info",
+                        detail: `class "${tok}" has an S meaning but ${T} has no matching S param`,
+                        suggestion: `Keep "${tok}" as a Vuetify class (Web-only last resort).` });
+                continue;
+            }
+            // conflict: same style already set in S
+            const conflict = supported.find((p) => sAlready.has(p.sParam));
+            if (conflict) {
+                out.push({ file, nodeId: id, component: T, kind: "style-conflict", severity: "warn",
+                    detail: `class "${tok}" duplicates S param "${conflict.sParam}" already set`,
+                    suggestion: `Remove "${tok}" from class (S is the source of truth).`,
+                    fix: { removeClassToken: tok } });
+                continue;
+            }
+            // migratable: move token to S
+            const needsValue = supported.some((p) => p.needsValue || p.value === undefined);
+            out.push({ file, nodeId: id, component: T, kind: "class-token-to-S", severity: "warn",
+                detail: `class "${tok}" → S ${supported.map((p) => p.sParam).join(", ")}`,
+                suggestion: needsValue
+                    ? `Move "${tok}" to S (${supported.map((p) => p.sParam).join(", ")}; value needed) and remove the token.`
+                    : `Move "${tok}" to S.xs-xl { ${supported.map((p) => `${p.sParam}: "${p.value}"`).join(", ")} } and remove the token.`,
+                fix: { removeClassToken: tok, sParam: supported[0].sParam, value: supported[0].value, needsValue } });
+            void anyUnsupported;
+        }
+    }
+    // invalid S params
+    const S = node.S;
+    if (S && typeof S === "object") {
+        for (const range of Object.values(S)) {
+            if (!range || typeof range !== "object")
+                continue;
+            for (const param of Object.keys(range)) {
+                // "break-point" is the Style-tab's range selector tag, never a real S param —
+                // writing it into S has frozen the Web runtime. Flag it like any invalid param.
+                if (!supportsS(T, param)) {
+                    const didYouMean = suggestSParam(T, param);
+                    out.push({ file, nodeId: id, component: T, kind: "unknown-S-param", severity: "error",
+                        detail: `S param "${param}" is not valid for ${T}`,
+                        suggestion: didYouMean
+                            ? `Rename S "${param}" → "${didYouMean}" for ${T} (the compiler silently drops "${param}").`
+                            : `Remove "${param}" from S — ${T} has no such param and the compiler silently drops it.`,
+                        fix: didYouMean ? { sParam: didYouMean } : undefined });
+                }
+            }
+        }
+    }
+    // S must include every default-valued param of the component (rule S3: emit every default —
+    // the default value or the design's override; nothing merges defaults at render).
+    {
+        const defaults = defaultSParams(T);
+        if (defaults) {
+            const missing = Object.keys(defaults).filter((p) => !sAlready.has(p));
+            if (missing.length) {
+                const total = Object.keys(defaults).length;
+                if (sAlready.size === 0) {
+                    out.push({ file, nodeId: id, component: T, kind: "missing-S", severity: "error",
+                        detail: `${T} has no S but ${total} of its params carry a default`,
+                        suggestion: `Add an S ("xs-xl") with every default-valued param from ${T}'s component-styles.json block: ${missing.join(", ")}.` });
+                }
+                else {
+                    out.push({ file, nodeId: id, component: T, kind: "incomplete-S", severity: "error",
+                        detail: `S is missing ${missing.length}/${total} of ${T}'s default-valued params`,
+                        suggestion: `Rule S3 — add (default value or your override): ${missing.join(", ")}.` });
+                }
+            }
+        }
+    }
+    // SC must mirror the component's inheritedChildList (component-styles.json) — the FULL block,
+    // not a subset: rule S3 says copy it as-is. Also flag a missing SC when the node has children
+    // of a mapped type.
+    const SC = node.SC;
+    {
+        const inherited = inheritedChildList(T);
+        if (inherited && (!SC || typeof SC !== "object")) {
+            const childTypes = new Set();
+            const C = node.C;
+            if (C && typeof C === "object")
+                for (const slot of Object.values(C))
+                    if (slot && Array.isArray(slot.c))
+                        for (const ch of slot.c)
+                            if (ch && ch.T)
+                                childTypes.add(ch.T);
+            const mappedTypes = new Set(Object.values(inherited).flatMap((m) => Object.keys(m)));
+            const hit = [...childTypes].filter((t) => mappedTypes.has(t));
+            if (hit.length) {
+                out.push({ file, nodeId: id, component: T, kind: "missing-SC", severity: "error",
+                    detail: `${T} has ${hit.join("/")} children but no SC`,
+                    suggestion: `Copy ${T}'s full inheritedChildList block from component-styles.json into SC (params: ${Object.keys(inherited).join(", ")}).` });
+            }
+        }
+        else if (inherited && SC) {
+            const missing = Object.keys(inherited).filter((p) => SC[p] === undefined);
+            if (missing.length) {
+                out.push({ file, nodeId: id, component: T, kind: "incomplete-SC", severity: "error",
+                    detail: `SC has ${Object.keys(SC).length}/${Object.keys(inherited).length} of ${T}'s inheritedChildList params`,
+                    suggestion: `SC must be the FULL inheritedChildList copy (rule S3) — add: ${missing.join(", ")}.` });
+            }
+        }
+    }
+    if (SC && typeof SC === "object") {
+        const inherited = inheritedChildList(T);
+        if (!inherited) {
+            if (styleParams(T)) {
+                out.push({ file, nodeId: id, component: T, kind: "unknown-SC", severity: "error",
+                    detail: `${T} has no inheritedChildList — its SC does nothing`,
+                    suggestion: `Remove SC from ${T}; only components with an inheritedChildList in component-styles.json cascade styles to children.` });
+            }
+        }
+        else {
+            for (const [param, childMap] of Object.entries(SC)) {
+                const validMap = inherited[param];
+                if (!validMap) {
+                    out.push({ file, nodeId: id, component: T, kind: "unknown-SC-param", severity: "error",
+                        detail: `SC param "${param}" is not in ${T}'s inheritedChildList`,
+                        suggestion: `Remove SC "${param}" or use one of: ${Object.keys(inherited).join(", ")}.` });
+                    continue;
+                }
+                if (childMap && typeof childMap === "object") {
+                    for (const [childT, childParam] of Object.entries(childMap)) {
+                        if (validMap[childT] === undefined) {
+                            out.push({ file, nodeId: id, component: T, kind: "unknown-SC-child", severity: "error",
+                                detail: `SC "${param}" maps to child type "${childT}" which is not in ${T}'s inheritedChildList`,
+                                suggestion: `Valid child types for "${param}": ${Object.keys(validMap).join(", ")}.` });
+                        }
+                        else if (validMap[childT] !== childParam) {
+                            out.push({ file, nodeId: id, component: T, kind: "wrong-SC-target", severity: "error",
+                                detail: `SC "${param}" → ${childT}."${childParam}" but the engine maps it to "${validMap[childT]}"`,
+                                suggestion: `Change SC "${param}".${childT} to "${validMap[childT]}" (from inheritedChildList).` });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    void knownComponent;
+}
+// ── run over files ───────────────────────────────────────────────────────────────
+async function collectFiles(env, target) {
+    const isDir = await env.fs.isDirectory(target);
+    if (!isDir)
+        return [target];
+    const out = [];
+    for (const e of await env.fs.readDir(target)) {
+        if (e.name.startsWith("."))
+            continue;
+        const p = env.path.join(target, e.name);
+        if (e.isDirectory)
+            out.push(...await collectFiles(env, p));
+        else if (e.name.endsWith(".qjson"))
+            out.push(p);
+    }
+    return out;
+}
+/** Validate files/folders; returns a structured report (no console output). Legacy pages are
+ *  reported with `skipped: true` and contribute no violations. */
+async function validateStyles(env, targets) {
+    const files = (await Promise.all(targets.map((t) => collectFiles(env, t)))).flat();
+    const fileReports = [];
+    for (const file of files) {
+        await loadReference(env, env.path.dirname(env.path.resolve(file)));
+        let doc;
+        try {
+            doc = await loadQjson(env, file);
+        }
+        catch (e) {
+            fileReports.push({ file, skipped: false, errors: 1, warnings: 0, infos: 0,
+                violations: [{ file, nodeId: "-", component: "-", kind: "parse-error", severity: "error",
+                        detail: `could not parse: ${e.message}`, suggestion: "Fix JSON/module syntax." }] });
+            continue;
+        }
+        const roots = Array.isArray(doc?.pJson) ? doc.pJson : Array.isArray(doc) ? doc : [];
+        if (!isStyleTrackPage(doc, roots)) {
+            fileReports.push({ file, skipped: true, violations: [], errors: 0, warnings: 0, infos: 0 });
+            continue;
+        }
+        const violations = [];
+        for (const node of walk(roots))
+            validateNode(file, node, violations);
+        fileReports.push({ file, skipped: false, violations,
+            errors: violations.filter((v) => v.severity === "error").length,
+            warnings: violations.filter((v) => v.severity === "warn").length,
+            infos: violations.filter((v) => v.severity === "info").length });
+    }
+    const errorCount = fileReports.reduce((n, f) => n + f.errors, 0);
+    const warningCount = fileReports.reduce((n, f) => n + f.warnings, 0);
+    const infoCount = fileReports.reduce((n, f) => n + f.infos, 0);
+    return { ok: errorCount === 0 && warningCount === 0, fileCount: files.length, errorCount, warningCount, infoCount, files: fileReports };
+}
+exports.validateStyles = validateStyles;
+/** Render a StyleReport as the human-readable text block (same style as the CLI output). */
+function formatStyleReport(env, r) {
+    const icon = (s) => (s === "error" ? "✖" : s === "warn" ? "▲" : "·");
+    const lines = [];
+    for (const fr of r.files) {
+        const rel = env.path.relative(env.cwd, fr.file);
+        if (fr.skipped) {
+            lines.push(`· ${rel}  (skipped — legacy page; S styling doesn't render here)`);
+            continue;
+        }
+        lines.push(`\n${rel}  (${fr.errors} error, ${fr.warnings} warn, ${fr.infos} info)`);
+        for (const v of fr.violations)
+            lines.push(`  ${icon(v.severity)} [${v.kind}] ${v.component}#${v.nodeId}: ${v.detail}\n      → ${v.suggestion}`);
+    }
+    const total = r.errorCount + r.warningCount + r.infoCount;
+    lines.push(total === 0
+        ? "\n✓ No style violations."
+        : `\n${total} violation(s): ${r.errorCount} error, ${r.warningCount} warn, ${r.infoCount} info.`);
+    return lines.join("\n");
+}
+exports.formatStyleReport = formatStyleReport;
+//# sourceMappingURL=validateStyles.js.map