@bastani/atomic 0.9.11-alpha.6 → 0.9.11-alpha.7

package/dist/builtin/workflows/skills/impeccable/scripts/detector/design-system.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import { finding } from './findings.mjs';
@@ -7,6 +8,11 @@ import { parseAnyColor, resolveLengthPx } from './rules/checks.mjs';
 
 const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
 const FALLBACK_DIRS = ['.agents/context', 'docs'];
+// Files/dirs whose presence marks a directory as a project root. Mirrors the
+// walk-up semantics of skill/scripts/context.mjs (`resolveProject`), which the
+// CLI can't import (separate tree). `.git` and `package.json` are the common
+// boundaries; `.impeccable` is our own project marker.
+const PROJECT_ROOT_MARKERS = ['.git', 'package.json', '.impeccable'];
 const COLOR_CHANNEL_TOLERANCE = 6;
 const RADIUS_TOLERANCE_PX = 0.5;
 const FONT_SIZE_TOLERANCE_PX = 0.5;
@@ -288,15 +294,74 @@ function addTypographyFonts(out, typography) {
   }
 }
 
+function addFontSizeStep(out, raw, { fluid = false } = {}) {
+  const text = String(raw ?? '').trim().toLowerCase();
+  if (!FONT_SIZE_LITERAL_RE.test(text)) return;
+  const px = resolveLengthPx(text, 16);
+  if (px == null || !Number.isFinite(px) || px <= 0) return;
+  out.allowedFontSizes.push({ value: text, px, fluid });
+}
+
+// Split a fluid value into its three terms, or null when it is not a
+// well-formed clamp(). Used both to read DESIGN.md's fluid roles and to
+// validate fluid values in source, so the two stay symmetric.
+function parseClampArgs(raw) {
+  const match = /^clamp\(\s*([\s\S]+)\s*\)$/i.exec(String(raw ?? '').trim());
+  if (!match) return null;
+  const args = splitTopLevelArgs(match[1]);
+  return args.length === 3 ? args : null;
+}
+
+// A fluid role declares its two fixed endpoints and interpolates between them
+// with a viewport unit. Both endpoints are documented sizes, so they belong in
+// the allowlist; the middle term is viewport-relative and never a fixed step.
+// Endpoints are marked `fluid` because they do not *enumerate* a ramp: see
+// `hasFontSizes` below for why that distinction has to survive.
+function addClampEndpoints(out, raw) {
+  const args = parseClampArgs(raw);
+  if (!args) return false;
+  addFontSizeStep(out, args[0], { fluid: true });
+  addFontSizeStep(out, args[2], { fluid: true });
+  return true;
+}
+
+function splitTopLevelArgs(s) {
+  const args = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of String(s)) {
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      args.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) args.push(current.trim());
+  return args;
+}
+
 function addTypographySizes(out, typography) {
   if (!typography || typeof typography !== 'object') return;
-  for (const role of Object.values(typography)) {
+
+  // `scale` is the enumerated ramp: a name -> size map, since the frontmatter
+  // parser has no list support. It sits alongside the named roles.
+  const scale = typography.scale;
+  if (scale && typeof scale === 'object') {
+    for (const value of Object.values(scale)) {
+      if (typeof value !== 'string' && typeof value !== 'number') continue;
+      addFontSizeStep(out, value);
+    }
+  }
+
+  for (const [name, role] of Object.entries(typography)) {
+    if (name === 'scale') continue;
     if (!role || typeof role !== 'object') continue;
     const raw = String(role.fontSize ?? '').trim().toLowerCase();
-    if (!FONT_SIZE_LITERAL_RE.test(raw)) continue;
-    const px = resolveLengthPx(raw, 16);
-    if (px == null || !Number.isFinite(px) || px <= 0) continue;
-    out.allowedFontSizes.push({ value: raw, px });
+    if (addClampEndpoints(out, raw)) continue;
+    addFontSizeStep(out, raw);
   }
 }
 
@@ -371,7 +436,10 @@ function normalizeDesignSystem(input = {}) {
   out.hasFonts = out.allowedFonts.size > 0;
   out.hasColors = out.allowedColorKeys.size > 0;
   out.hasRadii = out.allowedRadii.length > 0;
-  out.hasFontSizes = out.allowedFontSizes.length > 0;
+  // Gate on *enumerated* steps only. A fully fluid system declares clamp
+  // endpoints but no discrete ramp, so treating those endpoints as the whole
+  // allowlist would flag every intermediate size. Abstain instead.
+  out.hasFontSizes = out.allowedFontSizes.some(entry => !entry.fluid);
   return out;
 }
 
@@ -407,6 +475,62 @@ function loadDesignSystemForCwd(cwd = process.cwd()) {
   });
 }
 
+// Directory to begin the project-root walk from, given a scan target that may
+// be a file or a directory (and may not exist yet).
+function designSystemStartDir(targetPath, cwd = process.cwd()) {
+  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
+  try {
+    return fs.statSync(abs).isDirectory() ? abs : path.dirname(abs);
+  } catch {
+    // Nonexistent path: treat an extension-bearing leaf as a file.
+    return path.extname(abs) ? path.dirname(abs) : abs;
+  }
+}
+
+// Walk up from `startDir` to the directory that governs the target's design
+// system, mirroring skill/scripts/context.mjs's project-boundary semantics:
+//
+//   - A directory carrying a DESIGN.md (directly or in a fallback dir) IS the
+//     design root — that's where the rules live.
+//   - A directory carrying a project marker (.git / package.json / .impeccable)
+//     but no DESIGN.md is a project BOUNDARY: the walk stops with no design
+//     system, so a sibling project never inherits a parent's or cwd's rules.
+//   - Reaching the home directory / filesystem root with neither means no
+//     design system at all — never process.cwd()'s.
+//
+// Returns { dir, hasDesign } for the stopping directory, or null when the walk
+// runs out. This is the fix for cross-project contamination.
+export function findDesignRoot(startDir) {
+  let dir = path.resolve(startDir);
+  const homeDir = path.resolve(os.homedir());
+  while (true) {
+    if (resolveDesignMdPath(dir)) return { dir, hasDesign: true };
+    if (PROJECT_ROOT_MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)))) {
+      return { dir, hasDesign: false };
+    }
+    if (dir === homeDir) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Resolve the design system that governs a specific scan target, by walking up
+// from the target's own location — never process.cwd(). Scanning project B's
+// files from inside project A applies B's DESIGN.md (or none), not A's.
+//
+// Pass a `cache` Map to memoize by resolved design root across a multi-file
+// scan; a target with no design root above it resolves to null.
+export function loadDesignSystemForTarget(targetPath, { cache, cwd = process.cwd() } = {}) {
+  const startDir = designSystemStartDir(targetPath, cwd);
+  const found = findDesignRoot(startDir);
+  const key = found ? `root:${found.dir}` : '\0none';
+  if (cache && cache.has(key)) return cache.get(key);
+  const loaded = found?.hasDesign ? loadDesignSystemForCwd(found.dir) : null;
+  if (cache) cache.set(key, loaded);
+  return loaded;
+}
+
 function isAllowedFont(font, designSystem) {
   if (!font || GENERIC_FONTS.has(font)) return true;
   if (!designSystem?.hasFonts) return true;
@@ -438,17 +562,43 @@ function isAllowedRadiusRaw(raw, designSystem) {
   return designSystem.allowedRadii.some(entry => Math.abs(entry.px - px) <= RADIUS_TOLERANCE_PX);
 }
 
-function isAllowedFontSizeRaw(raw, designSystem) {
-  if (!designSystem?.hasFontSizes) return true;
-  const text = String(raw || '').trim().toLowerCase().replace(/\s*!important\s*$/, '');
-  if (!FONT_SIZE_LITERAL_RE.test(text)) return true;
+// One term of a font-size value. `unjudgeable` covers var(), calc(), percentages
+// and units the ramp cannot resolve (em is parent-relative, not root-relative);
+// those abstain rather than guess.
+function fontSizeStepStatus(raw, designSystem) {
+  const text = String(raw || '').trim().toLowerCase();
+  if (!FONT_SIZE_LITERAL_RE.test(text)) return 'unjudgeable';
   const px = resolveLengthPx(text, 16);
-  if (px == null || !Number.isFinite(px) || px <= 0) return true;
+  if (px == null || !Number.isFinite(px) || px <= 0) return 'unjudgeable';
   return designSystem.allowedFontSizes.some(
     entry => Math.abs(entry.px - px) <= FONT_SIZE_TOLERANCE_PX,
+  ) ? 'on-ramp' : 'off-ramp';
+}
+
+// The off-ramp endpoints of a fluid value, or null when `raw` is not a fluid
+// value at all. Only the min and max are judged: the viewport term interpolates
+// between them and is never a fixed step.
+//
+// Reading clamp endpoints as documented steps without also checking them in
+// usage would let `clamp(99rem, 1vw, 200rem)` through, which is how a fluid
+// declaration stayed invisible until someone measured computed styles.
+export function offRampClampEndpoints(raw, designSystem) {
+  if (!designSystem?.hasFontSizes) return null;
+  const args = parseClampArgs(String(raw || '').trim().replace(/\s*!important\s*$/i, ''));
+  if (!args) return null;
+  return [args[0], args[2]].filter(
+    endpoint => fontSizeStepStatus(endpoint, designSystem) === 'off-ramp',
   );
 }
 
+function isAllowedFontSizeRaw(raw, designSystem) {
+  if (!designSystem?.hasFontSizes) return true;
+  const text = String(raw || '').trim().toLowerCase().replace(/\s*!important\s*$/, '');
+  const offRampEndpoints = offRampClampEndpoints(text, designSystem);
+  if (offRampEndpoints) return offRampEndpoints.length === 0;
+  return fontSizeStepStatus(text, designSystem) !== 'off-ramp';
+}
+
 function lineLooksCommented(line) {
   const trimmed = String(line || '').trim();
   return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('<!--');
@@ -543,12 +693,31 @@ function checkRadiusValue(value, filePath, line, designSystem, context) {
 function checkFontSizeValue(value, filePath, line, designSystem, context) {
   const token = String(value || '').trim();
   if (isAllowedFontSizeRaw(token, designSystem)) return [];
+
+  // Name the offending endpoint on a fluid value; the whole clamp() string is
+  // not actionable on its own, and it makes a poor ignore-value.
+  const offRampEndpoints = offRampClampEndpoints(token, designSystem) || [];
+  if (offRampEndpoints.length > 0) {
+    const plural = offRampEndpoints.length > 1 ? 's' : '';
+    return [makeDesignFinding(
+      'design-system-font-size',
+      filePath,
+      `${context}: ${token} has fluid endpoint${plural} ${offRampEndpoints.join(' and ')} off the DESIGN.md type ramp`,
+      line,
+      { ignoreValue: offRampEndpoints[0] },
+    )];
+  }
+
+  // The snippet shows the declaration as authored, but the ignoreValue has to
+  // be what a `hooks ignore-value` waiver can match, so the priority marker is
+  // stripped. Otherwise the same size needs two different waivers depending on
+  // whether it carries !important. font-family already behaves this way.
   return [makeDesignFinding(
     'design-system-font-size',
     filePath,
     `${context}: ${token} is off the DESIGN.md type ramp`,
     line,
-    { ignoreValue: token },
+    { ignoreValue: token.replace(/\s*!important\s*$/i, '').trim() },
   )];
 }