prep-step/docs/formato-asm.md

# Come leggere un .asm Creo per dedurne i componenti

Il file `.asm` di Pro/ENGINEER-Creo è un formato binario proprietario, non
documentato pubblicamente. Non esiste un parser strutturale completo in questo
progetto: l'estrazione dei componenti si basa su un'euristica testuale,
validata a mano confrontando l'output con l'albero reale mostrato da Creo.
Questo documento riassume cosa si è osservato e i suoi limiti.

## Struttura osservata

Il file contiene, frammentate tra dati binari, molte coppie testuali del tipo

```
<nome_campo>\x00<valore>\x00
```

in encoding a 1 byte per carattere (Latin1/ASCII), es.:

```
6d 6f 64 65 6c 5f 6e 61 6d 65 00 39 30 34 34 32 30 37 30 36 31 5f 43 30 31 23 41 46 30 00
m  o  d  e  l  _  n  a  m  e \0 9  0  4  4  2  0  7  0  6  1  _  C  0  1  #  A  F  0 \0
```

I codici dei componenti (propri e sotto-componenti) compaiono come stringhe
ASCII leggibili in diversi campi ricorrenti:

- `model_name`, `generic_name`, `inst_name`, `gen_name`, `feat_name`,
  `family_name`, `name` — metadati associati a un modello referenziato.
- `Componente ID N (<codice>.PRT|.ASM)` — riga di placement: `N` è un ID
  progressivo assegnato da Creo al componente posizionato nell'assieme.
- `<codice>#AF0` — riferimento con suffisso di versione/configurazione.

Un codice reale compare **più volte** nel file (una per feature/placement
diverso); rumore binario che assomiglia casualmente a un codice compare quasi
sempre una sola volta. Questa è la base del filtro in
[`AssemblyComponentScanner.cs`](../CadSearchGui/AssemblyComponentScanner.cs)
e in [`scripts/ExtractCreoStrings.cs`](../scripts/ExtractCreoStrings.cs):

```
regex:        \b\d{8,12}(?:_[A-Za-z]\d{2,4}|[A-Za-z]{0,2})\b
occorrenze:   >= 2
```

## Falsi positivi noti

**ID di viste salvate.** Il pattern `ModelView#<numero>` (es.
`ModelView#1073741828`) genera candidati a 10 cifre indistinguibili da un
codice reale per forma, ma sono ID interni di viste orientate salvate, non
componenti. Si escludono con un lookbehind negativo sulla regex:
`(?<!ModelView#)`.

**Il codice dell'assieme stesso.** Il proprio codice compare spesso decine di
volte nei metadati (`CODICE`, `part_table`, `STAMPIGLIATURA`, ecc.) e supera
quindi la soglia di occorrenze. Va escluso esplicitamente confrontandolo con
il codice derivato dal nome del file in ingresso (`nomefile.split('.')[0]`).

**Riferimenti fantasma a codici superati/rinominati.** Caso osservato:
`9244207061.asm` contiene un riferimento a `9044207061` (stesso numero, prima
di una rinumerazione) con la stessa identica struttura sintattica di un
componente vero — `Componente ID 46 (9044207061.ASM)`, più i campi
`model_name`/`generic_name` corrispondenti. Il codice `9044207061` esiste
davvero nell'indice CAD (il file vecchio non è stato eliminato dalla share),
quindi supera anche una validazione incrociata contro il DB. Non è però un
componente realmente presente nell'albero mostrato da Creo per quell'assieme
(confermato aprendo il file in Creo).

Questo caso **non è distinguibile a livello testuale**: la sintassi è
identica a quella di un placement reale. Nessuna euristica sulla stringa
riesce a discriminarlo in modo affidabile senza rischiare di scartare
componenti veri con pattern simili altrove. Se ricompare, l'unica verifica
sicura resta l'apertura manuale in Creo del sotto-assieme sospetto.

## Viti/dadi/rosette normalizzati (family table UNI)

I componenti di minuteria standard (viti, dadi, rosette UNI) sono definiti in
Creo come **family table**: un file generico (es. `uni6592.prt`) con tante
righe/istanze quante sono le varianti dimensionali. Nel binario dell'assieme
compaiono così:

```
Componente ID 28755 (R6--_-_U6592<UNI6592>.PRT)
```

`R6--_-_U6592` è il nome della singola istanza (riga della family table), **non
un file separato su disco** — sulla share esiste solo `uni6592.prt.<versione>`
(verificato in `Unificati/`). Cercare l'istanza intera nell'indice fallisce
sempre; va estratto solo il contenuto tra `<` e `>` (`UNI6592`), che coincide
col nome del file generico realmente indicizzato:

```
regex aggiuntiva:  (?<=<)UNI\d+(?=>)
```

Implementata sia in [`scripts/ExtractCreoStrings.cs`](../scripts/ExtractCreoStrings.cs) sia in
[`AssemblyComponentScanner.cs`](../CadSearchGui/AssemblyComponentScanner.cs) (fase "Trova componenti
referenziati" dell'app).

## Risoluzione ricorsiva dell'albero

Un `.asm` referenzia solo i propri sotto-componenti diretti, non l'intero
albero annidato. Per ricostruire la distinta base completa serve una BFS:

1. Estrarre i codici candidati dal file corrente (euristica sopra).
2. Per ogni codice, cercarlo nell'indice `cad_index.db`
   (`files_ultima_versione`) per sapere se è un `.prt` (foglia) o un `.asm`
   (da accodare alla coda per essere scansionato a sua volta).
3. Un codice non trovato nell'indice va scartato/segnalato: o è rumore
   binario, o è un componente non ancora indicizzato.

Stessa logica in tre punti del codice, con scopi diversi:

- [`AssemblyComponentScanner.EstraiCodiciReferenziati`](../CadSearchGui/AssemblyComponentScanner.cs) — solo estrazione dei candidati da un file.
- [`Form1.AssiemeCompleto`](../CadSearchGui/Form1.cs) — BFS per verificare se un assieme è completo nell'indice (fase "Verifica completezza").
- [`scripts/ExtractCreoStrings.cs`](../scripts/ExtractCreoStrings.cs) — stesso BFS, standalone, per generare un `BOM.txt` da riga di comando.

## Strumento di analisi manuale

[`scripts/Analyze.cs`](../scripts/Analyze.cs) stampa il contesto testuale ed
esadecimale attorno a ogni occorrenza di un pattern in un file binario — usato
per tutte le osservazioni di questo documento:

```powershell
dotnet run scripts/Analyze.cs -- raw/9244207061.asm.1 "9044207061"
```

Utile per verificare a mano un nuovo falso positivo prima di modificare la
regex o l'esclusione nello script di estrazione.