code-extract

Plugin Typst pour extraire une déclaration C ou OCaml par son nom, avec Tree-sitter. Aucun commentaire BEGIN/END, aucune borne dépendant de la fonction suivante, aucun prétraitement du fichier source.

Le module WASM est livré dans dist/. Une compilation Typst ordinaire suffit pour l'utiliser ; Python, Node et WASI SDK ne servent qu'à la construction et aux tests.

Utilisation

Depuis ce dépôt :

#import "lib.typ": extract, extract-text

#extract(read("examples/code.ml"), "kleene")
#extract(read("examples/code.ml"), "regexp", kind: "type")
#extract(read("examples/code.ml"), ("regexp", "automate"), kind: "type")
#extract(read("examples/code.c"), "somme", language: "c")

extract affiche un bloc de code avec la coloration de Typst. extract-text renvoie uniquement une chaîne. Les alias extrait et extrait-texte acceptent les mêmes arguments.

Argument	Valeur
source	Contenu du fichier, obtenu avec read
name	Nom de la déclaration, ou tuple de noms à réunir dans un même bloc
language	"ocaml" par défaut, ou "c"
kind	"auto" par défaut, "function", "type", "value" ou "module" pour OCaml

Les espaces, les retours à la ligne et les commentaires internes sont conservés. Les positions sont calculées en octets UTF-8. Déplacer une fonction ou ajouter d'autres déclarations ne change pas son extraction. Pour plusieurs noms, les déclarations sont assemblées dans l'ordre demandé, séparées par une ligne vide. Un même groupe récursif n'est affiché qu'une fois.

Installation dans un autre projet

python3 scripts/install.py /chemin/vers/packages

Puis utiliser :

#import "@local/code-extract:0.2.0": extract
#extract(read("corrige.ml"), "kleene")

typst compile --package-path /chemin/vers/packages document.typ

Le script installe le package complet, module WASM et licences inclus, dans local/code-extract/0.2.0. Sans argument, il utilise build/packages. Ce prototype n'est pas publié sur Typst Universe.

Portée de la version 0.1

• OCaml : déclarations let, type et module au niveau supérieur. Un nom d'un groupe let rec … and … ou type … and … sélectionne le groupe entier. Un module est extrait entier ; ses déclarations internes et les variables locales ne sont pas recherchées séparément. Les motifs destructurants et les opérateurs ne sont pas encore sélectionnables par nom. kind: "function" reconnaît les paramètres explicites et les corps fun / function directs ; kind: "value" accepte toutes les liaisons simples.
• C : définitions de fonctions, alias typedef et définitions nommées struct, union, enum. Les prototypes seuls ne sont pas des définitions. Une déclaration contenant plusieurs alias est extraite entière.
• Le préprocesseur C n'est pas exécuté : toutes les branches conditionnelles sont analysées. Deux définitions du même nom dans des branches différentes sont donc ambiguës.
• Un nom absent ou ambigu produit une erreur. Utiliser kind pour distinguer un type et une valeur OCaml de même nom.
• Une erreur syntaxique signalée par Tree-sitter dans le fichier entraîne une erreur d'extraction. L'outil ne vérifie ni les types ni les dépendances : un extrait n'est pas nécessairement compilable seul.
• Les commentaires placés avant une déclaration ne sont pas inclus. Le plugin ne reformate pas le code et n'ajoute pas automatiquement les fonctions dont il dépend.
• L'entrée du plugin est limitée à 16 Mio. Le module compilé occupe environ 5,6 Mo.

Construire et vérifier

Avec Nix :

nix develop -c just check
nix develop -c just test-web

La première commande télécharge les sources verrouillées et WASI SDK, vérifie leurs SHA-256, construit les variantes native et WASM, puis exécute :

1. 44 cas sur l'implémentation C native ;
2. 88 appels au plugin WASM dans Node, en réutilisant la même instance ;
3. les 44 cas avec le compilateur Typst natif, dont 14 erreurs attendues ;
4. la compilation de examples/demo.typ vers build/demo.pdf ;
5. l'installation et l'import du package @local/code-extract:0.2.0.

just test-web installe les dépendances npm verrouillées puis teste les 44 cas avec le compilateur Typst compilé en WASM (typst.ts 0.8.0-rc3). Aucun accès aux polices ou à un CDN n'est nécessaire pour ces assertions.

Sans Nix, disposer de Python 3.12+, d'un compilateur C, de Node 22+ et de Typst 0.15+, puis lancer :

python3 scripts/build.py
python3 scripts/test.py
npm ci
npm test

Le téléchargement de WASI SDK est configuré pour macOS et Linux, sur ARM64 et x86-64, ainsi que Linux RISC-V64. La version initiale a été exécutée sur macOS ARM64 ; les autres plateformes restent à vérifier.

Pour vérifier également le module dans un vrai navigateur :

python3 -m http.server 8423 --bind 127.0.0.1

Ouvrir http://127.0.0.1:8423/tests/browser.html. Les 88 appels du même jeu de tests y sont exécutés avec le moteur WebAssembly du navigateur. Ce test est distinct de la compilation Typst WASM effectuée par npm test.

Architecture

• src/extract.c : sélection dans l'arbre syntaxique et calcul des positions.
• src/plugin.c : adaptation au protocole des plugins Typst.
• src/wasi_stubs.c : opérations d'horloge et de flux de libc remplacées par des fonctions locales déterministes. Le binaire final n'importe que les deux fonctions du protocole Typst ; scripts/check_wasm.py le vérifie.
• lib.typ : conversion des arguments et mise en forme Typst.
• dependencies.lock.json : versions et empreintes des archives amont.
• tests/cases.json : mêmes cas exécutés en natif, en WASM et par Typst.

Les grammaires C et OCaml sont compilées dans le module : rien n'est téléchargé pendant l'extraction. Voir THIRD_PARTY.md pour les licences.