# Arhitektuur

shikiphp muudab lähtekoodi teemastatud esiletõstetud HTML-ks, kasutades TextMate grammatikat ja VS Code teemasid, ilma PHP laiendusteta peale `json`/`mbstring`, Node'i käituskeskkonna ja natiivse Oniguruma sidumiseta. See leht võtab kokku töötlusahela; kogu normatiivne leping asub hoidlas failis `ARCHITECTURE.md`.

## Töötlusahel

```
source code
  └─ Highlighter::codeToTokens()
       ├─ Grammar\Registry        loads the grammar (+ its includes / embedded langs)
       ├─ Grammar\Tokenizer       line by line, driving an OnigScanner per rule state
       │     └─ Oniguruma\OnigScanner.findNextMatch()
       │           └─ Oniguruma\PatternConverter   Oniguruma pattern → JS regex
       │                 └─ Shikiphp\Regex (Parser + Matcher)   JS RegExp runtime
       ├─ Theme\Theme.match(scopeStack) → StyleAttributes   per token
       └─ Render\ThemedToken[]   (text + style) per line
  └─ Render\HtmlRenderer  → <pre class="shiki">…</pre>
```

Kõik toimingud kasutavad **UTF-16 koodiühikute** nihkeid — sama ühikuruumi nagu JS regulaaravaldiste mootor ja Shiki tokeniseerija. ASCII puhul võrdub see baidioffsetitega.

## Regulaaravaldiste käituskeskkond

Aluseks on `Shikiphp\Regex`, täielik puhas-PHP ECMAScripti regulaaravaldiste mootor, mis on **tarnitud lähtekoodist [`inline0/phasis`](https://github.com/inline0/phasis)** (puhas-PHP JavaScript mootor). See parsib JS-RegExp-i lähtekoodi koos lippudega ja teeb edasiotsinguid Oniguruma `onig_search` semantikaga.

## Oniguruma → JS teisendamine

TextMate grammatikad on kirjutatud Oniguruma-is. `Shikiphp\Oniguruma\PatternConverter` on PHP port teegist [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es): see teisendab Oniguruma mustri regulaaravaldiste mootorile sobivaks JS-RegExp-i lähtekoodiks ja lipustringiks. See on sama Oniguruma → RegExp-i tee, mida kasutab Shiki JavaScript regulaaravaldiste mootor; tänu sellele sobitub shikiphp selle mootori väljundiga nihke kaupa täpselt. Teisendaja käsitleb grammatikates kasutatavaid tegelikke konstruktsioone: POSIX-i klasse, ahneid kvantoreid ja aatomirühmi, tekstisiseseid lippe, nimetatud rühmi ja tagasiviiteid, Unicode omadusi ning muud.

## Skanner ja selle PCRE kiirtee

`Shikiphp\Oniguruma\OnigScanner` jäljendab `vscode-oniguruma` skannerit: see koostatakse iga reegli jaoks mustrite loendist ühe korra ning leiab vasakpoolseima vaste määratud alguspositsioonil või sellest edasi.

Puumatšija on korrektne, kuid aeglane, seega on skanneril **samaväärsusega kontrollitud PCRE kiirtee**, millel on kaks taset. `PcreTranslator` kirjutab teisendaja JS lähtekoodi ümber natiivseks PCRE mustriks ainult siis, kui saab tulemuse samaväärsust tõestada:

- **Täielik vaste.** Kui teisendus käitub matšijaga identselt, sealhulgas iga hõive puhul, käivitatakse muster otse PCRE abil. Sellest tasemest jäetakse välja nimetatud rühmad, tagasiviited, `\p{}`, `\b`, `\G`, aatomite emuleerimine ning hõived, mille JavaScript semantika erineb PCRE-st (kvantoriga rühma sees või tahavaates).
- **Ainult positsioon.** Kui erineda võivad ainult hõived, lubab teine teisendus need konstruktsioonid (`\b` ja `\B` täpsete ASCII tahavaadetena, aatomirühmad natiivse `(?>…)`-ina, `\p{…}` kui PCRE suudab selle kompileerida). PCRE leiab siis ainult järgmise vaste asukoha ning matšija käivitatakse selles nihkes uuesti, et saada õiged hõived. Ka siin jäetakse tagasiviited ja `\G` välja.

Kõik muu käivitatakse ainult matšijaga. Paketis kaasas olevate grammatikate puhul aadressil Shiki 3.23.0 käivitatakse umbes 39% 14,234 erinevatest mustritest täielikult PCRE abil, umbes 57% kasutab positsioonitaset ja umbes 4% jääb matšija kasutada. Liigitust kontrollib hoidlas olev arendustööriist (`bin/.oracle-tools/pcre-equivalence.php`), mis võrdleb kiirteed matšijaga — indeksit, lõppu ja esimesel tasemel iga hõive vahemikku — stsenaariumide sisendite ning sünteetiliste stringide korral, lubamata ühtegi erinevust.

## Grammatika ja teema

- **Grammatika** (`Shikiphp\Grammar`) on teegi `vscode-textmate` täpne port: `Registry` lahendab grammatikad ulatuse nime järgi (sealhulgas `include` viited, põimitud keeled ja injektsioonid) ning `Tokenizer` haldab reeglite ja ulatuste pinusid rida-realt.
- **Teema** (`Shikiphp\Theme`) kannab üle teegi `vscode-textmate` teemade sobitamise: esiplaani ja fondi laad lahendatakse ulatuse valija spetsiifilisuse ja ülemulatusse sobitamise põhjal.

## Renderdamine

`Shikiphp\Render\HtmlRenderer` koostab täpselt sama `pre.shiki > code > span.line >
span` HAST-puu nagu Shiki ning serialiseerib selle. Ühe teema režiimis väljastatakse lihtvärvid; kahe teema režiimis väljastatakse `--shiki-light` / `--shiki-dark` CSS muutujad.

## Kontrollitud teegi Shiki alusel

Shiki ise on etalon, mis on seotud versiooniga `shiki` 3.23.0 ja selle JavaScript regulaaravaldiste mootoriga. `scenarios/` kataloog sisaldab **214** testandmestikku, millest igaüks on üks sisend ühes keeles ja ühes kujunduses; kokku katavad need 167 253 kaasasolevast grammatikast, `lang: 'ansi'` ja kõik 65 kujundust. `bin/test-regression` tõstab igaüks esile mõlema mootoriga ja kontrollib, et HTML oleks pärast algus- ja lõputühikute eemaldamist identne. Valikuid ja teisendajaid kontrollivad pariteeditestid, mis võrdlevad väljundit sama Shiki ja `@shikijs/transformers` 4.2.0 põhjal jäädvustatud väljundiga. Mitte mingil juhul ei tohi esiletõstmise väljund taandareneda võrreldes versiooniga Shiki.