# ColdFusion 2025 Compatibility Migration

Usa questo reference quando il target runtime e' Adobe ColdFusion 2025. Questa modalita' riguarda la compatibilita' del codice con il runtime target; non sostituisce il workflow Provider/Consumer di `cross-version-migration.md`.

## Principi

1. Determina la versione ColdFusion sorgente quando disponibile.
2. Esegui assessment prima di modificare codice.
3. Distingui sempre provenienza della regola: Adobe, TESISQUARE o entrambe.
4. Applica fix solo se l'utente autorizza esplicitamente la modifica.
5. Non trasformare regex di detection in bulk replace non verificati.
6. Dopo ogni remediation esegui lint, test mirati e re-scan.
7. Se una regola legacy confligge con una rimozione CF2025, prevale il contratto del runtime target; segnala il conflitto.

## Precedence delle fonti

In caso di conflitto usa questo ordine:

1. documentazione Adobe aggiornata per stabilire se una feature esiste nel runtime CF2025;
2. regola TESISQUARE/Platform target-specific per il pattern applicativo certificato;
3. guida legacy interna solo se compatibile con il target;
4. inferenza agentica solo quando le fonti non chiudono il caso.

Esempio: Axis1 compare in guide storiche come opzione configurabile, ma Adobe lo dichiara rimosso in CF2025. Non proporre di riabilitarlo sul target 2025.

## Assessment statico

Dalla root del repository:

```bash
node skills/mcp-coldfusion-developer/scripts/scan-cf2025-compatibility.js --source-version 2021 <path>
```

Output JSON per automazione:

```bash
node skills/mcp-coldfusion-developer/scripts/scan-cf2025-compatibility.js --source-version 2021 --json <path>
```

Esclusione di una subtree generata:

```bash
node skills/mcp-coldfusion-developer/scripts/scan-cf2025-compatibility.js --source-version 2021 --exclude generated <path>
```

Exit code:

- `0`: nessun finding;
- `2`: finding presenti;
- `1`: errore di input o scansione.

Lo scanner e' read-only e analizza solo `.cfm` e `.cfc`. Le directory `.git`, `node_modules`, `vendor`, `dist`, `build` e `coverage` sono escluse di default.

## Classificazione remediation

### SAFE_AUTOFIX

Pattern meccanico con rischio basso, ma non autorizza automaticamente la modifica.

Esempi:

- `HTMLEditFormat()` -> `EncodeForHTML()` su call site sintatticamente semplice;
- rimozione `statusText` da `cfheader` mantenendo gli altri attributi.

Prima di applicare:

- verifica il boundary sintattico;
- evita match in stringhe/commenti;
- esegui lint dopo il fix.

### CONTEXTUAL_FIX

Richiede lettura del call site o del contratto dati.

Esempi:

- `ParameterExists()` -> `IsDefined()`;
- `URLEncodedFormat()` -> `EncodeForURL()`;
- `generateSecretKey("AES")` con lunghezza esplicita;
- cfsqltype legacy;
- `HSSFDateUtil`;
- `hash()` che dipende dall'algoritmo di default.

Non fare replace globale. Verifica argomenti opzionali, compatibilita' dei dati persistiti e semantica applicativa.

### SEMANTIC_REWRITE

Richiede ricostruzione del comportamento.

`new query()`:

- ricostruisci SQL, params, datasource, timeout, cache e metadata;
- migra a `QueryExecute(sql, params, options)` secondo coding standard locale;
- preserva result metadata e gestione errori.

`new http()`:

- preserva method, URL, headers, body, auth, timeout, proxy, binary/text handling e response result;
- migra a `cfhttp()` senza ridurre il contratto del call site.

### MANUAL_BLOCKER

Non esiste un fix generico sicuro.

Esempi:

- algoritmo `CFMX_COMPAT`;
- `ThreadTerminate`;
- Axis1;
- `cfschedule.requestTimeOut` quando il design dipende dall'attributo rimosso.

Produci handoff con impatto, alternative e test richiesti. Non marcare la migrazione come completata finche' il blocker non e' risolto o accettato esplicitamente.

## Regole Platform-specific con evidenza primaria

Lo scanner esegue detection guidata, senza autofix, sui soli path Platform canonici:

- `TS25-016` — `framework/cflib/gr_cfc/header.cfc`: il commit `cc81d0e79616006764fd5d786f1cc02290c48023` sostituisce il wrapper `HTMLEditFormat(maskParse(...))` con `maskParse(..., escapeSingleItems=true)` e rimuove il workaround che riapriva entita' HTML selezionate;
- `TS25-017` — `framework/cflib/lib/strutil.cfc`: lo stesso commit aggiunge `encodeItems=false` a `simpleTextParser`, `escapeSingleItems=false` a `maskParse` e propaga il flag per applicare `EncodeForHTML` ai singoli valori sostituiti, non alla maschera completa;
- `TS25-018` — `framework/cflib/gr_cfc/xgrid_common.cfc`: il commit `d07112fdd2abb9437271331130e85ad659765514` legge i metadata della query una volta e applica `EncodeForHTML` soltanto alle colonne `varchar`/`nvarchar`.

Questi finding sono `CONTEXTUAL_FIX`: descrivono il delta Platform certificato, ma non autorizzano una riscrittura. Verifica markup consentito, tipi restituiti dal datasource e comportamento applicativo prima di applicare la remediation.

Le trasformazioni `new query()` e `new http()` restano invece `SEMANTIC_REWRITE`: richiedono test su un runtime CF2025 reale per contratto SQL/metadata, request/response HTTP, error handling e side effect.

## Composizione con Cross-Version Migration

Se il task include sia trasferimento funzionale sia upgrade runtime:

1. usa `cross-version-migration.md` per Provider/Consumer, directory neutrale e tracking;
2. usa questo reference per assessment/remediation CF2025 sul codice che entra nel target;
3. non aggiungere regole CF2025 al tracking generico se non servono alla specifica iterazione;
4. il Consumer non deve marcare `ADDED`/`MERGED` come equivalente a "compatibile CF2025": sono stati distinti.

## Chiusura obbligatoria

Concludi con:

- versione sorgente e target;
- finding iniziali per categoria;
- fix applicati e non applicati;
- lint/test eseguiti;
- re-scan finale;
- blocker residui;
- elementi che richiedono test su istanza CF2025.

Per la matrice cumulativa delle versioni e le fonti, consulta [coldfusion-version-compatibility.md](coldfusion-version-compatibility.md).