@madgex/fert 7.2.0 → 7.2.1

package/README.md

@@ -341,3 +341,53 @@ Here are the default npm scripts in a Fert-scaffolded project.
   }
 }
 ```
+
+## Local Development
+
+Use this when you want to test or debug this local FERT codebase against a real branding repo.
+
+Link the local package:
+
+```bash
+cd ~/Repos/madgex-frontend-rollout-tool
+npm link
+
+cd ~/Repos/madgex-ff6102ff-0f4b-43d1-a2c7-83b835b8dee5
+npm link @madgex/fert
+```
+
+That gives you both of these:
+
+- a global `fert` command pointing at this local repo
+- a linked `@madgex/fert` inside the branding repo's `node_modules`
+
+From the branding repo, the closest match to normal usage is to run the repo scripts or `npx fert`:
+
+```bash
+npm run dev
+npx fert validate
+npx fert build --target=production
+npx fert publish --target=dev --dry-run
+```
+
+You can also run `fert ...` directly in a shell after the first `npm link`, because that creates the global symlink.
+
+To step-debug local FERT code in VS Code, open this repo, set breakpoints, open a JavaScript Debug Terminal, `cd` to the branding repo, then run any `fert` command there. Breakpoints in this repo will be hit automatically.
+
+If you do not want to link, run the CLI directly from the branding repo:
+
+```bash
+node ~/Repos/madgex-frontend-rollout-tool/bin/cli.js dev
+node ~/Repos/madgex-frontend-rollout-tool/bin/cli.js validate
+```
+
+To revert back to the published package:
+
+```bash
+cd ~/Repos/madgex-ff6102ff-0f4b-43d1-a2c7-83b835b8dee5
+npm unlink @madgex/fert
+npm install
+
+cd ~/Repos/madgex-frontend-rollout-tool
+npm unlink
+```

package/bin/commands/build.js

@@ -22,7 +22,10 @@ export async function build(options = {}) {
     throw Error(`Missing or invalid --target option. Choose from [${validTargets}]`);
   }
 
-  await validation.runServiceValidators(['brand-json', 'translations'], { fertConfig, throwable: true });
+  await validation.runServiceValidators(['brand-json', 'translations', 'redirects-csv'], {
+    fertConfig,
+    throwable: true,
+  });
 
   if (!options.only) {
     await rimraf(path.resolve(fertConfig.workingDir, 'dist'));

package/bin/commands/dev-server.js

@@ -33,10 +33,10 @@ export async function createDevServer(options = {}) {
   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 });
+    await validation.runServiceValidators(['brand-json', 'translations', 'redirects-csv'], { fertConfig });
   });
   // initial validation run
-  await validation.runServiceValidators(['brand-json', 'translations'], { fertConfig });
+  await validation.runServiceValidators(['brand-json', 'translations', 'redirects-csv'], { fertConfig });
 
   // building tokens
   await buildTokens(fertConfig);

package/bin/commands/validate.js

@@ -15,7 +15,7 @@ export async function validateCommand(/* options */) {
   for (const { serviceConfig } of serviceConfigs) {
     const fertConfig = await resolveConfig({ serviceName: serviceConfig.serviceName });
 
-    await validation.runServiceValidators(['brand-json', 'translations'], {
+    await validation.runServiceValidators(['brand-json', 'translations', 'redirects-csv'], {
       fertConfig,
       throwable: true,
     });

package/bin/utils/validation.js

@@ -2,9 +2,10 @@ 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';
+import * as validatorRedirectsCsv from '../validators/redirects-csv.validator.js';
 
 /** @type {Array<Validator>} */
-const validators = [validatorBrandJson, validatorTranslations];
+const validators = [validatorBrandJson, validatorTranslations, validatorRedirectsCsv];
 
 /**
  *

package/bin/validators/redirects-csv.validator.js

@@ -0,0 +1,147 @@
+import { REDIRECTS_CSV_FILENAME } from '../../constants.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import * as validation from '../utils/validation.js';
+
+export const name = 'redirects-csv';
+export const description = 'Validates redirects.csv for correct formatting and valid status codes';
+
+const VALID_STATUS_CODES = ['301', '302', '307', '308'];
+
+/**
+ * Extract `{name}` tokens from a Hapi Call path or string-template string.
+ * Hapi wildcards like `{name*}` or `{name*2}` are normalised to `name`.
+ */
+function extractParamNames(str) {
+  const names = new Set();
+  const re = /\{([^}]+)\}/g;
+  let m;
+  while ((m = re.exec(str)) !== null) {
+    const raw = m[1];
+    // strip Hapi wildcard suffix e.g. `name*`, `name*2`
+    const name = raw.replace(/\*\d*$/, '');
+    names.add(name);
+  }
+  return names;
+}
+
+function isAbsoluteUrl(str) {
+  return /^https?:\/\//i.test(str);
+}
+
+/** Strip trailing slash, matching the redirect consumer's behaviour. */
+function stripTrailingSlash(str) {
+  return str.length > 1 && str.endsWith('/') ? str.slice(0, -1) : str;
+}
+
+export async function validate({ fertConfig }) {
+  const resultsCollection = validation.createResultCollection();
+
+  const redirectsCsvPath = path.join(fertConfig.workingDir, 'public', REDIRECTS_CSV_FILENAME);
+  if (!fs.existsSync(redirectsCsvPath)) {
+    return resultsCollection.results;
+  }
+
+  let csvData;
+  try {
+    csvData = fs.readFileSync(redirectsCsvPath, 'utf-8');
+  } catch (error) {
+    resultsCollection
+      .addResult(`Error reading ${REDIRECTS_CSV_FILENAME}`)
+      .filePath(redirectsCsvPath)
+      .err()
+      .detail(error.message);
+    return resultsCollection.results;
+  }
+
+  const lines = csvData.split('\n');
+  const seenSources = new Map(); // source -> first line number where seen
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+
+    const parts = line.split(',').map((part) => part.trim());
+    const source = parts[0];
+    const destination = parts[1];
+    const status = parts[2];
+    const lineRef = `Line ${i + 1}: "${line.trim()}"`;
+
+    const addError = (message, detail) =>
+      resultsCollection.addResult(`${message}: ${lineRef}`).filePath(redirectsCsvPath).err().detail(detail);
+
+    // Column count — need at least source + destination
+    if (parts.length < 2) {
+      addError('Missing destination', 'Each row must have at least "source,destination"');
+      continue;
+    }
+
+    // Source
+    if (!source) {
+      addError('Missing source', 'Source (column 1) is required');
+    } else {
+      if (!source.startsWith('/')) {
+        addError('Source must start with /', `Source "${source}" must start with a /`);
+      }
+      if (source.includes('?') || source.includes('#')) {
+        addError(
+          'Source must not contain ? or #',
+          `Source "${source}" must not include query strings or fragments — the redirect handler preserves the request query string automatically`,
+        );
+      }
+    }
+
+    // Destination
+    if (!destination) {
+      addError('Missing destination', 'Destination (column 2) is required');
+    } else if (!destination.startsWith('/') && !isAbsoluteUrl(destination)) {
+      addError(
+        'Destination must be a relative path or absolute URL',
+        `Destination "${destination}" must start with / or be an absolute http(s):// URL`,
+      );
+    }
+
+    // Self-redirect + path-parameter consistency
+    if (source && destination) {
+      if (stripTrailingSlash(source) === stripTrailingSlash(destination)) {
+        addError(
+          'Self-redirect',
+          `Source and destination are the same ("${source}") — this would create an infinite redirect loop`,
+        );
+      }
+
+      const sourceParams = extractParamNames(source);
+      const destParams = extractParamNames(destination);
+      for (const p of destParams) {
+        if (!sourceParams.has(p)) {
+          addError(
+            'Destination references unknown path parameter',
+            `Destination "${destination}" references {${p}} which is not captured in source "${source}"`,
+          );
+        }
+      }
+    }
+
+    // Status code
+    if (status && !VALID_STATUS_CODES.includes(status)) {
+      addError(
+        'Invalid status code',
+        `Status "${status}" is not supported. Use 301 (permanent) or 302 (temporary); 307/308 preserve the HTTP method`,
+      );
+    }
+
+    // Duplicate source
+    if (source) {
+      if (seenSources.has(source)) {
+        addError(
+          'Duplicate source',
+          `Source "${source}" is already defined on line ${seenSources.get(source)} — only the first occurrence is applied`,
+        );
+      } else {
+        seenSources.set(source, i + 1);
+      }
+    }
+  }
+
+  return resultsCollection.results;
+}

package/constants.js

@@ -19,6 +19,7 @@ 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';
 export const BRAND_JSON_FILENAME = 'brand.json';
+export const REDIRECTS_CSV_FILENAME = 'redirects.csv';
 export const FERT_CONFIG_FILENAME = 'fert.config.js';
 export const FERT_SERVICE_CONFIG_FILENAME = 'fert.service.config.js';
 export const ASSET_STORE_API = 'https://asset-store-api.job.madgexhosting.net/';

package/package.json

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