@massimo-cassandro/minimo 1.41.4 → 1.41.5

package/dev-tools/design-tokens-builder/build-tokens-src/platforms.mjs

@@ -1,17 +1,21 @@
-// build-tokens-src/platforms.mjs
-// Builds and returns the `platforms` object for the Style Dictionary config.
-//
-// The `json` platform is included only if jsonBuildPath is set.
-// Output format (json/jsonc) and file splitting are delegated to buildJsonFiles().
+/*
+  build-tokens-src/platforms.mjs
+  Costruisce e restituisce l'oggetto `platforms` per la config di Style Dictionary.
+
+  La platform `json` è inclusa solo se jsonBuildPath è impostato.
+  Il formato di output (json/jsonc) e la suddivisione in file sono delegati a buildJsonFiles().
+*/
 
 import { buildJsonFiles } from './formats/json.mjs';
 
 /** @typedef {import('style-dictionary/types').PlatformConfig} PlatformConfig */
 
-// Transforms applied to the CSS platform.
-// Exported so other scripts (e.g. check-unresolved-custom-props.mjs) can
-// build a Style Dictionary instance with matching transformed token names.
-// name/kebab-prefixed = name/kebab + per-source prefix (see source-prefixes.mjs).
+/*
+  Transform applicate alla platform CSS.
+  Esportate così che altri script (ad es. check-unresolved-custom-props.mjs) possano
+  costruire un'istanza di Style Dictionary con nomi dei token trasformati in modo coerente.
+  name/kebab-prefixed = name/kebab + prefisso per sorgente (vedi source-prefixes.mjs).
+*/
 export const CSS_TRANSFORMS = [
   'attribute/cti',
   'name/kebab-prefixed',
@@ -25,13 +29,15 @@ export const CSS_TRANSFORMS = [
   'typography/css',
 ];
 
-// Transforms applied to the JSON platform.
-// Kept minimal on purpose: consuming tools expect original values (e.g. "16px"
-// not "1rem") and alias references ({...}) must be preserved to maintain
-// token links. Source prefixes are not applied here (plain name/kebab): the
-// JSON output keeps the original token tree.
-// Exported so build-source-modes.mjs can build a matching json platform per
-// sourceModes mode.
+/*
+  Transform applicate alla platform JSON.
+  Volutamente minimali: gli strumenti che le usano si aspettano i valori originali (es. "16px"
+  e non "1rem") e i riferimenti alias ({...}) devono essere conservati per mantenere
+  i collegamenti tra token. I prefissi delle sorgenti non vengono applicati qui (name/kebab semplice): l'output
+  JSON mantiene l'albero dei token originale.
+  Esportate così che build-source-modes.mjs possa costruire una platform json corrispondente per ogni
+  modalità di sourceModes.
+*/
 export const JSON_TRANSFORMS = [
   'attribute/cti',
   'name/kebab',
@@ -40,20 +46,20 @@ export const JSON_TRANSFORMS = [
 
 /**
  * @param {object}          opts
- * @param {string}          opts.buildPath           Absolute path for CSS output directory
- * @param {string}          opts.destFile            CSS output filename (e.g. "tokens.css")
- * @param {string|null}     opts.jsonBuildPath       Absolute path for JSON output (null = disabled)
- * @param {string|null}     opts.jsonDestFile        Base name for aggregated file; null = one file per source
- * @param {'json'|'jsonc'}  opts.jsonFormat          Output format for JSON files
- * @param {string[]}        opts.concreteFilePaths   Concrete (expanded) source file paths for multi-file mode.
- *                                                   Collected from sd.allTokens after SD initialisation.
- *                                                   Ignored when jsonDestFile is set.
- * @param {'keep'|'calc'|'resolve'} opts.jsonExpression  How to handle math expressions in dimension tokens.
- * @param {{name: string, prefixes: string[]}[]} opts.customPropsGroups  Named groups of name prefixes, moved to the top of the CSS output in list order.
- * @param {boolean}         opts.pxToRem             If false, skips the px→rem transform on the CSS platform. Default: true.
- * @param {string|null}     opts.addLayer            Wraps the generated custom properties inside `@layer <addLayer> { ... }`. null = no layer.
- * @param {string}          opts.selector            CSS selector wrapping the generated block (default: ':root').
- * @returns {Record<string, PlatformConfig>} platforms object ready for Style Dictionary config
+ * @param {string}          opts.buildPath           Percorso assoluto della directory di output CSS
+ * @param {string}          opts.destFile            Nome del file CSS di output (es. "tokens.css")
+ * @param {string|null}     opts.jsonBuildPath       Percorso assoluto dell'output JSON (null = disattivato)
+ * @param {string|null}     opts.jsonDestFile        Nome base del file aggregato; null = un file per sorgente
+ * @param {'json'|'jsonc'}  opts.jsonFormat          Formato di output dei file JSON
+ * @param {string[]}        opts.concreteFilePaths   Percorsi concreti (espansi) dei file sorgente per la modalità multi-file.
+ *                                                   Raccolti da sd.allTokens dopo l'inizializzazione di SD.
+ *                                                   Ignorato quando jsonDestFile è impostato.
+ * @param {'keep'|'calc'|'resolve'} opts.jsonExpression  Come gestire le espressioni matematiche nei token dimension.
+ * @param {{name: string, prefixes: string[]}[]} opts.customPropsGroups  Gruppi nominati di prefissi di nome, spostati in cima all'output CSS nell'ordine dell'elenco.
+ * @param {boolean}         opts.pxToRem             Se false, salta la transform px→rem sulla platform CSS (default: true).
+ * @param {string|null}     opts.addLayer            Racchiude le custom properties generate in `@layer <addLayer> { ... }`. null = nessun layer.
+ * @param {string}          opts.selector            Selettore CSS che racchiude il blocco generato (default: ':root').
+ * @returns {Record<string, PlatformConfig>} oggetto platforms pronto per la config di Style Dictionary
  */
 export const buildPlatforms = ({
   buildPath,

package/dev-tools/design-tokens-builder/build-tokens-src/resolve-source-paths.mjs

@@ -1,13 +1,15 @@
-// build-tokens-src/resolve-source-paths.mjs
-// Pure helper: resolves Style Dictionary `source` glob patterns relative to a
-// base directory, without touching glob syntax.
-// Shared by config.mjs (build-tokens.mjs) and check-unresolved-custom-props.mjs.
-//
-// Glob patterns (containing *, ?, {, [) are NOT passed through path.join,
-// because path.join can normalise/collapse sequences that carry syntactic
-// meaning in a glob (e.g. "**"). They are only prefixed with baseDir and
-// converted to forward slashes.
-// Concrete paths (no glob characters) are resolved canonically with path.resolve.
+/*
+  build-tokens-src/resolve-source-paths.mjs
+  Helper puro: risolve i pattern glob `source` di Style Dictionary rispetto a una
+  directory base, senza toccare la sintassi glob.
+  Condiviso da config.mjs (build-tokens.mjs) e da check-unresolved-custom-props.mjs.
+
+  I pattern glob (che contengono *, ?, {, [) NON vengono passati a path.join,
+  perché path.join può normalizzare/comprimere sequenze che in un glob hanno un
+  significato sintattico (ad es. "**"). Vengono solo preceduti da baseDir e
+  convertiti con forward slash.
+  I percorsi concreti (senza caratteri glob) vengono risolti in modo canonico con path.resolve.
+*/
 
 import * as path from 'node:path';
 
@@ -20,14 +22,14 @@ const GLOB_CHARS = /[*?{[]/;
  */
 export const resolveSourcePaths = (source, baseDir) => source.map((s) => {
   if (path.isAbsolute(s)) {
-    // Already absolute: only normalise separators (needed on Windows)
+    // Già assoluto: normalizza solo i separatori (necessario su Windows)
     return s.split(path.sep).join('/');
   }
   if (GLOB_CHARS.test(s)) {
-    // Glob pattern: prefix with baseDir without touching the pattern
+    // Pattern glob: antepone baseDir senza toccare il pattern
     const prefix = baseDir.split(path.sep).join('/');
     return `${prefix}/${s}`;
   }
-  // Concrete relative path: canonical resolution
+  // Percorso relativo concreto: risoluzione canonica
   return path.resolve(baseDir, s).split(path.sep).join('/');
 });

package/dev-tools/design-tokens-builder/build-tokens-src/source-prefixes.mjs

@@ -1,29 +1,31 @@
-// build-tokens-src/source-prefixes.mjs
-// Supports per-source custom property prefixes: an entry of `source` (or of a
-// `sourceModes` mode) can be an object `{ src, prefix }` instead of a plain
-// string, e.g.
-//
-//   { src: 'node_modules/open-props/open-props.style-dictionary-tokens.json', prefix: 'op' }
-//
-// so that every token defined by those files is rendered as `--op-<name>`.
-//
-// How it works: the prefix is applied to the token NAME only (see the
-// name/kebab-prefixed transform in transforms.mjs), never to its path.
-// {references} are resolved through the token path and rendered with the
-// already-prefixed name, so a token of another source referencing e.g.
-// {gray.5} becomes `var(--op-gray-5)` with no change to the token files. The
-// JSON output keeps the original (unprefixed) tree structure.
-//
-// The name transform only knows the concrete file a token comes from
-// (token.filePath), while `src` may contain glob patterns: registerSourcePrefixes()
-// expands them (through Style Dictionary itself, so the result matches
-// token.filePath exactly) into a file path -> prefix map.
-//
-// The same entry object can also carry a `transform` map (renaming/moving
-// token nodes within the file's tree, e.g. { primary: 'primary.100' }) — see
-// source-transforms.mjs / token-rename-parser.mjs. splitSourceEntries() below
-// extracts both `prefix` and `transform` from the same `{ src, ... }` shape,
-// since they share the same source-matching syntax.
+/*
+  build-tokens-src/source-prefixes.mjs
+  Supporta i prefissi delle custom properties per sorgente: una voce di `source` (o di una
+  modalità di `sourceModes`) può essere un oggetto `{ src, prefix }` invece di una semplice
+  stringa, ad es.
+
+    { src: 'node_modules/open-props/open-props.style-dictionary-tokens.json', prefix: 'op' }
+
+  in modo che ogni token definito da quei file venga reso come `--op-<nome>`.
+
+  Come funziona: il prefisso viene applicato solo al NOME del token (vedi la
+  transform name/kebab-prefixed in transforms.mjs), mai al suo percorso.
+  I {riferimenti} vengono risolti tramite il percorso del token e resi con il nome
+  già prefissato, quindi un token di un'altra sorgente che referenzia ad es.
+  {gray.5} diventa `var(--op-gray-5)` senza modificare i file dei token. L'output
+  JSON mantiene la struttura ad albero originale (senza prefisso).
+
+  La transform del nome conosce solo il file concreto da cui proviene un token
+  (token.filePath), mentre `src` può contenere pattern glob: registerSourcePrefixes()
+  li espande (tramite lo stesso Style Dictionary, così che il risultato corrisponda
+  esattamente a token.filePath) in una mappa percorso file -> prefisso.
+
+  La stessa voce può anche avere una mappa `transform` (che rinomina/sposta i
+  nodi dei token nell'albero del file, ad es. { primary: 'primary.100' }) — vedi
+  source-transforms.mjs / token-rename-parser.mjs. splitSourceEntries() più sotto
+  estrae sia `prefix` sia `transform` dalla stessa forma `{ src, ... }`,
+  dato che condividono la stessa sintassi di individuazione dei sorgenti.
+*/
 
 import StyleDictionary from 'style-dictionary';
 import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
@@ -33,18 +35,18 @@ import { normalizeTransformMap } from './source-transforms.mjs';
 
 /**
  * @typedef {object} PrefixedSource
- * @property {string[]} src     Source paths/globs, already resolved (see resolveSourcePaths)
- * @property {string}   prefix  Normalised prefix, without leading `--` or trailing `-`
+ * @property {string[]} src     Percorsi/glob sorgente, già risolti (vedi resolveSourcePaths)
+ * @property {string}   prefix  Prefisso normalizzato, senza `--` iniziale né `-` finale
  */
 
 /** @type {Map<string, string>} */
 let prefixByFile = new Map();
 
 /**
- * Normalises a user-provided prefix: 'op', 'op-' and '--op-' all become 'op'.
+ * Normalizza un prefisso fornito dall'utente: 'op', 'op-' e '--op-' diventano tutti 'op'.
  * @param {unknown} prefix
  * @returns {string}
- * @throws {Error} if the result is not a valid custom property name segment
+ * @throws {Error} se il risultato non è un segmento valido di nome di custom property
  */
 export const normalizePrefix = (prefix) => {
   const value = String(prefix).trim().replace(/^-+/, '').replace(/-+$/, '');
@@ -56,16 +58,16 @@ export const normalizePrefix = (prefix) => {
 
 /**
  * @typedef {object} TransformedSource
- * @property {string[]} src               Source paths/globs, already resolved
- * @property {Record<string,string>} transform  Validated rename map (see source-transforms.mjs)
+ * @property {string[]} src               Percorsi/glob sorgente, già risolti
+ * @property {Record<string,string>} transform  Mappa di rinomina validata (vedi source-transforms.mjs)
  */
 
 /**
- * Splits a `source` (or `sourceModes[mode]`) array, whose entries can be
- * strings or `{ src, prefix, transform }` objects, into the flat list of
- * patterns to pass to Style Dictionary, the list of the prefixed entries and
- * the list of the transformed (renamed) entries. Patterns are resolved
- * relative to baseDir (see resolveSourcePaths).
+ * Suddivide un array `source` (o `sourceModes[mode]`), le cui voci possono essere
+ * stringhe od oggetti `{ src, prefix, transform }`, nell'elenco piatto di
+ * pattern da passare a Style Dictionary, nell'elenco delle voci con prefisso e
+ * nell'elenco delle voci trasformate (rinominate). I pattern vengono risolti
+ * rispetto a baseDir (vedi resolveSourcePaths).
  * @param {(string|{src: string|string[], prefix?: string, transform?: Record<string,string>})[]} entries
  * @param {string} baseDir
  * @returns {{patterns: string[], prefixed: PrefixedSource[], transformed: TransformedSource[]}}
@@ -109,12 +111,12 @@ export const splitSourceEntries = (entries, baseDir) => {
 };
 
 /**
- * Expands the `src` patterns of every prefixed entry into concrete file paths
- * and stores the file path -> prefix map used by getSourcePrefix().
- * Must be called after registerLegacyTokensParser() and before any build.
+ * Espande i pattern `src` di ogni voce con prefisso in percorsi di file concreti
+ * e memorizza la mappa percorso file -> prefisso usata da getSourcePrefix().
+ * Va chiamata dopo registerLegacyTokensParser() e prima di qualsiasi build.
  * @param {PrefixedSource[]} prefixedSources
  * @returns {Promise<void>}
- * @throws {Error} if the same file is given two different prefixes
+ * @throws {Error} se allo stesso file vengono assegnati due prefissi diversi
  */
 export const registerSourcePrefixes = async (prefixedSources) => {
   /** @type {Map<string, string>} */
@@ -144,6 +146,6 @@ export const registerSourcePrefixes = async (prefixedSources) => {
 
 /**
  * @param {string|undefined} filePath  token.filePath
- * @returns {string|undefined} the prefix registered for that file, if any
+ * @returns {string|undefined} il prefisso registrato per quel file, se presente
  */
 export const getSourcePrefix = (filePath) => (filePath ? prefixByFile.get(filePath) : undefined);

package/dev-tools/design-tokens-builder/build-tokens-src/source-transforms.mjs

@@ -1,55 +1,57 @@
-// build-tokens-src/source-transforms.mjs
-// Supports per-source token renaming: an entry of `source` (or of a
-// `sourceModes` mode) can carry a `transform` object next to (or instead of)
-// `prefix` — see splitSourceEntries() in source-prefixes.mjs — e.g.
-//
-//   { src: './project-tokens/*.jsonc', transform: { primary: 'primary.100' } }
-//
-// so that the token found at dot-path `primary` in those files is moved to
-// dot-path `primary.100` before Style Dictionary ever sees it, i.e. before
-// {references} are resolved and before the CSS/JSON output is built.
-//
-// Typical use case: a preexisting project defines its tokens (e.g. exported
-// from Figma/Penpot) under names that don't match minimo's own naming (e.g.
-// the project's base color is `primary`, minimo's equivalent is
-// `primary.100`). Without this feature every custom property generated from
-// the project's tokens would have to be renamed by hand after each build, or
-// every minimo reference to `{primary.100}` would have to be tracked down and
-// changed instead. `transform` fixes the token's OWN path once, in config.
-//
-// Notation: both sides of the map use Style Dictionary's own dot-path
-// notation (e.g. 'primary.100'), NOT the hyphen-joined custom-property
-// notation (e.g. 'primary-100'). Token name segments in this project can
-// themselves contain hyphens (e.g. btn-close, status-buttons), so a hyphen
-// can't reliably tell a path separator from a literal part of a segment name;
-// a dot can, since Style Dictionary already reserves it as the path
-// separator in {references} and never allows it inside a single segment
-// name.
-//
-// Moving a node would otherwise leave every {reference} to its OLD path
-// dangling (in the same file or a completely different one) — so this module
-// also collects a flat, file-independent from -> to map (getAllRenames()),
-// used by the token-rename PREPROCESSOR (see token-rename-parser.mjs) to
-// rewrite every such {reference} tree-wide, once all files are merged. This
-// is safe to do because Style Dictionary resolves {references} against the
-// single merged token tree by absolute path: if `primary` existed exactly
-// once before the rename, every {primary} anywhere in the build
-// unambiguously pointed at that one node, so every one of them must now
-// become {primary.100} — there is no risk of rewriting an unrelated
-// reference. The one case this can't disambiguate is the same "from" key
-// renamed to a DIFFERENT destination in a different file (each valid on its
-// own, per-file); see registerSourceTransforms() below — that key is
-// excluded from the tree-wide rewrite (with a console warning), and its
-// {references} are left for the user to fix by hand.
-//
-// How it works: unlike `prefix` (a purely cosmetic CSS name transform, see
-// source-prefixes.mjs, which never touches the token tree), `transform`
-// restructures the actual parsed token tree of the source file, via a
-// dedicated Style Dictionary parser (see token-rename-parser.mjs) that runs
-// at parse time, before files are merged and before reference resolution.
-// Since both the CSS and JSON output formats rebuild their tree from
-// token.path (by then already renamed), no separate handling is needed to
-// make the JSON output reflect the renamed structure too.
+/*
+  build-tokens-src/source-transforms.mjs
+  Supporta la rinomina dei token per sorgente: una voce di `source` (o di una
+  modalità di `sourceModes`) può avere un oggetto `transform` accanto a (o al posto di)
+  `prefix` — vedi splitSourceEntries() in source-prefixes.mjs — ad es.
+
+    { src: './project-tokens/*.jsonc', transform: { primary: 'primary.100' } }
+
+  in modo che il token trovato al dot-path `primary` in quei file venga spostato al
+  dot-path `primary.100` prima ancora che Style Dictionary lo veda, cioè prima che
+  i {riferimenti} vengano risolti e prima che venga costruito l'output CSS/JSON.
+
+  Caso d'uso tipico: un progetto preesistente definisce i propri token (ad es. esportati
+  da Figma/Penpot) con nomi che non corrispondono alla nomenclatura di minimo (ad es.
+  il colore base del progetto è `primary`, l'equivalente di minimo è
+  `primary.100`). Senza questa funzionalità ogni custom property generata dai token
+  del progetto andrebbe rinominata a mano dopo ogni build, oppure ogni riferimento di minimo
+  a `{primary.100}` andrebbe cercato e modificato. `transform` corregge una volta
+  sola il percorso PROPRIO del token, nella config.
+
+  Notazione: entrambi i lati della mappa usano la notazione dot-path di Style Dictionary
+  (ad es. 'primary.100'), NON la notazione delle custom properties con trattini
+  (ad es. 'primary-100'). I segmenti dei nomi dei token in questo progetto possono
+  contenere trattini (ad es. btn-close, status-buttons), quindi un trattino
+  non permette di distinguere in modo affidabile un separatore di percorso da una parte letterale
+  del nome di un segmento; un punto sì, dato che Style Dictionary lo riserva già come
+  separatore di percorso nei {riferimenti} e non lo ammette mai dentro il nome
+  di un singolo segmento.
+
+  Spostare un nodo lascerebbe altrimenti ogni {riferimento} al suo VECCHIO percorso
+  pendente (nello stesso file o in uno completamente diverso) — quindi questo modulo
+  raccoglie anche una mappa piatta from -> to, indipendente dal file (getAllRenames()),
+  usata dal PREPROCESSOR di rinomina dei token (vedi token-rename-parser.mjs) per
+  riscrivere ogni {riferimento} di questo tipo in tutto l'albero, una volta uniti tutti i file. Si
+  può fare in sicurezza perché Style Dictionary risolve i {riferimenti} sull'unico
+  albero di token unito, tramite percorso assoluto: se `primary` esisteva una sola
+  volta prima della rinomina, ogni {primary} in qualsiasi punto della build
+  puntava senza ambiguità a quell'unico nodo, quindi ognuno deve ora
+  diventare {primary.100} — non c'è rischio di riscrivere un riferimento non correlato. L'unico
+  caso che non si può disambiguare è la stessa chiave "from" rinominata con una
+  destinazione DIVERSA in un file diverso (ciascuna valida per conto proprio, per
+  file); vedi registerSourceTransforms() più sotto — quella chiave viene
+  esclusa dalla riscrittura su tutto l'albero (con un warning in console) e i suoi
+  {riferimenti} restano da correggere a mano.
+
+  Come funziona: a differenza di `prefix` (una trasformazione puramente estetica del nome CSS, vedi
+  source-prefixes.mjs, che non tocca mai l'albero dei token), `transform`
+  ristruttura il vero albero dei token letto dal file sorgente, tramite un
+  parser dedicato di Style Dictionary (vedi token-rename-parser.mjs) che viene eseguito
+  in fase di parsing, prima dell'unione dei file e della risoluzione dei riferimenti.
+  Poiché sia l'output CSS sia quello JSON ricostruiscono il proprio albero da
+  token.path (ormai già rinominato), non serve una gestione separata perché
+  anche l'output JSON rifletta la struttura rinominata.
+*/
 
 import StyleDictionary from 'style-dictionary';
 import { collectConcreteFilePaths } from './formats/json.mjs';
@@ -58,29 +60,31 @@ import { LEGACY_TOKENS_PARSER_NAME } from './legacy-tokens-parser.mjs';
 /** @type {Map<string, Record<string,string>>} */
 let transformByFile = new Map();
 
-// Flat, file-independent from -> to map, used by the token-rename
-// preprocessor (see token-rename-parser.mjs) to rewrite any {reference}
-// pointing to a renamed token's OLD path, anywhere in the build (same file or
-// another one) — references are resolved by Style Dictionary against the
-// single merged token tree, by absolute path, so a bare dot-path is
-// unambiguous UNLESS the same "from" key was given a different destination
-// in a different file (each valid on its own — see registerSourceTransforms
-// below), in which case that key is excluded here (with a warning) and its
-// {references} are left for the user to fix by hand, same as before this
-// preprocessor existed.
+/*
+  Mappa piatta from -> to, indipendente dal file, usata dal preprocessor di
+  rinomina dei token (vedi token-rename-parser.mjs) per riscrivere ogni {riferimento}
+  che punta al VECCHIO percorso di un token rinominato, in qualsiasi punto della build (stesso file o
+  un altro) — i riferimenti vengono risolti da Style Dictionary sull'unico albero di
+  token unito, tramite percorso assoluto, quindi un semplice dot-path non è
+  ambiguo A MENO CHE la stessa chiave "from" non abbia ricevuto una destinazione diversa
+  in un file diverso (ciascuna valida per conto proprio — vedi registerSourceTransforms
+  più sotto), nel qual caso quella chiave viene esclusa qui (con un warning) e i suoi
+  {riferimenti} restano da correggere a mano, come prima dell'esistenza di questo
+  preprocessor.
+*/
 /** @type {Map<string, string>} */
 let globalRenames = new Map();
 
 const DOT_PATH = /^[^.\s][\w-]*(\.[^.\s][\w-]*)*$/;
 
 /**
- * Validates a `transform` map: every key/value must be a non-empty
- * Style-Dictionary dot-path string (e.g. 'primary.100'), not a
- * hyphen-joined custom-property name (e.g. 'primary-100') — see the notation
+ * Valida una mappa `transform`: ogni chiave/valore deve essere una stringa dot-path
+ * di Style Dictionary non vuota (ad es. 'primary.100'), non un nome di custom property
+ * con trattini (ad es. 'primary-100') — vedi la motivazione della notazione qui sopra.
  * rationale above.
  * @param {unknown} map
  * @returns {Record<string,string>}
- * @throws {Error} if the map is not a plain object, or a key/value is invalid
+ * @throws {Error} se la mappa non è un oggetto semplice o una chiave/valore non è valido
  */
 export const normalizeTransformMap = (map) => {
   if (map === null || typeof map !== 'object' || Array.isArray(map)) {
@@ -102,22 +106,24 @@ export const normalizeTransformMap = (map) => {
 };
 
 /**
- * Expands the `transform` entries' `src` patterns into concrete file paths
- * and stores the file path -> rename map used by getSourceTransform(). Must
- * be called after registerLegacyTokensParser() and before any real build.
- * Maps from different entries touching the same file are merged; the build
- * fails only if two entries disagree on the destination of the same source
- * key.
+ * Espande i pattern `src` delle voci `transform` in percorsi di file concreti
+ * e memorizza la mappa percorso file -> mappa di rinomina usata da getSourceTransform().
+ * Va chiamata dopo registerLegacyTokensParser() e prima di qualsiasi build reale.
+ * Le mappe di voci diverse che toccano lo stesso file vengono unite; la build
+ * fallisce solo se due voci non concordano sulla destinazione della stessa chiave
+ * sorgente.
  * @param {import('./source-prefixes.mjs').TransformedSource[]} transformedSources
  * @returns {Promise<void>}
- * @throws {Error} if the same file gets two conflicting destinations for the same key
+ * @throws {Error} se lo stesso file riceve due destinazioni in conflitto per la stessa chiave
  */
 export const registerSourceTransforms = async (transformedSources) => {
   /** @type {Map<string, Record<string,string>>} */
   const map = new Map();
-  // Every destination seen for a given "from" key, across all files — used
-  // below to build globalRenames, and to detect the cross-file ambiguous
-  // case (same "from" key, different destination in a different file).
+  /*
+    Ogni destinazione vista per una data chiave "from", in tutti i file — usata
+    più sotto per costruire globalRenames e per rilevare il caso ambiguo tra file
+    (stessa chiave "from", destinazione diversa in un file diverso).
+  */
   /** @type {Map<string, Set<string>>} */
   const destinationsByFrom = new Map();
 
@@ -166,24 +172,24 @@ export const registerSourceTransforms = async (transformedSources) => {
 };
 
 /**
- * @returns {Map<string, string>} the flat from -> to map used to rewrite
- * {references} across the whole build (see token-rename-parser.mjs)
+ * @returns {Map<string, string>} la mappa piatta from -> to usata per riscrivere
+ * i {riferimenti} in tutta la build (vedi token-rename-parser.mjs)
  */
 export const getAllRenames = () => globalRenames;
 
 /**
  * @param {string|undefined} filePath  token.filePath
- * @returns {Record<string,string>|undefined} the rename map registered for that file, if any
+ * @returns {Record<string,string>|undefined} la mappa di rinomina registrata per quel file, se presente
  */
 export const getSourceTransform = (filePath) => (filePath ? transformByFile.get(filePath) : undefined);
 
-/** @returns {boolean} true if at least one file has a registered transform */
+/** @returns {boolean} true se almeno un file ha una transform registrata */
 export const hasRegisteredTransforms = () => transformByFile.size > 0;
 
 /**
- * Builds the RegExp matching exactly the concrete files that have a
- * registered transform, for the Style Dictionary parser `pattern` (see
- * token-rename-parser.mjs). Returns null if no file has one.
+ * Costruisce la RegExp che corrisponde esattamente ai file concreti che hanno una
+ * transform registrata, per il `pattern` del parser di Style Dictionary (vedi
+ * token-rename-parser.mjs). Restituisce null se nessun file ne ha una.
  * @returns {RegExp|null}
  */
 export const transformedFilesPattern = () => {