Hansl Notebook

Notebooks VS Code pour hansl, le langage de script du logiciel d'économétrie gretl.

État : fonctionnel, non encore publié. Exécution, tableaux de régression, graphiques, coloration syntaxique et cache de données sont en place, vérifiés sur Windows et Linux par 146 tests en intégration continue. macOS n'est pas testé. Détail dans docs/PROJECT_STATE.md.

Le principe : votre notebook reste un script gretl

Un notebook Hansl est un fichier .inp ordinaire. Les cellules sont délimitées par des commentaires # %%, que gretl ignore :

# %% [markdown]
# # Régression hédonique
# Modèle de prix sur `data4-1`.

# %%
open data4-1.gdt

# %%
ols price 0 sqft

Ce fichier s'exécute tel quel hors de VS Code :

gretlcli -b -e mon_notebook.inp

Conséquences : diff Git lisible, aucun enfermement, partage possible avec des collègues qui n'ont pas l'extension. En contrepartie, les sorties ne sont pas enregistrées dans le fichier — rouvrir un notebook demande de réexécuter. Le raisonnement complet est dans ADR 0002.

Vos scripts existants ne sont pas capturés

L'extension se déclare avec priority: "option" : l'éditeur de texte reste l'éditeur par défaut pour tous les .inp. Installer l'extension ne change rien à votre habitude d'ouverture.

Pour ouvrir un fichier en notebook : clic droit → Reopen With… → Hansl Notebook, ou la commande Ouvrir comme Hansl Notebook.

Pour en faire le défaut, à vos risques :

"workbench.editorAssociations": { "*.inp": "hansl-notebook" }

Un .inp sans marqueur # %% s'ouvre comme un notebook à cellule unique — et le sauvegarder ne lui ajoute aucun marqueur. Vérifié sur les 133 scripts livrés avec gretl : tous survivent intacts à un aller-retour.

Prérequis

gretl doit être installé séparément. L'extension le localise dans cet ordre :

1. le réglage hanslNotebook.gretlcliPath ;
2. le PATH système ;
3. les emplacements d'installation connus (C:\Program Files\gretl\gretlcli.exe, /usr/bin/gretlcli, /Applications/Gretl.app/Contents/MacOS/gretlcli, …).

Le niveau 3 n'est pas superflu : l'installeur Windows de gretl n'ajoute pas son dossier au PATH.

Réglages

Partager un notebook exécuté

Par défaut, les sorties ne sont pas enregistrées : rouvrir un notebook montre des cellules vides tant qu'on ne réexécute pas. C'est le prix du format .inp, qui reste un script gretl valide.

Pour partager un notebook avec ses résultats — typiquement avec quelqu'un qui n'a pas gretl — activez :

"hanslNotebook.persistOutputs": true

Les sorties sont alors écrites dans un fichier voisin, mon_notebook.inp.outputs.json, à la fin de chaque exécution. Le .inp lui-même reste inchangé. Transmettez les deux fichiers.

Une sortie n'est restituée que si le code de sa cellule n'a pas changé depuis. Une cellule que vous avez modifiée rouvre vide plutôt que d'afficher un résultat qui ne lui correspond plus.

Le sidecar peut être versionné avec le notebook si vous voulez que le dépôt porte les résultats, ou ajouté à .gitignore (*.outputs.json) si vous préférez ne versionner que le code.

Coloration syntaxique

Le langage hansl est coloré dans les cellules comme dans l'éditeur de texte : commandes, fonctions, accesseurs $, substitutions @, types, chaînes, nombres et commentaires. Les marqueurs # %% sont distingués des commentaires ordinaires.

La grammaire n'est pas écrite à la main : elle est générée depuis les fichiers de référence livrés avec gretl — 149 commandes, 380 fonctions et 99 accesseurs, lus dans gretl_cli_cmdref.en et gretl_cli_fnref.en. Pour la régénérer après une mise à jour de gretl :

npm run grammar

Un test d'intégration compare la grammaire livrée à la référence de votre installation et signale tout ce qui manquerait.

Les commandes ne sont colorées qu'en tête de ligne (éventuellement après catch), et les fonctions seulement lorsqu'elles sont suivies d'une parenthèse : store employé comme nom de variable reste une variable.

Tableaux de régression

Les résultats d'estimation sont réaffichés sous forme de tableau, reconstruit depuis les données structurées que gretl expose — jamais en analysant le texte formaté, qui varierait d'une version à l'autre. La sortie texte d'origine reste disponible dans la même cellule.

Vérifié sur 22 estimateurs : ols, wls, tsls, logit, probit, tobit, poisson, negbin, lad, quantreg, hsk, mpols, logistic, duration, biprobit, heckit, ar1, arima, garch, panel (effets fixes et aléatoires) et dpanel.

var fait exception : un VAR est un système, sa sortie texte est déjà structurée par équation et c'est elle qui s'affiche.

Gros jeux de données

Chaque exécution relance gretl depuis le début du notebook. Le nombre de cellules ne coûte pratiquement rien (mesuré : 124 ms à une cellule, 130 ms à quatre-vingts), mais relire un gros .gdt coûte cher : 5,9 s pour un fichier de 75 Mo.

L'extension convertit donc ces fichiers au format binaire .gdtb de gretl, dans son propre dossier de cache :

Le cache s'amortit en deux exécutions, puis divise le temps par 21.

Votre fichier d'origine n'est jamais modifié, et le cache n'est jamais utilisé sans avoir été vérifié. La conversion perd en effet une information dans un cas précis : la description d'une série à valeurs textuelles. L'extension compare donc chaque cache à son original — structure, libellés, valeurs manquantes, valeurs textuelles, résumés numériques — et le supprime au moindre écart, en revenant silencieusement au .gdt. Vous perdez alors la vitesse, jamais l'exactitude.

Réglez hanslNotebook.datasetCache sur false pour le désactiver entièrement.

Toutes les versions de gretl ne produisent pas de .gdtb — celle empaquetée par Ubuntu (2023c) n'y parvient pas, là où la 2026b le fait. L'extension le détecte d'elle-même à la première tentative, le signale une fois, et s'en passe. Vos notebooks fonctionnent identiquement, simplement sans l'accélération.

Plateformes

La CI validant deux versions de gretl distantes de trois ans (2023c et 2026b), le contrat d'invocation ne dépend visiblement pas d'une version particulière.

Nous n'annonçons comme supporté que ce qui a été exécuté. Voir ADR 0005.

Développement

npm install
npm run typecheck     # tsc --noEmit, TypeScript strict
npm run test:unit     # Vitest — unitaires + intégration sur un vrai gretlcli
npm run test:vscode   # Mocha dans une véritable instance VS Code
npm test              # les trois

Construire un .vsix

npm run package

Le paquet produit ne contient que out/src/, le manifeste, le README et la licence — 17 fichiers, environ 29 Ko. Ni sources TypeScript, ni tests, ni documentation.

Installation locale du .vsix : Extensions → … → Install from VSIX…, ou code --install-extension hansl-notebook-0.0.1.vsix.

Les tests d'intégration utilisent les scripts et jeux de données livrés avec gretl, référencés en place et jamais copiés dans ce dépôt (ils sont sous GPL, le dépôt est sous MIT). Si gretl est introuvable, ils s'ignorent avec un message explicite plutôt qu'en silence.

Le dossier spike/ contient les scripts Node autonomes ayant servi à mesurer le comportement réel de gretlcli avant toute décision d'architecture.

Publication

L'extension est prête à être publiée au Marketplace : icône, journal des modifications, métadonnées et workflow sont en place. Les étapes qui demandent un compte éditeur et un jeton sont décrites dans docs/PUBLICATION.md.

Documentation

• État du projet — décisions, jalons, points ouverts
• Journal de vérification — chaque hypothèse, sa mesure, sa sortie brute
• Décisions d'architecture — ADR 0001 à 0005
• Publier au Marketplace — ce qui est prêt, ce qui vous revient

Licence

MIT — voir LICENSE. Cette extension pilote gretl (GPL v3) sans l'embarquer ni le redistribuer.