brandspec 0.1.0

package/dist/index.js

@@ -0,0 +1,718 @@
+// cli/parser.ts
+import yaml from "js-yaml";
+function parse(content) {
+  const errors = [];
+  const warnings = [];
+  let parsed;
+  try {
+    parsed = yaml.load(content);
+  } catch (e) {
+    return {
+      success: false,
+      errors: [`Invalid YAML: ${e instanceof Error ? e.message : "Unknown error"}`],
+      warnings: []
+    };
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return { success: false, errors: ["YAML must be an object"], warnings: [] };
+  }
+  const doc = parsed;
+  if (!doc.meta || typeof doc.meta !== "object") {
+    errors.push("Missing required field: meta");
+    return { success: false, errors, warnings };
+  }
+  const meta = doc.meta;
+  if (!meta.name || typeof meta.name !== "string") {
+    errors.push("Missing required field: meta.name");
+    return { success: false, errors, warnings };
+  }
+  if (doc.assets !== void 0) {
+    if (!Array.isArray(doc.assets)) {
+      errors.push("Field 'assets' must be an array");
+    } else {
+      doc.assets.forEach((asset, i) => {
+        if (!asset || typeof asset !== "object") {
+          errors.push(`assets[${i}] must be an object`);
+        } else {
+          const a = asset;
+          if (!a.file || typeof a.file !== "string") {
+            errors.push(`assets[${i}].file is required and must be a string`);
+          }
+        }
+      });
+    }
+  }
+  if (!doc.core) {
+    warnings.push("No 'core' section \u2014 brand essence, personality, and voice are recommended");
+  }
+  if (!doc.tokens) {
+    warnings.push("No 'tokens' section \u2014 design tokens are recommended");
+  }
+  if (errors.length > 0) {
+    return { success: false, errors, warnings };
+  }
+  return {
+    success: true,
+    data: doc,
+    errors: [],
+    warnings
+  };
+}
+function serialize(data) {
+  return yaml.dump(data, {
+    lineWidth: -1,
+    noRefs: true,
+    quotingType: '"',
+    forceQuotes: false
+  });
+}
+
+// cli/validate.ts
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+
+// cli/schema.ts
+var schema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://brandspec.tools/schema/v0.1.0",
+  title: "brandspec",
+  description: "Brand Identity specification format",
+  type: "object",
+  required: ["meta"],
+  properties: {
+    meta: {
+      type: "object",
+      description: "Brand metadata",
+      required: ["name"],
+      properties: {
+        name: { type: "string", description: "Brand name" },
+        version: { type: "string", description: "Brand spec version (semver)" },
+        updated: { type: "string", format: "date", description: "Last updated date" },
+        description: { type: "string", description: "Brief brand description" },
+        url: { type: "string", format: "uri", description: "Brand website" }
+      },
+      additionalProperties: true
+    },
+    core: {
+      type: "object",
+      description: "Brand essence, personality, and voice",
+      properties: {
+        essence: { type: "string" },
+        tagline: { type: "string" },
+        mission: { type: "string" },
+        vision: { type: "string" },
+        values: { type: "array", items: { type: "string" } },
+        personality: { type: "array", items: { type: "string" } },
+        voice: {
+          type: "object",
+          properties: {
+            tone: { type: "array", items: { type: "string" } },
+            principles: { type: "array", items: { type: "string" } }
+          },
+          additionalProperties: true
+        }
+      },
+      additionalProperties: true
+    },
+    tokens: {
+      type: "object",
+      description: "Design tokens (W3C DTCG compliant)",
+      additionalProperties: true
+    },
+    assets: {
+      type: "array",
+      description: "Brand assets",
+      items: {
+        type: "object",
+        required: ["file"],
+        properties: {
+          file: { type: "string" },
+          id: { type: "string" },
+          role: { type: "string" },
+          variant: { type: "string" },
+          context: { type: "string" },
+          description: { type: "string" },
+          formats: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                path: { type: "string" },
+                width: { type: "integer" },
+                height: { type: "integer" }
+              },
+              additionalProperties: true
+            }
+          },
+          tags: { type: "array", items: { type: "string" } }
+        },
+        additionalProperties: true
+      }
+    },
+    guidelines: {
+      type: "object",
+      description: "Usage guidelines",
+      additionalProperties: {
+        type: "object",
+        properties: {
+          content: { type: "string" },
+          rules: {
+            type: "array",
+            items: { $ref: "#/$defs/guidelineRule" }
+          }
+        },
+        additionalProperties: true
+      }
+    },
+    extensions: {
+      type: "object",
+      description: "Custom extensions",
+      additionalProperties: true
+    }
+  },
+  additionalProperties: true,
+  $defs: {
+    guidelineRule: {
+      type: "object",
+      required: ["description", "severity"],
+      properties: {
+        id: { type: "string" },
+        description: { type: "string" },
+        severity: {
+          type: "string",
+          enum: ["info", "warning", "error"]
+        },
+        criteria: { type: "array", items: { type: "string" } },
+        applies_to: { type: "string" }
+      },
+      additionalProperties: true
+    }
+  }
+};
+
+// cli/validate.ts
+var ajvInstance = null;
+function getAjv() {
+  if (!ajvInstance) {
+    ajvInstance = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajvInstance);
+  }
+  return ajvInstance;
+}
+function validate(data) {
+  const ajv = getAjv();
+  const { $schema: _, $id: __, ...schemaBody } = schema;
+  const valid = ajv.validate(schemaBody, data);
+  if (valid) {
+    return { valid: true, errors: [], warnings: [] };
+  }
+  const errors = (ajv.errors ?? []).map((err) => {
+    const path = err.instancePath || "/";
+    return `${path}: ${err.message}`;
+  });
+  return { valid: false, errors, warnings: [] };
+}
+
+// cli/tokens.ts
+function toCss(data) {
+  var _a;
+  const lines = [];
+  if (!data.tokens) return ":root {}\n";
+  for (const [group, tokens] of Object.entries(data.tokens)) {
+    if (!tokens) continue;
+    for (const [name, token] of Object.entries(tokens)) {
+      const prefix = group === "colors" ? "" : `${group}-`;
+      const varName = `--${prefix}${name}`;
+      lines.push(`  ${varName}: ${token.$value};`);
+    }
+  }
+  const darkLines = [];
+  if (data.tokens.colors) {
+    for (const [name, token] of Object.entries(data.tokens.colors)) {
+      const dark = (_a = token.$extensions) == null ? void 0 : _a["dark"];
+      if (typeof dark === "string") {
+        darkLines.push(`  --${name}: ${dark};`);
+      }
+    }
+  }
+  let output = `:root {
+${lines.join("\n")}
+}
+`;
+  if (darkLines.length > 0) {
+    output += `
+.dark {
+${darkLines.join("\n")}
+}
+`;
+  }
+  return output;
+}
+function toTailwindCss(data) {
+  const lines = [];
+  if (!data.tokens) return '@import "tailwindcss";\n\n@theme {}\n';
+  if (data.tokens.colors) {
+    for (const [name, token] of Object.entries(data.tokens.colors)) {
+      lines.push(`  --color-${name}: ${token.$value};`);
+    }
+  }
+  if (data.tokens.typography) {
+    for (const [name, token] of Object.entries(data.tokens.typography)) {
+      lines.push(`  --font-${name}: ${token.$value};`);
+    }
+  }
+  if (data.tokens.spacing) {
+    for (const [name, token] of Object.entries(data.tokens.spacing)) {
+      lines.push(`  --spacing-${name}: ${token.$value};`);
+    }
+  }
+  if (data.tokens.radius) {
+    for (const [name, token] of Object.entries(data.tokens.radius)) {
+      lines.push(`  --radius-${name}: ${token.$value};`);
+    }
+  }
+  return `@import "tailwindcss";
+
+@theme {
+${lines.join("\n")}
+}
+`;
+}
+function toFigmaTokens(data) {
+  if (!data.tokens) return JSON.stringify({}, null, 2);
+  const output = {};
+  for (const [group, tokens] of Object.entries(data.tokens)) {
+    if (!tokens) continue;
+    output[group] = {};
+    for (const [name, token] of Object.entries(tokens)) {
+      output[group][name] = {
+        value: token.$value,
+        type: token.$type ?? group,
+        ...token.$description && { description: token.$description }
+      };
+    }
+  }
+  return JSON.stringify(output, null, 2) + "\n";
+}
+function toStyleDictionary(data) {
+  const tokenFile = {};
+  if (data.tokens) {
+    for (const [group, tokens2] of Object.entries(data.tokens)) {
+      if (!tokens2) continue;
+      tokenFile[group] = {};
+      for (const [name, token] of Object.entries(tokens2)) {
+        tokenFile[group][name] = {
+          $value: token.$value,
+          $type: token.$type ?? group,
+          ...token.$description && { $description: token.$description }
+        };
+      }
+    }
+  }
+  const tokens = JSON.stringify(tokenFile, null, 2) + "\n";
+  const brandName = data.meta.name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  const config = {
+    source: ["tokens.json"],
+    usesDtcg: true,
+    platforms: {
+      css: {
+        transformGroup: "css",
+        buildPath: `build/css/`,
+        files: [
+          {
+            destination: "variables.css",
+            format: "css/variables",
+            options: { outputReferences: true }
+          }
+        ]
+      },
+      scss: {
+        transformGroup: "scss",
+        buildPath: `build/scss/`,
+        files: [
+          {
+            destination: "_variables.scss",
+            format: "scss/variables",
+            options: { outputReferences: true }
+          }
+        ]
+      },
+      ios: {
+        transformGroup: "ios-swift",
+        buildPath: `build/ios/`,
+        files: [
+          {
+            destination: `${brandName}.swift`,
+            format: "ios-swift/class.swift",
+            className: data.meta.name.replace(/[^a-zA-Z0-9]/g, "")
+          }
+        ]
+      },
+      android: {
+        transformGroup: "android",
+        buildPath: `build/android/`,
+        files: [
+          {
+            destination: "colors.xml",
+            format: "android/resources",
+            filter: { $type: "color" }
+          },
+          {
+            destination: "dimens.xml",
+            format: "android/resources",
+            filter: { $type: "dimension" }
+          }
+        ]
+      }
+    }
+  };
+  return { tokens, config: JSON.stringify(config, null, 2) + "\n" };
+}
+function flattenTokens(data) {
+  const result = [];
+  if (!data.tokens) return result;
+  for (const [group, tokens] of Object.entries(data.tokens)) {
+    if (!tokens) continue;
+    for (const [name, token] of Object.entries(tokens)) {
+      result.push({ group, name, token });
+    }
+  }
+  return result;
+}
+
+// cli/remote.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { resolve, dirname, join } from "path";
+import { homedir } from "os";
+var API_BASE = process.env.BRANDSPEC_API_URL ?? "https://brandspec.tools";
+function getCredentialsPath() {
+  return join(homedir(), ".config", "brandspec", "credentials");
+}
+function loadToken() {
+  const envToken = process.env.BRANDSPEC_TOKEN;
+  if (envToken) return envToken;
+  const credPath = getCredentialsPath();
+  if (existsSync(credPath)) {
+    const content = readFileSync(credPath, "utf-8").trim();
+    if (content) return content;
+  }
+  return null;
+}
+function parseOrgBrand(str) {
+  const parts = str.split("/");
+  if (parts.length !== 2) return null;
+  const [org, brand] = parts;
+  const slugRe = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+  if (!slugRe.test(org) || !slugRe.test(brand)) return null;
+  return { org, brand };
+}
+function loadRemote(args) {
+  const positional = args.find((a) => !a.startsWith("-") && a.includes("/"));
+  if (positional) return parseOrgBrand(positional);
+  const rcPath = resolve(".brandspecrc");
+  if (existsSync(rcPath)) {
+    const content = readFileSync(rcPath, "utf-8");
+    const match = content.match(/remote:\s*(.+)/);
+    if (match) return parseOrgBrand(match[1].trim());
+  }
+  return null;
+}
+function ensureBrandspecrc(org, brand) {
+  const rcPath = resolve(".brandspecrc");
+  if (!existsSync(rcPath)) {
+    writeFileSync(rcPath, `remote: ${org}/${brand}
+`, "utf-8");
+  }
+}
+function saveCredentials(token) {
+  const credPath = getCredentialsPath();
+  mkdirSync(dirname(credPath), { recursive: true });
+  writeFileSync(credPath, token, { mode: 384 });
+}
+
+// cli/color.ts
+function parseColor(color) {
+  const hex = color.match(/^#([0-9a-f]{3,8})$/i);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+    return [
+      parseInt(h.slice(0, 2), 16),
+      parseInt(h.slice(2, 4), 16),
+      parseInt(h.slice(4, 6), 16)
+    ];
+  }
+  const rgb = color.match(/^rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)/);
+  if (rgb) {
+    return [parseInt(rgb[1]), parseInt(rgb[2]), parseInt(rgb[3])];
+  }
+  const oklch = color.match(
+    /oklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)/
+  );
+  if (oklch) {
+    const L = oklch[2] === "%" ? parseFloat(oklch[1]) / 100 : parseFloat(oklch[1]);
+    const C = parseFloat(oklch[3]);
+    const H = parseFloat(oklch[4]);
+    return oklchToSrgb(L, C, H);
+  }
+  return null;
+}
+function oklchToSrgb(L, C, H) {
+  const hRad = H * Math.PI / 180;
+  const a = C * Math.cos(hRad);
+  const b = C * Math.sin(hRad);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  const rl = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const gl = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const bl = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+  const gamma = (x) => x <= 31308e-7 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
+  const clamp = (x) => Math.max(0, Math.min(255, Math.round(x * 255)));
+  return [clamp(gamma(rl)), clamp(gamma(gl)), clamp(gamma(bl))];
+}
+function relativeLuminance(r, g, b) {
+  const [rs, gs, bs] = [r, g, b].map((c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+function getContrastRatio(color1, color2) {
+  const c1 = parseColor(color1);
+  const c2 = parseColor(color2);
+  if (!c1 || !c2) return 21;
+  const l1 = relativeLuminance(...c1);
+  const l2 = relativeLuminance(...c2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function findColorValue(colors, name) {
+  const token = colors[name];
+  if (isToken(token)) return token.$value;
+  if (typeof token === "object" && token !== null) {
+    const nested = token;
+    if (isToken(nested)) return nested.$value;
+  }
+  return null;
+}
+function isToken(v) {
+  return typeof v === "object" && v !== null && "$value" in v;
+}
+
+// cli/lint.ts
+var requiredFields = (spec) => {
+  const results = [];
+  if (!spec.meta.version) {
+    results.push({
+      rule: "meta/version-required",
+      severity: "warning",
+      message: "meta.version is recommended for tracking changes",
+      path: "meta.version"
+    });
+  }
+  if (!spec.core) {
+    results.push({
+      rule: "core/missing",
+      severity: "warning",
+      message: "core section is missing \u2014 brand identity is undefined",
+      path: "core"
+    });
+  } else {
+    if (!spec.core.essence && !spec.core.tagline) {
+      results.push({
+        rule: "core/identity-missing",
+        severity: "warning",
+        message: "Neither essence nor tagline is defined",
+        path: "core"
+      });
+    }
+    if (!spec.core.personality || spec.core.personality.length === 0) {
+      results.push({
+        rule: "core/personality-empty",
+        severity: "info",
+        message: "No personality traits defined",
+        path: "core.personality"
+      });
+    }
+    if (!spec.core.voice) {
+      results.push({
+        rule: "core/voice-missing",
+        severity: "info",
+        message: "Voice guidelines not defined",
+        path: "core.voice"
+      });
+    }
+  }
+  if (!spec.tokens) {
+    results.push({
+      rule: "tokens/missing",
+      severity: "warning",
+      message: "No design tokens defined",
+      path: "tokens"
+    });
+  } else {
+    if (!spec.tokens.colors || Object.keys(spec.tokens.colors).length === 0) {
+      results.push({
+        rule: "tokens/colors-empty",
+        severity: "warning",
+        message: "No color tokens defined",
+        path: "tokens.colors"
+      });
+    }
+    if (!spec.tokens.typography || Object.keys(spec.tokens.typography).length === 0) {
+      results.push({
+        rule: "tokens/typography-empty",
+        severity: "info",
+        message: "No typography tokens defined",
+        path: "tokens.typography"
+      });
+    }
+  }
+  return results;
+};
+var colorContrast = (spec) => {
+  var _a;
+  const results = [];
+  const colors = (_a = spec.tokens) == null ? void 0 : _a.colors;
+  if (!colors) return results;
+  const bg = findColorValue(colors, "background");
+  const fg = findColorValue(colors, "foreground");
+  if (bg && fg) {
+    const ratio = getContrastRatio(bg, fg);
+    if (ratio < 4.5) {
+      results.push({
+        rule: "contrast/bg-fg-aa",
+        severity: "error",
+        message: `Background/foreground contrast ratio is ${ratio.toFixed(1)}:1 (WCAG AA requires 4.5:1)`,
+        path: "tokens.colors"
+      });
+    } else if (ratio < 7) {
+      results.push({
+        rule: "contrast/bg-fg-aaa",
+        severity: "info",
+        message: `Background/foreground contrast ratio is ${ratio.toFixed(1)}:1 (WCAG AAA requires 7:1)`,
+        path: "tokens.colors"
+      });
+    }
+  }
+  const primary = findColorValue(colors, "primary");
+  if (primary && bg) {
+    const ratio = getContrastRatio(bg, primary);
+    if (ratio < 3) {
+      results.push({
+        rule: "contrast/primary-bg",
+        severity: "warning",
+        message: `Primary on background contrast ratio is ${ratio.toFixed(1)}:1 (minimum 3:1 for large text)`,
+        path: "tokens.colors.primary"
+      });
+    }
+  }
+  return results;
+};
+var ASSET_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+)+$/;
+var assetNaming = (spec) => {
+  const results = [];
+  if (!spec.assets) return results;
+  for (const asset of spec.assets) {
+    const fileName = asset.file.split("/").pop() ?? asset.file;
+    if (!ASSET_PATTERN.test(fileName)) {
+      results.push({
+        rule: "assets/naming-convention",
+        severity: "warning",
+        message: `Asset "${asset.file}" doesn't follow {role}-{variant}.{ext} naming convention`,
+        path: "assets"
+      });
+    }
+    if (!asset.role) {
+      results.push({
+        rule: "assets/role-missing",
+        severity: "info",
+        message: `Asset "${asset.file}" has no role defined`,
+        path: "assets"
+      });
+    }
+  }
+  return results;
+};
+var KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+var tokenNaming = (spec) => {
+  const results = [];
+  if (!spec.tokens) return results;
+  for (const [group, tokens] of Object.entries(spec.tokens)) {
+    if (!tokens || typeof tokens !== "object") continue;
+    for (const name of Object.keys(tokens)) {
+      if (name.startsWith("$")) continue;
+      if (!KEBAB_CASE.test(name)) {
+        results.push({
+          rule: "tokens/naming-kebab",
+          severity: "info",
+          message: `Token "${group}.${name}" should use kebab-case`,
+          path: `tokens.${group}.${name}`
+        });
+      }
+    }
+  }
+  return results;
+};
+var essentialColors = (spec) => {
+  var _a;
+  const results = [];
+  const colors = (_a = spec.tokens) == null ? void 0 : _a.colors;
+  if (!colors) return results;
+  const essential = ["primary", "background", "foreground"];
+  for (const name of essential) {
+    if (!findColorValue(colors, name)) {
+      results.push({
+        rule: "tokens/essential-color",
+        severity: "warning",
+        message: `Essential color token "${name}" is missing`,
+        path: `tokens.colors.${name}`
+      });
+    }
+  }
+  return results;
+};
+var ALL_RULES = [
+  requiredFields,
+  colorContrast,
+  assetNaming,
+  tokenNaming,
+  essentialColors
+];
+function lintBrandspec(spec) {
+  const results = ALL_RULES.flatMap((rule) => rule(spec));
+  const errors = results.filter((r) => r.severity === "error").length;
+  const warnings = results.filter((r) => r.severity === "warning").length;
+  const infos = results.filter((r) => r.severity === "info").length;
+  const score = Math.max(
+    0,
+    Math.min(100, 100 - errors * 10 - warnings * 3 - infos)
+  );
+  return { score, results, errors, warnings, infos };
+}
+export {
+  API_BASE,
+  ensureBrandspecrc,
+  flattenTokens,
+  getContrastRatio,
+  getCredentialsPath,
+  lintBrandspec,
+  loadRemote,
+  loadToken,
+  parse,
+  parseColor,
+  parseOrgBrand,
+  saveCredentials,
+  schema,
+  serialize,
+  toCss,
+  toFigmaTokens,
+  toStyleDictionary,
+  toTailwindCss,
+  validate
+};