@reqvire-org/ads 0.3.6 → 0.3.8

package/dist/atomic-composition.mjs

@@ -0,0 +1,214 @@
+import path from "node:path";
+import ts from "typescript";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+import { isInside } from "./config.mjs";
+import { createAtomicTrace } from "./atomic-trace.mjs";
+
+export const atomicStyleGuide = "ads://guides/atomic-styles";
+
+const sides = ["top", "right", "bottom", "left"];
+const logicalSides = ["block-start", "block-end", "inline-start", "inline-end"];
+const intersects = (a, b) => a.some(value => b.includes(value));
+const previewValue = value => value.length > 200 ? value.slice(0, 197) + "..." : value;
+const shorthands = {
+  background: ["background-attachment", "background-clip", "background-color", "background-image", "background-origin", "background-position", "background-repeat", "background-size"],
+  "background-position": ["background-position-x", "background-position-y"],
+  "background-repeat": ["background-repeat-x", "background-repeat-y"],
+  font: ["font-family", "font-size", "font-stretch", "font-style", "font-variant", "font-weight", "line-height"],
+  animation: ["animation-name", "animation-duration", "animation-timing-function", "animation-delay", "animation-iteration-count", "animation-direction", "animation-fill-mode", "animation-play-state"],
+  transition: ["transition-property", "transition-duration", "transition-timing-function", "transition-delay", "transition-behavior"],
+  flex: ["flex-grow", "flex-shrink", "flex-basis"],
+  "flex-flow": ["flex-direction", "flex-wrap"],
+  gap: ["row-gap", "column-gap"],
+  outline: ["outline-color", "outline-style", "outline-width"],
+  columns: ["column-count", "column-width"],
+  "column-rule": ["column-rule-color", "column-rule-style", "column-rule-width"],
+  "list-style": ["list-style-image", "list-style-position", "list-style-type"],
+  "text-decoration": ["text-decoration-color", "text-decoration-style", "text-decoration-line", "text-decoration-thickness"],
+};
+const expand = property => shorthands[property]?.flatMap(expand) ?? [property];
+const longhands = new Map(Object.keys(shorthands).map(property => [property, expand(property)]));
+
+// CSS-language relationships, independent of components, tokens and frameworks.
+function footprint(property) {
+  const box = /^(padding|margin|scroll-padding|scroll-margin|inset)(?:-(top|right|bottom|left|block|inline|block-start|block-end|inline-start|inline-end))?$/.exec(property);
+  if (box) {
+    const side = box[2];
+    const logical = !!side && !sides.includes(side);
+    return { family: box[1], logical, slots: !side ? logicalSides : /^(block|inline)$/.test(side) ? [`${side}-start`, `${side}-end`] : [side], whole: !side };
+  }
+  if (sides.includes(property)) return { family: "inset", logical: false, slots: [property] };
+  const border = /^border(?:-(top|right|bottom|left|block|inline|block-start|block-end|inline-start|inline-end))?(?:-(color|style|width))?$/.exec(property);
+  if (border) {
+    const side = border[1];
+    return { family: "border", logical: !!side && !sides.includes(side), slots: !side ? logicalSides : /^(block|inline)$/.test(side) ? [`${side}-start`, `${side}-end`] : [side], whole: !side, fields: border[2] ? [border[2]] : ["color", "style", "width"] };
+  }
+  const corner = /^border-(?:(top-left|top-right|bottom-left|bottom-right|start-start|start-end|end-start|end-end)-)?radius$/.exec(property);
+  if (corner) return { family: "radius", logical: /^(start|end)-/.test(corner[1] ?? ""), whole: !corner[1], slots: [corner[1]] };
+  const dimension = /^(min-|max-)?(width|height|inline-size|block-size)$/.exec(property);
+  if (dimension) return { family: `${dimension[1] ?? ""}size`, logical: dimension[2].endsWith("-size"), slots: [dimension[2]] };
+  const overflow = /^(overflow|overscroll-behavior)(?:-(x|y|block|inline))?$/.exec(property);
+  if (overflow) return { family: overflow[1], logical: ["block", "inline"].includes(overflow[2]), whole: !overflow[2], slots: [overflow[2]] };
+  return null;
+}
+
+function overlaps(a, b) {
+  if (a === b || a.startsWith("--") || b.startsWith("--")) return false;
+  if ([a, b].includes("all")) return ![a, b].some(value => ["direction", "unicode-bidi"].includes(value));
+  const first = footprint(a), second = footprint(b);
+  if (first && second && first.family === second.family) {
+    if (first.fields && !intersects(first.fields, second.fields)) return false;
+    return first.whole || second.whole || first.logical !== second.logical || intersects(first.slots, second.slots);
+  }
+  return intersects(longhands.get(a) ?? [a], longhands.get(b) ?? [b]);
+}
+
+const modes = ["horizontal-tb", "vertical-rl", "vertical-lr"].flatMap(mode => ["ltr", "rtl"].map(direction => ({ mode, direction })));
+function physicalSlots(property, { mode, direction }) {
+  const value = footprint(property);
+  if (!value) return null;
+  if (value.whole) return sides;
+  const horizontal = mode === "horizontal-tb";
+  const axes = {
+    "block-start": horizontal ? "top" : mode === "vertical-rl" ? "right" : "left",
+    "block-end": horizontal ? "bottom" : mode === "vertical-rl" ? "left" : "right",
+    "inline-start": horizontal ? direction === "ltr" ? "left" : "right" : direction === "ltr" ? "top" : "bottom",
+    "inline-end": horizontal ? direction === "ltr" ? "right" : "left" : direction === "ltr" ? "bottom" : "top",
+    "inline-size": horizontal ? "width" : "height", "block-size": horizontal ? "height" : "width",
+    inline: horizontal ? "x" : "y", block: horizontal ? "y" : "x",
+  };
+  return value.slots.map(slot => value.family === "radius" && slot ? (/^(start|end)-/.test(slot) ? [axes[`block-${slot.split("-")[0]}`], axes[`inline-${slot.split("-")[1]}`]] : slot.split("-")).sort().join("-") : axes[slot] ?? slot);
+}
+function writingModeDependent(a, b) {
+  const first = footprint(a), second = footprint(b);
+  if (!first || !second || first.family !== second.family || first.whole || second.whole || first.logical === second.logical) return false;
+  const matches = modes.map(mode => intersects(physicalSlots(a, mode), physicalSlots(b, mode)));
+  return matches.some(Boolean) && !matches.every(Boolean);
+}
+function words(value) {
+  const nodes = valueParser(value).nodes;
+  return nodes.every(node => ["word", "space", "comment"].includes(node.type)) ? nodes.filter(node => node.type === "word").map(node => node.value.toLowerCase()) : null;
+}
+function boxValues(entry, mode) {
+  const value = footprint(entry.property), parts = words(entry.value);
+  if (!value || !["padding", "margin", "scroll-padding", "scroll-margin", "inset"].includes(value.family) || !parts?.length || parts.length > 4 || parts.some(part => ["inherit", "initial", "unset", "revert", "revert-layer"].includes(part))) return null;
+  const slots = physicalSlots(entry.property, mode);
+  if (!value.whole && parts.length > slots.length) return null;
+  const expanded = value.whole ? [parts[0], parts[1] ?? parts[0], parts[2] ?? parts[0], parts[3] ?? parts[1] ?? parts[0]] : slots.map((_slot, index) => parts[index] ?? parts[0]);
+  return new Map(slots.map((slot, index) => [slot, expanded[index]]));
+}
+function equivalent(a, b) {
+  // Only suppress values whose overlap can be established from literal source.
+  // var(), calc(), inheritance and token aliases still need rendered review.
+  const first = footprint(a.property), second = footprint(b.property);
+  if (first && second && first.family === second.family && ["padding", "margin", "scroll-padding", "scroll-margin", "inset"].includes(first.family)) {
+    return modes.every(mode => {
+      const left = boxValues(a, mode), right = boxValues(b, mode);
+      return left && right && [...left].every(([slot, value]) => !right.has(slot) || right.get(slot) === value);
+    });
+  }
+  const flex = a.property === "flex" ? a : b.property === "flex" ? b : null;
+  const field = flex === a ? b : a;
+  if (flex && ["flex-grow", "flex-shrink", "flex-basis"].includes(field.property)) {
+    const parts = words(flex.value);
+    return parts?.length === 3 && /^\d+(?:\.\d+)?$/.test(parts[0]) && /^\d+(?:\.\d+)?$/.test(parts[1]) && /^(?:auto|0|\d+(?:\.\d+)?(?:px|rem|em|%))$/.test(parts[2]) && parts[["flex-grow", "flex-shrink", "flex-basis"].indexOf(field.property)] === field.value.trim().toLowerCase();
+  }
+  return false;
+}
+
+function valueModeDependent(a, b) {
+  const equal = modes.map(mode => {
+    const left = boxValues(a, mode), right = boxValues(b, mode);
+    return left && right ? [...left].every(([slot, value]) => !right.has(slot) || right.get(slot) === value) : null;
+  });
+  return !equal.includes(null) && equal.some(Boolean) && !equal.every(Boolean);
+}
+
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+  return node;
+}
+
+/** Review only: valid CSS can intentionally overlap. Never rewrite project CSS. */
+export function createAtomicCompositionReview(program, options) {
+  const checker = program.getTypeChecker(), templates = new Map();
+  function imported(node, names, modules, seen = new Set()) {
+    node = unwrap(node);
+    if (!node || seen.has(node)) return false;
+    seen = new Set([...seen, node]);
+    const base = ts.isPropertyAccessExpression(node) ? node.expression : node;
+    const symbol = checker.getSymbolAtLocation(base);
+    for (const item of symbol?.declarations ?? []) {
+      if (ts.isImportSpecifier(item) && names.includes((item.propertyName ?? item.name).text) && modules.includes(item.parent.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isNamespaceImport(item) && ts.isPropertyAccessExpression(node) && names.includes(node.name.text) && modules.includes(item.parent.parent.moduleSpecifier.text)) return true;
+      if (ts.isVariableDeclaration(item) && imported(item.initializer, names, modules, seen)) return true;
+    }
+    return false;
+  }
+  const isCx = node => imported(node, ["cx"], ["@linaria/atomic", "@linaria/core"]);
+  function isAtomic(tag) {
+    if (ts.isCallExpression(tag)) tag = tag.expression;
+    if (imported(tag, ["css", "styled"], ["@linaria/atomic"])) return true;
+    return ts.isPropertyAccessExpression(tag) && imported(tag.expression, ["styled"], ["@linaria/atomic"]);
+  }
+  function entries(node) {
+    if (templates.has(node)) return templates.get(node);
+    const result = [];
+    templates.set(node, result);
+    const source = node.getSourceFile(), template = node.template;
+    const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text : template.head.text + template.templateSpans.map(span => `__ads_expression__${"\n".repeat(span.expression.getText(source).split("\n").length - 1)}${span.literal.text}`).join("");
+    const position = source.getLineAndCharacterOfPosition(template.getStart(source) + 1);
+    try {
+      postcss.parse(text).walkDecls(decl => {
+        const selectors = [], conditions = [];
+        for (let parent = decl.parent; parent?.type !== "root"; parent = parent?.parent) {
+          if (!parent) break;
+          if (parent.type === "rule") selectors.unshift(parent.selector.trim().replace(/\s+/g, " "));
+          if (parent.type === "atrule") conditions.unshift(`${parent.name} ${parent.params}`.trim().replace(/\s+/g, " "));
+        }
+        // Animation frames describe different instants, not combined classes.
+        if (conditions.some(condition => /^(?:-\w+-)?keyframes\b/.test(condition))) return;
+        result.push({ property: decl.prop.toLowerCase(), value: decl.value, important: !!decl.important, selectors: JSON.stringify(selectors), conditions: JSON.stringify(conditions),
+          file: path.relative(options.root, source.fileName).replaceAll("\\", "/"), line: position.line + decl.source.start.line, column: decl.source.start.column + (decl.source.start.line === 1 ? position.character : 0) });
+      });
+    } catch { /* The core CSS syntax diagnostic owns malformed templates. */ }
+    return result;
+  }
+  const trace = createAtomicTrace(program, options, { entries, isAtomic, isCx });
+  return source => {
+    const warnings = new Map(), limits = new Map();
+    const relative = entry => ({ ...entry, file: path.relative(options.root, entry.file).replaceAll("\\", "/") });
+    function compare(first, second, location, context = {}) {
+      for (const a of first) for (const b of second) {
+        if (a === b || a.selectors !== b.selectors || a.conditions !== b.conditions || a.important !== b.important || !overlaps(a.property, b.property) || equivalent(a, b)) continue;
+        const key = JSON.stringify([a, b].map(entry => [entry.file, entry.line, entry.column]).sort());
+        const composition = [...new Map([...(context.path ?? []), ...(a.via ?? []), ...(b.via ?? [])].map(entry => [JSON.stringify(entry), relative(entry)])).values()].slice(0, 16);
+        const previous = warnings.get(key);
+        if (previous && (previous.target || !context.target) && previous.composition.length >= composition.length) continue;
+        const position = source.getLineAndCharacterOfPosition(location.getStart(source));
+        const dependent = writingModeDependent(a.property, b.property) || valueModeDependent(a, b);
+        warnings.set(key, { rule: "atomic-composition-review", severity: "warning", line: position.line + 1, column: position.character + 1,
+          message: `Atomic declarations ${a.property}: ${previewValue(a.value)} and ${b.property}: ${previewValue(b.value)} may overlap without matching cx merge keys.${context.target ? ` Source tracing reaches the same <${context.target.name}> className.` : " This is a source composition risk, not a confirmed rendered conflict."}${dependent ? " The overlap depends on writing mode or direction." : ""} Their winner can depend on extraction order, specificity or writing mode. Use consistent property names/granularity across the base and variants, compose with Linaria cx, and verify computed styles in the built preview. Review all affected variants; valid tokens do not establish cascade correctness. See ${atomicStyleGuide}.`,
+          guidanceUri: atomicStyleGuide, writingModeDependent: dependent, composition, ...(context.target ? { target: relative(context.target) } : {}), ...(context.limits?.length ? { analysisLimits: [...new Set(context.limits)].slice(0, 5) } : {}),
+          related: [a, b].map(({ selectors: _selectors, conditions: _conditions, important: _important, via: _via, ...entry }) => ({...entry,value:previewValue(entry.value)})) });
+      }
+    }
+    function limit(node, reasons, composition) {
+      const key = reasons.join("\n");
+      if (limits.has(key) || limits.size >= 5) return;
+      const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+      limits.set(key, { rule: "atomic-composition-limit", severity: "info", line: position.line + 1, column: position.character + 1,
+        message: `Atomic source review is incomplete: ${[...new Set(reasons)].slice(0, 3).join(" ")} Review the actual DOM classes and computed styles in a built scenario. An unresolved path is not evidence that composition is safe. See ${atomicStyleGuide}.`, guidanceUri: atomicStyleGuide, composition: composition.slice(0, 16).map(relative) });
+    }
+    function visit(node) {
+      if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) {
+        const declarations = entries(node);
+        for (let index = 0; index < declarations.length; index++) compare([declarations[index]], declarations.slice(index + 1), node);
+      }
+      ts.forEachChild(node, visit);
+    }
+    if (isInside(options.dsRoot, source.fileName)) { visit(source); trace(source, { compare, limit }); }
+    return [...warnings.values(), ...limits.values()];
+  };
+}

package/dist/atomic-trace.mjs

@@ -0,0 +1,287 @@
+import ts from "typescript";
+import { isInside } from "./config.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+const unknown = reason => ({ kind: "unknown", reason });
+const literal = value => ({ kind: "literal", value });
+const reference = (node, env = new Map(), via = []) => node ? { kind: "node", node, env, via } : literal(undefined);
+const union = values => values.length === 1 ? values[0] : { kind: "union", values };
+const isFunction = node => node && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node));
+const nameOf = node => node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) ? node.text : undefined;
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+  return node;
+}
+
+/** Bounded symbolic source traversal. No project code is imported or executed. */
+export function createAtomicTrace(program, options, { entries, isAtomic, isCx }) {
+  const checker = program.getTypeChecker();
+  const symbol = node => checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+  function declaration(node) {
+    let value = symbol(node);
+    if (value?.flags & ts.SymbolFlags.Alias) value = checker.getAliasedSymbol(value);
+    return value?.valueDeclaration;
+  }
+  const state = () => ({ budget: { steps: 0 }, depth: 0, calls: new Set() });
+  function next(context) { return { ...context, depth: context.depth + 1 }; }
+  function exhausted(context) { return ++context.budget.steps > 4000 || context.depth > 48; }
+  function at(node, kind, name) {
+    const source = node.getSourceFile(), position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return { file: source.fileName, line: position.line + 1, column: position.character + 1, kind, name: name.slice(0, 100) };
+  }
+  function withVia(value, via) {
+    if (value.kind === "union") return { ...value, values: value.values.map(item => withVia(item, via)) };
+    return value.kind === "node" ? { ...value, via: [...new Map([...via, ...value.via].map(item => [JSON.stringify(item), item])).values()].slice(0, 16) } : value;
+  }
+  function withDefault(value, fallback, context) {
+    if (!fallback) return value;
+    value = resolve(value, next(context));
+    if (value.kind === "literal") return value.value === undefined ? fallback : value;
+    if (value.kind === "unknown") return union([value, fallback]);
+    if (value.kind === "union") return union(value.values.map(item => withDefault(item, fallback, next(context))));
+    return value;
+  }
+  function bind(pattern, value, env, via, context) {
+    if (ts.isIdentifier(pattern)) { env.set(symbol(pattern), value); return; }
+    if (ts.isObjectBindingPattern(pattern)) {
+      const excluded = new Set();
+      for (const part of pattern.elements) {
+        const key = nameOf(part.propertyName ?? part.name);
+        if (part.dotDotDotToken) bind(part.name, { kind: "rest", value, excluded: new Set(excluded) }, env, via, next(context));
+        else {
+          if (key === undefined) continue;
+          excluded.add(key);
+          bind(part.name, withDefault(get(value, key, next(context)), part.initializer && reference(part.initializer, env, via), context), env, via, next(context));
+        }
+      }
+    } else if (ts.isArrayBindingPattern(pattern)) {
+      pattern.elements.forEach((part, index) => {
+        if (ts.isBindingElement(part) && !part.dotDotDotToken) bind(part.name, withDefault(get(value, String(index), next(context)), part.initializer && reference(part.initializer, env, via), context), env, via, next(context));
+      });
+    }
+  }
+  function boundElement(node, env, via, context) {
+    let owner = node;
+    while (ts.isBindingElement(owner) || ts.isObjectBindingPattern(owner) || ts.isArrayBindingPattern(owner)) owner = owner.parent;
+    if (!ts.isVariableDeclaration(owner) || !owner.initializer || !(owner.parent.flags & ts.NodeFlags.Const)) return unknown();
+    const local = new Map(env);
+    bind(owner.name, reference(owner.initializer, env, via), local, via, next(context));
+    return local.get(symbol(node.name)) ?? unknown();
+  }
+  function get(value, key, context) {
+    value = resolve(value, next(context));
+    if (value.kind === "union") return union(value.values.map(item => get(item, key, next(context))));
+    if (value.kind === "rest") return value.excluded.has(key) ? literal(undefined) : get(value.value, key, next(context));
+    const layers = value.kind === "object" ? value.layers : [];
+    if (value.kind === "node" && ts.isObjectLiteralExpression(value.node)) {
+      for (const property of value.node.properties) {
+        if (ts.isSpreadAssignment(property)) layers.push(reference(property.expression, value.env, value.via));
+        else {
+          const name = nameOf(property.name);
+          if (name !== undefined) layers.push(new Map([[name, reference(ts.isShorthandPropertyAssignment(property) ? property.name : ts.isMethodDeclaration(property) ? property : property.initializer, value.env, value.via)]]));
+        }
+      }
+    } else if (value.kind === "node" && ts.isArrayLiteralExpression(value.node)) {
+      return reference(value.node.elements[Number(key)], value.env, value.via);
+    } else if (value.kind !== "object") return unknown(value.reason);
+    for (let index = layers.length - 1; index >= 0; index--) {
+      const layer = layers[index];
+      if (layer instanceof Map) { if (layer.has(key)) return layer.get(key); }
+      else {
+        const selected = get(layer, key, next(context));
+        if (selected.kind === "literal" && selected.value === undefined) continue;
+        // An opaque later spread may replace an earlier explicit property.
+        if (selected.kind === "unknown" || selected.kind === "union") return union([selected, get({ kind: "object", layers: layers.slice(0, index) }, key, next(context))]);
+        return selected;
+      }
+    }
+    return literal(undefined);
+  }
+  function keys(value, context) {
+    value = resolve(value, next(context));
+    if (value.kind === "union") return [...new Set(value.values.flatMap(item => keys(item, next(context))))];
+    if (value.kind === "node" && ts.isObjectLiteralExpression(value.node)) return value.node.properties.flatMap(property => ts.isSpreadAssignment(property) ? keys(reference(property.expression, value.env, value.via), next(context)) : nameOf(property.name) ?? []);
+    if (value.kind === "object") return [...new Set(value.layers.flatMap(layer => layer instanceof Map ? [...layer.keys()] : keys(layer, next(context))))];
+    return [];
+  }
+  function returns(fn, args, context, kind = "helper") {
+    if (context.calls.has(fn.node)) return [unknown("Recursive local call could not be fully traced.")];
+    if (!fn.node.body || fn.node.asteriskToken || fn.node.modifiers?.some(item => item.kind === ts.SyntaxKind.AsyncKeyword)) return [unknown("Async, generator or declaration-only calls are outside atomic source tracing.")];
+    const env = new Map(fn.env), via = [...fn.via, at(fn.node, kind, fn.node.name?.getText() ?? "local function")];
+    const inner = { ...next(context), calls: new Set([...context.calls, fn.node]) };
+    for (const [index, parameter] of fn.node.parameters.entries()) {
+      if (parameter.dotDotDotToken) { bind(parameter.name, { kind: "array", values: args.slice(index) }, env, via, inner); break; }
+      bind(parameter.name, withDefault(resolve(args[index] ?? literal(undefined), inner), parameter.initializer && reference(parameter.initializer, env, via), inner), env, via, inner);
+    }
+    const outputs = [];
+    function statement(node) {
+      if (ts.isReturnStatement(node)) { outputs.push(reference(node.expression, env, via)); return true; }
+      if (ts.isBlock(node)) { for (const child of node.statements) if (statement(child)) return true; }
+      else if (ts.isIfStatement(node)) {
+        const condition = resolve(reference(node.expression, env, via), inner);
+        if (condition.kind === "literal") return condition.value ? statement(node.thenStatement) : node.elseStatement ? statement(node.elseStatement) : false;
+        const left = statement(node.thenStatement), right = node.elseStatement ? statement(node.elseStatement) : false;
+        return left && right;
+      } else if (ts.isThrowStatement(node)) return true;
+      else if (ts.isIterationStatement(node, false) || ts.isSwitchStatement(node) || ts.isTryStatement(node)) outputs.push(unknown("Loop, switch or try control flow could not be fully traced."));
+      return false;
+    }
+    if (ts.isBlock(fn.node.body)) statement(fn.node.body);
+    else outputs.push(reference(fn.node.body, env, via));
+    // Keep call stacks with lazy return references, including nested helpers.
+    return outputs.length ? outputs.map(value => ({ ...value, context: inner })) : [literal(undefined)];
+  }
+  function resolve(value, context) {
+    if (!value) return literal(undefined);
+    context = value.context ?? context;
+    if (exhausted(context)) return unknown("Atomic source tracing reached its depth or work limit.");
+    if (value.kind !== "node") return value;
+    const node = unwrap(value.node), { env, via } = value;
+    if (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) return literal(ts.isNumericLiteral(node) ? Number(node.text) : node.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) return literal(node.kind === ts.SyntaxKind.TrueKeyword);
+    if (node.kind === ts.SyntaxKind.NullKeyword) return literal(null);
+    if (ts.isIdentifier(node)) {
+      if (env.has(symbol(node))) return resolve(env.get(symbol(node)), next(context));
+      const owner = declaration(node);
+      if (owner && isInside(options.dsRoot, owner.getSourceFile().fileName)) {
+        if (isFunction(owner)) return reference(owner, env, via);
+        if (ts.isVariableDeclaration(owner) && owner.initializer && owner.parent.flags & ts.NodeFlags.Const) return resolve(reference(owner.initializer, env, via), next(context));
+        if (ts.isBindingElement(owner)) return resolve(boundElement(owner, env, via, context), next(context));
+      }
+      return node.text === "undefined" && !owner ? literal(undefined) : unknown();
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      const key = ts.isPropertyAccessExpression(node) ? literal(node.name.text) : resolve(reference(node.argumentExpression, env, via), next(context));
+      const object = reference(node.expression, env, via);
+      if (key.kind === "literal") {
+        const selected = get(object, String(key.value), next(context));
+        const owner = declaration(node);
+        if (selected.kind === "unknown" && owner && isInside(options.dsRoot, owner.getSourceFile().fileName)) {
+          if (isFunction(owner)) return reference(owner, env, via);
+          if (ts.isVariableDeclaration(owner) && owner.initializer && owner.parent.flags & ts.NodeFlags.Const) return resolve(reference(owner.initializer, env, via), next(context));
+        }
+        return resolve(selected, next(context));
+      }
+      const names = keys(object, next(context));
+      return names.length ? union(names.map(name => get(object, name, next(context)))) : unknown();
+    }
+    if (ts.isConditionalExpression(node)) {
+      const condition = resolve(reference(node.condition, env, via), next(context));
+      return condition.kind === "literal" ? resolve(reference(condition.value ? node.whenTrue : node.whenFalse, env, via), next(context)) : union([reference(node.whenTrue, env, via), reference(node.whenFalse, env, via)]);
+    }
+    if (ts.isBinaryExpression(node)) {
+      const left = resolve(reference(node.left, env, via), next(context)), right = reference(node.right, env, via), operator = node.operatorToken.kind;
+      if (operator === ts.SyntaxKind.AmpersandAmpersandToken) return left.kind === "literal" ? left.value ? right : literal(undefined) : union([literal(undefined), right]);
+      if (operator === ts.SyntaxKind.BarBarToken) return left.kind === "literal" ? left.value ? left : right : union([left, right]);
+      if (operator === ts.SyntaxKind.QuestionQuestionToken) return left.kind === "literal" ? left.value == null ? right : left : union([left, right]);
+      const other = resolve(right, next(context));
+      if (left.kind === "literal" && other.kind === "literal" && [ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(operator)) return literal(operator === ts.SyntaxKind.EqualsEqualsEqualsToken ? left.value === other.value : left.value !== other.value);
+    }
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
+      const operand = resolve(reference(node.operand, env, via), next(context));
+      return operand.kind === "literal" ? literal(!operand.value) : unknown();
+    }
+    if (ts.isCallExpression(node) && !isCx(node.expression)) {
+      if (["memo", "forwardRef"].includes(uiOperation(node.expression, checker))) return resolve(reference(node.arguments[0], env, via), next(context));
+      const fn = resolve(reference(node.expression, env, via), next(context));
+      if (fn.kind === "node" && isFunction(fn.node)) {
+        const outputs = returns(fn, node.arguments.map(argument => reference(argument, env, via)), next(context));
+        return withVia(resolve(union(outputs), next(context)), outputs.flatMap(item => item.via ?? []));
+      }
+      return unknown(`Call ${node.expression.getText().slice(0, 80)} could not be traced to a local function.`);
+    }
+    return { ...value, node };
+  }
+  function arrays(value, context) {
+    value = resolve(value, next(context));
+    if (value.kind === "array") return value.values;
+    if (value.kind === "node" && ts.isArrayLiteralExpression(value.node)) return value.node.elements.map(node => reference(node, value.env, value.via));
+    return null;
+  }
+
+  return function review(source, { compare, limit }) {
+    const maxBranches = 32;
+    const unique = branches => [...new Map(branches.map(branch => [JSON.stringify(branch.map(entry => [entry.file, entry.line, entry.column])), branch])).values()];
+    function styles(input, context) {
+      const value = resolve(input, next(context));
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "unknown") return { branches: [[]], limits: value.reason ? [value.reason] : [] };
+      if (value.kind === "union") {
+        const results = value.values.slice(0, maxBranches).map(item => styles(item, next(context)));
+        const branches = unique(results.flatMap(item => item.branches));
+        return { branches: branches.slice(0, maxBranches), limits: [...results.flatMap(item => item.limits), ...(value.values.length > maxBranches || branches.length > maxBranches ? ["Atomic source tracing reached its alternative limit."] : [])] };
+      }
+      if (value.kind !== "node") return { branches: [[]], limits: [] };
+      const { node, env, via } = value;
+      if (ts.isTaggedTemplateExpression(node) && isAtomic(node.tag)) return { branches: [entries(node).map(entry => ({ ...entry, via }))], limits: [] };
+      if (ts.isCallExpression(node) && isCx(node.expression)) {
+        const inputs = node.arguments.flatMap(argument => ts.isSpreadElement(argument) ? arrays(reference(argument.expression, env, via), context) ?? [unknown("A dynamic class argument spread could not be traced.")] : [reference(argument, env, via)]);
+        let branches = [[]]; const limits = [];
+        for (const argument of inputs) {
+          const result = styles(argument, next(context));
+          limits.push(...result.limits);
+          const combined = new Map(); let truncated = false;
+          for (const first of branches) for (const second of result.branches) {
+            // cx replaces exact property/selector/condition keys; shorthand
+            // expansion remains the CSS overlap review's responsibility.
+            const merged = new Map([...first, ...second.map(entry => ({ ...entry, via: [...via, ...(entry.via ?? [])] }))].map(entry => [JSON.stringify([entry.property, entry.selectors, entry.conditions]), entry]));
+            const branch = [...merged.values()], key = JSON.stringify(branch.map(entry => [entry.file, entry.line, entry.column]));
+            if (!combined.has(key) && combined.size >= maxBranches) { truncated = true; continue; }
+            combined.set(key, branch);
+          }
+          if (truncated) limits.push("Atomic source tracing reached its alternative limit.");
+          branches = [...combined.values()];
+        }
+        return { branches, limits };
+      }
+      return { branches: [[]], limits: [] };
+    }
+    function inspect(value, node, context, target, path = []) {
+      const result = styles(value, context);
+      for (const branch of result.branches) for (let index = 0; index < branch.length; index++) compare([branch[index]], branch.slice(index + 1), node, { target, path, limits: result.limits });
+      if (result.limits.length && (result.branches.some(branch => branch.length) || ts.isCallExpression(node) && node.arguments.some(argument => styles(reference(argument), next(context)).branches.some(branch => branch.length)))) limit(node, result.limits, path);
+      return result;
+    }
+    function props(node, env, via) {
+      return { kind: "object", layers: node.attributes.properties.map(attribute => ts.isJsxSpreadAttribute(attribute) ? reference(attribute.expression, env, via) : new Map([[attribute.name.text, attribute.initializer ? ts.isJsxExpression(attribute.initializer) ? reference(attribute.initializer.expression, env, via) : reference(attribute.initializer, env, via) : literal(true)]])) };
+    }
+    function render(input, location, context, path = [], pendingStyles = false) {
+      const value = resolve(input, next(context));
+      context = value.context ?? input.context ?? context;
+      if (value.kind === "union") { for (const item of value.values.slice(0, maxBranches)) render(item, location, next(context), path, pendingStyles); return; }
+      if (value.kind !== "node") { if (value.reason && pendingStyles) limit(location, [value.reason], path); return; }
+      const { node, env, via } = value;
+      if (ts.isJsxExpression(node)) { render(reference(node.expression, env, via), location, next(context), path, pendingStyles); return; }
+      if (ts.isJsxFragment(node)) { for (const child of node.children) render(reference(child, env, via), location, next(context), path); return; }
+      if (ts.isArrayLiteralExpression(node)) { for (const child of node.elements) render(reference(child, env, via), location, next(context), path); return; }
+      if (!ts.isJsxElement(node) && !ts.isJsxSelfClosingElement(node)) return;
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const attributes = props(opening, env, via), classValue = get(attributes, "className", next(context));
+      const tag = opening.tagName.getText();
+      if (/^[a-z]/.test(tag) && !tag.includes(".")) {
+        inspect(classValue, location, context, at(opening, "element", tag), [...path, ...via]);
+        if (ts.isJsxElement(node)) for (const child of node.children) render(reference(child, env, via), location, next(context), path);
+        return;
+      }
+      function componentTarget(component) {
+        if (component.kind === "union") { for (const alternative of component.values.slice(0, maxBranches)) componentTarget(resolve(alternative, next(context))); return; }
+        if (component.kind === "literal" && typeof component.value === "string") {
+          inspect(classValue, location, context, at(opening, "element", component.value), [...path, ...via]);
+        } else if (component.kind === "node" && isFunction(component.node)) {
+          const passed = pendingStyles || styles(classValue, context).branches.some(branch => branch.length);
+          for (const output of returns(component, [attributes], next(context), "component")) render(output, location, output.context ?? next(context), [...path, at(opening, "component", tag)], passed);
+        } else {
+          const passed = styles(classValue, context);
+          if (passed.branches.some(branch => branch.length)) limit(location, [`Component ${tag.slice(0, 80)} could not be traced to its DOM className target.`, ...passed.limits], path);
+        }
+      }
+      componentTarget(resolve(reference(opening.tagName, env, via), next(context)));
+    }
+    function visit(node) {
+      if (ts.isCallExpression(node)) inspect(reference(node), node, state());
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) render(reference(node), node, state());
+      ts.forEachChild(node, visit);
+    }
+    visit(source);
+  };
+}

package/dist/check.mjs

@@ -19,6 +19,7 @@ import { inspectBehaviors, inspectControllers } from "./behaviors.mjs";
 import { numericCssUnit, tokenLengthLiteral } from "./css-values.mjs";
 import { foundationDeclaration, foundationSelector } from "./foundation.mjs";
 import { scopedTokens, scopedTokenOwner } from "./scoped-tokens.mjs";
+import { createAtomicCompositionReview } from "./atomic-composition.mjs";
 
 const scenarioLayoutGuidance = "Put demo-only sizing and framing in a public review/layout pattern. Keep required behavior in the runtime owner; add component props for deliberate product API needs.";
 const inlineStyleGuidance = `Own visual styles in component/pattern Linaria. ${scenarioLayoutGuidance} Reserve inlineStyleFiles for documented measured geometry, not demo layout.`;
@@ -50,6 +51,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
   const compiler = projectCompilerOptions(options);
   const program = ts.createProgram(scriptFiles, { ...compiler, paths: { ...compiler.paths, [config.publicAlias]: [path.join(dsRoot, config.publicEntry)] }, allowJs: true, noResolve: true, noLib: true, types: [], target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, jsx: ts.JsxEmit.Preserve });
   const checker = program.getTypeChecker();
+  const atomicCompositionReview = createAtomicCompositionReview(program, options);
   function report(file, rule, message, line = 1, column = 1) {
     diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule, message, line, column });
   }
@@ -149,6 +151,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     const source = program.getSourceFile(file);
     if (!source) continue;
     advisories.push(...pointerCaptureAdvisories(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
+    advisories.push(...atomicCompositionReview(source).map(entry => ({ file: path.relative(root, file).replaceAll("\\", "/"), ...entry })));
     for (const diagnostic of program.getSyntacticDiagnostics(source)) {
       const position = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
       report(file, "source-syntax", ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"), position.line + 1, position.character + 1);
@@ -259,5 +262,7 @@ export function checkProject(directory, { trackingRoot } = {}) {
     }
     visit(source);
   }
+  // Bounded clients should see actionable warnings before source-analysis limits.
+  advisories.sort((first, second) => Number(first.severity === "info") - Number(second.severity === "info"));
   return { ok: diagnostics.length === 0, diagnostics, ...(advisories.length ? { advisories } : {}) };
 }

package/dist/cli.mjs

@@ -113,7 +113,7 @@ async function main(args) {
   if (!json && result.diagnostics?.length) {
     for (const diagnostic of result.diagnostics) console.error(`${diagnostic.file}:${diagnostic.line}:${diagnostic.column} [${diagnostic.rule}] ${diagnostic.message}`);
   }
-  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [advisory:${advisory.rule}] ${advisory.message}`);
+  if (!json) for (const advisory of result.advisories ?? []) console.error(`${advisory.file}:${advisory.line}:${advisory.column} [${advisory.severity ?? "advisory"}:${advisory.rule}] ${advisory.message}`);
   if (result.ok === false || result.diagnostics?.length) process.exitCode = 1;
 }
 

package/dist/mcp/server.mjs

@@ -85,6 +85,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     return [
       { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
       { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
+      { uri: "ads://guides/atomic-styles", name: "Atomic style composition: conflicts, prevention and fixes", mimeType: "text/markdown" },
       { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
       { uri: BUILD_URI, name: "Preview build status and diagnostics", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/tokens`, name: "Project token values and themes", mimeType: "application/json" },
@@ -92,13 +93,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       { uri: `${PROJECT_URI}/scenarios`, name: "Independently mountable scenarios", mimeType: "application/json" },
       { uri: BEHAVIOR_URI, name: "Behavior contracts, demonstrations and current verification evidence", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/checks`, name: "Current ADS architecture diagnostics", mimeType: "application/json" },
+      ...documents.filter(document => promoted.has(document.uri)).sort((a, b) => Number(b.uri === context.publicEntryUri) - Number(a.uri === context.publicEntryUri)).map(({ file: _file, ...document }) => document),
       { uri: TOKENS_APP_URI, name: "Experimental token widget", mimeType: APP_MIME },
       { uri: SCENARIO_APP_URI, name: "Experimental scenario widget", mimeType: APP_MIME },
       ...(options.config.mcp.previewManifest ? [{ uri: PREVIEW_APP_URI, name: "Shared-resource preview App", mimeType: APP_MIME }, { uri: PREVIEW_MANIFEST_URI, name: "Preview dependency graph", mimeType: "application/json" }] : []),
       ...(options.config.mcp.previewManifest ? resourceAssets() : []),
       ...allApps().map((app) => ({ uri: appUri(app.id), name: app.title, description: app.description, mimeType: APP_MIME })),
       ...skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description, mimeType: "text/markdown" })),
-      ...documents.filter((document) => promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
       ...documents.filter((document) => !promoted.has(document.uri)).map(({ file: _file, ...document }) => document),
       ...[...skills.files.values()].filter((file) => !skillEntries.has(file.uri)).map(({ uri, name, mimeType }) => ({ uri, name, mimeType })),
     ];
@@ -121,6 +122,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   async function read(uri, signal) {
     if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
     if (uri === "ads://guides/behaviors") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../../docs/BEHAVIORS.md", import.meta.url), "utf8") }] };
+    if (uri === "ads://guides/atomic-styles") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../skills/ads-designer/references/atomic-styles.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -203,7 +205,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const matches = inventory.tokens.filter((token) => token.name.toLowerCase().includes(search.toLowerCase()));
         return json({ total: matches.length, tokens: matches.slice(0, limit), categories: tokenScenarios(), diagnosticCount: inventory.diagnostics.length, resourceUri: `${PROJECT_URI}/tokens` });
       } },
-      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
+      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking advisories, with warnings before informational limits. Atomic warnings include helper/forwarded-class paths and ads://guides/atomic-styles guidance; unresolved paths do not establish safe composition. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
         const result = checkProject(root);
         return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), advisoryCount: result.advisories?.length ?? 0, advisories: (result.advisories ?? []).slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
       } },