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

package/dist/studio-cli/src/isolatedCommands/validateStyles.js

@@ -1,672 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatStyleReport = exports.validateStyles = void 0;
-/**
- * validateStyles.ts — deterministic S-first style validator for Quick .qjson pages.
- *
- * The in-CLI twin of what used to be `.ai-kit/tools/validate_styles.ts`: it is invoked by
- * `runQjsonBuild` (qjsonBuild.ts) right after the structural validator, so the authoring
- * fix-loop gets S-style feedback for free every time it compiles — no separate tool the AI
- * has to remember to run. It reads its reference data (component-contracts.json +
- * component-styles.json) from the *workspace* `.ai-kit/reference/`, resolved from the file
- * being validated (see loadReference), so it uses the user's own contracts.
- *
- * It only runs on **S-track pages** (opt.V >= 2.0, or a page that actually carries an `S`
- * object); on legacy pages the `S` object doesn't render, so these checks don't apply and the
- * file is reported as skipped. Answers, per node:
- *   1. Is any prop actually a *styling* prop that has an `S` equivalent → should move to S?
- *   2. Does every `class` token have an S equivalent the component supports → should move to S?
- *   3. Is every `S` param real for this component (per component-styles.json)?
- *   4. Is a style set in BOTH S and class (conflict → drop the class token)?
- *   5. Is an unknown prop on the node, or legacy `O.layout` / `dOpt` still present?
- *
- * This does NOT compile the file (the official compiler does that). It only checks that styling
- * is expressed the S-first way, deterministically, from the reference contracts.
- *
- * NOTE: compiled as CommonJS inside the studio CLI, so `__dirname` and `require.main` are the
- * ambient module globals — no `import.meta` (which the CLI's tsconfig disallows).
- */
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-// ── locate the kit root (the dir holding reference/ or .ai-kit/reference/). Resolves from the
-// FILE being validated first — so bundled inside the studio CLI it finds the user's workspace
-// `.ai-kit/reference/` — then falls back to __dirname (so it still works from the bundled kit
-// copied next to the compiled code). Returns null when no reference data is found. ────────────
-function findKitRoot(startDir) {
-    let dir = startDir;
-    for (let i = 0; i < 8; i++) {
-        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, "reference", "component-styles.json")))
-            return dir;
-        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, ".ai-kit", "reference", "component-styles.json")))
-            return node_path_1.default.join(dir, ".ai-kit");
-        const parent = node_path_1.default.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
-function loadReference(startDir) {
-    const root = findKitRoot(startDir) ?? findKitRoot(__dirname);
-    if (root === loadedRoot)
-        return; // already loaded for this root
-    loadedRoot = root;
-    const refFile = (name) => node_path_1.default.join(root ?? "", "reference", name);
-    try {
-        contracts = JSON.parse(node_fs_1.default.readFileSync(refFile("component-contracts.json"), "utf8")).components ?? {};
-    }
-    catch {
-        contracts = {};
-    }
-    try {
-        styles = JSON.parse(node_fs_1.default.readFileSync(refFile("component-styles.json"), "utf8")).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
-}
-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);
-}
-function loadQjson(file) {
-    const raw = node_fs_1.default.readFileSync(file, "utf8").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 knownComponent = styleParams(T) !== null || 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: unknown prop, and styling prop with S equivalent
-    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;
-        }
-        // 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 ───────────────────────────────────────────────────────────────
-function collectFiles(target) {
-    const st = node_fs_1.default.statSync(target);
-    if (st.isFile())
-        return [target];
-    const out = [];
-    for (const e of node_fs_1.default.readdirSync(target, { withFileTypes: true })) {
-        if (e.name.startsWith("."))
-            continue;
-        const p = node_path_1.default.join(target, e.name);
-        if (e.isDirectory())
-            out.push(...collectFiles(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. */
-function validateStyles(targets) {
-    const files = targets.flatMap(collectFiles);
-    const fileReports = [];
-    for (const file of files) {
-        loadReference(node_path_1.default.dirname(node_path_1.default.resolve(file)));
-        let doc;
-        try {
-            doc = loadQjson(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(r) {
-    const icon = (s) => (s === "error" ? "✖" : s === "warn" ? "▲" : "·");
-    const lines = [];
-    for (const fr of r.files) {
-        const rel = node_path_1.default.relative(process.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;
-// ── CLI (standalone debugging only; the normal path is via qjsonBuild). ────────────
-function main() {
-    const args = process.argv.slice(2);
-    const json = args.includes("--json");
-    const quiet = args.includes("--quiet");
-    const targets = args.filter((a) => !a.startsWith("--"));
-    if (targets.length === 0) {
-        console.error("usage: validateStyles <file-or-folder.qjson> [--json] [--quiet]");
-        process.exit(2);
-    }
-    const report = validateStyles(targets);
-    if (json) {
-        const violations = report.files.flatMap((f) => f.violations);
-        console.log(JSON.stringify({ violationCount: violations.length, violations }, null, 2));
-    }
-    else if (!quiet) {
-        console.log(formatStyleReport(report));
-    }
-    // Use exitCode (not process.exit) so large stdout fully flushes before exit.
-    process.exitCode = report.errorCount + report.warningCount > 0 ? 1 : 0;
-}
-// Run main() only when invoked directly as a CLI, not when imported (e.g. by qjsonBuild).
-if (require.main === module)
-    main();
-//# sourceMappingURL=validateStyles.js.map