KITAQ SYSTÈME DE DÉVELOPPEMENT
MANUEL D'UTILISATION 2026.09

KITAQ SERIES • ÉDITION DE RÉFÉRENCE

SARAKURA

Diagnostics, comparaison et nouveaux tests

De votre première ligne à l'exécution, à l'observation et aux nouveaux tests.
Copie des sources : 14 septembre 2026 · Édition anglaise de référence : 14 septembre 2026

Outil Windows prêt à l'emploi

Le dépôt contient sarakura.exe à sa racine. Téléchargez l'archive ZIP du dépôt et conservez les mentions de licence avec l'exécutable. Cet outil Windows x64 en ligne de commande ne nécessite aucune installation de Rust, Python ou .NET pour fonctionner. Les étapes de compilation ci-dessous servent à le reconstruire depuis les sources. Le code propre au projet est proposé par DAISUKE OBA sous licence MIT ; les conditions des dépendances sont conservées dans BINARY_NOTICES.md et licenses/.

1. Le rôle de SARAKURA

SARAKURA rassemble les informations de compilation et les événements de diagnostic des émulateurs pour les présenter sous une forme utile aux corrections et aux nouveaux tests. Il n'exécute pas les ROM et ne modifie pas discrètement votre code C.

2. Compiler l'outil

powershell
Push-Location .\sarakura
.\scripts\build.ps1
.\sarakura.exe --help
Pop-Location

Les commandes courtes sarakura supposent que l'exécutable est dans PATH. Sinon, utilisez son chemin. Choisissez gb analyze pour la GB ou fc analyze pour la FC.

3. Votre première analyse

Deux entrées sont nécessaires : --metadata reçoit le JSON produit à la compilation et --events le JSONL de diagnostic produit à l'exécution. Un fichier JSONL contient un objet JSON par ligne.

powershell
sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\report --fail-on error

Ouvrez le fichier de sortie report.html dans un navigateur. Vérifiez la cible, le nombre d'images observées, le nombre d'erreurs et celui des avertissements avant de lire les diagnostics individuels. --frames décrit les conditions d'analyse ; il ne demande pas à SARAKURA d'exécuter une ROM pendant ce nombre d'images.

4. Examiner d'abord les entrées

powershell
sarakura inspect-metadata --metadata .\out\build.json
sarakura inspect-events --events .\out\gb_events.jsonl
sarakura emitter-check gb --metadata .\out\build.json --events .\out\gb_events.jsonl --strict

Traitez les fichiers illisibles, les incohérences de plateforme et les types d'événements non pris en charge avant d'examiner le comportement du jeu. Fournir un rapport ordinaire d'émulateur comme fichier d'événements n'en fait pas une entrée de diagnostic valide.

5. Interpréter les diagnostics

Une erreur mérite la priorité, un avertissement peut indiquer un problème selon les circonstances et une information apporte du contexte. La gravité aide au tri, mais ne connaît pas toute l'intention du jeu. Une observation de compteur ordinal répété ne permet pas toujours de distinguer une boucle d'attente normale sur un écran titre d'un blocage.

Comparez l'empreinte de la ROM, la séquence d'entrées, la scène, l'écran, le son et l'emplacement source. Gardez les mêmes conditions avant et après correction ; sinon, une diminution des diagnostics peut simplement signifier qu'une autre scène a été exécutée.

6. Fichiers de sortie

Les explications intégrées, les conseils de diagnostic et les instructions de correction sont en anglais, et le HTML déclare lang="en". Les chaînes de l'utilisateur et les identifiants d'événements ne sont pas traduits automatiquement. Le masquage par défaut remplace certains libellés et chemins de projet ; il n'anonymise pas toutes les adresses ni toutes les observations. Examinez les rapports avant de publier une analyse fondée sur des entrées privées.

FichierRôle
ai_diagnostics.jsonDiagnostics normalisés pour un traitement automatisé
diagnostic_summary.jsonComptages et résumé
report.htmlRapport destiné à la lecture humaine
repair_prompt.mdContexte de départ pour rechercher une correction
repair_plan.json / .mdOrdre et cibles des corrections
automation_plan.json / .mdPlan de travail fondé sur les capacités des outils
retest_plan.jsonPlan des vérifications à refaire
repro_bundle.zipArchive des informations de reproduction

Produire un plan ne signifie pas l'exécuter. Après une modification du source C ou de la ROM, relancez le compilateur, l'émulateur et SARAKURA.

7. Catalogues, filtres et couverture

powershell
sarakura catalog gb --json
sarakura catalog fc --json
sarakura pack-plan gb
sarakura coverage gb --events .\out\gb_events.jsonl --out .\out\coverage.json

catalog répertorie les règles de diagnostic, pack-plan les regroupe par domaine et coverage examine les événements correspondants effectivement observés. La présence d'une entrée dans le catalogue ne garantit pas que l'émulateur actuel émet cet événement.

powershell
sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\ppu_report --diagnostic-pack ppu --min-severity warn --fail-on error

--diagnostic-rule choisit un nom d'événement ou un identifiant de catalogue, --phase une étape et --diagnostic-pack un domaine. Masquer un diagnostic par un filtre ne résout pas sa cause.

8. Comparer avant et après

powershell
sarakura baseline-delta --baseline .\out\before --current .\out\after --out .\out\delta --markdown .\out\delta --fail-on-new error --fail-on-regression error --enforce

Les résultats sont classés comme nouveaux, résolus, améliorés, persistants ou aggravés. Distinguez les problèmes qui demeurent de ceux qui viennent d'apparaître. Conservez les mêmes entrées, nombres d'images et filtres de diagnostic pendant les comparaisons.

9. Validation et intégration continue

powershell
sarakura validate .\out\report\ai_diagnostics.json --strict
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
sarakura schema export --out .\out\schemas

L'intégration continue automatise les vérifications reproductibles. ci-summary ne modifie le code de sortie du processus que si --enforce est fourni ; sinon, lisez son verdict JSON. Pour analyze, --fail-on error renvoie un code non nul en présence d'erreurs. Le réglage par défaut never ne fait pas échouer le processus à cause des diagnostics : choisissez donc explicitement une politique en CI. Le choix warn ajoute les avertissements aux conditions d'échec.

powershell
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
if ($LASTEXITCODE -ne 0) { throw "The diagnostic failure condition was met" }

Une validation de schéma réussie vérifie le format des données. Pour vérifier qu'un jeu fonctionne comme prévu, il faut aussi tester les commandes, l'écran et le son.

10. Gérer les fichiers de reproduction

normalize-events normalise les événements. inspect-repro examine une archive de reproduction. Avant de la partager, vérifiez que ses informations correspondent à la ROM visée et qu'elle comprend les étapes d'entrée nécessaires. --allow-project-labels conserve explicitement les libellés et identifiants issus du projet.

11. Entrées minimales pour s'exercer

Le manuel fournit de petits exemples GB/FC de métadonnées de compilation et d'événements. Ouvrez le rapport synthétique GB ou le rapport synthétique FC. samples/sarakura_demo.ps1 montre comment les analyser. Ces entrées synthétiques servent à apprendre le format ; elles ne constituent pas des observations recueillies sur une vraie ROM. Pour les tests de ROM réelles, utilisez les événements enregistrés par KOKURA ou KUROSAKI.

12. Un cycle de correction et de nouveau test

  1. Reproduisez le problème avec la même ROM et les mêmes entrées, en conservant journaux et images.
  2. Organisez les pistes avec SARAKURA et examinez le source concerné.
  3. Apportez une modification ciblée sur la cause.
  4. Recompilez et rejouez les mêmes actions.
  5. Comparez baseline-delta avec les images, l'audio et le comportement du jeu.

Gardez ce cycle court pour que chaque modification et son effet restent compréhensibles.

Référence de syntaxe des commandes

L'aide ci-dessous a été enregistrée pour cette édition des sources. Consultez-la pour les arguments facultatifs, les valeurs par défaut et les valeurs acceptées. Remplacez les noms de fichiers illustratifs par vos propres sorties. Les réponses enregistrées des outils conservent leur texte d'origine.

sarakura
help
SARAKURA diagnostic translation CLI

Usage: sarakura.exe <COMMAND>

Commands:
  gb                
  fc                
  validate          
  compare           
  catalog           
  inspect-events    
  inspect-metadata  
  retest-plan       
  emitter-check     
  normalize-events  
  ci-summary        
  coverage          
  pack-plan         
  repair-plan       
  automation-plan   
  baseline-delta    
  schema            
  inspect-repro     
  help              Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
sarakura gb
help
Usage: sarakura.exe gb <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura gb analyze — Recueillir les diagnostics Game Boy
powershell
sarakura gb analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error
help
Usage: sarakura.exe gb analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help
sarakura fc
help
Usage: sarakura.exe fc <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura fc analyze — Recueillir les diagnostics Famicom
powershell
sarakura fc analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error
help
Usage: sarakura.exe fc analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help
sarakura validate — Valider le format des diagnostics
powershell
sarakura validate out/report/ai_diagnostics.json --strict
help
Usage: sarakura.exe validate [OPTIONS] <PATH>

Arguments:
  <PATH>  

Options:
      --strict  
  -h, --help    Print help
sarakura compare — Comparer deux résultats de diagnostic
powershell
sarakura compare --before out/before --after out/after --out out/comparison
help
Usage: sarakura.exe compare --before <BEFORE> --after <AFTER> --out <OUT>

Options:
      --before <BEFORE>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --after <AFTER>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>        
  -h, --help             Print help
sarakura catalog — Lister les règles de diagnostic
powershell
sarakura catalog gb --json
help
Usage: sarakura.exe catalog [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --json  Emit JSON instead of a Markdown table
  -h, --help  Print help
sarakura inspect-events — Résumer les événements
powershell
sarakura inspect-events --events out/events.jsonl
help
Usage: sarakura.exe inspect-events [OPTIONS] --events <EVENTS>

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write the JSON inspection summary
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help
sarakura inspect-metadata — Examiner les informations de compilation
powershell
sarakura inspect-metadata --metadata out/build.json
help
Usage: sarakura.exe inspect-metadata [OPTIONS] --metadata <METADATA>

Options:
      --metadata <METADATA>  
      --out <OUT>            Optional path to write the JSON inspection summary
      --json                 Emit JSON to stdout instead of a compact text summary
  -h, --help                 Print help
sarakura retest-plan — Créer un plan de nouveaux tests
powershell
sarakura retest-plan --diagnostics out/report --out out/retest.json
help
Usage: sarakura.exe retest-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write retest_plan.json. If omitted, JSON is printed to stdout
  -h, --help                       Print help
sarakura emitter-check — Vérifier le respect du contrat de l'émetteur
powershell
sarakura emitter-check gb --metadata out/build.json --events out/events.jsonl --strict
help
Usage: sarakura.exe emitter-check [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --metadata <METADATA>      
      --events <EVENTS>          
      --strict                   Fail when compatibility warnings are found
      --check-snapshot-refs      Check that snapshot_ref paths exist
      --check-trace-window-refs  Check that trace_window_ref paths exist
      --base-dir <BASE_DIR>      Base directory for snapshot_ref and trace_window_ref existence checks
      --out <OUT>                Optional path to write the compatibility summary JSON
  -h, --help                     Print help
sarakura normalize-events — Normaliser le format des événements
powershell
sarakura normalize-events --events out/events.jsonl --out out/normalized.jsonl
help
Usage: sarakura.exe normalize-events [OPTIONS] --events <EVENTS> --out <OUT>

Options:
      --events <EVENTS>  
      --out <OUT>        
      --json-array       Also write a pretty JSON array next to the JSONL output for fixture review
  -h, --help             Print help
sarakura ci-summary — Évaluer les conditions d'échec de la CI
powershell
sarakura ci-summary --diagnostics out/report --fail-on error --enforce
help
Usage: sarakura.exe ci-summary [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --fail-on <FAIL_ON>          CI policy. `error` fails only on errors, `warn` fails on errors or warnings [default: error] [possible values: never, error, warn, info]
      --out <OUT>                  Optional path to write sarakura_ci_summary.json
      --enforce                    Return a non-zero exit code when the CI policy fails
  -h, --help                       Print help
sarakura coverage — Lister les règles observées
powershell
sarakura coverage gb --events out/events.jsonl --out out/coverage.json
help
Usage: sarakura.exe coverage [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write catalog coverage JSON. If a directory is given, diagnostic_coverage.json is created inside it
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help
sarakura pack-plan — Décrire les plans de règles par domaine
powershell
sarakura pack-plan gb
help
Usage: sarakura.exe pack-plan [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --out <OUT>  Optional path to write pack plan JSON. If a directory is given, diagnostic_pack_plan.json is created inside it
      --json       Emit JSON to stdout instead of a Markdown summary
  -h, --help       Print help
sarakura repair-plan — Créer un plan de correction
powershell
sarakura repair-plan --diagnostics out/report --out out/repair.json --markdown out/repair.md
help
Usage: sarakura.exe repair-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write repair_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>        Optional path to write repair_plan.md. If a directory is given, repair_plan.md is created inside it
  -h, --help                       Print help
sarakura automation-plan — Faire correspondre les plans aux capacités des outils
powershell
sarakura automation-plan --diagnostics out/report --tool kokura --out out/automation.json
help
Usage: sarakura.exe automation-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --tool <TOOL>                  Tool name for generated commands. Use auto, kokura, or kurosaki [default: auto]
      --out <OUT>                    Optional path to write automation_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>          Optional path to write automation_plan.md. If a directory is given, automation_plan.md is created inside it
      --capabilities <CAPABILITIES>  Optional SARAKURA tool capability JSON. Unsupported options are omitted from generated commands
  -h, --help                         Print help
sarakura baseline-delta — Mesurer les améliorations et régressions par rapport à une référence
powershell
sarakura baseline-delta --baseline out/before --current out/after --out out/delta --markdown out/delta
help
Usage: sarakura.exe baseline-delta [OPTIONS] --baseline <BASELINE> --current <CURRENT>

Options:
      --baseline <BASELINE>
          Baseline directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --current <CURRENT>
          Current directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>
          Optional path to write baseline_delta.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>
          Optional path to write baseline_delta.md. If a directory is given, baseline_delta.md is created inside it
      --fail-on-new <FAIL_ON_NEW>
          Fail when new diagnostics at or above this severity are introduced [default: error] [possible values: never, error, warn, info]
      --fail-on-regression <FAIL_ON_REGRESSION>
          Fail when existing diagnostics regress at or above this severity [default: error] [possible values: never, error, warn, info]
      --enforce
          Return a non-zero exit code when the baseline policy fails
  -h, --help
          Print help
sarakura schema
help
Usage: sarakura.exe schema <COMMAND>

Commands:
  export  
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura schema export — Exporter les schémas JSON
powershell
sarakura schema export --out out/schemas
help
Usage: sarakura.exe schema export [OPTIONS] --out <OUT>

Options:
      --out <OUT>            
      --manifest <MANIFEST>  
  -h, --help                 Print help
sarakura inspect-repro — Examiner une archive de reproduction
powershell
sarakura inspect-repro out/report/repro_bundle.zip --json
help
Usage: sarakura.exe inspect-repro [OPTIONS] <BUNDLE>

Arguments:
  <BUNDLE>  

Options:
      --out <OUT>  
      --json       
  -h, --help       Print help