@madgex/fert 7.0.14 → 7.1.0

package/bin/cli.js

@@ -10,6 +10,7 @@ import { printBanner } from './utils/index.js';
 import { serviceCommandBootstrap } from './commands/_service-command-bootstrap.js';
 import { configsCommand } from './commands/configs.js';
 import { initCommand } from './commands/init.js';
+import { validateCommand } from './commands/validate.js';
 
 const cli = cac('fert');
 
@@ -56,6 +57,8 @@ const run = () => {
     .option('--cpid <cpid>', 'Specify the clientPropertyId to use in the new project')
     .action((...args) => initCommand(...args));
 
+  cli.command('validate', 'Validate branding project for common issues').action((...args) => validateCommand(...args));
+
   cli.option('--no-cache', 'Do not use cache');
   cli.option('--purge-cache', 'Purge all caches');
   cli.help();

package/bin/commands/build.js

@@ -6,6 +6,10 @@ import { bundleEntry } from './build-tasks/bundle-entry.js';
 import { buildCssFromTokens } from './build-tasks/build-tokens.js';
 import { buildExternalAssets } from './build-tasks/build-external-assets.js';
 import { validateLocalConfigs } from '../utils/configs.js';
+import { runValidators, reportResults } from '../utils/validation-helpers.js';
+import * as brandJsonValidator from '../validators/brand-json-validator.js';
+
+const validators = [brandJsonValidator];
 
 export { bundleEntry, buildExternalAssets };
 
@@ -22,6 +26,15 @@ export async function build(options = {}) {
     clientPropertyId: fertConfig.clientPropertyId,
   });
 
+  const validationResults = await runValidators(validators, {
+    rootDir: fertConfig.rootDir,
+    options,
+  });
+  const validationExitCode = reportResults(validationResults, fertConfig.rootDir);
+  if (validationExitCode !== 0) {
+    throw new Error('Build aborted due to validation errors');
+  }
+
   if (!options.only) {
     await rimraf(path.resolve(fertConfig.workingDir, 'dist'));
     await buildTokens(fertConfig, options);

package/bin/commands/dev-server.js

@@ -6,9 +6,11 @@ import open from 'open';
 import chokidar from 'chokidar5';
 import { resolveConfig, findFertConfigDir } from '../utils/index.js';
 import { validateLocalConfigs } from '../utils/configs.js';
+import { runValidators, reportResults } from '../utils/validation-helpers.js';
 import { devServer } from '../../server/server.js';
 import { buildTokens, buildExternalAssets } from './build.js';
 import { BRAND_JSON_FILENAME, FERT_CONFIG_FILENAME, FERT_SERVICE_CONFIG_FILENAME } from '../../constants.js';
+import * as brandJsonValidator from '../validators/brand-json-validator.js';
 
 export async function createDevServer(options = {}) {
   let fertConfig = await resolveConfig(options);
@@ -43,6 +45,9 @@ export async function createDevServer(options = {}) {
 
   chokidar.watch(brandPath, { ignoreInitial: true }).on('all', async () => {
     await buildTokens(fertConfig);
+
+    const results = await runValidators([brandJsonValidator], { rootDir: fertConfig.rootDir, options });
+    reportResults(results, rootDir);
   });
 
   const configPath = path.resolve(fertConfigDir, FERT_CONFIG_FILENAME);

package/bin/commands/validate.js

@@ -0,0 +1,27 @@
+import { findFertConfigDir } from '../utils/index.js';
+import { runValidators, reportResults } from '../utils/validation-helpers.js';
+import { log } from '../utils/logging.js';
+
+// Register all validators here
+import * as brandJsonValidator from '../validators/brand-json-validator.js';
+
+const validators = [brandJsonValidator];
+
+export async function validateCommand(options) {
+  log.info('Running validations…\n');
+
+  const rootDir = await findFertConfigDir();
+
+  const context = {
+    rootDir,
+    options,
+  };
+
+  const results = await runValidators(validators, context);
+  const exitCode = reportResults(results, rootDir);
+
+  if (exitCode !== 0) {
+    // eslint-disable-next-line n/no-process-exit
+    process.exit(exitCode);
+  }
+}

package/bin/utils/validation-helpers.js

@@ -0,0 +1,87 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { log } from './logging.js';
+
+export const Severity = Object.freeze({
+  ERROR: 'ERROR',
+  WARNING: 'WARNING',
+});
+
+/**
+ * Creates a validation result entry.
+ */
+export function createResult(severity, message, { filePath, detail } = {}) {
+  return { severity, message, filePath, detail };
+}
+
+/**
+ * Runs an array of validator functions and collects all results.
+ * Each validator receives `context` and must return an array of result objects.
+ */
+export async function runValidators(validators, context) {
+  const results = [];
+
+  for (const validator of validators) {
+    const validatorResults = await validator.validate(context);
+    results.push(...validatorResults);
+  }
+
+  return results;
+}
+
+/**
+ * Prints validation results — errors first, then warnings grouped by file.
+ * Paths are shown relative to rootDir.
+ * Returns 1 if any ERROR results exist, 0 otherwise.
+ */
+export function reportResults(results, rootDir = process.cwd()) {
+  const errors = results.filter((r) => r.severity === Severity.ERROR);
+  const warnings = results.filter((r) => r.severity === Severity.WARNING);
+
+  if (errors.length) {
+    console.log(chalk.red.bold(`\n✖  ${errors.length} error${errors.length === 1 ? '' : 's'}\n`));
+    printGrouped(groupByFile(errors), rootDir, Severity.ERROR);
+  }
+
+  if (warnings.length) {
+    console.log(chalk.yellow.bold(`\n⚠  ${warnings.length} warning${warnings.length === 1 ? '' : 's'}\n`));
+    printGrouped(groupByFile(warnings), rootDir, Severity.WARNING);
+  }
+
+  if (!errors.length && !warnings.length) {
+    log.success('All validations passed');
+  }
+
+  console.log('');
+
+  return errors.length > 0 ? 1 : 0;
+}
+
+function groupByFile(results) {
+  const groups = new Map();
+  for (const result of results) {
+    const key = result.filePath ?? null;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(result);
+  }
+  return groups;
+}
+
+function printGrouped(groups, rootDir, severity) {
+  const color = severity === Severity.ERROR ? chalk.red : chalk.yellow;
+  const symbol = severity === Severity.ERROR ? '✖' : '⚠';
+
+  for (const [filePath, items] of groups) {
+    if (filePath) {
+      console.log(chalk.dim(`  ${path.relative(rootDir, filePath)}`));
+    }
+    for (const item of items) {
+      const indent = filePath ? '    ' : '  ';
+      console.log(color.bold(symbol), `${indent}${item.message}`);
+      if (item.detail) {
+        console.log(chalk.dim(`  ${indent}${item.detail}`));
+      }
+    }
+    console.log('');
+  }
+}

package/bin/validators/brand-json-validator.js

@@ -0,0 +1,160 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { createStyleDictionary } from '@madgex/design-system/style-dictionary';
+// eslint-disable-next-line n/no-extraneous-import
+import { resolveReferences } from 'style-dictionary/utils';
+import { loadServiceConfigFiles } from '../utils/index.js';
+import { Severity, createResult } from '../utils/validation-helpers.js';
+import { BRAND_JSON_FILENAME } from '../../constants.js';
+
+export const name = 'brand-json';
+export const description = 'Validates brand.json overrides against the MDS base token schema';
+
+/**
+ * Recursively extracts all dot-separated token paths from a token object.
+ * Stops at `$value` leaves and skips `$`-prefixed metadata keys.
+ */
+export function extractTokenPaths(obj, prefix = '') {
+  const paths = new Set();
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+
+    const currentPath = prefix ? `${prefix}.${key}` : key;
+
+    if (value && typeof value === 'object' && !('$value' in value)) {
+      const childPaths = extractTokenPaths(value, currentPath);
+      if (childPaths.size > 0) {
+        for (const childPath of childPaths) {
+          paths.add(childPath);
+        }
+      } else {
+        // Empty group — emit the path itself so it can be validated against the schema
+        paths.add(currentPath);
+      }
+    } else {
+      paths.add(currentPath);
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Recursively resolves a token `$value` through any `{references}` to a final scalar.
+ */
+export function resolveToFinalValue(rawValue, tokens) {
+  if (typeof rawValue !== 'string' || !rawValue.includes('{')) return rawValue;
+  const resolved = resolveReferences(rawValue, tokens, { usesDtcg: true});
+  if (resolved) {
+    return resolveToFinalValue(resolved, tokens);
+  }
+  return resolved;
+}
+
+/**
+ * Walks a nested object by dot-separated path and returns the `$value` at that leaf.
+ */
+export function getValueAtPath(obj, dotPath) {
+  let current = obj;
+  for (const part of dotPath.split('.')) {
+    if (!current || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current?.$value;
+}
+
+/**
+ * Loads all MDS base tokens via StyleDictionary and returns the set of valid
+ * token paths, their resolved values, and the tokens tree for reference resolution.
+ */
+async function loadBaseSchema() {
+  const { styleDictionary, cleanTempFiles } = await createStyleDictionary();
+  const basePaths = new Set();
+  const baseResolvedValues = new Map();
+
+  for (const token of styleDictionary.allTokens) {
+    const tokenPath = token.key.slice(1, -1);
+    basePaths.add(tokenPath);
+    baseResolvedValues.set(tokenPath, resolveToFinalValue(token.$value, styleDictionary.tokens));
+  }
+
+  const baseTokens = styleDictionary.tokens;
+  await cleanTempFiles();
+  return { basePaths, baseResolvedValues, baseTokens };
+}
+
+export async function validate() {
+  const results = [];
+  const { basePaths, baseResolvedValues, baseTokens } = await loadBaseSchema();
+
+  let serviceConfigs;
+  try {
+    serviceConfigs = await loadServiceConfigFiles();
+  } catch {
+    results.push(
+      createResult(Severity.WARNING, 'Could not discover services — skipping brand.json validation', {
+        detail: 'Ensure you are running from a branding repo with a fert.config.js',
+      }),
+    );
+    return results;
+  }
+
+  for (const { dir } of serviceConfigs) {
+    const brandJsonPath = path.join(dir, BRAND_JSON_FILENAME);
+
+    if (!fs.existsSync(brandJsonPath)) {
+      results.push(
+        createResult(Severity.WARNING, `Missing ${BRAND_JSON_FILENAME}`, {
+          filePath: brandJsonPath,
+          detail: 'Each service should have a brand.json for token overrides',
+        }),
+      );
+      continue;
+    }
+
+    let brandData;
+    try {
+      brandData = JSON.parse(fs.readFileSync(brandJsonPath, 'utf-8'));
+    } catch (err) {
+      results.push(
+        createResult(Severity.ERROR, `Invalid JSON in ${BRAND_JSON_FILENAME}`, {
+          filePath: brandJsonPath,
+          detail: err.message,
+        }),
+      );
+      continue;
+    }
+
+    const overridePaths = extractTokenPaths(brandData);
+
+    for (const overridePath of overridePaths) {
+      if (!basePaths.has(overridePath)) {
+        results.push(
+          createResult(Severity.WARNING, `Unknown token path: "${overridePath}"`, {
+            filePath: brandJsonPath,
+            detail: 'This path does not exist in the MDS base schema and will have no effect',
+          }),
+        );
+        continue;
+      }
+
+      const rawOverrideValue = getValueAtPath(brandData, overridePath);
+      if (rawOverrideValue === undefined) continue;
+
+      const resolvedOverride = resolveToFinalValue(rawOverrideValue, baseTokens);
+      const resolvedBase = baseResolvedValues.get(overridePath);
+
+      if (resolvedOverride === resolvedBase) {
+        results.push(
+          createResult(Severity.WARNING, `Redundant override: "${overridePath}"`, {
+            filePath: brandJsonPath,
+            detail: `Value "${String(rawOverrideValue)}" resolves to the same value as the MDS base ("${String(resolvedBase)}")`,
+          }),
+        );
+      }
+    }
+  }
+
+  return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madgex/fert",
-  "version": "7.0.14",
+  "version": "7.1.0",
   "description": "Tool to help build the V6 branding",
   "bin": {
     "fert": "./bin/cli.js"