# CLI

Phasis sisältää kolme pääasiallista suoritettavaa ohjelmaa paketissa `bin/`:

- **`bin/phasis`** — suorita JavaScript-tiedostoja, arvioi komentoriviltä annettua lähdekoodia ja tulosta AST-puut.
- **`bin/test262`** — suorita virallinen ECMAScript-yhteensopivuustestipaketti ohjelmaa Phasis vasten.
- **`bin/wpt`** — suorita Web Platform Tests -testitapaukset ohjelmaa Phasis vasten (URL, merkistökoodaus, fetch, otsakkeet, Blob, AbortSignal, virrat, …).

Kun `composer require phasis/phasis` on asennettu, paketista `vendor/bin/` linkitetään ohjelmat `bin/phasis` ja `bin/test262`. Vain `bin/phasis` toimii siellä: `bin/test262` tarvitsee `test262`-git-alimoduulin ja testiluokat, joita paketti Composer ei sisällä, eikä ohjelmaa `bin/wpt` toimiteta lainkaan. Suorita molemmat Phasis-tietovaraston kloonista.

## bin/phasis

```
phasis <file.js> | phasis -e '<source>' | phasis --ast <file.js>
```

Nämä kolme muotoa kattavat koko käyttöliittymän. Käytettävissä ei ole REPL:iä, vakiosyötettä eikä moduulilippua.

### Suorita tiedosto

```bash
./vendor/bin/phasis script.js
```

Suorittaa `script.js`-tiedoston tavallisena skriptinä. Kun suoritus päättyy, kaikki, mitä skripti kirjoitti toiminnoilla `console.log` (sekä `console.error`, `console.warn`, …), tulostetaan kerralla vakiotulosteeseen. Jos skripti heittää virheen, virheilmoitus tulostuu vakiovirheeseen ja paluuarvo on 1.

Tiedosto jäsennetään aina tavallisena skriptinä, joten tiedosto, jossa on `import` / `export` tai ylimmän tason `await`, aiheuttaa SyntaxError-virheen. Suorita ES-moduuli käyttämällä toimintoa `Engine::evalAsModule()` lähteessä PHP (katso [API-viite](https://phasis.inline0.dev/fi/docs/api#evalasmodule)) tai niputa koodi ensin.

### Arvioi lähdekoodi

```bash
./vendor/bin/phasis -e 'console.log(Math.PI * 2)'
# 6.283185307179586
```

Argumentti arvioidaan kokonaisena skriptinä. Vain `console`-tuloste näytetään; viimeisen lausekkeen arvoa ei tulosteta, joten `phasis -e '1 + 2'` ei tulosta mitään.

### Tulosta AST-puu

```bash
./vendor/bin/phasis --ast script.js
./vendor/bin/phasis -e 'a + b' --ast
```

Tulostaa jäsennyspuun muodossa JSON (kahden välilyönnin sisennyksellä). Hyödyllinen jäsentimen ongelmien selvittämiseen tai ohjelman Phasis päälle rakennettavien työkalujen luomiseen. Ohjelmallista käyttöä varten käytä [jäsentimen API](https://phasis.inline0.dev/fi/docs/parser).

## bin/test262

`bin/test262` suorittaa ohjelmaa Phasis vasten virallisen [test262-testipaketin](https://github.com/tc39/test262). Se toimii hyödyllisenä regressiotestien ajajana muutoksiin osallistuttaessa. Paketin `COMPAT.md` kattavan testipaketin tilannevedoksen tuottaa siihen liittyvä ohjelma `bin/compat-report`, jota manuaalisesti käynnistetty CI-matriisi ajaa osissa.

### Suorita yksi luokka

```bash
./bin/test262 --category built-ins/Array
```

### Suorita koko testipaketti

```bash
./bin/test262 --jobs 4
```

### Asetukset

Suoritin lukee tiedoston `config/support.php` projektin juuresta. Sen `test262_skipped_features`-luettelo on tyhjä: mitään test262-ominaisuutta ei ohiteta, mukaan lukien `tail-call-optimization`. Tiedostossa luetellaan myös luokat ja testit, jotka on suoritettava eristyksissä.

Testipaketti itsessään on `test262`-git-alimoduuli; suorita `git submodule update --init test262` kloonauksen jälkeen. Ilman sitä suoritin päättyy ilmoitukseen "test262 suite not found".

### Muita hyödyllisiä valitsimia

| Valitsin | Tarkoitus |
|---|---|
| `--failures` | tulosta yksi rivi kutakin epäonnistunutta testiä kohden |
| `--limit N` | pysähdy ensimmäisen N testin jälkeen |
| `--jobs N` | suorita N testiä rinnakkain |
| `--files-from file` | suorita vain tiedostossa `file` luetellut testit |
| `--json` | tulosta koneellisesti luettava yhteenveto vakiotulosteeseen |
| `--no-progress` | älä tulosta edistymisriviä |

Katso uusimmat tulokset kohdasta [Yhteensopivuus](https://phasis.inline0.dev/fi/docs/compatibility).

## bin/wpt

`bin/wpt` suorittaa ohjelmaan `tests/Wpt/fixtures/` tuodut Web Platform Tests -testitapaukset. Testijoukko kattaa alueet URL, merkistökoodauksen, atob/btoa:n, structuredClone-toiminnon, performance-toiminnon, Headers-, Blob/File-, AbortController/Signal-, EventTarget- ja FormData-toiminnot, WHATWG Streams -virrat, toiminnon `crypto`/`SubtleCrypto` koko rajapinnan, toiminnot `fetch`/`Request`/`Response` ja `XMLHttpRequest`/`XMLHttpRequestUpload` sekä toiminnon `WebSocket`. Aluekohtainen läpäisyprosenttitaulukko on kohdassa [Web-rajapinnat](https://phasis.inline0.dev/fi/docs/compatibility/web-apis).

### Suorita kaikki tuodut testitapaukset

```bash
./bin/wpt
```

### Suorita yksi luokka

```bash
./bin/wpt --category headers
./bin/wpt --category streams
./bin/wpt --category blob
```

### Alitestien tuloste

```bash
./bin/wpt --category abort --verbose
```

Tulostaa jokaisen alitestin (PASS / FAIL) kussakin testitapauksessa sekä epäonnistumisten assertion-viestit.

### JSON-tuloste

```bash
./bin/wpt --json
```

Koneellisesti luettava läpäisy-/hylkäysyhteenveto CI-putkia tai ohjelmoitua analyysia varten.

### Huomautuksia

- Fetch-toimintoa käyttävät testitapaukset käynnistävät automaattisesti mukana toimitetun WPT-testipalvelimen osoitteessa `tests/Wpt/fetch-server.php` portissa `127.0.0.1:8765` ja sammuttavat sen suorituksen jälkeen.
- Kohdan `tests/Wpt/testharness-shim.js` testiharness-sovitin toteuttaa vain tuoduissa testitapauksissa käytetyt WPT:n API-toiminnot (noin 400 riviä verrattuna täyden version noin 3 000-riviseen toteutukseen `testharness.js`).
- Lähdetestitapaukset ovat polussa `tests/Wpt/upstream/` (gitin ohittama harva klooni [web-platform-tests/wpt](https://github.com/web-platform-tests/wpt)). Tuo lisää kopioimalla tiedostot `.any.js` lähteestä `upstream/<area>/` kohteeseen `fixtures/<category>/`, niin suoritin ottaa ne automaattisesti käyttöön.

## Palautuskoodit

`bin/phasis` palauttaa jommankumman kahdesta paluukoodista:

| Koodi | Merkitys |
|---|---|
| `0` | onnistuminen — skripti suoritettiin loppuun (myös arvon `--ast` jälkeen) |
| `1` | mikä tahansa muu: sieppaamaton JS-poikkeus, syntaksivirhe, puuttuva tiedosto tai virheelliset argumentit |

Skriptin virheilmoitukset tulostetaan vakiovirheeseen. Virheellisistä argumenteista ja puuttuvista tiedostoista tulostetaan käyttöohje vakiovirheeseen.

## Resurssirajat

`bin/phasis` toimii moottorin oletusasetuksilla, eikä rajoille ole valitsimia: 4,096 kehyksen JS-kutsupinon yläraja, 8,192 kehyksen suoja transpiloiduille sulkeumille ja oletusarvoinen `maxLoopIterations` 100,000, joka koskee vain puukävelytulkin suorittamaa koodia (katso [API: setLimit](https://phasis.inline0.dev/fi/docs/api#setlimit)). Aikarajaa ei ole; kääri komento `timeout`-komentoon, jos komentosarja ei välttämättä pääty.