@usefragments/core 1.3.0 → 1.4.0

package/dist/index.js

@@ -109,7 +109,7 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-MLRDNSSA.js";
+} from "./chunk-CBSNXFOD.js";
 import {
   AGENT_FORMAT_SCHEMA_VERSION,
   agentErrorEnvelopeSchema,
@@ -185,6 +185,8 @@ var BRAND = {
   legacyConfigFile: "segments.config.ts",
   /** CLI command name (e.g., "fragments") */
   cliCommand: "fragments",
+  /** Full user-facing CLI invocation for copy printed to end users (e.g., "npx @usefragments/cli") */
+  cliInvocation: "npx @usefragments/cli",
   /** Directory for storing fragments, registry, and cache */
   dataDir: ".fragments",
   /** Components subdirectory within .fragments/ */
@@ -1679,16 +1681,20 @@ var tokenSourceSchema = z4.object({
 var tokenConfigSchema = z4.object({
   include: repoRelativePathsSchema.optional(),
   sources: z4.array(tokenSourceSchema).min(1).optional(),
+  // Declared design-system packages whose shipped fragments.json token
+  // vocabulary seeds the known-token set (#7c). A packages-only tokens block
+  // is valid — see the superRefine below.
+  packages: z4.array(z4.string().min(1)).optional(),
   exclude: z4.array(repoRelativePathSchema).optional(),
   themeSelectors: z4.record(z4.string()).optional(),
   enabled: z4.boolean().optional(),
   format: z4.enum(["auto", "css", "scss", "dtcg", "tailwind"]).optional(),
   namespace: z4.string().min(1).optional()
 }).passthrough().superRefine((tokens, ctx) => {
-  if (!tokens.include?.length && !tokens.sources?.length) {
+  if (!tokens.include?.length && !tokens.sources?.length && !tokens.packages?.length) {
     ctx.addIssue({
       code: z4.ZodIssueCode.custom,
-      message: "Add tokens.include or tokens.sources",
+      message: "Add tokens.include, tokens.sources, or tokens.packages",
       path: ["sources"]
     });
   }
@@ -2931,30 +2937,41 @@ function inferTokenGroup(name) {
       return category;
   }
 }
+var TOKEN_GROUP_COMMENT_MAPPINGS = {
+  "base configuration": "base",
+  typography: "typography",
+  "spacing (micro)": "spacing",
+  spacing: "spacing",
+  "density padding": "spacing",
+  "border radius": "radius",
+  transitions: "transitions",
+  colors: "colors",
+  surfaces: "surfaces",
+  text: "text",
+  borders: "borders",
+  shadows: "shadows",
+  focus: "focus",
+  scrollbar: "scrollbar",
+  "component heights": "component-sizing",
+  "appshell layout": "layout",
+  codeblock: "code",
+  tooltip: "tooltip",
+  "hero/marketing gradient": "marketing"
+};
+function looksLikeCleanHeading(text) {
+  if (!/^[a-z0-9][a-z0-9 -]*$/.test(text)) return false;
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  return wordCount > 0 && wordCount <= 3;
+}
 function normalizeTokenGroupComment(comment) {
   const text = comment.trim().replace(/^\/\/\s*/, "").replace(/^\/\*+\s*/, "").replace(/\s*\*+\/$/, "").trim().toLowerCase();
-  const mappings = {
-    "base configuration": "base",
-    typography: "typography",
-    "spacing (micro)": "spacing",
-    spacing: "spacing",
-    "density padding": "spacing",
-    "border radius": "radius",
-    transitions: "transitions",
-    colors: "colors",
-    surfaces: "surfaces",
-    text: "text",
-    borders: "borders",
-    shadows: "shadows",
-    focus: "focus",
-    scrollbar: "scrollbar",
-    "component heights": "component-sizing",
-    "appshell layout": "layout",
-    codeblock: "code",
-    tooltip: "tooltip",
-    "hero/marketing gradient": "marketing"
-  };
-  return mappings[text] ?? text.replace(/\s+/g, "-");
+  if (text in TOKEN_GROUP_COMMENT_MAPPINGS) {
+    return TOKEN_GROUP_COMMENT_MAPPINGS[text];
+  }
+  if (!looksLikeCleanHeading(text)) {
+    return null;
+  }
+  return text.replace(/\s+/g, "-");
 }
 
 // src/tokens/scss.ts
@@ -3021,7 +3038,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
   const tokens = [];
   const seenNames = /* @__PURE__ */ new Set();
   let currentCategory = "other";
-  let hasCommentCategories = false;
+  let currentCategoryIsCurated = false;
   const scssVars = parseScssVariables(content);
   const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
   const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
@@ -3031,7 +3048,9 @@ function parseScssTokens(content, filePath = "tokens.scss") {
       const normalized = normalizeTokenGroupComment(commentMatch[0]);
       if (normalized) {
         currentCategory = normalized;
-        hasCommentCategories = true;
+        currentCategoryIsCurated = true;
+      } else {
+        currentCategoryIsCurated = false;
       }
       continue;
     }
@@ -3047,7 +3066,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
       tokens.push({
         name,
         value: cleanValue || void 0,
-        category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+        category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name),
         description
       });
     }
@@ -3058,7 +3077,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
     tokens.push({
       name,
       value,
-      category: hasCommentCategories ? currentCategory : inferTokenGroup(name)
+      category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name)
     });
   }
   const cssVarValues = /* @__PURE__ */ new Map();
@@ -5057,11 +5076,13 @@ function ruleComponentsPreferLibrary(ix) {
   const textByNode = indexTextChildrenByNodeId(ix);
   const classTokensByNode = indexClassTokensByNode(ix);
   const reimplTargets = canonicalReimplTargets(sources, mappings);
+  const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(ix, sources);
   const findings = [];
   const seenImportFixes = /* @__PURE__ */ new Set();
   for (const node of ix.byKind("usage_node")) {
     if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
     if (node.element.includes(".")) continue;
+    if (canonicalDirectoryResolvedNodes.has(node.id)) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
     const importsForFile = importsByFileAndLocal.get(node.file);
@@ -5587,7 +5608,27 @@ function sourceLabel(source) {
 function canonicalImportPath(source) {
   if (source.kind === "npm") return source.specifier;
   if (source.kind === "registry") return source.importPath;
-  return void 0;
+  return source.include?.length ? source.path : void 0;
+}
+function indexCanonicalDirectoryResolvedNodes(ix, sources) {
+  const out = /* @__PURE__ */ new Set();
+  const directoryPaths = sources.filter(
+    (source) => source.kind === "directory"
+  ).map((source) => normalizePath(source.path));
+  if (directoryPaths.length === 0) return out;
+  for (const fact of ix.byKind("usage_component")) {
+    const module = componentIdModule(fact.componentId);
+    if (module === void 0) continue;
+    const normalizedModule = normalizePath(module);
+    if (directoryPaths.some((path) => isPathInSource(normalizedModule, path))) {
+      out.add(fact.nodeId);
+    }
+  }
+  return out;
+}
+function componentIdModule(componentId2) {
+  const hash = componentId2.indexOf("#");
+  return hash > 0 ? componentId2.slice(0, hash) : void 0;
 }
 function isCanonicalSourceImplementationFile(file, sources) {
   const normalizedFile = normalizePath(file);
@@ -6228,6 +6269,7 @@ function ruleStylesNoRawColor(ix) {
   const colorTokens = ix.tokens.byCategory("color");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings = [];
+  const advisorySeverity = policy.severity === "error" ? "warn" : policy.severity;
   for (const decl of ix.byKind("style_declaration")) {
     if (decl.property.startsWith("--") && decl.declaredTokenSource === true) continue;
     const color = detectRawColor(decl.value);
@@ -6267,6 +6309,37 @@ function ruleStylesNoRawColor(ix) {
   }
   const componentByNode = indexComponentByNodeId(ix);
   for (const inline of ix.byKind("usage_inline_style")) {
+    if (inline.valueKind === "dynamic-raw") {
+      const node2 = readUsageNode(ix, inline.nodeId);
+      if (!node2) continue;
+      const componentEvidenceId2 = componentByNode.get(node2.id)?.id;
+      const evidenceIds2 = componentEvidenceId2 ? [node2.id, componentEvidenceId2, inline.id, policy.id] : [node2.id, inline.id, policy.id];
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID8,
+          ruleVersion: RULE_VERSION9,
+          severity: advisorySeverity,
+          message: `Runtime-constructed raw color \`${inline.value}\` on inline \`${inline.property}\`. Use a ${preferLabel} instead.`,
+          location: node2.location,
+          evidence: ix.evidence(evidenceIds2),
+          fingerprintIdentity: {
+            source: "usage_inline_style_dynamic",
+            file: node2.file,
+            nodePath: node2.nodePath,
+            element: node2.element,
+            property: inline.property,
+            value: inline.value
+          },
+          attributes: {
+            property: inline.property,
+            rawValue: inline.value,
+            source: "jsx",
+            dynamic: true
+          }
+        })
+      );
+      continue;
+    }
     if (inline.valueKind === "css-variable") continue;
     const color = detectRawColor(inline.value);
     if (!color) continue;
@@ -6307,8 +6380,68 @@ function ruleStylesNoRawColor(ix) {
       })
     );
   }
+  for (const prop of ix.byKind("usage_prop_resolved")) {
+    if (prop.resolution !== "static") continue;
+    if (typeof prop.value !== "string") continue;
+    if (!SVG_PAINT_ATTRS.has(prop.prop)) continue;
+    const color = detectRawColor(prop.value);
+    if (!color) continue;
+    if (isExemptColor(color, policy.except)) continue;
+    const node = readUsageNode(ix, prop.nodeId);
+    if (!node) continue;
+    const componentEvidenceId = componentByNode.get(node.id)?.id;
+    const cssProperty = SVG_PAINT_CSS_PROPERTY[prop.prop] ?? prop.prop;
+    const resolution = resolveColorToken(cssProperty, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(cssProperty, prop.value, color, resolution, ix) : void 0;
+    const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, prop.id, policy.id] : [node.id, prop.id, policy.id];
+    const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID8,
+        ruleVersion: RULE_VERSION9,
+        severity: advisorySeverity,
+        message: colorMessage(color, `\`${prop.prop}\``, resolution, preferLabel),
+        location: prop.location ?? node.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "usage_prop_resolved",
+          file: node.file,
+          nodePath: node.nodePath,
+          element: node.element,
+          property: prop.prop,
+          value: color
+        },
+        fix: fixEmission?.fix,
+        attributes: {
+          property: prop.prop,
+          rawValue: prop.value,
+          color,
+          source: "jsx",
+          suggestedToken: resolution?.token.name,
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
+        }
+      })
+    );
+  }
   return findings;
 }
+var SVG_PAINT_ATTRS = /* @__PURE__ */ new Set([
+  "fill",
+  "stroke",
+  "color",
+  "stop-color",
+  "stopColor",
+  "flood-color",
+  "floodColor",
+  "lighting-color",
+  "lightingColor"
+]);
+var SVG_PAINT_CSS_PROPERTY = {
+  stopColor: "stop-color",
+  floodColor: "flood-color",
+  lightingColor: "lighting-color"
+};
 function resolveColorToken(property, raw, tokens) {
   const exact = findTokenMatch(property, raw, tokens);
   if (exact) return { kind: "exact", token: exact.token, ambiguous: exact.ambiguous };