@invariant-ui/cli 0.0.0-stage → 0.1.0

package/dist/validation/validate-usage.js

@@ -0,0 +1,196 @@
+import { normalize } from "../contract-query/index.js";
+import { nearest, quoteList } from "./text.js";
+export const isDynamic = (v) => typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    Object.keys(v).length === 1 &&
+    typeof v.expression === "string";
+/**
+ * Attributes frameworks pass through to the rendered element. A component rarely declares them, and whether it
+ * forwards them is not in the contract, so an undeclared one is not evidence of a mistake.
+ */
+const HTML_ATTRIBUTES = new Set("accept alt autocomplete autofocus checked cols colspan disabled download draggable for form height href hreflang htmlfor inputmode lang list loading max maxlength method min minlength multiple name novalidate pattern placeholder readonly rel required rows rowspan selected size spellcheck src srcset step target type value width wrap dir content crossorigin enterkeyhint open".split(" "));
+const PASSTHROUGH = /^(data-|aria-)|^(key|ref|class|className|style|id|slot|role|tabindex|title|hidden)$/i;
+const isPassthrough = (name) => PASSTHROUGH.test(name) || HTML_ATTRIBUTES.has(name.toLowerCase());
+function sameValue(allowed, v) {
+    if (allowed === v)
+        return true;
+    return typeof v === "string" && typeof allowed !== "string" && String(allowed) === v;
+}
+export function validateUsage(ds, input) {
+    const findings = [];
+    const found = ds.findComponent(input.component);
+    if (!found.match) {
+        const names = found.candidates.map((c) => c.name);
+        const close = names.length > 0
+            ? names
+            : nearest(input.component, ds.contract.components.map((c) => c.name));
+        findings.push({
+            code: found.candidates.length > 1 && names.some((n) => normalize(n) === normalize(input.component))
+                ? "component-ambiguous"
+                : "component-unknown",
+            severity: "error",
+            message: `"${input.component}" is not a component in the contract${close.length > 0 ? `. Candidates: ${close.join(", ")}` : ""}`,
+            basis: "discovered",
+            ...(close.length > 0
+                ? { suggestion: `Did you mean ${close.slice(0, 3).join(" or ")}?` }
+                : {
+                    suggestion: "Find a component with search_design_system or `invariant components list`, or add the component to the design system."
+                })
+        });
+        return { findings, unverifiedValues: 0 };
+    }
+    const c = found.match;
+    const framework = input.framework;
+    if (framework && !c.implementations.some((i) => i.framework === framework))
+        findings.push({
+            code: "framework-not-implemented",
+            severity: "error",
+            subject: c.id,
+            message: `${c.name} has no ${framework} implementation (it has: ${c.implementations.map((i) => i.framework).join(", ")})`,
+            basis: "discovered",
+            suggestion: `Use the ${c.implementations.map((i) => i.framework).join(" or ")} implementation, or a ${framework} component with the same role.`
+        });
+    if (c.lifecycle === "deprecated") {
+        const replacement = c.deprecated?.replacedBy ? ds.component(c.deprecated.replacedBy)?.name : undefined;
+        findings.push({
+            code: "component-deprecated",
+            severity: "warning",
+            subject: c.id,
+            message: `${c.name} is deprecated${c.deprecated?.reason ? `: ${c.deprecated.reason}` : ""}`,
+            basis: ds.factView(c.facts, "lifecycle")?.status === "documented" ? "documented" : "discovered",
+            ...(ds.factView(c.facts, "lifecycle")?.source
+                ? { source: ds.factView(c.facts, "lifecycle")?.source }
+                : {}),
+            suggestion: replacement
+                ? `Use ${replacement}.`
+                : "Migrate to the component that replaces it; check the component's documentation."
+        });
+    }
+    const complete = ds.propsComplete(c, framework);
+    const props = input.props ?? {};
+    let unverified = 0;
+    const basisOf = (path) => {
+        const s = ds.factView(c.facts, path)?.status;
+        return s === "documented" || s === "inferred" || s === "approved" ? s : "discovered";
+    };
+    const where = (path) => {
+        const s = ds.factView(c.facts, path)?.source;
+        return s ? { source: s } : {};
+    };
+    const eventNames = new Set(c.events.map((e) => normalize(e.name)));
+    const slotNames = new Set(c.slots.map((s) => normalize(s.name)));
+    for (const [name, value] of Object.entries(props)) {
+        const prop = c.props.find((p) => p.name === name);
+        if (!prop) {
+            if (isPassthrough(name) ||
+                eventNames.has(normalize(name.replace(/^on(?=[A-Z])/, ""))) ||
+                slotNames.has(normalize(name)))
+                continue;
+            const close = nearest(name, c.props.map((p) => p.name));
+            findings.push(complete
+                ? {
+                    code: "unknown-prop",
+                    severity: "warning",
+                    subject: c.id,
+                    message: `${c.name} does not declare a prop "${name}"`,
+                    path: `props.${name}`,
+                    basis: "discovered",
+                    suggestion: close.length > 0
+                        ? `Did you mean ${close.map((x) => `"${x}"`).join(" or ")}?`
+                        : `Remove "${name}", or check the props ${c.name} declares (get_component).`
+                }
+                : {
+                    code: "unverifiable-prop",
+                    severity: "info",
+                    subject: c.id,
+                    message: `${c.name}'s prop list is incomplete, so "${name}" could not be verified`,
+                    path: `props.${name}`,
+                    basis: "discovered"
+                });
+            continue;
+        }
+        const base = `props.${name}`;
+        if (prop.deprecated)
+            findings.push({
+                code: "prop-deprecated",
+                severity: "warning",
+                subject: c.id,
+                message: `${c.name}.${name} is deprecated${prop.deprecated.reason ? `: ${prop.deprecated.reason}` : ""}`,
+                path: base,
+                basis: basisOf(`${base}.deprecated`),
+                ...where(`${base}.deprecated`),
+                suggestion: prop.deprecated.reason
+                    ? `Follow the deprecation note: ${prop.deprecated.reason}`
+                    : `Stop using "${name}"; see ${c.name}'s documentation for its replacement.`
+            });
+        if (isDynamic(value)) {
+            unverified++;
+            continue;
+        }
+        if (prop.allowedValues &&
+            (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
+            if (!prop.allowedValues.some((a) => sameValue(a, value))) {
+                const close = typeof value === "string" ? nearest(value, prop.allowedValues.map(String)) : [];
+                findings.push({
+                    code: "prop-value-not-allowed",
+                    severity: "error",
+                    subject: c.id,
+                    message: `${c.name}.${name} is ${JSON.stringify(value)}, which is not one of ${quoteList(prop.allowedValues)}`,
+                    path: `${base}.allowedValues`,
+                    basis: basisOf(`${base}.allowedValues`),
+                    ...where(`${base}.allowedValues`),
+                    suggestion: `Use one of ${quoteList(prop.allowedValues)}${close.length > 0 ? ` (closest: ${JSON.stringify(close[0])})` : ""}.`
+                });
+            }
+        }
+        else {
+            const kind = prop.type.kind;
+            const bad = (kind === "boolean" && typeof value !== "boolean") ||
+                (kind === "number" && typeof value !== "number") ||
+                (kind === "string" && typeof value !== "string");
+            if (bad)
+                findings.push({
+                    code: "prop-type-mismatch",
+                    severity: "warning",
+                    subject: c.id,
+                    message: `${c.name}.${name} expects ${kind} (${prop.type.text}) but got ${JSON.stringify(value)}`,
+                    path: `${base}.type`,
+                    basis: basisOf(`${base}.type.text`),
+                    ...where(`${base}.type.text`),
+                    suggestion: `Pass a ${kind} value${kind === "boolean" ? ` (for example ${name}={true})` : ""}.`
+                });
+        }
+    }
+    if (!input.hasSpread)
+        for (const p of c.props) {
+            if (!p.required || p.name in props)
+                continue;
+            if (p.name === "children") {
+                if (input.hasChildren === false)
+                    findings.push({
+                        code: "required-prop-missing",
+                        severity: "error",
+                        subject: c.id,
+                        message: `${c.name} requires children`,
+                        path: "props.children",
+                        basis: basisOf("props.children.required"),
+                        ...where("props.children.required"),
+                        suggestion: `Put content inside ${c.name}.`
+                    });
+                continue;
+            }
+            findings.push({
+                code: "required-prop-missing",
+                severity: "error",
+                subject: c.id,
+                message: `${c.name} requires the prop "${p.name}"`,
+                path: `props.${p.name}`,
+                basis: basisOf(`props.${p.name}.required`),
+                ...where(`props.${p.name}.required`),
+                suggestion: `Add ${p.name} (${p.type.text}${p.allowedValues ? `: ${quoteList(p.allowedValues)}` : ""}).`
+            });
+        }
+    return { component: c.id, findings, unverifiedValues: unverified };
+}
+//# sourceMappingURL=validate-usage.js.map

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@invariant-ui/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Compile your design system, UX patterns and page layouts into a contract AI agents can read, and check code against it.",
+  "keywords": [
+    "design-system",
+    "ai-agents",
+    "mcp",
+    "design-tokens",
+    "storybook",
+    "linting",
+    "ux-patterns"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://mcarlucci.github.io/invariant/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcarlucci/invariant.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mcarlucci/invariant/issues"
+  },
+  "type": "module",
+  "bin": {
+    "invariant": "dist/cli/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "3.5.44",
+    "typescript": "5.9.3",
+    "zod": "4.6.7"
+  }
+}