feat(importer): detect duplicate destination filenames in generate.js

Two source folders writing SVGs with the same filename into the flat
intermediate/ directory cause non-deterministic React atom output (the
asynchronous fs.readdir + fs.stat + fs.copyFileSync race makes the
final byte content depend on callback order).

Add a Map-based detector that, at file copy time, records the first
source folder to claim each destination. When a second source folder
attempts to write the same destination, the collision is recorded and
reported via a process.on('exit') hook after the async walker drains.

Behaviour is controlled by a new --on-duplicate flag (fail|warn|ignore,
default fail). A KNOWN_DUPLICATE_SOURCE regex allowlists the existing
'<Name> Temp (LTR|RTL)/' folders so the build does not break today;
those folders are staging artifacts that need a separate cleanup PR.

Refs: #1009

Author: Hotell

importer/generate.js

@@ -42,21 +42,29 @@ const parseArgs = (args=process.argv.slice(2)) => {
       describe: 'Keep original directories in output',
       default: false,
     })
+    .option('on-duplicate', {
+      type: 'string',
+      choices: ['fail', 'warn', 'ignore'],
+      describe: 'How to handle two source folders producing the same destination filename',
+      default: 'fail',
+    })
     .help()
     .wrap(Math.min(120, process.stdout.columns || 120))
     .argv;
 
   /**
    * @typedef {'react'|'android'|'ios'|'flutter'} TargetType
    * @typedef {'svg'|'xml'|'pdf'|'tsx'} ExtensionType
+   * @typedef {'fail'|'warn'|'ignore'} OnDuplicate
    *
    * @typedef {{
    *   SRC_PATH: string,
    *   DEST_PATH: string,
    *   EXTENSION: ExtensionType,
    *   TARGET: TargetType,
    *   SELECTOR: boolean,
-   *   KEEP_DIRS: boolean
+   *   KEEP_DIRS: boolean,
+   *   ON_DUPLICATE: OnDuplicate,
    * }} ParseResult
    */
 
@@ -67,10 +75,30 @@ const parseArgs = (args=process.argv.slice(2)) => {
     TARGET: /** @type {TargetType} */ (argv.target),
     SELECTOR: Boolean(argv.selector),
     KEEP_DIRS: Boolean(argv.keepdirs),
+    ON_DUPLICATE: /** @type {OnDuplicate} */ (argv['on-duplicate']),
   });
 };
 
-const { SRC_PATH, DEST_PATH, EXTENSION, TARGET, SELECTOR, KEEP_DIRS } = parseArgs();
+const { SRC_PATH, DEST_PATH, EXTENSION, TARGET, SELECTOR, KEEP_DIRS, ON_DUPLICATE } = parseArgs();
+
+/**
+ * Source folders known to collide with canonical asset folders today.
+ * These folders appear to be staging artifacts (no metadata.json, contain SVG
+ * files named after the OPPOSITE icon, e.g. `Arrow Undo Temp RTL/SVG/ic_fluent_arrow_redo_*.svg`).
+ * They cause non-deterministic atom output because multiple source folders
+ * write to the same intermediate filename — see issue tracker for cleanup.
+ * Until they are removed from `assets/`, collisions involving these folders
+ * are downgraded to warnings so the build does not fail today.
+ *
+ * TODO: remove this allowlist once the `* Temp (LTR|RTL)` folders are deleted
+ * from `assets/`.
+ */
+const KNOWN_DUPLICATE_SOURCE = / Temp (LTR|RTL)(\/|\\|$)/;
+
+/** @type {Map<string, string>} destFile -> first srcFile that wrote it */
+const writtenFiles = new Map();
+/** @type {Array<{ destFile: string, previousSrc: string, conflictingSrc: string, allowlisted: boolean }>} */
+const duplicateCollisions = [];
 const ICON_OUTLINE_STYLE = '_regular'
 const ICON_FILLED_STYLE = '_filled'
 const ICON_LIGHT_STYLE = '_light'
@@ -166,6 +194,14 @@ function processFolder(srcPath, destPath, folderDepth) {
         if (!fs.existsSync(destPath)) {
           fs.mkdirSync(destPath)
         }
+        const previousSrc = writtenFiles.get(destFile);
+        if (previousSrc && previousSrc !== srcFile) {
+          const allowlisted =
+            KNOWN_DUPLICATE_SOURCE.test(previousSrc) || KNOWN_DUPLICATE_SOURCE.test(srcFile);
+          duplicateCollisions.push({ destFile, previousSrc, conflictingSrc: srcFile, allowlisted });
+        } else {
+          writtenFiles.set(destFile, srcFile);
+        }
         fs.copyFileSync(srcFile, destFile);
         // Generate selector if both filled/regular styles are available
         if (SELECTOR && file.endsWith(SVG_EXTENSION)) {
@@ -240,3 +276,52 @@ export default ${iconName + REACT_SUFFIX};
     if (err) throw err;
   });
 }
+
+/**
+ * Report any duplicate-destination collisions detected during the walk.
+ *
+ * The walker is async-callback based and has no explicit completion signal,
+ * so we hook `process.on('exit')` which fires after all queued callbacks drain
+ * and Node would otherwise exit naturally.
+ *
+ * Behaviour per `--on-duplicate`:
+ *   - fail    (default): non-zero exit if any non-allowlisted collision occurred
+ *   - warn             : prints all collisions but keeps exit code 0
+ *   - ignore           : prints nothing
+ *
+ * Collisions where either side matches `KNOWN_DUPLICATE_SOURCE` are downgraded
+ * to a warning even under `--on-duplicate=fail`.
+ */
+process.on('exit', () => {
+  if (ON_DUPLICATE === 'ignore' || duplicateCollisions.length === 0) {
+    return;
+  }
+  const blocking = duplicateCollisions.filter((c) => !c.allowlisted);
+  const allowlisted = duplicateCollisions.filter((c) => c.allowlisted);
+  /** @param {typeof duplicateCollisions} list */
+  const formatList = (list) =>
+    list
+      .map(
+        (c) =>
+          `  - ${c.destFile}\n      first : ${c.previousSrc}\n      collide: ${c.conflictingSrc}`
+      )
+      .join('\n');
+  if (allowlisted.length > 0) {
+    console.warn(
+      `\n[generate.js] ${allowlisted.length} known duplicate destination(s) ` +
+        `(allowlisted via KNOWN_DUPLICATE_SOURCE):\n${formatList(allowlisted)}\n`
+    );
+  }
+  if (blocking.length > 0) {
+    const message =
+      `\n[generate.js] ${blocking.length} duplicate destination(s) detected. ` +
+      `Two source folders produced the same output filename; output is non-deterministic. ` +
+      `Rename one of the source folders or remove the duplicate asset.\n${formatList(blocking)}\n`;
+    if (ON_DUPLICATE === 'fail') {
+      console.error(message);
+      process.exitCode = 1;
+    } else {
+      console.warn(message);
+    }
+  }
+});