Sait kshana.dev

web/ on puu, mida GitHub Pages serveerib aadressil https://kshana.dev: lehed (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), dokumentatsioon kataloogi docs/ all ja Kshana Studio kataloogi studio/ all (serveeritud aadressil https://kshana.dev/studio/), rakendus, mis käitab mootorit brauseris WebAssemblyna (WASM) ilma serveripoolse arvutuseta ja midagi üles laadimata. Studios on ühe mootori kaks vaadet: lihtne vaade (studio/index.html, vastus esmalt tavasõnadega) ja täpsem vaade (studio/advanced/index.html, täielik armatuurlaud), mis jagab lihtsa vaate mootorit, töölist, mooduleid ja andmeid väljade <base href="../"> kaudu.

Alates 0.35.0 on Studios neli lisavaadet, igaüks oma lehena väljaga <base href="../">, ilma otsinguindekseerimiseta, ja sünteetiliste näidiste kaustaga, mida selle test loeb:

studio/trust/: mereline usaldusvaade, laeva asukohavoo vastuvõtja usaldusskoor, demotrajektooriga failis trust/demo/.
studio/training/: meeskonna koolituse debrief, mis taasesitab sünteetilist NMEA-d segamise, drag-off, ajaspuufimise või taasesituse sündmusega (training/demo/).
studio/interference/: häirekaart ja marsruudi eksponeeritus (interference/demo/).
studio/tools/: üks leht tööriistakaartidest koos näidetega (tools/examples/, tools/samples/), sealhulgas allkirjastatud tõendipaketid (#evidence), test-bench eksport (#bench), compliance kaardistus (#compliance), Galileo OSNMA kontroll (#osnma) ja tehisintellekti assistendi kanalid (#ai).

Kust failid pärinevad#

Siin elab kolme liiki faile ja neid muudetakse kolmel erineval viisil.

Porditud failid. Lehed, docs/, css/, js/, assets/, saidi andmed kataloogis data/ (land.json, search.json, series.json) ja kõik kataloogi studio/ all kirjutab web/tools/port_site.py saidi ehitusest ja Studio lähtekoodist. PORT-MANIFEST.json loetleb igaühe koos selle SHA-256 (Secure Hash Algorithm, 256-bitine) kontrollsummaga. Neid ei tohi siin muuta: site.test.mjs kukub käsitsi muudatuse peale läbi. Muuta tuleb lähtekoodi ja port käivitada uuesti:
```
python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder>
python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder> --check
```
Port on deterministlik: teine käivitus ei kirjuta midagi ja --check väljub väärtusega 1, kui web/ ei ole see, mida port kirjutaks. See kannab saidi ehituse indekseerimisfailid muutmata üle (iga lehe kanooniline, sotsiaalkaardi ja schema.org sildid, robots.txt, sitemap.xml, llms.txt, llms-full.txt), kontrollib neid, kirjutab legacy-redirects.js, 404.html ja suunamislehe Studio vanal aadressil (playground/index.html, aadressile /studio/) ning suunab iga lehe kohalikele fontidele ja skriptiteekidele (allpool).
Failid, mida web/ omab. Need on omaette allikad ja port ei puuduta neid kunagi:
- capabilities.json on võimekuskaartide ja standardiruudustiku struktureeritud allikas. Muuta tuleb seda, mitte HTML-i.
- data/verification-matrix.json on genereeritud (cargo run --bin gen_validation_artifacts) ja kinnitatud failiga tests/verification_artifacts_doc_sync.rs; seda ei tohi käsitsi muuta. data/card-matrix-map.json, data/oracle-references.json ja data/standards-matrix-map.json on käsitsi hooldatud vasted, mida sama test kontrollib genereeritud maatriksi vastu. Studio koopiad kataloogi studio/data/ all on need failid bait baidi haaval.
- og-card.svg, og-card.png ja og-card.rendered-from.json on sotsiaalkaart (python3 tools/gen_og_card.py).
- CNAME, .well-known/security.txt, favicon.svg.
- fonts/ ja vendor/: fondifailid ja skriptiteek, mida lehed kasutavad, korra alla toodud käsuga tools/fetch_third_party.py ja sisse kirjutatud (vt „Kolmandate osapoolte päringuid pole“).
- build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs ja tools/.
Ehitusväljundid, git-ignoreeritud ja toodetud käsuga build.sh: pkg/ (pakett wasm-pack, millest ehitatakse ka npm pakett), studio/pkg/ (sama pakett seal, kus Studio selle impordib) ja scenarios/ (iga etalonstsenaarium aadressil, kust varasem ühelehene sait neid serveeris).

Ehitamine ja kohalik serveerimine#

./web/build.sh                     # compiles the WASM module and stages it for the Studio
python3 -m http.server -d web 8000 # serve over HTTP (required for WASM)
# open http://localhost:8000/

Ilma WASM tööriistaketita valmistab KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh kompileerimise asemel ette olemasoleva paketi. Pages töövoog ei kasuta seda kunagi.

Testid#

node web/smoke.mjs                 # the WASM bindings (needs web/pkg)
node web/site.test.mjs             # the ported tree: manifest, version, counts, links, inline JSON
node web/tools/inline-json.test.mjs  # the guard for corrupt inline page data (an unescaped version bump)
node web/legacy-urls.test.mjs      # every old kshana.dev address still resolves
for f in web/studio/lib/*.test.mjs; do node "$f"; done   # the Studio's modules

Iga moodul kataloogis studio/lib/ on puhas loogika vastava *.test.mjs-ga; Studio DOM (Document Object Model, lehe elemendipuu) juhid on studio/app.js (lihtne vaade) ja studio/advanced.js (täpsem vaade). Pidev integreerimine käivitab neist igaühe eraldi sammuna ja kukub läbi, kui kataloogi web/ testifailil pole sammu.

Kolmandate osapoolte päringuid pole#

kshana.dev serveerib oma fonte, stiile ja skripte ise. Leht ei tee päringut fondihosti ega skriptihosti poole, nii et külastaja aadressi ei anta kellelegi edasi.

Sait ja Studio on kirjutatud Google Fontsi ja skriptihosti vastu. Port asendab iga lehe Google Fontsi lingi vastava stiililehega kataloogis fonts/ (samad @font-face reeglid ja samad fondifailid, kõik alamhulgad, nii et tekst renderdub nagu enne) ja iga skriptihosti aadressi failiga kataloogi vendor/ all. fonts/FONTS.json ja vendor/VENDOR.json salvestavad, kust iga fail pärines, ja selle kontrollsumma; fondid on SIL Open Font License (fonts/OFL-*.txt) all ja three.js MIT litsentsi (vendor/three@…/LICENSE) all.

tools/fetch_third_party.py --from <site folder> --from <Studio folder> on ainus samm, mis kasutab võrku. Seda tuleb uuesti käivitada ainult siis, kui leht küsib fondikomplekti või teegi versiooni, mida siin pole: port keeldub ja ütleb seda. site.test.mjs kukub läbi, kui mõni porditud leht, stiilileht või skript nimetab fondihosti või laadib midagi teiselt hostilt.

Leht 404#

GitHub Pages vastab puuduvale aadressile failiga /404.html ja olekuga 404. Port teeb selle lehe avalehe enda kestast (navigatsioon, jalus, otsing) lühikese sõnumi ümber, mille lingid viivad avalehele, dokumentatsiooni ja Studiosse. Kõik selle aadressid on kirjutatud saidi juurest, sest seda serveeritakse mis tahes sügavusel.

Vanad aadressid#

Kuni v0.28.0 oli sait üks leht ja kõik asus aadressi / fragmendi taga (/#playground, /#ledger, jagamislingid kujul /#s=…, manused kujul /?embed=1&…; manuselingi vana vahekaardi nimi, näiteks tab=fom, avab selle asendanud Studio vahekaardi). tools/legacy-urls.json loetleb iga sellise aadressi, mida avaldatud materjal kasutab, ja kuhu see praegu jõuab; avaleht laadib selle loendi põhjal genereeritud legacy-redirects.js, et need sinna saata. Enne mis tahes aadressi kasutuselt kõrvaldamist tuleb loendisse lisada juhtum.

Juurutus#

GitHub Actions töövoog pages juurutab väljalaskesildi, mitte main: release.yml käivitab selle, kui väljalase on avaldatud, ning käsitsi käivitus juurutab nimetatud sildi uuesti. See käivitab build.sh, ettevalmistab web/ ilma testideta, ehitusskripti, tools/, manifesti ja selle failita ning avaldab tulemuse GitHub Pagesis.