@madgex/fert 7.1.1 → 7.2.0

package/bin/cli.js

@@ -11,6 +11,7 @@ import { serviceCommandBootstrap } from './commands/_service-command-bootstrap.j
 import { configsCommand } from './commands/configs.js';
 import { initCommand } from './commands/init.js';
 import { validateCommand } from './commands/validate.js';
+import { rootTasksBootstrap } from './commands/_root-tasks-bootstrap.js';
 
 const cli = cac('fert');
 
@@ -24,7 +25,10 @@ const run = () => {
     .option('--host [host]', '[string] specify hostname')
     .option('--port <port>', '[number] specify port')
     .option('--service-name <serviceName>', '[string] run a single service')
-    .action((...args) => serviceCommandBootstrap('dev', ...args));
+    .action(async (...args) => {
+      await rootTasksBootstrap('dev', ...args);
+      await serviceCommandBootstrap('dev', ...args);
+    });
 
   cli
     .command('build', 'Build project. Can supply a branding directory if running FERT standalone')
@@ -32,14 +36,20 @@ const run = () => {
     .option('--config [dir]', 'Use custom rollup config file')
     .option('--target <env>', 'Environment to build for, "dev" or "production"')
     .option('--service-name <serviceName>', '[string] run a single service')
-    .action((...args) => serviceCommandBootstrap('build', ...args));
+    .action(async (...args) => {
+      await rootTasksBootstrap('build', ...args);
+      await serviceCommandBootstrap('build', ...args);
+    });
 
   cli
     .command('publish', 'Publish the project')
     .option('--target <env>', 'Environment to publish to, "dev" or "production"')
     .option('--service-name <serviceName>', '[string] run a single service')
     .option('--dry-run', 'Dry run, dont actually upload anything')
-    .action((...args) => serviceCommandBootstrap('publish', ...args));
+    .action(async (...args) => {
+      await rootTasksBootstrap('publish', ...args);
+      await serviceCommandBootstrap('publish', ...args);
+    });
 
   cli
     .command('configs', 'Query/Publish project configs')

package/bin/commands/_root-tasks-bootstrap.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import chokidar from 'chokidar5';
+import { validateLocalConfigs } from '../utils/configs.js';
+import { findFertConfigDir, loadConfigFromFile } from '../utils/index.js';
+
+/**
+ * Tasks to run against the root directory of a Branding repo (not a service folder).
+ *
+ * These are run once on a cli command
+ *
+ * @param {"dev"|"build"|"publish"} command
+ * @param {*} options
+ * @returns
+ */
+export async function rootTasksBootstrap(command /* , options */) {
+  const rootDir = await findFertConfigDir();
+  const configFromFile = await loadConfigFromFile({ dir: rootDir });
+
+  if (command === 'dev') {
+    await validateLocalConfigs({
+      workingDir: rootDir,
+      clientPropertyId: configFromFile.clientPropertyId,
+      throwable: false,
+    });
+    // watch local configs - revalidate on change
+
+    const configPaths = await Array.fromAsync(fs.promises.glob(path.resolve(rootDir, './config/*.json')));
+    chokidar.watch(configPaths, { ignoreInitial: true }).on('all', async () => {
+      await validateLocalConfigs({
+        workingDir: rootDir,
+        clientPropertyId: configFromFile.clientPropertyId,
+        throwable: false,
+      });
+    });
+    return;
+  }
+
+  if (command === 'build') {
+    await validateLocalConfigs({
+      workingDir: rootDir,
+      clientPropertyId: configFromFile.clientPropertyId,
+    });
+  }
+}

package/bin/commands/_service-command-bootstrap.js

@@ -15,6 +15,10 @@ const commandMap = {
 /**
  * determine if we are running a single service, otherwise search for all services
  * Then run command
+ *
+ * @param {"dev"|"build"|"publish"} command
+ * @param {*} options
+ * @returns
  */
 export async function serviceCommandBootstrap(command, options) {
   // explicitly run a single service - via CLI option
@@ -64,9 +68,12 @@ export async function serviceCommandBootstrap(command, options) {
         serviceName: serviceConfig.serviceName,
       });
     } catch (err) {
-      throw new Error(`Failed to run command ${command} on service ${serviceConfig.serviceName}: ${err.message}`, {
-        cause: err,
-      });
+      throw new Error(
+        `Failed to run command ${chalk.green(command)} on service ${chalk.green(serviceConfig.serviceName)}: ${chalk.red(err.message)}`,
+        {
+          cause: err,
+        },
+      );
     }
   }
 }

package/bin/commands/build.js

@@ -5,14 +5,15 @@ import { log } from '../utils/logging.js';
 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];
+import * as validation from '../utils/validation.js';
 
 export { bundleEntry, buildExternalAssets };
 
+/**
+ * Service-level task
+ * @param {*} options
+ * @returns
+ */
 export async function build(options = {}) {
   const fertConfig = await resolveConfig(options);
   const validTargets = ['dev', 'production'];
@@ -21,19 +22,7 @@ export async function build(options = {}) {
     throw Error(`Missing or invalid --target option. Choose from [${validTargets}]`);
   }
 
-  await validateLocalConfigs({
-    workingDir: fertConfig.rootDir,
-    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');
-  }
+  await validation.runServiceValidators(['brand-json', 'translations'], { fertConfig, throwable: true });
 
   if (!options.only) {
     await rimraf(path.resolve(fertConfig.workingDir, 'dist'));

package/bin/commands/dev-server.js

@@ -1,17 +1,24 @@
 import path from 'node:path';
-// eslint-disable-next-line n/no-unsupported-features/node-builtins
-import { glob } from 'node:fs/promises';
+
 import chalk from 'chalk';
 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 { resolveConfig } from '../utils/index.js';
+import * as validation from '../utils/validation.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';
+import {
+  BRAND_JSON_FILENAME,
+  FERT_CONFIG_FILENAME,
+  FERT_SERVICE_CONFIG_FILENAME,
+  SERVICE_TRANSLATIONS_FILEPATH,
+} from '../../constants.js';
 
+/**
+ * Service-level task
+ * @param {*} options
+ * @returns
+ */
 export async function createDevServer(options = {}) {
   let fertConfig = await resolveConfig(options);
 
@@ -21,36 +28,24 @@ export async function createDevServer(options = {}) {
     )}\n`,
   );
 
-  await validateLocalConfigs({
-    workingDir: fertConfig.rootDir,
-    clientPropertyId: fertConfig.clientPropertyId,
-    throwable: false,
-  });
-  await buildTokens(fertConfig);
-
-  const fertConfigDir = await findFertConfigDir();
-
-  // watch local configs - revalidate on change
-  const configPaths = await Array.fromAsync(glob(path.resolve(fertConfigDir, './config/*.json')));
-  chokidar.watch(configPaths, { ignoreInitial: true }).on('all', async () => {
-    await validateLocalConfigs({
-      workingDir: fertConfig.rootDir,
-      clientPropertyId: fertConfig.clientPropertyId,
-      throwable: false,
-    });
-  });
-
-  // watch brand.json & fert.config.js - refresh on change
+  // validation
   const brandPath = path.resolve(fertConfig.workingDir, BRAND_JSON_FILENAME);
+  const translationPath = path.resolve(fertConfig.workingDir, SERVICE_TRANSLATIONS_FILEPATH);
+  // watch brand.json & translation.json - re-validate
+  chokidar.watch([brandPath, translationPath], { ignoreInitial: true }).on('all', async () => {
+    await validation.runServiceValidators(['brand-json', 'translations'], { fertConfig });
+  });
+  // initial validation run
+  await validation.runServiceValidators(['brand-json', 'translations'], { fertConfig });
 
-  chokidar.watch(brandPath, { ignoreInitial: true }).on('all', async () => {
+  // building tokens
+  await buildTokens(fertConfig);
+  // rebuild tokens for brand json update
+  chokidar.watch([brandPath]).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);
+  const configPath = path.resolve(fertConfig.rootDir, FERT_CONFIG_FILENAME);
   const serviceConfigPath = path.resolve(fertConfig.workingDir, FERT_SERVICE_CONFIG_FILENAME);
   chokidar.watch([configPath, serviceConfigPath]).on('change', async () => {
     console.log('Config changed, reloading…');
@@ -68,7 +63,8 @@ export async function createDevServer(options = {}) {
   // start server
 
   /**
-   * having a port number to start with helps keep the ports changing too much in development
+   * having a port number to start with helps keep the ports changing too much in development.
+   * This is the exception to the rule, do not create map-like objects for hardcoded service names.
    */
   const STARTING_PORT_FOR_SERVICE_FOR_CONVENIENCE = {
     'jobseekers-frontend': 4001,

package/bin/commands/publish.js

@@ -17,6 +17,11 @@ import {
   ASSET_STORE_INVALIDATION_PATH,
 } from '../../constants.js';
 
+/**
+ * Service-level task
+ * @param {*} options
+ * @returns
+ */
 export async function publish(options) {
   const fertConfig = await resolveConfig(options);
   const validTargets = ['dev', 'prod', 'production'];

package/bin/commands/validate.js

@@ -1,27 +1,23 @@
-import { findFertConfigDir } from '../utils/index.js';
-import { runValidators, reportResults } from '../utils/validation-helpers.js';
+import { loadServiceConfigFiles, resolveConfig } from '../utils/index.js';
+import * as validation from '../utils/validation.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) {
+/**
+ * root-level task
+ * @param {*} options
+ * @returns
+ */
+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);
+  const serviceConfigs = await loadServiceConfigFiles();
+  // run validators for each service
+  for (const { serviceConfig } of serviceConfigs) {
+    const fertConfig = await resolveConfig({ serviceName: serviceConfig.serviceName });
 
-  if (exitCode !== 0) {
-    // eslint-disable-next-line n/no-process-exit
-    process.exit(exitCode);
+    await validation.runServiceValidators(['brand-json', 'translations'], {
+      fertConfig,
+      throwable: true,
+    });
   }
 }

package/bin/utils/cpid-lookup.js

@@ -6,7 +6,7 @@ import { PersistentCacheWithTtl } from './persistent-cache-with-ttl.js';
 const cache = new PersistentCacheWithTtl('cpid-cache', {
   ttl: ONE_WEEK,
 });
-
+/** @return {Promise<Client>} */
 export async function doCpidLookup(clientPropertyId) {
   const API_URL = new URL(clientPropertyId, PROPERTY_ID_API).toString();
   try {
@@ -33,7 +33,7 @@ export async function doCpidLookup(clientPropertyId) {
     throw error;
   }
 }
-
+/** @return {Promise<Client>} */
 export async function cpidLookup(clientPropertyId, options = {}) {
   if (options.purgeCache) {
     cache.purgeCacheFile();

package/bin/utils/index.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { pathToFileURL } from 'node:url';
-// eslint-disable-next-line n/no-unsupported-features/node-builtins
+
 import { glob } from 'node:fs/promises';
 import { findUp } from 'find-up-simple';
 import chalk from 'chalk';
@@ -18,13 +18,20 @@ export function printBanner() {
   console.log(`\n${chalk.green.bold('Fert')} v${VERSION}`);
 }
 
-export async function getConfig(cpid, configNames = []) {
+/**
+ * get a config values from `clientconfig` from config-api
+ *
+ * @param {string} cpid
+ * @param {Array<string>} configNames array of config keys to fetch from clientconfig
+ * @returns
+ */
+export async function getClientConfig(cpid, configNames = []) {
   Hoek.assert(Array.isArray(configNames), 'configNames must be an array');
 
   const result = {};
 
   for (let config of configNames) {
-    const url = CONFIG_API.replace('{cpid}', cpid).replace('{config}', config);
+    const url = CONFIG_API.replace('{configGroup}', 'clientconfig').replace('{cpid}', cpid).replace('{config}', config);
     const { data } = await fetch(url).then((response) => response.json());
     const { value } = data?.[0] || {};
 
@@ -89,7 +96,7 @@ export async function resolveConfig(options = {}) {
 
   fertConfig.externalAssets = resolveExternalAssets(fertConfig.externalAssets);
 
-  fertConfig.config = await getConfig(fertConfig.clientPropertyId, ['JobseekerSiteWebSitePath', 'SiteName']);
+  fertConfig.config = await getClientConfig(fertConfig.clientPropertyId, ['JobseekerSiteWebSitePath', 'SiteName']);
 
   return {
     ...fertConfig,
@@ -117,7 +124,7 @@ export async function findFertConfigDir() {
 /**
  * find and load all service config files, return config and location
  * @param {string} root directory path
- * @returns
+ * @returns {Array<{dir:string, serviceConfig:FertServiceConfigFile}>}
  */
 export async function loadServiceConfigFiles() {
   const rootDir = await findFertConfigDir();
@@ -141,6 +148,14 @@ export async function loadServiceConfigFiles() {
   return serviceConfigs;
 }
 
+/**
+ * load FERT JSON file from a directory, optionally specifying the config files name.
+ * @param {object} options
+ * @param {string} [options.dir] defaults to process.cwd()
+ * @param {string} options.filename default FERT_CONFIG_FILENAME, e.g. use `FERT_SERVICE_CONFIG_FILENAME` to load service-level config file
+ * @param {boolean} options.silent set to `true` to not throw if file cant be loaded
+ * @returns {FertConfigFile | FertServiceConfigFile} depending on filename provided
+ */
 export async function loadConfigFromFile({ dir = process.cwd(), filename = FERT_CONFIG_FILENAME, silent = false }) {
   const configPath = path.resolve(dir, filename);
   try {
@@ -166,7 +181,7 @@ export function ensureTrailingSlash(str) {
 
 export async function exists(_path) {
   try {
-    fs.access(_path);
+    await fs.promises.access(_path);
     return true;
   } catch {
     return false;

package/bin/utils/validation.js

@@ -0,0 +1,145 @@
+import chalk from 'chalk';
+import { log } from './logging.js';
+import * as validatorBrandJson from '../validators/brand-json.validator.js';
+import * as validatorTranslations from '../validators/translations.validator.js';
+
+/** @type {Array<Validator>} */
+const validators = [validatorBrandJson, validatorTranslations];
+
+/**
+ *
+ * Runs an array of validator functions and collects all results. This is targeting a service, and requires a fertConfig.
+ * Each validator receives `{fertConfig}` and must return an array of result objects.
+ *
+ * @param {Array<string>} validatorNames, array of strings matching name from validator js file. e.g. ['brand-json', 'translations']
+ * @param {object} options
+ * @param {FertConfig} options.fertConfig required
+ * @param {object} options.throwable to throw if validation has errors
+ * @returns {Array<ValidationResult>}
+ */
+export async function runServiceValidators(validatorNames = [], { fertConfig, throwable = false } = {}) {
+  const results = [];
+
+  for (const validator of validators) {
+    if (!validatorNames.includes(validator.name)) continue;
+    const validatorResults = await validator.validate({ fertConfig });
+    results.push(...validatorResults);
+  }
+  const validationExitCode = reportResults(results, fertConfig);
+  if (throwable && validationExitCode !== 0) {
+    throw new Error('Validation has errors');
+  }
+
+  return results;
+}
+/** @type {ValidationSeverity} */
+const Severity = Object.freeze({
+  ERROR: 'ERROR',
+  WARNING: 'WARNING',
+});
+
+/**
+ * @returns {ValidationResultCollection}
+ */
+export function createResultCollection() {
+  /** @type {Array<ValidationResult>} */
+  const results = [];
+  /** @type {ValidationResultCollection} */
+  return {
+    results,
+    /** add a result to results collection, and returns a builder to modify the results severity, filePath and detail */
+    addResult(message) {
+      /** @type {ValidationResult} */
+      const result = { severity: Severity.WARNING, message, filePath: undefined, detail: undefined };
+      results.push(result);
+      /** @type {ValidationResultBuilder} */
+      return {
+        /** set ValidationResult.severity to ERROR */
+        err() {
+          result.severity = Severity.ERROR;
+          return this;
+        },
+        /** set ValidationResult.filePath */
+        filePath(_filePath) {
+          result.filePath = _filePath;
+          return this;
+        },
+        /** set ValidationResult.filePath */
+        detail(_detail) {
+          result.detail = _detail;
+          return this;
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Prints validation results — errors first, then warnings grouped by file.
+ * Full paths are shown.
+ * Returns 1 if any ERROR results exist, 0 otherwise.
+ *
+ * @param {Array<ValidationResult>} results
+ * @param {FertConfig} fertConfig
+ * @returns {0|1}
+ */
+export function reportResults(results, fertConfig) {
+  const errors = results.filter((r) => r.severity === Severity.ERROR);
+  if (errors.length) {
+    console.log(chalk.red.bold(`\n✖  ${errors.length} error${errors.length === 1 ? '' : 's'}\n`));
+    logResults(errors);
+  }
+
+  const warnings = results.filter((r) => r.severity === Severity.WARNING);
+  if (warnings.length) {
+    console.log(chalk.yellow.bold(`\n⚠  ${warnings.length} warning${warnings.length === 1 ? '' : 's'}\n`));
+    logResults(warnings);
+  }
+
+  if (!errors.length && !warnings.length) {
+    log.success(`All validations passed for ${chalk.green(fertConfig.workingDir)}`);
+  } else {
+    log.warn(`all validations did not passed for ${chalk.yellow(fertConfig.workingDir)}`);
+  }
+
+  return errors.length > 0 ? 1 : 0;
+}
+
+/**
+ * Group errors by filePath
+ * @param {Array<ValidationResult>} results
+ * @returns {Map<string, Array<ValidationResult>>}
+ */
+function groupByFilePath(results) {
+  const groups = new Map();
+  for (const result of results) {
+    const key = result.filePath ?? 'no-file-path';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(result);
+  }
+  return groups;
+}
+
+/**
+ * Log each ValidationResult in the array
+ * @param {Array<ValidationResult>} results
+ */
+function logResults(results) {
+  // order results, and only print filePath once per file
+  const groups = groupByFilePath(results);
+  for (const [filePath, items] of groups) {
+    if (filePath) {
+      console.log(chalk.dim(`${filePath}`));
+    }
+    for (const item of items) {
+      const color = item.severity === Severity.ERROR ? chalk.red : chalk.yellow;
+      const symbol = item.severity === Severity.ERROR ? '✖' : '⚠';
+      const indent = filePath ? '    ' : '  ';
+      console.log(color.bold(symbol), `${indent}${item.message}`);
+      if (item.detail) {
+        console.log(chalk.dim(`  ${indent}${item.detail}`));
+      }
+    }
+    console.log('\n');
+  }
+}

package/bin/validators/{brand-json-validator.js → brand-json.validator.js}

@@ -3,9 +3,9 @@ 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 * as validation from '../utils/validation.js';
 import { BRAND_JSON_FILENAME } from '../../constants.js';
+import { exists } from '../utils/index.js';
 
 export const name = 'brand-json';
 export const description = 'Validates brand.json overrides against the MDS base token schema';
@@ -45,9 +45,9 @@ export function extractTokenPaths(obj, prefix = '') {
  */
 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);
+  const resolved = resolveReferences(rawValue, tokens);
+  if (resolved !== undefined && typeof resolved === 'object' && '$value' in resolved) {
+    return resolveToFinalValue(resolved.$value, tokens, { usesDtcg: true });
   }
   return resolved;
 }
@@ -83,78 +83,64 @@ async function loadBaseSchema() {
   await cleanTempFiles();
   return { basePaths, baseResolvedValues, baseTokens };
 }
-
-export async function validate() {
-  const results = [];
+/**
+ * Main validation function.
+ * Validates brand json override file for specified service (fertConfig)
+ * @property {object} options
+ * @property {FertConfig} options.fertConfig
+ * @returns {Promise<Array<ValidationResult>>} Array of validation results
+ */
+export async function validate({ fertConfig }) {
+  const resultsCollection = validation.createResultCollection();
   const { basePaths, baseResolvedValues, baseTokens } = await loadBaseSchema();
 
-  let serviceConfigs;
+  const brandJsonPath = path.join(fertConfig.workingDir, BRAND_JSON_FILENAME);
+
+  if (!(await exists(brandJsonPath))) {
+    resultsCollection
+      .addResult(`Missing ${BRAND_JSON_FILENAME}`)
+      .filePath(brandJsonPath)
+      .detail('Each service should have a brand.json for token overrides');
+    return resultsCollection.results; // abort early
+  }
+
+  let brandData;
   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;
+    brandData = JSON.parse(fs.readFileSync(brandJsonPath, 'utf-8'));
+  } catch (err) {
+    resultsCollection
+      .addResult(`Invalid JSON in ${BRAND_JSON_FILENAME}`)
+      .err()
+      .filePath(brandJsonPath)
+      .detail(err.message);
+    return resultsCollection.results; // abort early
   }
 
-  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;
-    }
+  const overridePaths = extractTokenPaths(brandData);
 
-    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;
+  for (const overridePath of overridePaths) {
+    if (!basePaths.has(overridePath)) {
+      resultsCollection
+        .addResult(`Unknown token path: "${overridePath}"`)
+        .filePath(brandJsonPath)
+        .detail('This path does not exist in the MDS base schema and will have no effect');
     }
 
-    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 rawOverrideValue = getValueAtPath(brandData, overridePath);
+    if (rawOverrideValue !== undefined) {
       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)}")`,
-          }),
-        );
+        resultsCollection
+          .addResult(`Redundant override: "${overridePath}"`)
+          .filePath(brandJsonPath)
+          .detail(
+            `Value "${String(rawOverrideValue)}" resolves to the same value as the MDS base ("${String(resolvedBase)}")`,
+          );
       }
     }
   }
 
-  return results;
+  return resultsCollection.results;
 }

package/bin/validators/translations.validator.js

@@ -0,0 +1,137 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import * as validation from '../utils/validation.js';
+import { PersistentCacheWithTtl } from '../utils/persistent-cache-with-ttl.js';
+import { ONE_WEEK, SERVICE_API_TRANSLATIONS, SERVICE_TRANSLATIONS_FILEPATH } from '../../constants.js';
+import { exists } from '../utils/index.js';
+import { log } from '../utils/logging.js';
+
+export const name = 'translations';
+export const description = 'Validates translation override files against base translations from upstream repositories';
+
+const cache = new PersistentCacheWithTtl('base-translations', { ttl: ONE_WEEK });
+
+/**
+ * Fetches base translations from remote version of this service.
+ * Uses caching with 1-week TTL to minimize API calls while dev server is running.
+ *
+ * @property {FertConfig} fertConfig
+ * @returns {Promise<Object|null>} Base translations object, or null if fetch fails
+ */
+async function fetchBaseTranslations(fertConfig) {
+  const cacheKey = `translations-${fertConfig.serviceName}-${fertConfig.clientPropertyId}`;
+  // Check cache first
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+  const url = new URL(SERVICE_API_TRANSLATIONS.replace('{serviceName}', fertConfig.serviceName));
+  // let service endpoint know we dont want to include client translations overrides, that's what we're looking at in our branding repo!
+  url.searchParams.set('excludeClientTranslationOverrides', true);
+
+  const res = await fetch(url.href, {
+    headers: { 'x-client-property-id': fertConfig.clientPropertyId },
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`failed to fetch base translations - ${text}`);
+  }
+
+  const translations = await res.json();
+  cache.set(cacheKey, translations);
+  return translations;
+}
+
+/**
+ * Recursively flattens a nested translation object into a Map of key paths to values.
+ * Example: { header: { "sign-in": "Sign in" } } → Map { "header.sign-in" => "Sign in" }
+ *
+ * @param {Object} obj - Translation object to flatten
+ * @param {string} prefix - Current path prefix
+ * @returns {Map<string, any>} Map of flattened key paths to their values
+ */
+export function flattenKeysWithValues(obj, prefix = '') {
+  const entries = new Map();
+
+  if (!obj || typeof obj !== 'object') {
+    return entries;
+  }
+
+  for (const [key, value] of Object.entries(obj)) {
+    const currentPath = prefix ? `${prefix}.${key}` : key;
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recurse into nested objects
+      const childEntries = flattenKeysWithValues(value, currentPath);
+      for (const [childKey, childValue] of childEntries) {
+        entries.set(childKey, childValue);
+      }
+    } else {
+      // Leaf node - add the path with its value
+      entries.set(currentPath, value);
+    }
+  }
+
+  return entries;
+}
+/**
+ * Main validation function.
+ * Validates translation override file for specified service (fertConfig)
+ * @property {object} options
+ * @property {FertConfig} options.fertConfig
+ * @returns {Promise<Array<ValidationResult>>} Array of validation results
+ */
+export async function validate({ fertConfig }) {
+  const resultsCollection = validation.createResultCollection();
+
+  const overridePath = path.resolve(fertConfig.workingDir, SERVICE_TRANSLATIONS_FILEPATH);
+  // cant read override file - nothing to validate
+  if (!(await exists(overridePath))) return resultsCollection.results; // abort early
+
+  // Parse override file (not using `import` to not cache json file as a module)
+  let overrideTranslations;
+  try {
+    const overrideContent = await fs.promises.readFile(overridePath, 'utf-8');
+    overrideTranslations = JSON.parse(overrideContent);
+  } catch (err) {
+    resultsCollection.addResult(`Failed to parse translation override: ${err.message}`).err().filePath(overridePath);
+    return resultsCollection.results; // abort early
+  }
+
+  // Fetch remote base translations
+  let baseTranslations;
+  try {
+    baseTranslations = await fetchBaseTranslations(fertConfig);
+  } catch (err) {
+    log.warn(`Could not fetch base translations for ${fertConfig.serviceName}. Skipping validation. ${err.message}`);
+
+    return resultsCollection.results; // abort early
+  }
+
+  // Flatten both translation objects with values
+  const baseEntries = flattenKeysWithValues(baseTranslations);
+  const overrideEntries = flattenKeysWithValues(overrideTranslations);
+
+  // Check each override key
+  for (const [overrideKey, overrideValue] of overrideEntries) {
+    if (!baseEntries.has(overrideKey)) {
+      // Extra key that doesn't exist in base
+      resultsCollection
+        .addResult(
+          `Unknown key: Translation key "${overrideKey}" is defined in override but does not exist in base translations`,
+        )
+        .filePath(overridePath)
+        .detail(
+          `This key may be unused or invalid. Base translations for ${fertConfig.serviceName} do not include this key.`,
+        );
+    } else if (baseEntries.get(overrideKey) === overrideValue) {
+      // Redundant override with same value as base
+      resultsCollection
+        .addResult(`Redundant override: "${overrideKey}"`)
+        .filePath(overridePath)
+        .detail(`Value "${String(overrideValue)}" is the same as the base translation and can be removed`);
+    }
+  }
+
+  return resultsCollection.results;
+}

package/constants.js

@@ -1,13 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import os from 'node:os';
-import { createRequire } from 'node:module';
+import pkg from './package.json' with { type: 'json' };
 
-const require = createRequire(import.meta.url);
-
-export const { version: VERSION } = JSON.parse(
-  fs.readFileSync(path.resolve(import.meta.dirname, './package.json')).toString(),
-);
+export const VERSION = pkg.version;
 
 export const ONE_MINUTE = 60000;
 export const ONE_HOUR = ONE_MINUTE * 60;
@@ -17,7 +14,7 @@ export const ONE_WEEK = ONE_DAY * 7;
 export const TMP_DIR = fs.realpathSync(os.tmpdir());
 export const FERT_PACKAGE_DIR = path.resolve('./');
 export const CUSTOM_TEMPLATES_DIR = './pages';
-export const MDS_PATH = path.dirname(require.resolve('@madgex/design-system/package.json'));
+export const MDS_PATH = path.dirname(fileURLToPath(import.meta.resolve('@madgex/design-system/package.json')));
 export const AWS_REGION = 'eu-west-1';
 export const PROPERTY_ID_API = 'https://property-identification-api.cs.madgexhosting.net/properties/';
 export const ASSETS_API_URL = 'https://asset-store.job.madgexhosting.net';
@@ -50,9 +47,14 @@ export const ASSET_STORE_INVALIDATION_PATH = `/{fertConfig.client.rootClientProp
 export const ASSET_STORE_USER_GUID = 'a386d4b6-f2df-4b80-ad1f-0349e23f530b';
 
 export const CONFIG_API =
-  'https://configuration-api.job.madgexhosting.net/configs/override/{cpid}/production/clientconfig/{config}';
+  'https://configuration-api.job.madgexhosting.net/configs/override/{cpid}/production/{configGroup}/{config}';
 export const CONFIG_DIR = 'config';
 
+/** we assume the remove version of a service hosts an api translations endpoint */
+export const SERVICE_API_TRANSLATIONS = 'https://{serviceName}.job.madgexhosting.net/api/translations';
+
+export const SERVICE_TRANSLATIONS_FILEPATH = 'public/translation.json';
+
 export const MOCK_AUTH_OBJECT = {
   'recruiterservices-frontend': {
     credentials: {

package/jsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ESNext",
+    "checkJs": false
+  },
+  "include": ["**/*.js", "types.d.ts"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madgex/fert",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "Tool to help build the V6 branding",
   "bin": {
     "fert": "./bin/cli.js"
@@ -19,7 +19,7 @@
     "url": "https://github.com/wiley/madgex-frontend-rollout-tool.git"
   },
   "engines": {
-    "node": ">=22.16"
+    "node": ">=22.17"
   },
   "author": "Madgex",
   "license": "UNLICENSED",
@@ -51,7 +51,7 @@
     "simple-git": "3.33.0",
     "simple-update-notifier": "2.0.0",
     "uuid-validate": "0.0.3",
-    "vite": "7.3.1",
+    "vite": "7.3.2",
     "vite-plugin-static-copy": "3.4.0"
   },
   "devDependencies": {
@@ -62,7 +62,7 @@
     "eslint": "10.1.0",
     "husky": "9.1.7",
     "lint-staged": "16.4.0",
-    "msw": "^2.12.14",
+    "msw": "2.13.0",
     "prettier": "3.8.1",
     "semantic-release": "25.0.3"
   },

package/types.d.ts

@@ -0,0 +1,54 @@
+type ValidationSeverity = {
+  ERROR: 'ERROR';
+  WARNING: 'WARNING';
+};
+
+type Validator = {
+  name: string;
+  description?: string;
+  validate: function;
+};
+
+type ValidationResult = {
+  severity: ValidationSeverity;
+  message: string;
+  filePath: string;
+  detail: string;
+};
+
+type ValidationResultCollection = {
+  results: ValidationResult[];
+  addResult(message: string): ValidationResultBuilder;
+};
+type ValidationResultBuilder = {
+  err(): ValidationResultBuilder;
+  filePath(filePath: string): ValidationResultBuilder;
+  detail(detail: string): ValidationResultBuilder;
+};
+
+interface FertConfigFile {
+  clientPropertyId: string;
+}
+interface FertServiceConfigFile {
+  serviceName: string;
+  entry?: string;
+  externalAssets?: {
+    links?: string[] | string;
+    scripts?: string[] | string;
+  };
+}
+type Client = {
+  brandName: string;
+  parentCpid: string;
+  rootClientPropertyId: string;
+  isAffiliate: boolean;
+};
+type FertConfig = FertConfigFile &
+  FertServiceConfigFile & {
+    /** always the root of the branding repo where fert.config.js file is */
+    rootDir: string;
+    /** always the service directory where fert.service.config.js is */
+    workingDir: any;
+    cli: object;
+    client: Client;
+  };

package/bin/utils/validation-helpers.js

@@ -1,87 +0,0 @@
-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('');
-  }
-}