# Guida per chi sviluppa

Come lavorare sul codice e sui doc. Per capire com'è fatto il programma parti da
[`architettura.md`](architettura.md); per rilasciare vedi [`rilascio.md`](rilascio.md).

## Requisiti

- Windows e [.NET 10 SDK](https://dotnet.microsoft.com/download).
- Accesso alla share `X:\` solo per indicizzare davvero; i test non ne hanno bisogno.
- Node.js (per `npx markdownlint-cli2`, solo per i doc).

## Build e avvio

```powershell
cd PrepStep
dotnet build -c Release
dotnet run -c Release
```

In sviluppo `cad_index.db` si cerca nella cartella di build, non nella radice del repo: vedi
[`db-cad-index.md`](db-cad-index.md#come-lapp-trova-il-db-allavvio).

## Test

```powershell
cd PrepStep.Tests
dotnet test
```

I test xUnit chiamano gli `internal` del progetto principale grazie a `InternalsVisibleTo`. I
`.asm` dei test si costruiscono byte per byte con piccoli helper invece di versionare file
binari: ogni caso strano trovato sulla share diventa un test minimale. Elenco dei file di test in
[`architettura.md`](architettura.md#test).

## Script standalone

Si lanciano dalla **root del repo**, mai da dentro `PrepStep/` (che è un `WinExe`: `dotnet run`
avvierebbe la GUI e resterebbe bloccato). Elenco in
[`architettura.md`](architettura.md#script-standalone-scripts).

```powershell
dotnet run scripts/Query.cs -- cad_index.db "SELECT COUNT(*) FROM files"
```

## Documentazione come codice

I doc stanno in git, si modificano nello stesso commit del codice e si verificano a mano:

```powershell
dotnet run scripts/CheckDocs.cs   # link, ancore, versione/CHANGELOG, copertura dei doc
npx markdownlint-cli2             # stile Markdown (.markdownlint-cli2.jsonc)
```

Regole di scrittura:

- **Una sola fonte per ogni informazione**, altrove un link (tabella in [`README.md`](README.md)).
- **Ogni doc ha un solo scopo** (Diátaxis): non mescolare istruzioni, riferimento e motivazioni.
- Un cambiamento strutturale (fasi, formato `.asm`, schema DB, criterio di scelta di un file)
  aggiorna i doc e il CHANGELOG **nello stesso commit**.
- Se la modifica nasce da un fallimento reale di Creo scrivi **il sintomo**: i messaggi di Creo
  non nominano il file né la causa (esempio: §7.3-7.5 di
  [`formato-asm-record.md`](formato-asm-record.md)).
- Una scelta con alternative reali non banali merita una voce in
  [`decisioni/`](decisioni/README.md).
- Un nuovo `.cs` va descritto in `architettura.md` e un nuovo doc elencato in `docs/README.md`:
  `CheckDocs.cs` lo verifica.