Compilatore TypeScript -> miniSL

English version

Un sistema completo per la traduzione di TypeScript nel linguaggio miniSL composto da tre componenti principali: Annotator, Extractor e Checker. Le componenti possono essere usate singolarmente o tutte insieme attraverso la pipeline definita.

Struttura del Progetto

prgTesi/
├── extractor/          # Componente per l'estrazione del codice miniSL
│   ├── annotatedCode/  # File di input annotati
│   ├── config.json     # Configurazione extractor
│   ├── extractor.ts    # Codice principale
│   └── output.txt      # Output generato
├── annotator/          # Componente per l'annotazione automatica
│   ├── inputCode/      # File di input TypeScript
│   │   └── input.ts    # File di input principale
│   ├── config.json     # Configurazione annotator
│   ├── annotator.ts    # Codice principale
│   └── output.txt      # Annotazioni generate
├── miniSLChecker/      # Componente per la verifica del codice miniSL
│   ├── miniSLGrammar/  # Grammatica ANTLR
│   ├── checker.ts      # Codice principale
│   └── miniSLCode.txt  # Codice miniSL da verificare
├── .vscode/           # Configurazione VS Code
│   ├── launch.json    # Configurazione debug
│   └── tasks.json     # Task VS Code
├── package.json       # Configurazione principale del progetto
├── Makefile          # Automazione con Make (Windows/Linux/macOS)
├── build.bat         # Script batch per Windows
├── .gitignore        # File da ignorare in git
└── README.md         # Questo file

Installazione

Si consiglia l'utilizzo di VS Code, in quanto sicuramente supportato.

Prerequisiti

• Node.js (versione 16 o superiore)
• npm
• Make (per Linux/macOS/Windows con WSL o MinGW)
• Git (per version control)

Setup Rapido

Usando Make (raccomandato):

make setup

Manuale:

npm install
make install  # Installa dipendenze di tutti i componenti
make build    # Compila tutti i componenti

Componenti

1. Extractor

Estrae il codice miniSL dal codice annotato TypeScript.

Uso singolo:

# Con Make
make build-extractor
make extract INPUT_FILE=../annotator/output.txt ENTRY_POINT=main

# Diretto
cd extractor
npm run build
node dist/extractor.js ../annotator/output.txt main

2. Annotator

Genera automaticamente le annotazioni miniSL per il codice TypeScript.

Uso singolo:

# Con Make
make build-annotator
make annotate INPUT_FILE=inputCode/input.ts ENTRY_POINT=main

# Diretto
cd annotator
npm run build
node dist/annotator.js inputCode/input.ts output.txt main

Note: L'annotator prende in input file TypeScript parzialmente annotati (con solo call e defCall), un entry point specifico, e genera file completamente annotati salvati come output.txt.

3. Checker

Verifica la correttezza sintattica del codice miniSL.

Uso singolo:

# Con Make (file di default)
make build-checker
make check

# Con Make (file personalizzato)
make check INPUT_FILE=path/to/minisl/file.txt

# Diretto
cd miniSLChecker
npm run build
node dist/checker.js path/to/minisl/file.txt

Note: Il checker accetta qualsiasi file contenente codice miniSL. Il file di default è l'output dell'extractor, ma può essere personalizzato per testare file miniSL specifici.

Pipeline Completa

Il sistema miniSL segue questa pipeline integrata:

Flusso di Lavoro Principale

File TypeScript            File TypeScript            Codice miniSL
parzialmente annotato  →    completamente annotato  →  + Checking
(input.ts)                  (output.txt)               (output.txt)
       ↓                           ↓                         ↓
   ANNOTATOR               →     EXTRACTOR           →    CHECKER

Dettaglio del processo:

1. ANNOTATOR: input.ts → annotator/output.txt (annotazioni complete)
2. EXTRACTOR: annotator/output.txt → extractor/output.txt (codice miniSL)
3. CHECKER: extractor/output.txt → verifica sintattica (output console)

Esegue tutti e tre i componenti in sequenza:

Usando Make:

make pipeline
# oppure con parametri personalizzati
make pipeline ENTRY_POINT=myFunction

Manuale:

# Step 1: Annotazione completa (partial → complete annotations)
make annotate ENTRY_POINT=main

# Step 2: Estrazione miniSL (complete annotations → miniSL code)
make extract INPUT_FILE=../annotator/output.txt ENTRY_POINT=main

# Step 3: Verifica sintattica
make check

Comandi Make Disponibili

Tutti i comandi sono stati testati e verificati su Windows con PowerShell.

Comando	Descrizione	Esempio
make help	Mostra l'aiuto con tutti i comandi disponibili	make help
make install	Installa tutte le dipendenze	make install
make build	Compila tutti i componenti	make build
make clean	Pulisce i file di build	make clean
make setup	Installazione + build completo	make setup
make pipeline	Esegue la pipeline completa (annotate → extract → check)	make pipeline
make annotate	Esegue l'annotator con entry point specificato	make annotate ENTRY_POINT=main
make extract	Esegue l'extractor	make extract ENTRY_POINT=main
make check	Esegue il checker su file miniSL specificato	make check INPUT_FILE_CHECKER=myfile.txt
make check-standalone	Esegue il checker su miniSLCode.txt predefinito	make check-standalone
make dev-annotator	Build + esecuzione rapida annotator	make dev-annotator
make dev-extractor	Build + esecuzione rapida extractor	make dev-extractor
make dev-checker	Build + esecuzione rapida checker	make dev-checker
make test	Esegue test completo su tutti i componenti	make test

Comandi NPM Disponibili

Nota: I comandi Make sono raccomandati. I comandi NPM sono disponibili per compatibilità ma potrebbero non gestire tutti i percorsi correttamente.

Comando	Descrizione
npm run build	Compila tutti i componenti (usa make build invece)

Parametri Personalizzabili

Il sistema supporta parametri flessibili per tutti i componenti.

Variabili di Input Disponibili

Variabile	Componente	Default	Descrizione
INPUT_FILE	Checker/Annotator/Extractor	myDir\myFileName.txt	Path del file che fa da input al componente
ENTRY_POINT	Annotator/Extractor	main	Funzione entry point per l'analisi

Esempi di Uso con Parametri Personalizzati

Annotator con file personalizzato:

make annotate INPUT_FILE=./inputCode/input3.ts ENTRY_POINT=myFunction

Extractor con file personalizzato:

make extract INPUT_FILE=./myAnnotatedFile.ts ENTRY_POINT=customEntry

Checker con file miniSL personalizzato:

make check INPUT_FILE=path/to/mycode.minisl

Pipeline completa con entry point personalizzato:

make pipeline ENTRY_POINT=customFunction

Combinazione di parametri personalizzati:

make pipeline INPUT_FILE=./inputCode/input4.ts ENTRY_POINT=specialFunction

Sviluppo e Debug

Debug in VS Code

Il progetto include configurazioni per VS Code:

Configurazioni disponibili:

• Debug Annotator: Debug del processo di annotazione
• Debug Extractor: Debug del processo di estrazione
• Debug Checker: Debug del processo di verifica

Per usare il debug:

1. Apri VS Code nella cartella del progetto
2. Vai a "Run and Debug" (Ctrl+Shift+D)
3. Seleziona la configurazione desiderata
4. Premi F5 per avviare il debug

Build Singolo Componente

# Extractor
cd extractor && npm run build

# Annotator  
cd annotator && npm run build

# Checker
cd miniSLChecker && npm run build

Modalità Sviluppo

# Build rapido + esecuzione
make dev-extractor
make dev-annotator
make dev-checker

Test

make test    # Testa tutti i componenti con file di esempio

Il comando test Esegue:

1. Build di tutti i componenti
2. Test dell'annotator con file di default
3. Test dell'extractor sull'output dell'annotator
4. Test del checker sull'output dell'extractor
5. Test standalone del checker su miniSLCode.txt

Output di esempio del test:

• Annotator: genera annotazioni complete e salva in output.txt
• Extractor: estrae codice miniSL e salva in output.txt
• Checker: verifica sintattica con messaggio "Checking completed successfully" o errori riscontrati

File Importanti

File di Input Predefiniti

• annotator/inputCode/input.ts - File di input principale per l'annotator
• annotator/inputCode/input4example.ts - Esempio di file parzialmente annotato

File di Output

• annotator/output.txt - Output dell'annotator (annotazioni complete)
• extractor/output.txt - Output dell'extractor (codice miniSL)

File di Configurazione

• annotator/config.json - Configurazione per l'annotator
• extractor/config.json - Configurazione per l'extractor
• miniSLChecker/miniSLGrammar/miniSLGrammar.g4 - Grammatica ANTLR per miniSL
• annotator/dist/ - Codice compilato dell'annotator
• miniSLChecker/dist/ - Codice compilato del checker
• File di output personalizzabili tramite parametri

Troubleshooting

Errori di Compilazione TypeScript

# Pulisci e ricompila
make clean
make build

Errori di Dipendenze

# Reinstalla tutte le dipendenze
make clean
make install

Problemi con Make su Windows

Make è supportato su Windows con WSL, MinGW, o strumenti simili. Se non disponibile:

1. Installa Make tramite chocolatey:

   choco install make

2. Oppure usa comandi diretti:

   # Setup manuale
   npm install
   cd annotator && npm install && npm run build && cd ..
   cd extractor && npm install && npm run build && cd ..
   cd miniSLChecker && npm install && npm run build && cd ..

Git e Version Control

Il progetto include un .gitignore configurato per:

• File node_modules
• Directory di build (dist/)
• File di output della pipeline (*.txt)
• File temporanei e cache
• File di configurazione locali

Per inizializzare git:

git init
git add .
git commit -m "Initial Compiler setup"

Contribuire

1. Fork del repository
2. Crea un branch per la tua feature (git checkout -b feature/nuova-feature)
3. Testa le modifiche con make test e make pipeline
4. Commit le modifiche (git commit -am 'Aggiunge nuova feature')
5. Push al branch (git push origin feature/nuova-feature)
6. Crea una pull request