https://cheroliv.com/ JBake Bootstrap Template en-gb Fri, 25 Sep 2026 01:45:07 +0000 Fri, 25 Sep 2026 01:45:07 +0000 https://cheroliv.com/blog/2026/0126_hyperframes_asciidoc_video_post.html Sun, 31 May 2026 00:00:00 +0000 blog/2026/0126_hyperframes_asciidoc_video_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_buco_nel_pipeline_video">il buco nel pipeline video</a></li> <li><a href="#_hyperframes_il_motore">HyperFrames : Il Motore</a></li> <li><a href="#_larchitettura_del_plugin">L’architettura del plugin</a> <ul class="sectlevel2"> <li><a href="#_il_pipeline_in_quattro_fasi">Il pipeline in quattro fasi</a></li> <li><a href="#_il_dsl_asciidoc">Il DSL AsciiDoc</a></li> <li><a href="#_il_bridge_node_js">Il Bridge Node.js</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 8 minutes</div> <p>Due settimane fa, ho lanciato`capsule-gradle`— un plugin che trasforma un deck reveal.js in una capsula video WebM con TTS. Oggi, aggiungo un nuovo plugin: <code>hyperframes-gradle</code>. Fa qualcosa che capsule-gradle non fa : trasformare l’AsciiDoc <strong>direttamente</strong> in video MP4, senza passare da reveal.js.</p> </div> <div class="paragraph"> <p>Ecco perché questo plugin esiste, come si articola con l’esistente, e ciò che il motore HyperFrames di HeyGen apporta al pipeline di produzione del contenuto</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_buco_nel_pipeline_video">il buco nel pipeline video</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il mio pipeline documentario produce due tipi di video:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Capsula di revisione</strong> (capsule-gradle) — un deck reveal.js catturato in WebM con</p> </li> </ol> </div> <div class="paragraph"> <p>narrazione TTS. Perfetto per rivedere un modulo.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Slides d’animation</strong> (slider-gradle) — un deck reveal.js HTML interattivo per</p> </li> </ol> </div> <div class="paragraph"> <p>Il formatore in presenza</p> </div> <div class="paragraph"> <p>Ma manca un terzo formato : il <strong>video standalone</strong></p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5565%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">caso d’uso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Soluzione attuale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mancanza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides formatore</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">slider-gradle → reveal.js</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No output)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Capsula revisione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Video teaser</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>nessuna</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Demo tecnica animata</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>nessuna</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Da documento a video</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Nessuna</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Il primo use case è critico: come generare automaticamente un video di 60 secondi che presenta un progetto o un modulo, con animazioni GSAP, narration TTS, e sottofondo musicale — il tutto dallo stesso file AsciiDoc cosa le slide ?</p> </div> <div class="paragraph"> <p>Capsule-gradle non può rispondere: gli serve <strong>già</strong> un deck reveal.js. slider-gradle produce bene questo deck, ma non è progettato per il rendering video. Era necessario avere un pipeline <strong>direct</strong> : AsciiDoc → video.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hyperframes_il_motore">HyperFrames : Il Motore</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ho scopertohttps://github.com/heygen-com/hyperframes[HyperFrames] il y a alcuni giorni. È un framework open-source (Apache 2.0) creato da HeyGen, l’unicorno del video IA. 22 700 stelle su GitHub. Il pitch contiene in una frase :</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p><strong>Scrivi HTML. Renderizza video. Realizzato per gli agenti.</strong></p> </div> </blockquote> </div> <div class="paragraph"> <p>Il principio: voi scrivete HTML con dei`data-*`attributi, fate riferimento un’animazione GSAP (o CSS, Lottie, Three.js…), e il motore rende tutto in MP4 via Puppeteer (Chrome headless) + FFmpeg. Risultato deterministico: stesso input, stessi frame, stesso video</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><div id="stage" data-composition-id="intro" data-start="0" data-width="1920" data-height="1080"> <video class="clip" data-start="0" data-duration="6" data-track-index="0" src="background.mp4" muted playsinline></video> <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1"> Formation Docker & Kubernetes </h1> <audio data-start="0" data-duration="6" data-track-index="2" data-volume="0.3" src="music.wav"></audio> <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script> const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.__timelines = window.__timelines || {}; window.__timelines.intro = tl; </script> </div></code></pre> </div> </div> <div class="paragraph"> <p>Che cosa rende HyperFrames diverso da Remotion? Nessun React, nessun bundler, senza JSX. HTML grezzo che gli agenti IA sanno scrivere nativamente. È tagliato <strong>esattamente</strong> per il mio pipeline : planner-gradle con deepseek può generare questo HTML a partire da un piano SPG/SPD, e un plugin Gradle può convertirlo in MP4.</p> </div> </div> </div> <div class="sect1"> <h2 id="_larchitettura_del_plugin">L’architettura del plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle segue lo stesso pattern di tutti i miei plugin : il <a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">pattern « Plugin Indipendente + Radice Consumatore »</a>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">hyperframes-gradle/ ├── settings.gradle.kts ← racine consommateur (dogfood) ├── build.gradle.kts ← 3 lignes : apply plugin hyperframes ├── hyperframes-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── build.gradle.kts ← java-gradle-plugin │ ├── src/main/kotlin/education/cccp/hyperframes/ │ │ ├── HyperframesPlugin.kt │ │ ├── GenerateHyperframesHtmlTask.kt │ │ ├── RenderHyperframesTask.kt │ │ └── HyperframesExtension.kt │ ├── .agents/ ← gouvernance agent │ └── doc/ │ └── HYPERFRAMES_ARCHITECTURE.adoc └── video.yml ← configuration dogfood</code></pre> </div> </div> <div class="sect2"> <h3 id="_il_pipeline_in_quattro_fasi">Il pipeline in quattro fasi</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title condotta hyperframes-gradle rectangle "AsciiDoc\nsorgente" as adoc #LightYellow rectangle "AsciidoctorJ" as asciidoctorj #LightBlue rectangle "HTML HyperFrames (data-* attributi)" as html #LightGreen ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11 title condotta hyperframes-gradle rectangle "AsciiDoc\nsorgente" as adoc #LightYellow rectangle "AsciidoctorJ" as asciidoctorj #LightBlue rectangle "HTML HyperFrames (data-* attributi)" as html #LightGreen rectangle "HyperFrames CLI (Node.js 22+)" as cli #Lavender rectangle "video.mp4" as mp4 #Gold adoc -right-> asciidoctorj : parse blocs customs asciidoctorj -right-> html : génère HTML html -right-> cli : ProcessBuilder\nnpx hyperframes render cli -right-> mp4 : Puppeteer + FFmpeg @enduml</pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>AsciidoctorJ</strong> analizza il sorgente AsciiDoc e estrae i blocchi personalizzati</p> </li> </ol> </div> <div class="paragraph"> <p><code>[hyperframes-composition]</code>, <code>[hyperframes-track]</code>, <code>[hyperframes-animation]</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>GenerateHyperframesHtmlTask</strong> genera l’HTML HyperFrames con le</p> </li> </ol> </div> <div class="paragraph"> <p>`data-*`attributi corrispondenti.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RenderHyperframesTask</strong> appelle la CLI HyperFrames via <code>ProcessBuilder</code>:</p> </li> </ol> </div> <div class="paragraph"> <p><code>npx hyperframes render --input index.html --output video.mp4</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Il MP4 è distribuito in`output/`con un`metadata.json`per l’orchestrazione.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_il_dsl_asciidoc">Il DSL AsciiDoc</h3> <div class="paragraph"> <p>Il vero valore aggiunto del plugin è il DSL AsciiDoc. L’utente Non scrive mai HTML. Annota il suo documento AsciiDoc esistente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Formation Docker & Kubernetes :hyperframes-width: 1920 :hyperframes-height: 1080 :hyperframes-fps: 30 [hyperframes-composition, id="intro"] == Introduction Le titre apparaît avec un fondu GSAP sur fond vidéo. [hyperframes-track, index=0, start=0, duration=6] video::assets/background.mp4[muted, playsinline] [hyperframes-track, index=1, start=1, duration=4] Formation Docker & Kubernetes [hyperframes-animation, type=gsap]</code></pre> </div> </div> <div class="paragraph"> <p>const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.<em>timelines = window.</em>timelines || {}; window.__timelines.intro = tl;</p> </div> <div class="paragraph"> <p>Gli attributi docinfo`:hyperframes-width:`) configurano le dimensioni. I blocchi personalizzati definiscono le composizioni e le tracce. `[hyperframes-animation]`contiene il codice GSAP grezzo — che l’agente IA può generare a partire da una descrizione in linguaggio naturale.</p> </div> </div> <div class="sect2"> <h3 id="_il_bridge_node_js">Il Bridge Node.js</h3> <div class="paragraph"> <p>L’unico punto di attrito tecnico: HyperFrames è in Node.js/TypeScript, e i miei plugin sono in Kotlin/JVM. La soluzione è un`ProcessBuilder`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class RenderHyperframesTask : DefaultTask() { @TaskAction fun render() { val process = ProcessBuilder( "npx", "hyperframes", "render", "--input", inputHtml.absolutePath, "--output", outputMp4.absolutePath ) .inheritIO() .start() val exitCode = process.waitFor() require(exitCode == 0) { "HyperFrames render failed with exit code $exitCode" } } }</code></pre> </div> </div> <div class="paragraph"> <p>Zero accoppiamento tra il codice JVM e Node.js. Il contratto è via riga di comando. e file su disco. È lo stesso modello che`plantuml-gradle` <mark>#</mark> Gradle Integration JBake can be integrated into Gradle builds using the JBake Gradle plugin or by calling the JBake CLI directly:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") }`slider-gradle`(chi chiama AsciidoctorJ). Niente di nuovo sotto il sole — semplicemente applicato a uno strumento più recente. == Due Plugins Video, Due Usi |=== | |capsula-gradle |hyperframes-gradle |Source |Deck reveal.js (HTML esistante) |AsciiDoc → HyperFrames HTML |Caso d'uso |Capsula di revisione |Video standalone esplicativa |Natura |Diapositive → video |Documento → video |reso |Playwright Java → WebM |HyperFrames CLI → MP4 |Animazione |Transizioni reveal.js nativi |GSAP/CSS attributi data |pila |100% JVM (Kotlin) |### Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin JBake per Gradle oppure richiamando direttamente la CLI di JBake: ---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } |=== |=== |EPIC |Description |Priorità |HF-0 |Bootstrap governance + inquadramento architettura |TERMINATO |HF-1 |Plugin Gradle stub + integrazione AsciidoctorJ |P0 |HF-2 |### Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin JBake Gradle oppure chiamando direttamente la CLI di JBake: ```kotlin ---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } |P1 |HF-3 |DSL AsciiDoc abitudini (blocchi, docinfo, template) |P1 |HF-4 |Integrazione runner-gradle (metadata.json) |P2 |HF-5 |Template pronti all'uso (title-card, code-diff, captions) |P3 |HF-6 |CI + pubblicazione Maven Central / Gradle Portal |P3 |=== La session 000 (bootstrap) è già terminata. La session 001 attaccherà HF-1 : lo stub del plugin Gradle e l'integrazione AsciidoctorJ. == Perché funziona Tre ragioni: 1. *HyperFrames è "built for agents*". Il mio pipeline si basa su agenti IA (planner-gradle + deepseek) che generano contenuto. HyperFrames accetta HTML grezzo — il formato che i LLM padroneggiano meglio. Niente React, niente di JSX, nessuna curva di apprendimento per l'agente. 1. *Il DSL AsciiDoc è naturale*. Tutto il mio ecosistema parla AsciiDoc. slider-gradle, codex-gradle, training-gradle — tutti consumano del`.adoc`. Aggiungere blocchi personalizzati`[hyperframes-composition]`è un'estensione logico, non una rottura. 1. *Il bridge Node.js è un pattern collaudato*. ProcessBuilder fuori dalla JVM, Questo è quello che faccio già per PlantUML, Graphviz, Piper. Aggiungi HyperFrames non cambia nulla all'architettura — è uno strumento esterno in più, pilotato da Gradle [NOTE] ==== La vera forza del pattern è che non c'è *nessuna* dipendenza npm in la build Gradle. Il plugin non importa alcun codice Node.js. Esegue una comando shell. Se HyperFrames evolve o si rompe, il plugin non è accoppiato. — basta aggiornare il comando. ==== == Conclusion: L'anello mancante Con hyperframes-gradle, il mio pipeline video è completo. Ho: * Le *slide interattive* (slider-gradle) * Le *capsule di revisione* (capsule-gradle) * Le *video standalone* (hyperframes-gradle) Tre formati. Un unico file sorgente: l'AsciiDoc. L'obiettivo successivo è HF-1 : fare compilare il plugin e generare un primo HTML HyperFrames a partire da un documento AsciiDoc annotato. La sessione 001 è già inquadrata. hyperframes-gradle esiste. La governance è in atto. Il backlog è scritto. L'architettura è documentata. Il plugin è nato. == Riferimenti * ### Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin Gradle JBake o chiamando direttamente la CLI JBake: ---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } ``` xref:0124_architecture_plugin_gradle_racine_consommateur_independant_post.adoc[Articolo 0124 — L'Architettura Plugin Indipendente + Radice Consumatore] * https://github.com/heygen-com/hyperframes[HyperFrames — GitHub] * https://hyperframes.heygen.com/introduction[HyperFrames — Documentazione] * `foundry/public/hyperframes-gradle/hyperframes-plugin/doc/HYPERFRAMES_ARCHITECTURE.adoc`— Architettura dettagliata</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html Thu, 14 May 2026 00:00:00 +0000 blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_problema_tre_architetture_che_mi_hanno_fatto_perdere_tempo">Il Problema: Tre Architetture Che Mi Hanno Fatto Perdere Tempo</a> <ul class="sectlevel2"> <li><a href="#_integrazione_gradle"><mark>#</mark> Integrazione Gradle</a></li> </ul> </li> <li><a href="#_1_builder_le_plugin">1. Builder le plugin</a></li> <li><a href="#_2_lexercer_depuis_la_racine">2. L’exercer depuis la racine</a></li> <li><a href="#_la_boucle_est_fermée_le_plugin_est_testé_dans_des_conditions">La boucle est fermée. Le plugin est testé dans des conditions</a></li> <li><a href="#_réelles_de_consommation_par_le_projet_même_qui_lhéberge">réelles de consommation, par le projet même qui l’héberge.</a></li> <li><a href="#_la_seule_friction_du_pattern">La seule "friction" du pattern</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 11 minutes</div> <p>Cloni un repository di plugin Gradle. Apri un terminale. Cosa digiti? poi?<code>./gradlew tasks</code>, certo. Ma in quale cartella? La radice? Il sottomodulo? Bisogna prima leggere un README per sapere come costruire? Se voi esitate, non sarebbe un attimo, l’architettura del progetto è rotta.</p> </div> <div class="paragraph"> <p>Ecco come ho risolto questo problema una volta per tutte—e perché questo pattern è oggi la firma di tutti i miei plugin Gradle in`foundry/public/`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_tre_architetture_che_mi_hanno_fatto_perdere_tempo">Il Problema: Tre Architetture Che Mi Hanno Fatto Perdere Tempo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Prima di convergere verso il pattern attuale, ho vagato tra tre approcci classici per organizzare un plugin Gradle. Ognuna aveva un difetto fatale.</p> </div> <div class="sect2"> <h3 id="_integrazione_gradle"><mark>#</mark> Integrazione Gradle</h3> <div class="paragraph"> <p>JBake può essere integrato nelle build Gradle utilizzando il plugin Gradle di JBake o chiamando direttamente l’interfaccia a riga di comando di JBake:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } ---- Opzione 1: Il Plugin Isolato (nessun dogfooding) Il progetto contiene solo il plugin. Nessun esempio di consumo. Nessun progetto che lo esercita. Per testarlo, è necessario creare un progetto esterno, y referenziare il plugin tramite`mavenLocal`o un composite build, e solo lì verificare che funzioni. [source,shell] ---- $ git clone mon-plugin $ cd mon-plugin $ ./gradlew build # le plugin compile $ # ... et maintenant ? comment je l'essaie ? ---- [WARNING] ==== Un plugin Gradle senza un esempio di consumo, è una libreria senza test di integrazione. Non sai mai se l'ultima modifica a rovinato l'esperienza utente. ==== === Opzione 2 : Il Monorepo Classico (`include(":plugin")`) Gradle `init`genera`settings.gradle.kts`con`include("plugin")`. Il root e il sottomodulo condividono lo stesso demone, le stesse configurazioni, gli stessi cataloghi. Pratico, ma collegato. [source,text] ---- . ├── settings.gradle.kts → include("plugin") ├── build.gradle.kts → plugins { id("mon-plugin") } ├── plugin/ │ └── build.gradle.kts → java-gradle-plugin └── gradle/ └── libs.versions.toml ---- Il problema: * Il root**deve**avere la stessa versione di Gradle del sottomodulo. * `libs.versions.toml`è condiviso — versioni cataloghi comuni, dipendenze che fuggono da un modulo all'altro. * Impossibile costruire il plugin indipendentemente dalla radice. * Il CI deve costruire i due moduli, anche se solo il plugin è cambiato. === Opzione 3: Build composito (`includeBuild()`) Si separano i due in build Gradle distinti e li colleghiamo tramite `includeBuild("mon-plugin")`in`settings.gradle.kts`. È già meglio. Il build del plugin è isolato. Ma il consumatore deve esplicitamente fare riferimento al build esterno — e l'output di `./gradlew tasks`alla radice dipende dalla corretta configurazione del composito. Il clonaggio non è zero-config: bisogna sapere che il Il plugin si trova in una cartella a parte, che il root lo riferisce, ecc. [source,shell] ---- . ├── settings.gradle.kts → includeBuild("plugin-build/") ├── build.gradle.kts → plugins { id("mon-plugin") } └── plugin-build/ ├── settings.gradle.kts └── build.gradle.kts ---- Stavo cercando meglio. Molto meglio. == La Soluzione: Due Build Indipendenti, Una Radice Consumatore Ecco il pattern che ho finito per adottare: [source,text] ---- . ├── settings.gradle.kts ← racine consommateur ├── build.gradle.kts ← 3 lignes : apply plugin + dogfood ├── gradle/ │ └── libs.versions.toml ← catalogue du consommateur ├── {name}-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── settings.gradle.kts ← rootProject.name = "{name}-plugin" │ ├── build.gradle.kts ← java-gradle-plugin, signing, publish │ ├── gradle/ │ │ ├── libs.versions.toml ← catalogue du plugin │ │ └── wrapper/ │ ├── src/ ← sources du plugin │ ├── .agents/ ← gouvernance agent │ └── *.adoc ← AGENT, PROMPT_REPRISE, snapshot, etc. └── site.yml / slides-context.yml / ... ← configs dogfood ---- [IMPORTANT] ==== La chiave :`{name}-plugin/`è un progetto Gradle *completo e autonomo*. Ha il suo wrapper, le sue impostazioni, il suo catalogo di versioni. Si clona, si build, si testa, e si pubblica senza che il root sia al corrente della sua esistenza. ==== Il root, lui, fa solo *una* cosa: applicare il plugin. [source,kotlin] ---- plugins { alias(libs.plugins.bakery) } repositories { mavenLocal() mavenCentral() } bakery { configPath = file("site.yml").absolutePath } ---- Tre righe nel caso di`bakery-gradle`. Niente di più. Zero`include()`, zero`includeBuild()`, zero sottoprogetto Un build Gradle classico che applica un plugin come qualsiasi Quale consumatore lo farebbe. === Il flusso di lavoro [plantuml,architecture-deux-builds,svg] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 12 left to right direction package "RADICE (Consumatore)" #CCFFCC { usecase "Clona il repository" as Clone usecase "### Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin Gradle di JBake o chiamando direttamente l'interfaccia a riga di comando di JBake: ```kotlin tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") }</code></pre> </div> </div> <div class="literalblock"> <div class="title">/gradlew tasks" as Tasks</div> <div class="content"> <pre> usecase "./gradlew bake" as Dogfood note bottom of Dogfood Exerce le plugin Feedback immédiat Zéro config end note }</pre> </div> </div> <div class="paragraph"> <p>package "{name}-plugin/ (Build indipendente)" #CCE5FF { usecase "./gradlew build" as BuildPlugin usecase "./gradlew publishToMavenLocal" as MavenLocal usecase "./gradlew test" as TestPlugin note bottom of BuildPlugin Cycle de vie isolé Tests unitaires + Cucumber CI dédiée possible end note }</p> </div> <div class="paragraph"> <p>Clone -down→ Tasks Tasks -down→ Dogfood Dogfood ..> MavenLocal : "dipende dal plugin pubblicato localmente" BuildPlugin -up→ MavenLocal TestPlugin -up→ BuildPlugin</p> </div> <div class="paragraph"> <p>@enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>=== Il workflow concreto [source,shell]</pre> </div> </div> </div> </div> </div> <h1 id="_1_builder_le_plugin" class="sect0">1. Builder le plugin</h1> <div class="paragraph"> <p>$ cd codebase-plugin $ ./gradlew publishToMavenLocal</p> </div> <h1 id="_2_lexercer_depuis_la_racine" class="sect0">2. L’exercer depuis la racine</h1> <div class="paragraph"> <p>$ cd .. $ ./gradlew indexCodebase queryCodebase snapshot</p> </div> <h1 id="_la_boucle_est_fermée_le_plugin_est_testé_dans_des_conditions" class="sect0">La boucle est fermée. Le plugin est testé dans des conditions</h1> <h1 id="_réelles_de_consommation_par_le_projet_même_qui_lhéberge" class="sect0">réelles de consommation, par le projet même qui l’héberge.</h1> <div class="listingblock"> <div class="content"> <pre>== Perché questa architettura mi ha conquistato Tre benefici che, combinati, valgono il costo della « duplicazione» : === 1. Dogfooding nativo, feedback istantaneo Il miglior test di un plugin Gradle è usarlo. Non un test unitario mockato. Non un`GradleRunner`con un progetto di test. Un *vero* build che applica il plugin su file reali. [source,shell]</pre> </div> </div> <div class="paragraph"> <p>$ git clone bakery-gradle $ cd bakery-gradle $ ./gradlew bake # ← le plugin est exercé immédiatement</p> </div> <div class="listingblock"> <div class="content"> <pre>Se il plugin è rotto, il build radice lo dice. Non c'è bisogno di andare cercare un progetto di test esterno. Il dogfooding è la *prima* compito lanciato da un nuovo contributore. È il smoke test definitivo. [TIP] ==== ### JBake CLI Commands ``` # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ``` La regola è semplice : se la radice compila e`./gradlew tasks` mostra i tuoi task del plugin, il plugin è funzionante. Nessuna sorpresa in produzione. ==== === 2. Clonaggio Zero-Config Un `git clone && ./gradlew tasks`e il nuovo arrivato vede tutto camminare senza configurare nulla. Il`build.gradle.kts`radice è la documentazione vivente d'uso del plugin. Il`site.yml`accanto mostra la configurazione attesa. Confronta con l'alternativa : un README di tre paragrafi che spiega come builder il plugin e come builder il progetto di test. Un nuovo contributore legge il README in diagonale, apre un'issue — mentre l'informazione potrebbe essere *eseguibile*. [IMPORTANT] ==== La documentazione più robusta non è quella che si legge. È quella che**esegui**. Il build radice è la documentazione eseguibile del plugin. ==== === 3. Builds Isolés, CI Indépendants Il plugin ha il suo wrapper Gradle proprio, il suo ciclo di vita proprio, i suoi test. Puoi : * Aggiornare Gradle nel plugin senza toccare la root * Aggiungere una dipendenza nel plugin senza che perda nella radice * Rompere il plugin senza impattare il build radice (finché tu non non pubblicare la versione rotta) * Avere una CI che build/test il plugin, e un'altra che esercita il root — indipendentemente [source,text]</pre> </div> </div> <div class="paragraph"> <div class="title">github/workflows/</div> <p>├── test-plugin.yml → codebase-plugin/.gradlew build ├── test-root.yml → .gradlew tasks (vérifie que le plugin est consommable) └── publish.yml → codebase-plugin/.gradlew publish</p> </div> <div class="listingblock"> <div class="content"> <pre>== L'anatomia della sottocartella `{name}-plugin/ Diamo un'occhiata più da vicino a ciò che vive nella cartella del plugin : [source,text]</pre> </div> </div> <div class="paragraph"> <p>codebase-plugin/ ├── gradlew ← wrapper indépendant ├── settings.gradle.kts ← @Suppress("UnstableApiUsage") │ + foobar-resolver-convention ├── build.gradle.kts ← java-gradle-plugin + signing + publish ├── gradle/ │ ├── libs.versions.toml ← catalogue complet (langchain4j, pgvector…​) │ └── wrapper/ ├── buildSrc/ ← classes utilitaires buildSrc │ ├── build.gradle.kts │ └── src/main/kotlin/ │ ├── codebase/ ← CodebaseYmlAnonymizer, CodebaseConfiguration │ ├── benchmark/ ← BenchmarkConfig, BenchmarkProtocol │ ├── readme/ ← ReadmeYmlAnonymizer │ ├── site/ ← SiteYmlAnonymizer │ ├── slider/ ← SliderYmlAnonymizer │ └── snapshot/ ← SnapshotManager ├── src/ │ ├── main/kotlin/codebase/ │ │ ├── CodebasePlugin.kt ← class Plugin<Project> │ │ ├── rag/ ← pgvector, embedding, anonymization…​ │ │ ├── benchmark/ ← BenchmarkRunner, export, comparison…​ │ │ └── walker/ ← WorkspaceWalker │ └── test/ │ ├── kotlin/codebase/scenarios/ ← steps Cucumber │ ├── features/ ← .feature files │ └── resources/datasets/ ← fixtures .adoc, .yml, .json ├── .agents/ ← gouvernance agent (INDEX, SESSIONS, etc.) ├── AGENT.adoc ← règles agent ├── PROMPT_REPRISE.adoc ← mission session ├── BACKLOG.adoc ← backlog produit ├── snapshot.adoc ← snapshot auto-généré du projet └── embeds.yml ← config RAG embeds</p> </div> <div class="listingblock"> <div class="content"> <pre>Tutto è qui. Nessuna dispersione tra la radice e la sottocartella. Le développeur qui travaille sur le plugin n'a jamais besoin de lasciare`codebase-plugin/`. Lo sviluppatore che utilizza il plugin guarda solo alla radice — e il`build.gradle.kts`di 3 righe gli dice tutto ciò di cui ha bisogno di sapere === Il Catalogo delle Versioni : Due File Distinti [cols="2,3,3"] |=== | |`gradle/libs.versions.toml`(radice) |`{name}-plugin/gradle/libs.versions.toml` |Numero di dipendenze |2-3 (plugin + readme eventualmente) |30+ (langchain4j, pgvector, cucumber...) |Ruolo |Consumare il plugin |Builder il plugin |Chi lo legge |L'utente del plugin |Il sviluppatore del plugin |=== Il root ha un catalogo intenzionalmente minimo. Il plugin ha un catalogo completo. La confusione è impossibile: ogni build ha il proprio ambito dipendenze. [NOTE] ==== Se hai già passato un'ora a debuggare una collisione di dipendenze tra il tuo plugin e il tuo progetto di test, comprendi il valore di questa separazione. I cataloghi indipendenti eliminano questo problema per costruzione. ==== == Ciò che non si fa Questo pattern non è magico. Impone un vincolo che io mi infligge volentieri : *Il root non effettua il build del plugin.* Devi`publishToMavenLocal` ou distribuire su un repository prima che il root possa consumarlo È un costo minimo, e questa è la *buona* vincolo. Il root consuma il plugin come un client esterno — tramite Maven. Esattamente come farebbe un progetto di terze parti. Se il plugin non è pubblicabile, La root Le lo dice immediatamente. [source,shell]</pre> </div> </div> <h1 id="_la_seule_friction_du_pattern" class="sect0">La seule "friction" du pattern</h1> <div class="paragraph"> <p>$ cd codebase-plugin && ./gradlew publishToMavenLocal && cd .. $ ./gradlew tasks --group=codebase</p> </div> <div class="listingblock"> <div class="content"> <pre>== Confronto: Le tre architetture di fronte al dogfooding [cols="2,2,2,2,2"] |=== | |Plugin isolato |Monorepo`include()` |composito`includeBuild()` |**Radice + plugin indipendente** |`git clone && gradlew tasks`fornisce le attività del plugin |�❌ |</think> (No output) |�✅ |✅ |Plugin di build indipendente dalla radice |(no output) |❌ |�✅ |(No output) |catalogo versioni separato |�✅ |�❌ |(no output) |</think> |nessun`include()` ni `includeBuild()` |✅ |❌ |�❌ |�✅ |Dogfood nativo senza configurazione |�❌ |�✅ |⚠️ |(No output) |plug-in CI indipendente |�✅ |�❌ |�✅ |</think> ✅ |Il root è un esempio di consumo reale |�❌ |(No output) |�✅ |(no output) |=== La colonna di destra spunta tutte le caselle. È per questo che io non tornerò più indietro. == Il Contratto DAG : Una build radice non importa mai da una sottocartella Questa architettura si integra naturalmente nel DAG N0→N3 del mio workspace. Il pattern è : *il plugin N2 è il hub delle sue dipendenze, la radice N3 è un terminale chi applica i hub* [plantuml,contrat-dag-architecture,svg]</pre> </div> </div> <div class="paragraph"> <p>@startuml skinparam backgroundColor #FEFEFE skinparam defaultFontSize 11</p> </div> <div class="paragraph"> <p>title Contratto DAG — Radice Consumatore vs Plugin Indipendente package "N3 — RADICE (deposito)" #FFCCCC { [build.gradle.kts (3 lignes)] as ROOT [libs.versions.toml (minimal)] as ROOT_TOML note right of ROOT plugins { bakery } bakery { configPath = …​ } Aucune logique métier end note }</p> </div> <div class="paragraph"> <p>package "N2 — {name}-plugin/" #CCFFCC { [build.gradle.kts (complet)] as PLUGIN [src/main/kotlin/] as SRC [gradle/libs.versions.toml] as PLUGIN_TOML [buildSrc/] as BUILDSRC note bottom of PLUGIN java-gradle-plugin signing + publish Tests unitaires + Cucumber CI dédiée end note }</p> </div> <div class="paragraph"> <p>ROOT_TOML -→ ROOT : "versione plugin" ROOT -down→ PLUGIN : "publishToMavenLocal" @enduml</p> </div> <div class="listingblock"> <div class="content"> <pre>Le `codebase-gradle/build.gradle.kts`fa 6 righe. Nessun`src/`, nessun`buildSrc/`, nessun`gradle/rag-bench.gradle.kts`. Giusto `plugins { alias(libs.plugins.codebase) }`e i repository. Tutta la complessità vive in`codebase-plugin/`. == Conclusion : La Duplicazione Apparente Che Fa Risparmiare Tempo Quando mostro questa struttura a qualcuno, la prima reazione è spesso : « Ma hai due`gradlew`, due`settings.gradle.kts`, due`libs.versions.toml`— è una duplicazione! Sì. E no. La « duplicazione », è riprodurre la stessa informazione in due posti. Qui, sono due file *distinti* che servono due usi *distinti*: il catalogo del plugin (30+ dipendenze per builder) e il catalogo dalla radice (2-3 dipendenze da consumare). Il wrapper del plugin (versione bloccata per lo sviluppo) e il wrapper della radice (versione potenzialmente diversa, per l'esercizio del plugin). Non è una duplicazione. È una **separazione delle** responsabilità** applicata al sistema di build. Ogni build fa una cosa, e solo una. La radice consuma. Il plugin si compila. Il costo? Un ordine`publishToMavenLocal`tra la build del plugin e il build della radice. Il vantaggio? Una chiarezza architettonica che elimina ore di debugging a valle Da quando ho distribuito questo pattern su`bakery-gradle`, `plantuml-gradle`, `codebase-gradle`, e gli altri plugin di`foundry/public/`, non ho mai più esitato nell'aprire un terminale in uno dei miei repository. Le primo riflesso —`./gradlew tasks`— cammina sempre, dà sempre i buoni compiti, e mi dice istantaneamente se tutto è sano. Ed ecco l'architettura corretta. Non si legge in un README. Si verifica in un terminal, in meno di dieci secondi. == Riferimenti * xref:0105_integrer_graphify_workflow_gradle_post.adoc[Articolo 0105 — Integrare Graphify in un workflow Gradle] * xref:0117_granularisation_oss_css_repositorie_workspace_post.adoc[Article 0117 — La Granularizzazione OSS/CSS] * xref:0123_knowledge_graph_moteur_recommandation_articles_connexes_post.adoc[Article 0123 — Il Knowledge Graph come motore di raccomandazione]</pre> </div> </div> https://cheroliv.com/blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html Tue, 12 May 2026 00:00:00 +0000 blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scena_martedì_12_maggio_1730">La scena : Martedì 12 maggio, 17:30</a></li> <li><a href="#_la_diagnosi_tre_tipi_di_relazioni_che_nessun_template_vede">La Diagnosi: Tre Tipi di Relazioni che Nessun Template Vede</a></li> <li><a href="#_la_soluzione_un_pipeline_gradle_non_una_chiamata_llm_a_caldo">La Soluzione : Un pipeline Gradle, non una chiamata LLM a caldo</a> <ul class="sectlevel2"> <li><a href="#_larchitettura_bakery_importa_graphify_non_engine">L’architettura : Bakery Importa Graphify, Non Engine</a></li> <li><a href="#_il_pipeline_scan_grafo_modello">Il Pipeline : Scan → Grafo → Modello</a></li> <li><a href="#_fallback_cronologico">Fallback cronologico</a></li> </ul> </li> <li><a href="#_lontologia_emergente_quando_gli_articoli_si_raggruppano_senza_conoscersi">L’ontologia emergente: Quando gli articoli si raggruppano senza conoscersi</a></li> <li><a href="#_il_contratto_dag_chi_importa_chi">Il Contratto DAG: Chi Importa Chi</a></li> <li><a href="#_cosa_si_guadagna_e_cosa_non_si_guadagna">Cosa si guadagna (e cosa non si guadagna)</a></li> <li><a href="#_prospettive_il_blog_come_knowledge_graph_pubblico">Prospettive : Il Blog Come Knowledge Graph Pubblico</a></li> <li><a href="#_conclusione_il_sistema_di_file_sa_ciò_che_il_modello_ignora">Conclusione : Il sistema di file sa ciò che il modello ignora</a></li> <li><a href="#_riferimenti">Riferimenti</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 14 minutes</div> <p>Stai leggendo un articolo sull’integrazione di pgvector con LangChain4j. In fondo alla pagina, JBake ti suggerisce « Articoli correlati ». Clicchi. È un articolo su…​ la configurazione di Kitty Terminal. L’unico punto in comune tra i due? Sono stati pubblicati da meno di quindici giorni di distanza. Non è una raccomandazione. È un calendario travestito da editoriale.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_scena_martedì_12_maggio_1730">La scena : Martedì 12 maggio, 17:30</h2> <div class="sectionbody"> <div class="paragraph"> <p>Sto rileggendo uno dei miei articoli — <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">quello sul Knowledge Graph come strumento di comprensione della codebase</a> Il contenuto è denso : nodi, archi, comunità, PlantUML, onboarding. Un articolo tecnica di 15 minuti di lettura che mobilizza`graphify-gradle`, <code>plantuml-gradle</code>, e i concetti di topologia di grafo.</p> </div> <div class="paragraph"> <p>Alla fine della pagina, gli « Articoli correlati » mi propongono :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Un articolo su Firebase Contact Form (0113)</p> </li> <li> <p>Un articolo sul meccanismo Eager/Lazy (0108)</p> </li> <li> <p>Un articolo sulla migrazione Gradle script → plugin (0102)</p> </li> <li> <p>Un articolo sul cumulo di abbonamenti Ollama Pro (0120)</p> </li> </ol> </div> <div class="paragraph"> <p>Tre di questi quattro articoli non hanno <strong>alcun</strong> rapporto con il Knowledge Graph. Sono lì perché sono gli ultimi pubblicati — vicinanza temporale, non vicinato semantico</p> </div> <div class="paragraph"> <p>Sto guardando il template`post.thyme`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes (liens internes SEO) --> <th:block th:each="post,postStat : ${published_posts}"> <th:block th:if="${!post.uri.equals(content.uri) and postStat.index lt 4}"> ... </th:block> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>`published_posts`è una lista cronologica.`postStat.index lt 4`prende le i primi quattro che non sono il post corrente. È tutto. Nessuna logica di similarità. Nessuna nozione di contenuto. Solo un ciclo`for`travestita da raccomandazione.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>Non è un bug di JBake. È il comportamento predefinito di tutto generatore di sito statico : l’elenco dei post è piatto e ordinato per data. Il modello fa quello che può con quello che ha.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Ma non è una ragione per accettarlo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_diagnosi_tre_tipi_di_relazioni_che_nessun_template_vede">La Diagnosi: Tre Tipi di Relazioni che Nessun Template Vede</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il mio corpus di articoli — 23 post in 4 mesi — ha una struttura ricca che il template cronologico sovrascrive completamente :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Riferimenti espliciti</strong> : utilizzo`xref:`massivamente nei miei articoli.</p> </li> </ol> </div> <div class="paragraph"> <p>L’articolo 0122 fa riferimento al 0106 (knowledge graph) e al 0116 (compartimentaggio) epistemico). Questi link sono del <strong>hard linking</strong> editoriale — ho ha deliberatamente deciso di collegare questi concetti.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Tag condivisi</strong> : ogni articolo ha`:jbake-tags:`. L’articolo su</p> </li> </ol> </div> <div class="paragraph"> <p>Graphify + PlantUML (0105) ha`gradle, graphify, plantuml, knowledge-graph`. L’articolo sul Knowledge Graph (0106) ha <code>knowledge-graph, graphify, plantuml</code>. Tre tag in comune su sette — 43% di sovrapposizione.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Entità nominate co-occorrenti</strong> : « pgvector », « RAG », « embedding</p> </li> </ol> </div> <div class="paragraph"> <p>appaiono insieme in quattro articoli diversi. « LangChain4j », </think> appaiono insieme in quattro articoli diversi. « LangChain4j », </think> appaiono insieme in quattro articoli diversi. « LangChain4j », Ollama », « plugin Gradle » in sei altri. Questi non sono tag dichiarati — sono dei <strong>patterns emergenti</strong> del corpus che solo un NLP può rilevare.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/trois-couches-relation-articles.svg" alt="trois couches relation articles" width="1742" height="5492"> </div> </div> <div class="paragraph"> <p>Oggi, il mio sito non utilizza <strong>nessuna</strong> di questi tre livelli. Utilizza lo strato zero : l’ordine di inserimento in una lista Java</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_un_pipeline_gradle_non_una_chiamata_llm_a_caldo">La Soluzione : Un pipeline Gradle, non una chiamata LLM a caldo</h2> <div class="sectionbody"> <div class="paragraph"> <p>La prima tentazione sarebbe quella di chiamare un LLM al momento del bake : « Per questo articolo, trova i tre articoli più simili nel corpus. Non lo fate.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Una chiamata LLM a ciascuno`./gradlew bake`costa tempo, denaro e introduce non determinismo nel tuo build. La risposta del LLM può cambiare tra due build senza che il contenuto sia cambiato. Il tuo CI diventa non riproducibile, i vostri test diventano flaky.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>La soluzione è deterministica: un pipeline Gradle che precalcola il grafo di similarità e lo memorizza in`graph.json`. Il template legge il risultato — mai avvia un calcolo.</p> </div> <div class="sect2"> <h3 id="_larchitettura_bakery_importa_graphify_non_engine">L’architettura : Bakery Importa Graphify, Non Engine</h3> <div class="paragraph"> <p>È il punto di architettura più importante. La tentazione sarebbe di cablare la collaborazione in`engine/build.gradle.kts` : engine applique graphify per lo scan, bakery per il bake, e engine fa da ponte tra i due.</p> </div> <div class="paragraph"> <p>È un antipattern. Engine è un <strong>terminal consumatore</strong> — aplica dei plug-in, non implementa la logica di business. La regola è : <strong>L’onere della prova è sul plugin proprietario.</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="./images/bakery-import-graphify.svg" alt="bakery import graphify" width="1736" height="5700"> </div> <div class="title">Figure 1. Architettura corretta — Bakery importa Graphify</div> </div> <div class="paragraph"> <p>Il contratto DAG è rispettato : bakery (N2) importa graphify (N0), N2 > N0, Nessuna violazione. Il motore (N3) importa la panetteria (N2), N3 > N2, OK.</p> </div> <div class="paragraph"> <p>Motore non ha <strong>alcuna</strong> linea di codice che fa riferimento`graph.json`, <code>relatedPosts</code>, o qualsiasi altra nozione di similarità. Applica bakery, punto. La La collaborazione è interna a bakery.</p> </div> </div> <div class="sect2"> <h3 id="_il_pipeline_scan_grafo_modello">Il Pipeline : Scan → Grafo → Modello</h3> <div class="paragraph"> <p>Ecco il pipeline completo in tre fasi</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Scansione</strong> (graficare) :`graphify-plugin`scansiona il workspace. Nel suo</p> </li> </ol> </div> <div class="paragraph"> <p>forma attuale, già rileva i`xref:`tra`.adoc`e i esponi in`graph.json`come degli edge di tipo`reference`.<br> Lo arricchiamo per il contenuto editoriale: * Analizza i metadati JBake (<code>:jbake-tags:</code>, <code>:jbake-description:</code>) di ogni`.adoc`del blog * Calcola le co-occorrenze dei tag → edges`tag_cooccurrence`con peso * Estrai le entità nominate dalle descrizioni tramite TF-IDF → archi`entity_overlap` * Inietti una sezione`blog_articles`nel`graph.json`esistente (No output)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Extrait de l'enrichissement graphify pour le blog fun enrichBlogSection(graphJson: File, blogDir: File): GraphJson { val articles = blogDir.listFiles { f -> f.extension == "adoc" } .map { parseJbakeMetadata(it) } val nodes = articles.map { ArticleNode(it.slug, it.title, it.tags) } val edges = mutableListOf<GraphEdge>() // Couche 1 : xref (déjà fait par scanWorkspace) // Couche 2 : co-occurrences de tags for (a in articles) { for (b in articles) { if (a.slug == b.slug) continue val common = a.tags.intersect(b.tags) if (common.isNotEmpty()) { edges.add(GraphEdge( source = a.slug, target = b.slug, type = "tag_cooccurrence", weight = common.size.toDouble() / (a.tags.size + b.tags.size) )) } } } return graphJson.copy( blogArticles = BlogSection(nodes, edges) ) }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Bake</strong> (bakery) : al momento del`./gradlew bake`, `BakeryPlugin`letto</p> </li> </ol> </div> <div class="paragraph"> <p>`graph.json`e risolve gli articoli correlati per ogni post. (No output)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BakeryPlugin — résolution des articles connexes fun resolveRelatedPosts( currentSlug: String, graph: GraphJson, maxResults: Int = 4 ): List<RelatedPost> { val edges = graph.blogArticles.edges .filter { it.source == currentSlug || it.target == currentSlug } return edges .sortedByDescending { it.weight } .take(maxResults) .map { edge -> val relatedSlug = if (edge.source == currentSlug) edge.target else edge.source graph.blogArticles.nodes.first { it.slug == relatedSlug } } }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>(No output)<code>post.thyme</code>) : il modello JBake riceve ora una mappa</p> </li> </ol> </div> <div class="paragraph"> <p>strutturata invece di una lista cronologica piatta<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes basés sur le Knowledge Graph --> <th:block th:if="${relatedPosts != null and !relatedPosts.empty}"> <section class="mt-5 pt-4 border-top"> <h2 class="h4 mb-3">Articles connexes</h2> <th:block th:each="related : ${relatedPosts}"> <div class="mb-2"> <a th:href="${content.rootpath} + ${related.uri}" th:text="${related.title}" class="fw-semibold"></a> <br/> <small class="text-muted"> <th:block th:each="reason,iterStat : ${related.reasons}"> <span class="badge bg-light text-dark" th:text="${reason}"></span> </th:block> </small> </div> </th:block> </section> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>Il template è lo stesso — non sa <strong>da dove</strong> vengono i dati. Solo il contratto tra bakery e JBake è cambiato :`published_posts`(lista cronologico) diventa`relatedPosts`(mappa ponderata dal grafo).</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Il badge « ragione » (es:`xref 0122`, <code>tag:gradle</code>, <code>cluster:pgvector-rag</code>) spiega al lettore <strong>perché</strong> questo articolo è correlato. Non è solo della trasparenza — è pedagogia sulla topologia di il tuo contenuto.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_fallback_cronologico">Fallback cronologico</h3> <div class="paragraph"> <p>Si `graph.json`est assente (build locale senza scan preliminare, primo) distribuzione, CI che non ha ancora integrato lo scan graphify), il template deve degradarsi elegantemente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveRelatedPosts(currentSlug: String, graph: GraphJson?): List<RelatedPost> { if (graph != null && graph.blogArticles != null) { return resolveFromGraph(currentSlug, graph) } // Fallback chronologique — même comportement qu'aujourd'hui logger.warn("[bakery] graph.json absent — fallback chronologique") return resolveFromChronology(currentSlug) }</code></pre> </div> </div> <div class="paragraph"> <p>Il comportamento predefinito è identico al comportamento corrente. Il motore di raccomandazione è un <strong>miglioramento progressivo</strong> — non un modifica di rottura.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lontologia_emergente_quando_gli_articoli_si_raggruppano_senza_conoscersi">L’ontologia emergente: Quando gli articoli si raggruppano senza conoscersi</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo strato più interessante è il terzo: l’ontologia emergente. Articoli che non vengono citati, che non hanno gli stessi tag, ma chi parlano della stessa cosa senza rendersene conto.</p> </div> <div class="paragraph"> <p>Prendiamo un esempio concreto. Tre articoli del mio corpus :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>0119 — Benchmark DGX Spark vs Abbonamento Cloud LLM</p> </li> <li> <p>0121 — Plugin Gradle Pilotare due istanze Ollama Pro</p> </li> <li> <p>0122 — Rapporto di efficienza 27x 45x Flotta di esperti IA</p> </li> </ol> </div> <div class="paragraph"> <p>Questi tre articoli non hanno <strong>nessuno</strong> xref tra di loro. I loro tag non si si limitano al 20% (« ollama », « llm » comuni). Ma un NLP leggero sulle descrizioni rivela un cluster evidente: « costo », « abbonamento », cloud », « GPU », « API key », « Ollama Pro », « efficacia », « ratio</p> </div> <div class="paragraph"> <p>Formano un cluster ontologico: <strong>l’economia del LLM self-hosted vs cloud</strong>. Questo cluster non è dichiarato da nessuna parte. Esso emerge dal corpus.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/cluster-ontologique-exemple.svg" alt="cluster ontologique exemple" width="697" height="405"> </div> </div> <div class="paragraph"> <p>Questo cluster ontologico diventa un edge composite in`graph.json`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "source": "0119-benchmark-dgx-spark", "target": "cluster:economie-llm", "type": "entity_cluster", "weight": 0.73, "metadata": { "clusterLabel": "Économie LLM Self-Hosted vs Cloud", "commonEntities": ["coût", "GPU", "abonnement", "Ollama Pro", "ratio"], "articlesInCluster": [ "0119-benchmark-dgx-spark", "0121-ollama-pro-deux-instances", "0122-ratio-efficacite-flotte-experts" ] } }</code></pre> </div> </div> <div class="paragraph"> <p>Il NLP è volontariamente leggero — TF-IDF + cosine similarity sui descrizioni. Non c’è bisogno di BERT, non c’è bisogno di un modello linguistico Il corpus è composto da 23 articoli, la matrice di similarità sta in un file JSON di 50 KB.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>La potenza del NLP non deriva dalla sofisticazione dell’algoritmo, ma del <strong>dimensione del corpus</strong> e del <strong>qualità delle descrizioni</strong>. Una `:jbake-description:`ben scritta di 150 caratteri contiene più di segnale per TF-IDF che un articolo intero di 3000 parole.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_il_contratto_dag_chi_importa_chi">Il Contratto DAG: Chi Importa Chi</h2> <div class="sectionbody"> <div class="paragraph"> <p>È il punto in cui la disciplina architettonica paga. Il DAG N0→N3 definito in`engine/build.gradle.kts`dà una regola semplice: nessun progetto importa un progetto di livello superiore.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 27.2728%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Plugin consumatore</th> <th class="tableblock halign-left valign-top">Plugin importato</th> <th class="tableblock halign-left valign-top">Livello consumatore</th> <th class="tableblock halign-left valign-top">Livello importato</th> <th class="tableblock halign-left valign-top">Valido?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N2 > N0 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N3 > N2 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Tecnica OK, ma <strong>concettualmente falsa</strong> — la collaborazione è interna alla bakery</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Il motore applica la panetteria. La panetteria applica graphify. È tutto. Se un giorno voglio aggiungere il vector store codebase (N1) per la ricerca semantica cross-corpus, bakery lo importa anche. Il motore non cambia.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Il pattern è : <strong>il plugin N2 è l’hub delle sue dipendenze</strong>. Engine N3 non è un hub — è un terminale che applica gli hub.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_cosa_si_guadagna_e_cosa_non_si_guadagna">Cosa si guadagna (e cosa non si guadagna)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il guadagno principale è editoriale, non tecnico</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Prima</th> <th class="tableblock halign-left valign-top">Dopo</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Articoli correlati = 4 ultimi post</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Articoli correlati = top 4 per peso nel Knowledge Graph</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Lettore legge il RAG → raccomandazione Kitty Terminal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il lettore legge RAG → raccomandazione pgvector, chunking, vector store</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero trasparenza sul perché</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Distintivo`xref 0122`, <code>tag:gradle</code>, `cluster:rag`visibile</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake standard, zero sforzo, zero valore</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pipeline Gradle deterministica, riproducibile, testabile</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nessuna curva di apprendimento per il lettore</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il lettore scopre la <strong>topologia</strong> del mio contenuto</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Ciò che <strong>non</strong> si guadagna:</p> </div> <div class="ulist"> <ul> <li> <p>Non è un « vero » motore di raccomandazione (nessun collaborativo</p> </li> </ul> </div> <div class="paragraph"> <p>filtering, senza A/B testing, senza feedback loop)</p> </div> <div class="ulist"> <ul> <li> <p>La qualità dipende dalla ricchezza dei metadati JBake — se il tuo</p> </li> </ul> </div> <div class="paragraph"> <p>le descrizioni sono vuote, TF-IDF non vede nulla</p> </div> <div class="ulist"> <ul> <li> <p>Il NLP è offline — i nuovi articoli sono clusterizzati solo al</p> </li> </ul> </div> <div class="paragraph"> <p>prossimo scan (è buono : il build rimane deterministico)</p> </div> </div> </div> <div class="sect1"> <h2 id="_prospettive_il_blog_come_knowledge_graph_pubblico">Prospettive : Il Blog Come Knowledge Graph Pubblico</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa funzionalità apre una prospettiva più ampia: e se`cheroliv.com` diventava lui stesso un <strong>knowledge graph navigabile</strong> ?</p> </div> <div class="paragraph"> <p>Gli articoli sono nodi. I tag sono comunità. I xref sono degli spigoli. Il lettore non legge più un articolo isolato — si muove in un <strong>grafo della conoscenza</strong> di cui l’articolo corrente è il punto di ingresso.</p> </div> <div class="paragraph"> <p>Immaginate una home page che non mostra l’elenco cronologico degli ultimi post, ma una <strong>mappa del corpus</strong> : cluster ontologici, articoli pivot (quelli con il maggior numero di archi), percorsi di lettura consigliati « Se ti è piaciuto l’articolo su Graphify, leggi poi quello sul Knowledge Graph come strumento di comprensione )</p> </div> <div class="paragraph"> <p>Non è più un blog. È un <strong>atlas semantico</strong>.</p> </div> <div class="paragraph"> <p>E non è fantascienza. Il`graph.json`esiste già. Gli manca solo l’interfaccia di navigazione.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione_il_sistema_di_file_sa_ciò_che_il_modello_ignora">Conclusione : Il sistema di file sa ciò che il modello ignora</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ciò che ho progettato martedì sera, è la sostituzione di una euristica pigra (l’ordine cronologico) mediante una rappresentazione fedele della struttura del mio corpus (il Knowledge Graph)</p> </div> <div class="paragraph"> <p>Il template`post.thyme`Non cambia. Ciò che cambia, è ciò che si gli dà da mangiare. Prima : una lista Java ordinata per`date`. Dopo : un grafo pesato derivato da tre livelli di analisi — xrefs, co-occorrenze di tags, e ontologia emergente per NLP.</p> </div> <div class="paragraph"> <p>Il ciclo è chiuso. graphify scansiona il workspace. Bakery legge il grafico e nutre il modello. Il lettore vede delle raccomandazioni pertinenti. E engine — il maestro d’orchestra — non sa nemmeno che Tutto questo esiste.</p> </div> <div class="paragraph"> <p>Questa è la buona architettura. Ogni plugin fa una cosa. E il terminale del consumatore non ha bisogno di sapere come.</p> </div> </div> </div> <div class="sect1"> <h2 id="_riferimenti">Riferimenti</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Articolo 0105 — Integrazione di Graphify in un flusso di lavoro Gradle</a></p> </li> <li> <p>Articolo 0106 — Il Knowledge Graph come strumento di comprensione</p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Articolo 0117 — La Granularizzazione OSS/CSS</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Articolo 0121 — Plugin Gradle Pilotare Due Istanze Ollama Pro</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Articolo 0122 — 27× a 45× più efficace : flotta di esperti IA</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_perché_due_volte_la_stessa_cosa">Perché due volte la stessa cosa?</a></li> <li><a href="#_il_cuore_del_problema_la_chiave_del_dispositivo">Il cuore del problema: la chiave del dispositivo</a></li> <li><a href="#_preparazione_passo_dopo_passo">Preparazione — Passo dopo passo</a> <ul class="sectlevel2"> <li><a href="#_prerequisito">Prerequisito</a></li> <li><a href="#_passo_1_creare_il_volume">Passo 1: Creare il Volume</a></li> <li><a href="#_passo_2_avvia_il_contenitore_docker">Passo 2: Avvia il contenitore Docker</a></li> <li><a href="#_passo_3_recupera_la_chiave_pubblica">Passo 3: Recupera la Chiave Pubblica</a></li> <li><a href="#_passo_4_registra_la_chiave_su_ollama_com">Passo 4 : Registra la Chiave su Ollama.com</a></li> <li><a href="#_passo_5_testare_con_un_piccolo_modello_gratuito">Passo 5 : Testare con un Piccolo Modello Gratuito</a></li> </ul> </li> <li><a href="#_la_trappola_dellapi_v1models">La trappola dell’API `/v1/models</a></li> <li><a href="#_risultato_due_sessioni_due_conti_zero_conflitto">Risultato: Due Sessioni, Due Conti, Zero Conflitto</a></li> <li><a href="#_lezioni_apprese">Lezioni Apprese</a></li> <li><a href="#_per_andare_oltre">Per Andare Oltre</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 14 minutes</div> <p>Due abbonamenti Pro, una sola macchina, una sola carta bancaria, e zero conflitti di rete. Come Docker mi ha permesso di raddoppiare la mia capacità di inferenza cloud senza acquistare un secondo PC.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Uso Ollama Pro da diversi mesi per alimentare le mie sessioni OpenCode con modelli cloud. Il trucco è che anche con un abbonamento Pro, si viene rapidamente limitati dal <strong>rate limiting</strong> quando si avviano più agenti in parallelo. La soluzione evidente: un secondo abbonamento.</p> </div> <div class="paragraph"> <p>Ma allora è un dramma.</p> </div> <div class="paragraph"> <p>Ollama identifica ogni macchina tramite una chiave SSH unica — la famosa <strong>Device Key</strong>. Due istanze sullo stesso OS condividerebbero la stessa identità, ed è impossibile collegare due account Pro allo stesso dispositivo. E come immagini, non stavo per comprare un secondo laptop solo per quello.</p> </div> <div class="paragraph"> <p>La soluzione: imbrogliare. Far credere a Ollama che stia eseguendo su due macchine diverse, mentre in realtà condividono la stessa CPU, la stessa RAM e la stessa connessione di rete. Docker ci offrirà una bolla di isolamento perfetta.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml ... ... ( skipping 130 lines ) ... skinparam StereotypeI { BackgroundColor white BorderColor black } skinparam StereotypeN { BackgroundColor white BorderColor black } skinparam UseCaseStereoType { FontColor black FontName Verdana } skinparam BoxPadding 10 skinparam DefaultFontSize 12 left to right direction node "Macchina Fisica" { frame "Ollama Istanza A (Nativa)" as Native { database "Identità ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml !theme plain skinparam BoxPadding 10 skinparam DefaultFontSize 12 left to right direction node "Macchina Fisica" { frame "Ollama Istanza A (Nativa)" as Native { database "Identità /usr/share/ollama/.ollama/id_ed25519" as KeyA portin "API :11434" as PortA } frame "Istanza Ollama B (Docker)" as Docker { database "Identità\n~/ollama-b-data/id_ed25519" as KeyB portin "API\n:11435" as PortB } } cloud "Ollama Cloud" { actor "Conto Pro A (email 1)" as AccountA actor "Conto Pro B\n(email 2)" as AccountB } KeyA --> AccountA : "Chiave SSH A" KeyB --> AccountB : "Chiave SSH B" PortA --> AccountA : "Richieste A" PortB --> AccountB : "Richieste B" note bottom of Docker Conteneur isolé : identité SSH distincte, port réseau distinct, volume persistant end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_due_volte_la_stessa_cosa">Perché due volte la stessa cosa?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Prima di considerarmi malato mentale, lasciami spiegare il caso d’uso.</p> </div> <div class="paragraph"> <p>Con un unico abbonamento Pro, posso avviare un modello come`deepseek-v4-pro:cloud`in una sessione OpenCode. Il problema si presenta quando voglio <strong>due</strong> sessioni simultanee. Le quote di rate limiting fanno sì che la seconda sessione sia lenta o venga rifiutata completamente.</p> </div> <div class="paragraph"> <p>Con due abbonamenti Pro indipendenti :</p> </div> <div class="ulist"> <ul> <li> <p>Sessione OpenCode 1 → Conto Pro A`localhost:11434`)</p> </li> <li> <p>Session OpenCode 2 → Compte Pro B (<code>localhost:11435</code>)</p> </li> </ul> </div> <div class="paragraph"> <p>Ogni sessione ha il suo proprio quota, il suo proprio contesto e non ostacola l’altra. È del multi-processing umano.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Due abbonamenti Pro = due email diversi. La stessa carta bancaria funziona — il sistema di pagamento Ollama non blocca le sottoscrizioni multiple dallo stesso metodo di pagamento. L’ho verificato.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_il_cuore_del_problema_la_chiave_del_dispositivo">Il cuore del problema: la chiave del dispositivo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando installi Ollama, una coppia di chiavi SSH ed25519 viene generata nella directory di identità :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...</code></pre> </div> </div> <div class="paragraph"> <p>Questa chiave viene caricata sui server di Ollama durante il`ollama signin`. È lei che dice « questa macchina appartiene a un account Pro ». Se le tue due istanze condividono lo stesso file`id_ed25519`, condividono la stessa identità. Fine della partita.</p> </div> <div class="paragraph"> <p>La parade: dare alla nostra seconda istanza il suo proprio directory di identità, isolato in un volume Docker.</p> </div> </div> </div> <div class="sect1"> <h2 id="_preparazione_passo_dopo_passo">Preparazione — Passo dopo passo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_prerequisito">Prerequisito</h3> <div class="ulist"> <ul> <li> <p>Un’installazione nativa funzionante di Ollama (script ufficiale`curl | sh`)</p> </li> <li> <p>Docker installato e funzionante</p> </li> <li> <p>Portainer o docker-compose per il deployment</p> </li> <li> <p>Due account Ollama con due email distinti</p> </li> </ul> </div> <div class="paragraph"> <p>Ho utilizzato la versione`0.20.2`— quella fornita dallo script ufficiale e dall’immagine Docker corrispondente.</p> </div> </div> <div class="sect2"> <h3 id="_passo_1_creare_il_volume">Passo 1: Creare il Volume</h3> <div class="paragraph"> <p>Una semplice directory sull’host servirà da volume persistente per l’identità dell’istanza B:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/ollama-b-data</code></pre> </div> </div> <div class="paragraph"> <p>Questa cartella verrà montata nel contenitore Docker come`/root/.ollama`, lì dove Ollama memorizza le sue chiavi d’identità, la sua cronologia e i suoi modelli.</p> </div> </div> <div class="sect2"> <h3 id="_passo_2_avvia_il_contenitore_docker">Passo 2: Avvia il contenitore Docker</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml"># docker-compose.yml services: ollama-instance-b: image: ollama/ollama:0.20.2 container_name: ollama-instance-b ports: - "11435:11434" volumes: - /home/cheroliv/ollama-b-data:/root/.ollama environment: - OLLAMA_HOST=0.0.0.0 restart: always</code></pre> </div> </div> <div class="paragraph"> <p>Cosa sta succedendo qui :</p> </div> <div class="ulist"> <ul> <li> <p>Il porto<strong>11435</strong>dell’host è mappato sul<strong>11434</strong>interno del contenitore. Così, l’istanza Docker ascolta su`:11435`senza conflitto con l’istanza nativa che occupa`:11434`.</p> </li> <li> <p>Il volume`~/ollama-b-data`è montato su`/root/.ollama`— lì verrà memorizzata l’identità SSH.</p> </li> <li> <p>`OLLAMA_HOST=0.0.0.0`permette al contenitore di accettare connessioni esterne.</p> </li> </ul> </div> <div class="paragraph"> <p>Ho distribuito questa stack tramite Portainer, ma un semplice`docker compose up -d`funziona altrettanto bene.</p> </div> </div> <div class="sect2"> <h3 id="_passo_3_recupera_la_chiave_pubblica">Passo 3: Recupera la Chiave Pubblica</h3> <div class="paragraph"> <p>Il contenitore essendo vuoto al primo avvio, Ollama genera automaticamente una nuova coppia di chiavi SSH nel volume. Si recupera la chiave pubblica:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b cat /root/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ+dvnfmuo49q5O8LOlvgZ39SKORFw47ry9k4H2jPc</code></pre> </div> </div> <div class="paragraph"> <p>Verifico che questa chiave sia <strong>diversa</strong> da quella dell’istanza nativa :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Instance native $ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGyF...(différente) # Instance Docker $ cat ~/ollama-b-data/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ...(différente)</code></pre> </div> </div> <div class="paragraph"> <p>Due chiavi distinte, due identità separate. Il gioco è fatto.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Se il tuo contenitore si riavvia, <strong>riutilizza</strong> le chiavi presenti nel volume. L’identità è persistente. Non perderai l’associazione con l’account Pro.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_passo_4_registra_la_chiave_su_ollama_com">Passo 4 : Registra la Chiave su Ollama.com</h3> <div class="paragraph"> <p>Direzione <a href="https://ollama.com/settings/keys" class="bare">https://ollama.com/settings/keys</a> → Aggiungi chiave SSH. Si incolla la chiave pubblica dell’istanza Docker e si conferma.</p> </div> <div class="paragraph"> <p>Poi, si collega questa identità all’account Pro B:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin</code></pre> </div> </div> <div class="paragraph"> <p>Il navigatore si apre, ci si connette con l’email dell’account B e il token è associato alla chiave SSH del contenitore. Si verifica che tutto sia OK :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin User: cherolivpro</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_passo_5_testare_con_un_piccolo_modello_gratuito">Passo 5 : Testare con un Piccolo Modello Gratuito</h3> <div class="paragraph"> <p>Prima di valutare il prezzo di un abbonamento Pro, voglio essere certo che il tubo funzioni. Faccio un pull di un piccolo modello locale e gratuito per validare la connettività :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull qwen3:0.6b pulling manifest pulling 7f4030143c1c: 100% ▕██████████████████▏ 522 MB success $ curl -s http://localhost:11435/api/tags {"models":[{"name":"qwen3:0.6b","model":"qwen3:0.6b",...}]}</code></pre> </div> </div> <div class="paragraph"> <p>Il porto`11435`risponde, il modello è servito. L’istanza B è vivente.</p> </div> <div class="paragraph"> <p>Una volta rassicurato, passo al pull del vero modello cloud Pro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull deepseek-v4-pro:cloud pulling manifest pulling 31c3059e137e: 100% ▕██████████████████▏ 344 B success</code></pre> </div> </div> <div class="paragraph"> <p>344 byte per il manifesto di un modello cloud — normale, l’inferenza viene eseguita lato server, non in locale. Ed ecco il test definitivo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl -s http://localhost:11435/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4-pro:cloud","messages":[{"role":"user","content":"Dis bonjour en une phrase courte."}]}' { "id": "chatcmpl-480", "model": "deepseek-v4-pro", "choices": [{ "message": { "content": "Bonjour !" }, "finish_reason": "stop" }], "usage": { "total_tokens": 181 } }</code></pre> </div> </div> <div class="paragraph"> <p>Buongiorno anche a te, istanza B.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_trappola_dellapi_v1models">La trappola dell’API `/v1/models</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ho perso 20 minuti su un dettaglio stupido. Quando ho configurato il provider`ollama-b`In OpenCode, niente appariva nel selettore dei modelli. Niente. Nulla.</p> </div> <div class="paragraph"> <p>La ragione? L’API`/v1/models`dell’istanza B restituiva`{"object":"list","data":null}`al posto di`{"object":"list","data":[]}`quand nessun modello era stato estratto. Il valore`null`faceva bloccare il parsing lato OpenCode, che non mostrava il provider.</p> </div> <div class="paragraph"> <p>La soluzione: dichiarare i modelli <strong>esplicitamente</strong> nella configurazione OpenCode anziché fare affidamento sulla scoperta dinamica.</p> </div> <div class="listingblock"> <div class="title">~/.config/opencode/opencode.json</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "gemma4:e2b": { "name": "Gemma 4 E2B (local)" } } }, "ollama-b": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Instance B (Docker)", "options": { "baseURL": "http://localhost:11435/v1" }, "models": { "qwen3:0.6b": { "name": "Qwen3 0.6B (B)" }, "deepseek-v4-pro:cloud": { "name": "DeepSeek V4 Pro (B)" } } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Con questa dichiarazione esplicita, OpenCode vede immediatamente il provider B e i suoi modelli. Un riavvio di sessione, e il selettore`/models`visualizza le due istanze una accanto all’altra.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Se non vedi il tuo provider personalizzato in`/models`, non perdere tre ore a riavviare il tuo terminale. Dichiara i modelli manualmente in`opencode.json`— risolve il problema immediatamente.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_risultato_due_sessioni_due_conti_zero_conflitto">Risultato: Due Sessioni, Due Conti, Zero Conflitto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Alla fine, posso lanciare due sessioni OpenCode contemporaneamente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Session 1 → /models → Ollama (local) → deepseek-v4-pro:cloud → Compte A Session 2 → /models → Ollama Instance B (Docker) → deepseek-v4-pro:cloud → Compte B</code></pre> </div> </div> <div class="paragraph"> <p>Ogni session ha il proprio quota, il proprio rate limit, e non si calpestano i piedi. Stessa macchina, stessa carta blu, due email diverse.</p> </div> <div class="paragraph"> <p>E il meglio? Il contenitore Docker è`restart: always`. Sopravvive ai riavvii del sistema senza intervento manuale.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lezioni_apprese">Lezioni Apprese</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Docker isola tutto, persino l’identità</strong>— Un semplice bind mount di volume è sufficiente per dare a un contenitore il proprio set di chiavi SSH, rendendolo indistinguibile da una macchina fisica diversa agli occhi di Ollama.</p> </li> <li> <p><strong>Due email, stessa CB</strong>— Ollama non blocca le sottoscrizioni multiple dallo stesso metodo di pagamento. Solo l’email deve essere distinta.</p> </li> <li> <p><strong>Test gratuito prima di pagare</strong> — Un <code>ollama pull qwen3:0.6b</code> (modèle libre, 522 Mo) permet de valider toute la chaîne réseau sans débourser un centime. Vous validez le plomberie d’abord, vous activez le Pro ensuite.</p> </li> <li> <p><strong>/v1/models` con <code>data: null</code> rompe OpenCode</strong>— Se configuri un provider personalizzato con`"models": {}`, OpenCode tenta di scoprire i modelli tramite l’API. Se l’API risponde`data: null`, il provider non appare. Dichiari i modelli esplicitamente.</p> </li> <li> <p><strong>Due conti, è un multi-processing umano</strong>Un account Pro = una sessione OpenCode attiva. Due account = due sessioni parallele. Per chi gestisce contemporaneamente diversi progetti Gradle, è un game changer.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_per_andare_oltre">Per Andare Oltre</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/settings/keys">Impostazioni di Ollama — Gestione delle chiavi SSH</a></p> </li> <li> <p><a href="https://docs.ollama.com/">Documentazione ufficiale Ollama</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Immagine Docker Ollama su Docker Hub</a></p> </li> <li> <p><a href="https://opencode.ai/docs/providers/#ollama">OpenCode — Configuration Provider Ollama</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Articolo pubblicato il 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_perché_gradle_per_linfra">Perché Gradle per l’Infra ?</a></li> <li><a href="#_il_build_gradle_kts_completo">Il build.gradle.kts completo</a></li> <li><a href="#_anatomia_delle_attività_chiave">Anatomia delle attività chiave</a> <ul class="sectlevel2"> <li><a href="#_startollamab_il_lanciatore">startOllamaB` — Il Lanciatore</a></li> <li><a href="#_signinb_linterattivo">signInB` — L’Interattivo</a></li> <li><a href="#_pullmodelb_il_configurabile">pullModelB` — Il configurabile</a></li> <li><a href="#_statusollamaall_il_diagnostico">statusOllamaAll` — Il Diagnostico</a></li> <li><a href="#_cleanollamab_la_pulizia_che_preserva_lidentità">cleanOllamaB` — la pulizia che preserva l’identità</a></li> </ul> </li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_resetconservato_lidentità_ssh_sopravvive_alla_pulizia_al_prossimostartollamab_le_stesse_chiavi_verranno_riutilizzate_non_cè_bisogno_di_rifare_il_sign_in_né_di_re_registrare_la_device_key">Clear the output directory before baking jbake -b . output --reset<strong>conservato</strong>. L’identità SSH sopravvive alla pulizia. Al prossimo`startOllamaB`, le stesse chiavi verranno riutilizzate — non c’è bisogno di rifare il sign-in né di re-registrare la Device Key.</a> <ul class="sectlevel1"> <li><a href="#_workflow_completo_da_zero_a_due_sessioni">Workflow Completo — Da Zero a Due Sessioni</a></li> <li><a href="#_perché_non_farne_un_vero_plugin_gradle">Perché non farne un vero plugin Gradle?</a></li> <li><a href="#_lezioni_apprese">Lezioni apprese</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_risorse">Risorse</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura: 18 minutes</div> <p>Perché digitare i comandi docker a mano quando si può incapsulare tutto in task Gradle? Ecco come ho industrializzato la mia configurazione dual-Ollama Pro senza script shell esterni. Avvio, arresto, identità, sign-in, pull — tutto passa per`./gradlew`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nell’articolo precedente, ho mostrato come far coesistere due account Ollama Pro sulla stessa macchina isolando la seconda istanza in un contenitore Docker. Il montaggio funziona, ma la gestione quotidiana diventa rapidamente fastidiosa: ricordarsi il nome del contenitore, riavviare i comandi corretti`docker exec`, controlla quale porta è attiva…​</p> </div> <div class="paragraph"> <p>Conosci quel momento in cui hai 14 terminali aperti, che stai digitando`docker exec ollama-instance-b ollama list`per la quarta volta, e ti dici « deve esserci un modo più pulito »?</p> </div> <div class="paragraph"> <p>Questo mezzo è Gradle.</p> </div> <div class="paragraph"> <p>Non solo per costruire il codice. Gradle come un direttore d’orchestra dell’infrastruttura locale. Compiti che provisionano, verificano, testano e puliscono. Tutto versionato in un`build.gradle.kts`che vive accanto al`docker-compose.yml`.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-gradle-ollama.svg" alt="architecture gradle ollama" width="716" height="513"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_gradle_per_linfra">Perché Gradle per l’Infra ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La domanda è legittima. Gradle, è uno strumento di build. Normalmente, compila, testa, impacchetta. Non lancia container Docker.</p> </div> <div class="paragraph"> <p>Eccetto che Gradle è anche un motore di grafo di dipendenze — ed è lì che diventa interessante per il nostro caso.</p> </div> <div class="paragraph"> <p>Vogliamo:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Che il contenitore venga avviato prima di un sign-in</p> </li> <li> <p>Che l’identità sia verificata prima di un pull di modello</p> </li> <li> <p>Un test API fallisce silenziosamente se il contenitore è inattivo</p> </li> </ol> </div> <div class="paragraph"> <p>Dal puro grafo delle dipendenze. Gradle è su misura per questo. Il DSL Kotlin rende la scrittura delle attività fluida, e il`doLast`consente di eseguire comandi di sistema come se fossero codice applicativo.</p> </div> <div class="paragraph"> <p>E soprattutto: nessun bashrc da mantenere, nessun script che giace in`~/bin`, nessun Makefile accanto a docker-compose. Tutto è contenuto in un unico file, nello stesso posto del codice del progetto.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_build_gradle_kts_completo">Il build.gradle.kts completo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ecco il file che ho finito per scrivere. Fa tutto, dal provisioning del volume al curl di verifica, passando per il sign-in interattivo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.io.ByteArrayOutputStream plugins { base } // ------------------------------------------------------------------------- // Configuration // ------------------------------------------------------------------------- val instanceName = "ollama-instance-b" val instancePort = 11435 val instanceImage = "ollama/ollama:0.20.2" val dataDir = file("${System.getProperty("user.home")}/ollama-b-data") val nativePort = 11434 // Modèles à gérer — cloud Pro + un modèle local gratuit pour les tests val proModels = listOf("deepseek-v4-pro:cloud", "gemma4:31b-cloud") val freeModels = listOf("qwen3:0.6b") // ------------------------------------------------------------------------- // Tâche préparatoire — création du volume si absent // ------------------------------------------------------------------------- val prepareVolume by tasks.registering { group = "ollama" description = "Crée le répertoire de volume pour l'instance B si absent" doLast { if (!dataDir.exists()) { dataDir.mkdirs() println("Volume créé : ${dataDir.absolutePath}") } else { println("Volume existant : ${dataDir.absolutePath}") } } } // ------------------------------------------------------------------------- // Démarrage du conteneur Docker // ------------------------------------------------------------------------- val startOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Lance le conteneur Docker pour l'instance Ollama B" dependsOn(prepareVolume) commandLine( "docker", "run", "-d", "--name", instanceName, "-p", "$instancePort:11434", "-v", "${dataDir.absolutePath}:/root/.ollama", "-e", "OLLAMA_HOST=0.0.0.0", "--restart", "always", instanceImage ) isIgnoreExitValue = true doLast { val alreadyRunning = executionResult.get().exitValue != 0 if (alreadyRunning) { logger.lifecycle("Le conteneur '$instanceName' existe déjà — tentative de démarrage") } else { logger.lifecycle("Conteneur '$instanceName' lancé") } } } // ------------------------------------------------------------------------- // Arrêt du conteneur // ------------------------------------------------------------------------- val stopOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête le conteneur Docker de l'instance B" commandLine("docker", "stop", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' arrêté") } } // ------------------------------------------------------------------------- // Affichage de la clé publique (Device Key) // ------------------------------------------------------------------------- val checkIdentity by tasks.registering(Exec::class) { group = "ollama" description = "Affiche la clé publique SSH de l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "cat", "/root/.ollama/id_ed25519.pub") standardOutput = ByteArrayOutputStream() doLast { val pubKey = standardOutput.toString().trim() println("=".repeat(60)) println("Device Key (Instance B)") println("=".repeat(60)) println(pubKey) println("=".repeat(60)) println("→ Enregistre cette clé sur https://ollama.com/settings/keys") println("→ Puis exécute : ./gradlew signInB") println("=".repeat(60)) } } // ------------------------------------------------------------------------- // Sign-in interactif (Ouvrira le navigateur) // ------------------------------------------------------------------------- val signInB by tasks.registering(Exec::class) { group = "ollama" description = "Lance l'authentification interactive Ollama pour le compte B" dependsOn(startOllamaB) standardInput = System.`in` standardOutput = System.out errorOutput = System.err commandLine("docker", "exec", "-it", instanceName, "ollama", "signin") doFirst { logger.lifecycle("Authentification pour le Compte Pro B...") logger.lifecycle("Ouvre ton navigateur et connecte-toi avec l'email du compte B") } } // ------------------------------------------------------------------------- // Pull d'un modèle (paramétrable via propriété Gradle) // ------------------------------------------------------------------------- val pullModelB by tasks.registering(Exec::class) { group = "ollama" description = "Pull un modèle sur l'instance B. Usage : ./gradlew pullModelB -Pmodel=nom:tag" dependsOn(startOllamaB) val modelName = project.findProperty("model") as? String ?: "qwen3:0.6b" commandLine("docker", "exec", instanceName, "ollama", "pull", modelName) doFirst { logger.lifecycle("Pull du modèle '$modelName' sur l'instance B...") } doLast { logger.lifecycle("Modèle '$modelName' pullé avec succès") } } // ------------------------------------------------------------------------- // Pull de tous les modèles Pro (batch) // ------------------------------------------------------------------------- val pullAllProModels by tasks.registering { group = "ollama" description = "Pull tous les modèles cloud Pro sur l'instance B" dependsOn(startOllamaB) doLast { proModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles Pro pullés") } } // ------------------------------------------------------------------------- // Pull de tous les modèles gratuits (batch / première install) // ------------------------------------------------------------------------- val pullAllFreeModels by tasks.registering { group = "ollama" description = "Pull tous les modèles locaux gratuits sur l'instance B" dependsOn(startOllamaB) doLast { freeModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles gratuits pullés") } } // ------------------------------------------------------------------------- // Liste des modèles disponibles sur l'instance B // ------------------------------------------------------------------------- val listModelsB by tasks.registering(Exec::class) { group = "ollama" description = "Liste les modèles disponibles sur l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "ollama", "list") } // ------------------------------------------------------------------------- // Health check — test API sur les deux instances // ------------------------------------------------------------------------- val testOllamaB by tasks.registering { group = "ollama" description = "Teste la connectivité API de l'instance B avec un simple chat" dependsOn(startOllamaB) doLast { val model = project.findProperty("model") as? String ?: "qwen3:0.6b" logger.lifecycle("Test de l'instance B avec le modèle '$model'...") val payload = """ { "model": "$model", "messages": [{"role": "user", "content": "Réponds uniquement par OK"}], "max_tokens": 5 } """.trimIndent() val process = ProcessBuilder( "curl", "-s", "http://localhost:$instancePort/v1/chat/completions", "-H", "Content-Type: application/json", "-d", payload ).start() val response = process.inputStream.bufferedReader().readText() process.waitFor() if (response.contains("\"id\":\"chatcmpl") || response.contains("\"choices\"")) { println("✓ Instance B OK — port $instancePort répond") println(" Response: ${response.take(120)}...") } else { println("✗ Instance B INACTIVE — vérifie le conteneur avec './gradlew statusOllamaAll'") println(" Raw: $response") } } } // ------------------------------------------------------------------------- // Health check sur les deux instances simultanément // ------------------------------------------------------------------------- val statusOllamaAll by tasks.registering { group = "ollama" description = "Vérifie le statut des deux instances Ollama (native + Docker)" doLast { // Instance native runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$nativePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Native — port $nativePort OK (HTTP $code)" else "✗ Instance Native — port $nativePort (HTTP $code)") }.getOrElse { println("✗ Instance Native — injoignable sur le port $nativePort") } // Instance Docker runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$instancePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Docker B — port $instancePort OK (HTTP $code)" else "✗ Instance Docker B — port $instancePort (HTTP $code)") }.getOrElse { println("✗ Instance Docker B — injoignable sur le port $instancePort") } // Info conteneur runCatching { val process = ProcessBuilder("docker", "ps", "--filter", "name=$instanceName", "--format", "table {{.Names}}\\t{{.Status}}\\t{{.Ports}}").start() val status = process.inputStream.bufferedReader().readText() process.waitFor() println() println("Conteneur Docker :") println(status) } } } // ------------------------------------------------------------------------- // Nettoyage complet // ------------------------------------------------------------------------- val cleanOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête et supprime le conteneur Docker de l'instance B" dependsOn(stopOllamaB) commandLine("docker", "rm", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' supprimé") logger.lifecycle("Le volume ${dataDir.absolutePath} est conservé (identité persistante)") } } // ------------------------------------------------------------------------- // Affichage des instructions // ------------------------------------------------------------------------- val helpOllama by tasks.registering { group = "ollama" description = "Affiche l'aide des tâches Ollama disponibles" doLast { println(""" ╔══════════════════════════════════════════════════════════════╗ ║ Tâches Gradle — Pilotage Dual Ollama Pro ║ ╠══════════════════════════════════════════════════════════════╣ ║ ./gradlew startOllamaB Démarrer l'instance Docker B ║ ║ ./gradlew stopOllamaB Arrêter l'instance Docker B ║ ║ ./gradlew checkIdentity Afficher la clé SSH publique ║ ║ ./gradlew signInB Sign-in interactif compte B ║ ║ ./gradlew pullModelB Pull un modèle (-Pmodel=...) ║ ║ ./gradlew pullAllProModels Pull tous les modèles Pro ║ ║ ./gradlew pullAllFreeModels Pull tous les modèles gratuits ║ ║ ./gradlew listModelsB Lister les modèles instance B ║ ║ ./gradlew testOllamaB Test API avec un chat simple ║ ║ ./gradlew statusOllamaAll Santé des 2 instances ║ ║ ./gradlew cleanOllamaB Supprimer le conteneur ║ ║ ./gradlew helpOllama Cette aide ║ ╚══════════════════════════════════════════════════════════════╝ """.trimIndent()) } }</code></pre> </div> </div> <div class="paragraph"> <p>Ecco. Dodici compiti, un unico punto di ingresso e zero attrito.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomia_delle_attività_chiave">Anatomia delle attività chiave</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startollamab_il_lanciatore">startOllamaB` — Il Lanciatore</h3> <div class="paragraph"> <p>Niente di difficile: un`docker run -d`con i parametri giusti. Il trucco è nel`isIgnoreExitValue = true`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>Se il contenitore esiste già, il comando`docker run`non riesce (exit code ≠ 0). Senza questa proprietà, Gradle interromperebbe l’intero build in errore. Qui, l’errore è silenzioso — e il`doLast`rileva se era un "già esistente" o un vero errore.</p> </div> <div class="paragraph"> <p>Le `doLast`è fondamentale : si esegue <strong>dopo</strong> l’esecuzione del comando, ciò permette di ispezionare`executionResult.get().exitValue`e di registrare un messaggio appropriato.</p> </div> </div> <div class="sect2"> <h3 id="_signinb_linterattivo">signInB` — L’Interattivo</h3> <div class="paragraph"> <p>È l’unica task che richiede interazione umana. Gradle trasmette`System.in`al processo affinché il prompt`ollama signin`possa essere visualizzato normalmente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">standardInput = System.`in` standardOutput = System.out errorOutput = System.err</code></pre> </div> </div> <div class="paragraph"> <p>Senza ciò, l’accesso si bloccherebbe perché stdin sarebbe chiuso e non vedresti mai il prompt.</p> </div> </div> <div class="sect2"> <h3 id="_pullmodelb_il_configurabile">pullModelB` — Il configurabile</h3> <div class="paragraph"> <p>Un’attività generica che accetta un parametro via`-P`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew pullModelB -Pmodel=deepseek-v4-pro:cloud ./gradlew pullModelB # fallback : qwen3:0.6b</code></pre> </div> </div> <div class="paragraph"> <p>Il fallback è importante :`project.findProperty("model") as? String ?: "qwen3:0.6b"`garantisce che l’operazione non scoppi se si dimentica il parametro.</p> </div> </div> <div class="sect2"> <h3 id="_statusollamaall_il_diagnostico">statusOllamaAll` — Il Diagnostico</h3> <div class="paragraph"> <p>Due`curl`in salute sui porti`11434` et <code>11435</code>, con un fallback in`runCatching`per non bloccarsi se una delle istanze è down. L’output è strutturato :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">✓ Instance Native — port 11434 OK (HTTP 200) ✓ Instance Docker B — port 11435 OK (HTTP 200) Conteneur Docker : NAMES STATUS PORTS ollama-instance-b Up 3 hours 0.0.0.0:11435->11434/tcp</code></pre> </div> </div> <div class="paragraph"> <p>Un colpo d’occhio, e sai esattamente cosa funziona e cosa non va.</p> </div> </div> <div class="sect2"> <h3 id="_cleanollamab_la_pulizia_che_preserva_lidentità">cleanOllamaB` — la pulizia che preserva l’identità</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">commandLine("docker", "rm", instanceName) isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>Il contenitore è eliminato, ma il volume`~/ollama-b-data`<mark>#</mark> JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_resetconservato_lidentità_ssh_sopravvive_alla_pulizia_al_prossimostartollamab_le_stesse_chiavi_verranno_riutilizzate_non_cè_bisogno_di_rifare_il_sign_in_né_di_re_registrare_la_device_key" class="sect0">Clear the output directory before baking jbake -b . output --reset<strong>conservato</strong>. L’identità SSH sopravvive alla pulizia. Al prossimo`startOllamaB`, le stesse chiavi verranno riutilizzate — non c’è bisogno di rifare il sign-in né di re-registrare la Device Key.</h1> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p><code>cleanOllamaB`non toccare il volume. Se vuoi cancellare l’identità B (e ricominciare da zero), è necessario eliminare</code>~/ollama-b-data`manualmente. È volontario — un`clean`non dovrebbe distruggere le credenziali.</p> </div> </td> </tr> </table> </div> <div class="sect1"> <h2 id="_workflow_completo_da_zero_a_due_sessioni">Workflow Completo — Da Zero a Due Sessioni</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ecco la sequenza ideale per qualcuno che arriva sul progetto e vuole impostare tutto senza aprire la documentazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text"># 1. Premier contact — que faire ? $ ./gradlew helpOllama # 2. On démarre l'instance B $ ./gradlew startOllamaB # 3. On récupère la Device Key et on l'enregistre sur ollama.com $ ./gradlew checkIdentity # → copier-coller de la clé sur https://ollama.com/settings/keys # 4. Authentification interactive $ ./gradlew signInB # 5. Pull d'un petit modèle gratuit pour tester la plomberie $ ./gradlew pullModelB # 6. Test API $ ./gradlew testOllamaB # 7. Si tout est vert, pull des modèles Pro $ ./gradlew pullAllProModels # 8. Vérification finale des deux instances $ ./gradlew statusOllamaAll</code></pre> </div> </div> <div class="paragraph"> <p>Meno di due minuti, tutto è provisionato. Nessun README da leggere, nessuna variabile d’ambiente da impostare. Il compito`helpOllama`fa da documentazione integrata.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml ... ... ( skipping 128 lines ) ... BorderColor black } skinparam StereotypeI { BackgroundColor white BorderColor black } skinparam StereotypeN { BackgroundColor white BorderColor black } skinparam UseCaseStereoType { FontColor black FontName Verdana } skinparam DefaultFontSize 11 actor Développeur as Dev participant "Gradle\n(build.gradle.kts)" as Gradle participant "Docker\nDaemon" as Docker participant "Ollama ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml !theme plain skinparam DefaultFontSize 11 actor Développeur as Dev participant "Gradle\n(build.gradle.kts)" as Gradle participant "Docker\nDaemon" as Docker participant "Ollama Istanza B" as OllamaB participant "Ollama\nCloud" as Cloud == Provisionnement == Dev -> Gradle : helpOllama Gradle --> Dev : Aide et instructions Dev -> Gradle : startOllamaB Gradle -> Docker : docker run -d ollama/ollama:0.20.2 Docker -> OllamaB : Génération clés SSH (id_ed25519) Docker --> Gradle : conteneur lancé Gradle --> Dev : OK Dev -> Gradle : checkIdentity Gradle -> Docker : cat id_ed25519.pub Gradle --> Dev : Clé publique SSH Dev -> Cloud : Enregistrement clé SSH\n(sur ollama.com/settings/keys) == Authentification == Dev -> Gradle : signInB Gradle -> Docker : ollama signin (interactif) Dev <-> Cloud : Login navigateur (compte B) Docker -> Cloud : Échange token ⇔ Device Key Gradle --> Dev : Authentifié == Vérification == Dev -> Gradle : pullModelB Gradle -> Docker : ollama pull qwen3:0.6b Gradle --> Dev : Modèle pullé Dev -> Gradle : testOllamaB Gradle -> Docker : curl /v1/chat/completions Gradle --> Dev : ✓ Instance B OK == Production == Dev -> Gradle : pullAllProModels Gradle -> Docker : ollama pull deepseek-v4-pro:cloud Gradle -> Docker : ollama pull gemma4:31b-cloud Gradle --> Dev : Modèles Pro pullés Dev -> Gradle : statusOllamaAll Gradle --> Dev : ✓ Native ✓ Docker B @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_non_farne_un_vero_plugin_gradle">Perché non farne un vero plugin Gradle?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Domanda legittima. Estrarre questo`build.gradle.kts`in un plugin Gradle autonomo avrebbe dei vantaggi: riutilizzo tra progetti, configurazione dichiarativa, estensione DSL.</p> </div> <div class="paragraph"> <p>Ma per ora, non ha senso. Questo build non ha una logica di business complessa — è un wrapper attorno a comandi Docker e curl. Lo strato aggiuntivo di un plugin Gradle completo (con estensione, test unitari, pubblicazione) sarebbe sproporzionato per 12 attività utili.</p> </div> <div class="paragraph"> <p>Le `build.gradle.kts`inline vive nel progetto che ne ha bisogno. È banale da copiare altrove. Se un giorno avrò tre progetti che ne dipendono, lo trasformerò in un plugin. Per ora, KISS.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Il giorno in cui hai tre`build.gradle.kts`JBake CLI Commands <code>` # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset </code>` identici in tre progetti, è il segnale che è necessario estrarre un plugin. Prima di allora, la duplicazione è meno costosa dell’astrazione. Saggezza di dev.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_lezioni_apprese">Lezioni apprese</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gradle non è solo uno strumento di build</strong>— Il motore del grafo delle dipendenze ne fa un orchestratore di infrastrutture temibile.<code>doLast</code>, <code>isIgnoreExitValue</code>, <code>dependsOn</code>: questi tre primitivi sono sufficienti per pilotare un container Docker con la stessa affidabilità di una pipeline CI.</p> </li> <li> <p><strong>isIgnoreExitValue` è tuo amico</strong>— In un mondo ideale,<code>docker run`su un contenitore già esistente restituirebbe un avviso invece di un codice di uscita di errore. Nel mondo reale, tu metti`isIgnoreExitValue = true`e tu gestisci la diagnosi in`doLast</code>.</p> </li> <li> <p><strong>Le attività configurabili uccidono l’ambiguità</strong> — Un <code>pullModelB`generico con</code>-Pmodel=…​`sostituisce N attività specializzate. Un solo compito, una sola documentazione, un solo comportamento.</p> </li> <li> <p><strong>runCatching` per i controlli di stato</strong>Quando testi N endpoint, il crash del primo non deve impedire di testare gli altri.<code>runCatching</code>+`getOrElse`per endpoint, e la diagnosi rimane completa anche in caso di guasto parziale.</p> </li> <li> <p><strong>Il compito <code>helpOllama</code> come documentazione eseguibile</strong> — Un `println()`ben formattato sostituisce un README di tre paragrafi. È auto-documentato, sempre aggiornato e accessibile senza uscire dal terminale.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Siamo passati da comandi docker da digitare manualmente a un workflow Gradle completo, versionato, riutilizzabile. Dodici attività coprono l’intero ciclo di vita: provisioning, identità, sign-in, pull, test, diagnostico, pulizia.</p> </div> <div class="paragraph"> <p>Il combo docker-compose + build.gradle.kts + opencode.json forma una trinità pulita: Docker per l’isolamento, Gradle per l’orchestrazione, OpenCode per il consumo. Ogni livello ha la propria responsabilità, e nessuno sconfinisce sull’altro.</p> </div> <div class="paragraph"> <p>Prossimo passo? Automatizzare il ciclo di vita nella CI affinché le istanze Ollama siano disponibili negli ambienti di sviluppo effimeri. Ma questo è un altro articolo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_risorse">Risorse</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/tutorial_using_tasks.html">Manuale Utente Gradle — Attività</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_tasks.html">Manuale Utente Gradle — Attività Personalizzate</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Immagine Docker Ollama su Docker Hub</a></p> </li> <li> <p><a href="https://kotlinlang.org/docs/gradle.html">Gradle DSL Kotlin — Documentation</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Articolo pubblicato il 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0080_kitty_term_post.html Thu, 7 May 2026 00:00:00 +0000 blog/2025/0080_kitty_term_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_perché_scegliere_kitty_e_zsh">Perché scegliere Kitty e Zsh?</a></li> <li><a href="#_prerequisiti_di_sistema">Prerequisiti di sistema</a></li> <li><a href="#_download_e_installazione_di_kitty">Download e installazione di Kitty</a> <ul class="sectlevel2"> <li><a href="#_scarica_lo_script_di_installazione">Scarica lo script di installazione</a></li> <li><a href="#_creazione_dei_link_simbolici">Creazione dei link simbolici</a></li> </ul> </li> <li><a href="#_integrazione_di_kitty_in_xubuntu">Integrazione di Kitty in Xubuntu</a> <ul class="sectlevel2"> <li><a href="#_copiare_il_file_desktop">Copiare il file desktop</a></li> <li><a href="#_modifica_il_file_desktop">Modifica il file desktop</a></li> <li><a href="#_associare_kitty_come_terminale_predefinito_facoltativo">Associare Kitty come terminale predefinito (facoltativo)</a></li> </ul> </li> <li><a href="#_installazione_di_zsh">Installazione di Zsh</a></li> <li><a href="#_imposta_zsh_come_shell_predefinito">Imposta Zsh come shell predefinito</a> <ul class="sectlevel2"> <li><a href="#_metodo_globale_per_tutti_i_terminali">Metodo globale (per tutti i terminali)</a></li> <li><a href="#_metodo_specifico_per_kitty">Metodo specifico per Kitty</a></li> </ul> </li> <li><a href="#_configurazione_di_zsh_opzionale">Configurazione di Zsh (opzionale)</a> <ul class="sectlevel2"> <li><a href="#_creare_un_file_zshrc">Creare un file .zshrc</a></li> <li><a href="#_esempio_di_configurazione_minima">Esempio di configurazione minima</a></li> </ul> </li> <li><a href="#_riassunto_del_flusso_di_lavoro_completo">Riassunto del flusso di lavoro completo</a></li> <li><a href="#_verifica_finale">Verifica finale</a> <ul class="sectlevel2"> <li><a href="#_aprire_il_file_di_configurazione">Aprire il file di configurazione</a></li> <li><a href="#_️_aggiungi_o_modifica_font_size">🖋️ Aggiungi o modifica `font_size</a></li> <li><a href="#_salva_e_riavvia_kitty">💾 Salva e riavvia Kitty</a></li> <li><a href="#_regolazione_dinamica_zoom_temporaneo">�✅ Regolazione dinamica (Zoom temporaneo)</a></li> </ul> </li> <li><a href="#_installazione_e_configurazione_di_oh_my_zsh">Installazione e configurazione di Oh My Zsh</a> <ul class="sectlevel2"> <li><a href="#_installazione_di_oh_my_zsh">Installazione di Oh My Zsh</a></li> <li><a href="#_cambiare_il_tema">Cambiare il tema</a></li> <li><a href="#_verifica">Verifica</a></li> <li><a href="#_diagramma_dei_casi_duso">Diagramma dei casi d’uso</a></li> </ul> </li> <li><a href="#_attivare_la_traslucenza_in_kitty">Attivare la traslucenza in Kitty</a> <ul class="sectlevel2"> <li><a href="#_prerequisito_per_la_trasparenza">Prerequisito per la trasparenza</a></li> <li><a href="#_configurazione_della_trasparenza_in_kitty_conf">Configurazione della trasparenza in kitty.conf</a></li> <li><a href="#_riavvia_kitty">Riavvia Kitty</a></li> <li><a href="#_integratori_possibili">Integratori possibili</a></li> <li><a href="#_diagramma_di_sequenza_inizializzazione_di_kitty_con_trasparenza">Diagramma di sequenza - Inizializzazione di Kitty con trasparenza</a></li> <li><a href="#_limitazioni_note">Limitazioni note</a></li> </ul> </li> <li><a href="#_disattiva_il_segnale_acustico_segnale_acustico">Disattiva il segnale acustico (segnale acustico)</a></li> <li><a href="#_aggiornamento_di_kitty">Aggiornamento di Kitty</a></li> <li><a href="#_riferimenti">Riferimenti</a></li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Questa guida spiega passo dopo passo come installare il terminale <strong>kitty</strong> su Xubuntu, configurarlo correttamente e sostituire bash con <strong>zsh</strong> come shell predefinita. Il progetto kitty è disponibile qui : <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a>.</p> </div> <div class="paragraph"> <p><em><em>_ Kitty è un terminale moderno, veloce e configurabile, particolarmente adatto agli sviluppatori esigenti. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_perché_scegliere_kitty_e_zsh">Perché scegliere Kitty e Zsh?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty si distingue per:</p> </div> <div class="ulist"> <ul> <li> <p>Performance superiori grazie all’accelerazione GPU,</p> </li> <li> <p>Una configurazione interamente basata su un unico file di testo,</p> </li> <li> <p>Un eccellente supporto dei caratteri e delle legature</p> </li> </ul> </div> <div class="paragraph"> <p>Zsh, invece, è un potente shell interattivo che offre:</p> </div> <div class="ulist"> <ul> <li> <p>Un completamento intelligente,</p> </li> <li> <p>Un prompt personalizzabile,</p> </li> <li> <p>Una grande compatibilità con bash.</p> </li> </ul> </div> <div class="paragraph"> <p>Associando Kitty e Zsh, si beneficia di un ambiente produttivo ed estetico.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/kitty-zsh-overview.png" alt="kitty zsh overview" width="729" height="305"> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Questa guida è volontariamente limitata all’installazione tramite script e a Xubuntu.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_prerequisiti_di_sistema">Prerequisiti di sistema</h2> <div class="sectionbody"> <div class="paragraph"> <p>Prima di iniziare, assicurati di avere:</p> </div> <div class="ulist"> <ul> <li> <p>Xubuntu installato,</p> </li> <li> <p>un accesso a internet,</p> </li> <li> <p>un shell bash funzionante per avviare lo script.</p> </li> </ul> </div> <div class="paragraph"> <p>Controlla il tuo ambiente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">uname -a lsb_release -a</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_download_e_installazione_di_kitty">Download e installazione di Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty raccomanda di installarlo tramite uno script ufficiale che posiziona i file in`~/.local/kitty.app`.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>Questo metodo è indipendente dai gestori di pacchetti (pas de`apt`).</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_scarica_lo_script_di_installazione">Scarica lo script di installazione</h3> <div class="paragraph"> <p>Esegui il seguente comando</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>Questo comando esegue :</p> </div> <div class="ulist"> <ul> <li> <p>download dei binari,</p> </li> <li> <p>estrazione in`~/.local/kitty.app`,</p> </li> <li> <p>creazione dei collegamenti simbolici.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/download-install.svg" alt="download install" width="303" height="336"> </div> </div> </div> <div class="sect2"> <h3 id="_creazione_dei_link_simbolici">Creazione dei link simbolici</h3> <div class="paragraph"> <p>Al fine di poter invocare`kitty`dal terminal, crea un collegamento simbolico:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/kitty</code></pre> </div> </div> <div class="paragraph"> <p>Aggiungete`~/.local/bin`aggiungilo al tuo PATH se non l’hai ancora fatto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>Puoi verificare l’installazione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty --version</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integrazione_di_kitty_in_xubuntu">Integrazione di Kitty in Xubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Affinchè Kitty appaia nel menu delle applicazioni:</p> </div> <div class="sect2"> <h3 id="_copiare_il_file_desktop">Copiare il file desktop</h3> <div class="paragraph"> <p>Copia il file`.desktop`fornito :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_modifica_il_file_desktop">Modifica il file desktop</h3> <div class="paragraph"> <p>Modifica il file :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.local/share/applications/kitty.desktop</code></pre> </div> </div> <div class="paragraph"> <p>Verifica o modifica le seguenti righe:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Desktop Entry] Version=1.0 Type=Application Name=Kitty Terminal Comment=Fast GPU-based terminal emulator Exec=/home/$USER/.local/kitty.app/bin/kitty Icon=kitty Categories=System;TerminalEmulator;</code></pre> </div> </div> <div class="paragraph"> <p>Sostituisca`YOURUSER`con il tuo nome utente.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/desktop-integration.png" alt="desktop integration" width="449" height="335"> </div> </div> </div> <div class="sect2"> <h3 id="_associare_kitty_come_terminale_predefinito_facoltativo">Associare Kitty come terminale predefinito (facoltativo)</h3> <div class="paragraph"> <p>Perché Kitty sia il terminale predefinito :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator ~/.local/kitty.app/bin/kitty 50 sudo update-alternatives --config x-terminal-emulator</code></pre> </div> </div> <div class="paragraph"> <p>Selezionate`kitty`nel menu proposto.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_installazione_di_zsh">Installazione di Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se Zsh non è ancora installato, esegui :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install zsh</code></pre> </div> </div> <div class="paragraph"> <p>Verifica l’installazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">zsh --version</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_imposta_zsh_come_shell_predefinito">Imposta Zsh come shell predefinito</h2> <div class="sectionbody"> <div class="paragraph"> <p>Puoi cambiare il tuo shell globalmente o solo in Kitty.</p> </div> <div class="sect2"> <h3 id="_metodo_globale_per_tutti_i_terminali">Metodo globale (per tutti i terminali)</h3> <div class="paragraph"> <p>Identifica il percorso assoluto :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">which zsh</code></pre> </div> </div> <div class="paragraph"> <p>In generale`/usr/bin/zsh`.</p> </div> <div class="paragraph"> <p>Modifica la shell predefinita:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">chsh -s /usr/bin/zsh</code></pre> </div> </div> <div class="paragraph"> <p>Disconnettiti e riconnettiti.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/zsh-default-shell.svg" alt="zsh default shell" width="546" height="341"> </div> </div> </div> <div class="sect2"> <h3 id="_metodo_specifico_per_kitty">Metodo specifico per Kitty</h3> <div class="paragraph"> <p>Se preferisci cambiare solo la shell in Kitty, modifica il file di configurazione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>Aggiungi questa riga :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">shell zsh</code></pre> </div> </div> <div class="paragraph"> <p>Salva e riavvia Kitty.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configurazione_di_zsh_opzionale">Configurazione di Zsh (opzionale)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per personalizzare il tuo Zsh :</p> </div> <div class="sect2"> <h3 id="_creare_un_file_zshrc">Creare un file .zshrc</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">touch ~/.zshrc nano ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_esempio_di_configurazione_minima">Esempio di configurazione minima</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export ZSH_THEME="robbyrussell" export PATH="$HOME/.local/bin:$PATH" alias ll="ls -la"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_riassunto_del_flusso_di_lavoro_completo">Riassunto del flusso di lavoro completo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo schema sottostante riepiloga l’intero processo :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/full-workflow.png" alt="full workflow" width="427" height="643"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verifica_finale">Verifica finale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avvia Kitty :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> <div class="paragraph"> <p>Lei dovrebbe vedere che`zsh`è attivo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $SHELL</code></pre> </div> </div> <div class="paragraph"> <p>Risultato atteso:</p> </div> <div class="paragraph"> <p>/usr/bin/zsh</p> </div> <div class="paragraph"> <p>Per modificare la dimensione del carattere in<strong>gattina</strong>, bisogna regolare il parametro`font_size`nel file di configurazione. Ecco la procedura dettagliata:</p> </div> <div class="sect2"> <h3 id="_aprire_il_file_di_configurazione">Aprire il file di configurazione</h3> <div class="paragraph"> <p>Il file principale di configurazione si trova solitamente in :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>Se questo file non esiste ancora, puoi crearlo. Esempio:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_️_aggiungi_o_modifica_font_size">🖋️ Aggiungi o modifica `font_size</h3> <div class="paragraph"> <p>Aggiungi la seguente direttiva, o modificala se esiste già:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">font_size 14.0</code></pre> </div> </div> <div class="paragraph"> <p>qui`14.0`corrisponde alla dimensione desiderata. Puoi inserire qualsiasi valore decimale, ad esempio`12.0`, <code>15.5</code>, ecc.</p> </div> </div> <div class="sect2"> <h3 id="_salva_e_riavvia_kitty">💾 Salva e riavvia Kitty</h3> <div class="ulist"> <ul> <li> <p>Salva (<code>Ctrl + O</code>, poi`Entrée`) e lascia (<code>Ctrl + X</code>) se utilizzate`nano`.</p> </li> <li> <p>Chiudi tutte le finestre di Kitty, poi riavvia il terminale affinché il cambiamento abbia effetto.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_regolazione_dinamica_zoom_temporaneo">�✅ Regolazione dinamica (Zoom temporaneo)</h3> <div class="paragraph"> <p>Se vuoi eseguire temporaneamente uno zoom avanti/indietro senza modificare la configurazione, utilizza le scorciatoie da tastiera predefinite:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Aumentare la dimensione del carattere</strong> :</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + =</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Ridurre la dimensione del carattere</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + -</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>Reimposta la dimensione</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + Backspace</code></p> </div> <div class="paragraph"> <p>Queste impostazioni non persistono dopo la chiusura del terminale.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_installazione_e_configurazione_di_oh_my_zsh">Installazione e configurazione di Oh My Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una volta installato e configurato Zsh come shell predefinito, puoi arricchire il tuo ambiente con <strong>Oh My Zsh</strong>, un framework di gestione della configurazione di Zsh, offrendo:</p> </div> <div class="ulist"> <ul> <li> <p>una collezione di temi per il prompt,</p> </li> <li> <p>numerosi plugin,</p> </li> <li> <p>un’organizzazione chiara della configurazione.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_installazione_di_oh_my_zsh">Installazione di Oh My Zsh</h3> <div class="paragraph"> <p>Assicurati che Zsh sia attivo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh --version</code></pre> </div> </div> <div class="paragraph"> <p>Se necessario, avvia:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh</code></pre> </div> </div> <div class="paragraph"> <p>Poi scarica ed esegui lo script di installazione ufficiale:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"</code></pre> </div> </div> <div class="paragraph"> <p>Questo script :</p> </div> <div class="ulist"> <ul> <li> <p>crea la cartella`~/.oh-my-zsh`,</p> </li> <li> <p>Salva eventualmente il tuo file`~/.zshrc`,</p> </li> <li> <p>attiva automaticamente il nuovo prompt.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_cambiare_il_tema">Cambiare il tema</h3> <div class="paragraph"> <p>Apri il tuo file di configurazione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>Modifica la variabile`ZSH_THEME`per scegliere un altro tema (ad esempio`agnoster`) :</p> </div> <div class="paragraph"> <p>ZSH_THEME="agnoster</p> </div> <div class="paragraph"> <p>Salvare poi ricaricare la configurazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">source ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_verifica">Verifica</h3> <div class="paragraph"> <p>Avvia Kitty e verifica che il prompt sia cambiato correttamente. Puoi confermare che Oh My Zsh è attivo eseguendo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $ZSH</code></pre> </div> </div> <div class="paragraph"> <p>Il risultato dovrebbe essere simile a:</p> </div> <div class="paragraph"> <p>/home/tuo_utente/.oh-my-zsh</p> </div> </div> <div class="sect2"> <h3 id="_diagramma_dei_casi_duso">Diagramma dei casi d’uso</h3> <div class="imageblock"> <div class="content"> <img src="./images/ohmyzsh-installation.png" alt="ohmyzsh installation" width="531" height="480"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_attivare_la_traslucenza_in_kitty">Attivare la traslucenza in Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una delle funzionalità più apprezzate di Kitty è la possibilità di aggiungere <strong>trasparenza</strong> allo sfondo del terminale. Ciò permette di vedere leggermente l’ambiente sottostante (finestra, desktop, ecc.), il che è particolarmente utile nel multitasking.</p> </div> <div class="sect2"> <h3 id="_prerequisito_per_la_trasparenza">Prerequisito per la trasparenza</h3> <div class="paragraph"> <p>La trasparenza in Kitty si basa sul<strong>compositore di finestre</strong>utilizzato dall’ambiente grafico. In Xubuntu (basato su XFCE), assicurati che la<strong>composizione è attivata</strong>.</p> </div> <div class="ulist"> <div class="title">Da verificare :</div> <ul> <li> <p>clic destro sul desktop > Impostazioni ><strong>Impostazioni del gestore delle finestre</strong>,</p> </li> <li> <p>scheda<strong>Compositore</strong>: la casella <strong>"Attivare la composizione"</strong> deve essere selezionata.</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/transparency-usecase.png" alt="transparency usecase" width="593" height="224"> </div> </div> </div> <div class="sect2"> <h3 id="_configurazione_della_trasparenza_in_kitty_conf">Configurazione della trasparenza in kitty.conf</h3> <div class="paragraph"> <p>Apra il suo file di configurazione`~/.config/kitty/kitty.conf` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>Aggiungete o modificate le seguenti righe:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background_opacity 0.85</code></pre> </div> </div> <div class="paragraph"> <p>Questo parametro accetta valori compresi tra :</p> </div> <div class="ulist"> <ul> <li> <p><code>1.0</code>→ opaco (nessuna trasparenza),</p> </li> <li> <p><code>0.0</code>→ completamente trasparente (inutilizzabile)</p> </li> <li> <p>valori intermedi come`0.90`, <code>0.75</code>, ecc.</p> </li> </ul> </div> <div class="paragraph"> <p>Un buon compromesso visivo è generalmente tra`0.85` et <code>0.95</code>.</p> </div> </div> <div class="sect2"> <h3 id="_riavvia_kitty">Riavvia Kitty</h3> <div class="paragraph"> <p>Chiudi tutte le istanze di Kitty, quindi riapri una nuova finestra affinché le modifiche abbiano effetto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_integratori_possibili">Integratori possibili</h3> <div class="paragraph"> <p>Se utilizzi uno sfondo del terminale personalizzato, puoi anche impostare un colore di sfondo con trasparenza (in RGBA):</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background #1e1e2eff</code></pre> </div> </div> <div class="paragraph"> <p>L’ultima componente (<code>ff</code>) indica l’opacità (di`00` à <code>ff</code>).</p> </div> </div> <div class="sect2"> <h3 id="_diagramma_di_sequenza_inizializzazione_di_kitty_con_trasparenza">Diagramma di sequenza - Inizializzazione di Kitty con trasparenza</h3> <div class="imageblock"> <div class="content"> <img src="./images/transparency-sequence.png" alt="transparency sequence" width="784" height="422"> </div> </div> </div> <div class="sect2"> <h3 id="_limitazioni_note">Limitazioni note</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>La traslucenza non funziona se : - il compositore XFCE è disattivato, - un gestore di finestre incompatibile è utilizzato, - utilizzi Kitty in modalità <strong>tmux</strong> in background senza supporto per la trasparenza.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_disattiva_il_segnale_acustico_segnale_acustico">Disattiva il segnale acustico (segnale acustico)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per impostazione predefinita, Kitty emette un suono di <strong>bip</strong> quando viene inserito un comando errato o quando un evento del terminal lo attiva. Questo rumore può diventare rapidamente fastidioso, soprattutto in un ambiente di sviluppo intensivo.</p> </div> <div class="paragraph"> <p>Per disattivare questo comportamento, aggiunga la seguente direttiva al file`~/.config/kitty/kitty.conf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">audible_bell no</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Puoi anche attivare un <strong>feedback visivo</strong> al posto del segnale acustico:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">visual_bell yes</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_aggiornamento_di_kitty">Aggiornamento di Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poiché Kitty è installato tramite uno script e non un gestore di pacchetti, l’aggiornamento si effettua rilanciando lo script di installazione ufficiale. Questo permette di scaricare l’ultima versione e di aggiornare la tua installazione esistente in`~/.local/kitty.app`.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Il suffisso`.app`nel cammino`~/.local/kitty.app`è la convenzione di installazione di Kitty su Linux tramite il suo script ufficiale, e non indica in alcun modo una compatibilità esclusiva con macOS.</p> </div> </td> </tr> </table> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>Prima di eseguire il comando di aggiornamento, assicurati di essere nella tua directory personale (<code>~</code>).</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Esegua il comando seguente dalla sua directory personale:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>Questo script si occuperà di:</p> </div> <div class="ulist"> <ul> <li> <p>Scarica i binari della nuova versione.</p> </li> <li> <p>Estrarre i file in`~/.local/kitty.app`.</p> </li> <li> <p>Aggiornare i link simbolici se necessario.</p> </li> </ul> </div> <div class="paragraph"> <p>Dopo l’aggiornamento, si consiglia di chiudere tutte le istanze di Kitty e di riavviarle affinché la nuova versione venga correttamente riconosciuta.</p> </div> </div> </div> <div class="sect1"> <h2 id="_riferimenti">Riferimenti</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se desideri approfondire la personalizzazione, consulta la documentazione ufficiale:</p> </div> <div class="ulist"> <ul> <li> <p>Kitty: <a href="https://sw.kovidgoyal.net/kitty/" class="bare">https://sw.kovidgoyal.net/kitty/</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell</a></p> </li> <li> <p>Zsh: <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p>Github: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a></p> </li> <li> <p>Zsh: <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p><a href="https://ohmyz.sh/" class="bare">https://ohmyz.sh/</a></p> </li> <li> <p><a href="https://github.com/ohmyzsh/ohmyzsh/wiki" class="bare">https://github.com/ohmyzsh/ohmyzsh/wiki</a></p> </li> <li> <p><a href="https://docs.xfce.org/xfce/xfwm4/compositor" class="bare">https://docs.xfce.org/xfce/xfwm4/compositor</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ora hai:</p> </div> <div class="ulist"> <ul> <li> <p>di un terminale moderno e performante (Kitty)</p> </li> <li> <p>di un shell potente e personalizzabile (Zsh)</p> </li> <li> <p>di una configurazione pulita e indipendente dai pacchetti di sistema</p> </li> <li> <p>di un terminale estetico e funzionale equipaggiato di Oh My Zsh</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html Wed, 6 May 2026 00:00:00 +0000 blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_contesto_un_mercato_che_ha_subito_una_svolta">Il Contesto : Un Mercato Che Ha Subito Una Svolta</a></li> <li><a href="#_il_pannello_delle_opzioni">Il Pannello delle Opzioni</a> <ul class="sectlevel2"> <li><a href="#_cosa_ho_escluso_e_perché">Cosa ho escluso (e perché)</a></li> </ul> </li> <li><a href="#_inferenza_semplice_la_morte_dellhardware_locale">Inferenza semplice: La morte dell’hardware locale</a> <ul class="sectlevel2"> <li><a href="#_il_calcolo">Il Calcolo</a></li> <li><a href="#_anche_con_un_utilizzo_intensivo">Anche con un utilizzo intensivo</a></li> </ul> </li> <li><a href="#_fine_tuning_il_cloud_è_imbattibile">Fine-Tuning : Il Cloud è imbattibile</a> <ul class="sectlevel2"> <li><a href="#_il_costo_reale_di_un_fine_tune">Il Costo Reale di un Fine-Tune</a></li> <li><a href="#_gli_attori_specializzati">Gli Attori Specializzati</a></li> </ul> </li> <li><a href="#_lunica_vera_ragione_la_sovranità_dei_dati">L’unica vera ragione: la sovranità dei dati</a> <ul class="sectlevel2"> <li><a href="#_il_vero_calcolo_della_confidenzialità">Il Vero Calcolo della Confidenzialità</a></li> </ul> </li> <li><a href="#_sintesi_la_matrice_di_decisione">Sintesi : La Matrice di Decisione</a></li> <li><a href="#_il_caso_particolare_labbonamento_pro_di_fronte_ai_modelli_cinesi">Il Caso Particolare: L’Abbonamento Pro di Fronte ai Modelli Cinesi</a> <ul class="sectlevel2"> <li><a href="#_perché_i_modelli_cinesi_cambiano_tutto">Perché i Modelli Cinesi Cambiano Tutto</a></li> <li><a href="#_che_cosa_significa_per_lhardware">Che Cosa Significa per l’Hardware</a></li> </ul> </li> <li><a href="#_e_huawei">E Huawei?</a></li> <li><a href="#_conclusione_il_lusso_della_vicinanza">Conclusione: Il lusso della vicinanza</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 14 minutes</div> <p>NVIDIA vende il DGX Spark come un « supercomputer IA da scrivania » a $4 699. Ollama propone i suoi modelli cloud a $20/mese. Un H100 si noleggia a $1.38/h presso Vast.ai. E i modelli cinesi open-source — DeepSeek, Qwen, GLM — sono disponibili ovunque, gratuitamente, senza dover acquistare una scheda. Allora, questo Spark, a cosa serve esattamente? Ho fatto i conti.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">indice</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_contesto_un_mercato_che_ha_subito_una_svolta">Il Contesto : Un Mercato Che Ha Subito Una Svolta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nel maggio 2026, il panorama dell’IA è cambiato radicalmente rispetto all’annuncio del DGX Spark al CES 2025. Tre forze hanno convergito per rendere l’hardware locale sempre più difficile da giustificare :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Il crollo dei prezzi del cloud GPU</strong>Un H100 si affitta fra $1,38 e $3/ora, rispetto ai $5‑8/ora di 18 mesi fa.</p> </li> <li> <p><strong>L’esplosione dei modelli cinesi open-source</strong>DeepSeek‑V4, Qwen‑3, GLM‑5 sono competitivi con i modelli occidentali, disponibili gratuitamente</p> </li> <li> <p><strong>L’ascesa delle piattaforme di inferenza gestita</strong>Ollama, Groq, Together AI offrono API a tariffe aggressive, con piani gratuiti generosi</p> </li> </ul> </div> <div class="paragraph"> <p>Il DGX Spark, annunciato a $2 999 e poi portato a $4 699, arriva in un mondo che non ha più bisogno di lui.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_pannello_delle_opzioni">Il Pannello delle Opzioni</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ecco le soluzioni disponibili a maggio 2026 per far girare i LLM, dalla più leggera alla più pesante :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Opzione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">VRAM / Capacità</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelli accessibili</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Vincolo principale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Free</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0/mese</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cloud leggero</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti i modelli pubblici</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utilizzo limitato, 1 modello simultaneo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Claude Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/mese (~$240/anno)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N/A (API chiusa)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solo Claude 4.x</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modello unico, nessun open-source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/mese (~$200/anno)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">mezzo cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti i modelli pubblici</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Massimo 3 modelli simultanei</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Max</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$100/mese (~$1 200/anno)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nuvola pesante</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti i modelli pubblici</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">10 modelli simultanei</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>GPU cloud (H100)</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$1.38-3/h</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">80 Go HBM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti i modelli, fine-tuning</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fatturazione oraria, setup richiesto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>DGX Spark</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 (acquisto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">128 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <128 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lento (~10x meno di un H100), fisso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mac Studio M3 Ultra</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~$5 000+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">192 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <192 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non CUDA, ecosistema MLX</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>I prezzi cloud GPU citati sono quelli di Vast.ai e RunPod a maggio 2026 — spot/on-demand, non riservato. I prezzi degli hyperscaler (AWS, GCP, Azure) rimangono 2-3 volte più alti.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_cosa_ho_escluso_e_perché">Cosa ho escluso (e perché)</h3> <div class="paragraph"> <p>Ho deliberatamente escluso le seguenti opzioni da questo benchmark:</p> </div> <div class="ulist"> <ul> <li> <p><strong>API OpenAI / Anthropic / Google</strong>: l’argomento qui è far girare dei modelli <strong>open-source</strong> che si possono scegliere, fine-tunare, e non essere dipendenti da un unico fornitore</p> </li> <li> <p><strong>Huawei Ascend / Atlas</strong> : Huawei ne commercialise pas d’équivalent desktop au DGX Spark. La gamme Ascend (910C, 910D) et Atlas (300I Duo, 350) est orientée datacenter — cartes PCIe, serveurs rack — pas des boîtiers compacts prêts à brancher. La puce Ascend 910C embarque 128 Go HBM mais c’est une puce serveur, pas un système autonome. L’Atlas 300I Duo offre 96 Go pour ~$1 400 mais nécessite une machine hôte</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_inferenza_semplice_la_morte_dellhardware_locale">Inferenza semplice: La morte dell’hardware locale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Partiamo dal caso d’uso più comune: chattare con un LLM, fare code review, generare testo. Nessun fine-tuning, nessun batch processing, solo inferenza interattiva.</p> </div> <div class="sect2"> <h3 id="_il_calcolo">Il Calcolo</h3> <div class="paragraph"> <p>Un DGX Spark a $4.699. Dividiamo per il costo annuale di ogni abbonamento:</p> </div> <div id="diag-breakeven" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Soglia di Redditività — DGX Spark ($4 699) vs Abbonamenti rectangle "DGX Spark $4.699" as spark #FFCDD2 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Soglia di Redditività — DGX Spark ($4 699) vs Abbonamenti rectangle "DGX Spark $4.699" as spark #FFCDD2 rectangle "Ollama Pro\n$200/anno" as opro #C8E6C9 rectangle "Claude Pro $240/anno" as cpro #C8E6C9 rectangle "Ollama Max $1 200/anno" as omax #FFF9C4 rectangle "Cloud H100 $3/h × 10h/settimana? Wait check: "10h/settimana". I wrote "10h/settimana". Yes. So final. </think> Cloud H100 $3/h × 10h/settimana" as cloud #BBDEFB spark --> opro : 23.5 années ⏳ spark --> cpro : 19.6 années ⏳ spark --> omax : 3.9 années spark --> cloud : 3.0 années (à 10h/semaine, intermittent) note bottom of spark Sans compter l'électricité (~$150/an) Sans compter l'obsolescence hardware Sans compter qu'il est 10x plus lent end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Il verdetto è brutale. Per l’inferenza :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>: ti servirebbe<strong>23 anni</strong>per ammortizzare un DGX Spark. Lo Spark sarà obsoleto da 20 anni.</p> </li> <li> <p><strong>Ollama Max</strong>(No output, as the input text is empty)<strong>4 anni</strong>— a condizione di utilizzare Spark 24/7, cosa che nessuno fa</p> </li> <li> <p><strong>Claude Pro</strong>: stesso problema,<strong>20 anni</strong>per single-model chiuso</p> </li> </ul> </div> <div class="paragraph"> <p>(output empty) La promessa del « supercomputer IA da scrivania » si scontra con una realtà contabile elementare : $4 699 / $20 al mese = mai redditizio per un uso individuale. (No output)</p> </div> </div> <div class="sect2"> <h3 id="_anche_con_un_utilizzo_intensivo">Anche con un utilizzo intensivo</h3> <div class="paragraph"> <p>Consideriamo il caso peggiore per il cloud: fai girare un H100 8h/giorno, 5 giorni/settimana, 52 settimane/anno.</p> </div> <div class="ulist"> <ul> <li> <p>8 × 5 × 52 = 2 080 ore/anno</p> </li> <li> <p>2 080 × $2/h (prezzo medio spot H100) =<strong>$4 160/anno</strong></p> </li> </ul> </div> <div class="paragraph"> <p>Lo Spark ($4 699) si ripaga in<strong>13 mesi</strong>. Tranne che :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Il H100 è<strong>~10 volte più veloce</strong>che il GB10 di Spark. Fate in 1h quello che Spark fa in 10h. Per lo stesso volume di lavoro, l’H100 ti costa $416/anno, non $4 160.</p> </li> <li> <p>Le H100 a 80 Go HBM à 3.35 To/s de bande passante. Le Spark a 128 Go LPDDR5X à 273 Go/s. Pour les gros modèles, la bande passante compte plus que la capacité.</p> </li> </ol> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Confrontare 1h di H100 con 1h di Spark non ha senso. L’H100 svolge il lavoro 10x più velocemente. Il vero costo cloud per un workload dato è quindi ~10x inferiore al calcolo ingenuo basato sulle ore.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fine_tuning_il_cloud_è_imbattibile">Fine-Tuning : Il Cloud è imbattibile</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’argomento classico dei difensori di Spark: « sì ma per il fine-tuning, è diverso ».</p> </div> <div class="paragraph"> <p>No, non lo è.</p> </div> <div class="sect2"> <h3 id="_il_costo_reale_di_un_fine_tune">Il Costo Reale di un Fine-Tune</h3> <div class="paragraph"> <p>un fine-tune LoRA/QLoRA su Unsloth di un modello 7B:</p> </div> <div class="ulist"> <ul> <li> <p>~2-3h su un H100 =<strong>$5 a $9</strong></p> </li> <li> <p>Stessa cosa sul Spark =<strong>20-30h</strong>(10x più lento), blocca la macchina</p> </li> </ul> </div> <div class="paragraph"> <p>Con i $4 699 di Spark, puoi finanziare:</p> </div> <div class="ulist"> <ul> <li> <p><strong>~500 a ~900 fine-tunes</strong>nel cloud H100</p> </li> <li> <p>Ou <strong>~23 anni</strong>di Ollama Pro</p> </li> <li> <p>Ou <strong>~4 anni</strong>di Ollama Max</p> </li> </ul> </div> <div class="paragraph"> <p>E per i modelli più grandi (70B+) :</p> </div> <div class="ulist"> <ul> <li> <p>Le Spark avec ses 128 Go peut charger un 70B en Q4 — mais le fine-tune sera extrêmement lent</p> </li> <li> <p>Un H100 avec 80 Go peut fine-tuner un 70B en QLoRA 4-bit en quelques heures</p> </li> <li> <p>Per un fine-tuning completo, serve comunque il multi-GPU — Spark è fuori gioco</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_gli_attori_specializzati">Gli Attori Specializzati</h3> <div class="paragraph"> <p>Nel 2026, piattaforme come Unsloth, Modal, Replicate e Together AI propongono il fine-tuning serverless :</p> </div> <div class="ulist"> <ul> <li> <p>Nessuna gestione della GPU</p> </li> <li> <p>Nessuna configurazione dell’ambiente</p> </li> <li> <p>Pagamento al minuto</p> </li> <li> <p>Ottimizzazioni integrate (flash attention, quantizzazione automatica)</p> </li> </ul> </div> <div id="diag-fine-tuning-cost" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-125b0bcad8559ffe870bd57c7b3a6b6a.svg" alt="Comparaison des coûts de fine-tuning" width="626" height="244"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lunica_vera_ragione_la_sovranità_dei_dati">L’unica vera ragione: la sovranità dei dati</h2> <div class="sectionbody"> <div class="paragraph"> <p>Dopo aver eliminato l’inferenza, il fine‑tuning e il rapporto qualità/prezzo — cosa resta al Spark?</p> </div> <div class="paragraph"> <p><strong>Assoluta riservatezza.</strong></p> </div> <div class="paragraph"> <p>Non è questione di riservatezza «non voglio che i miei prompt vengano letti da un dipendente di OpenAI». Questo è un falso problema nel 2026: Ollama, Groq e la maggior parte dei provider rispettabili hanno politiche di zero log e zero retention.</p> </div> <div class="paragraph"> <p>La vera riservatezza, è:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Air-gap normativo</strong>: difesa, diplomazia, salute — i dati non possono <strong>fisicamente</strong> lasciare l’edificio</p> </li> <li> <p><strong>dati proprietari critici</strong>: codice sorgente di un prodotto non pubblicato, segreti industriali, algoritmi di trading</p> </li> <li> <p><strong>Resilienza di rete</strong>: l’IA deve continuare a funzionare anche se Internet cade</p> </li> </ul> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Ma siamo onesti: quale percentuale degli acquirenti di DGX Spark è realmente in questo caso? 1%? Il resto è semplicemente un «nice to have» trasformato in una spesa di $4 699.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_il_vero_calcolo_della_confidenzialità">Il Vero Calcolo della Confidenzialità</h3> <div class="paragraph"> <p>Per uso individuale :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong>($20/mese) + modelli open source cinesi = soluzione pragmatica</p> </li> <li> <p>Se una richiesta trapelasse da Ollama, si perde tra i milioni di richieste giornaliere. È una goccia d’acqua nell’oceano.</p> </li> <li> <p>Il rischio reale non è la fuga di un prompt — è l’addestramento non consensuale sui tuoi dati. E questo, i provider seri lo vietano per contratto.</p> </li> </ul> </div> <div class="paragraph"> <p><em>__</em> La paura di « distillare il proprio prompt nel LLM » è un livello di diffusione di informazioni personali così diluito che appartiene più all’ansia che a una minaccia reale. Su scala industriale, è diverso. Ma su scala individuale, è solo rumore. (no output)</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_sintesi_la_matrice_di_decisione">Sintesi : La Matrice di Decisione</h2> <div class="sectionbody"> <div id="diag-decision-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-eefa340d58be395a31244452056759d9.svg" alt="Matrice de décision pour choisir sa solution LLM" width="2012" height="433"> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2232%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Criterio</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Free</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPU Cloud H100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DGX Spark</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Inferenza</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ limitata</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅ Comodo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�✅ eccessivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Lento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>affinamento</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Imbattibile</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Possibile ma lento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Costo annuo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$200</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variabile (~$416-2 080*)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 anticipato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>riservatezza</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Cloud US</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Nuvola US</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�⚠️ Cloud US (variabile)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Totale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Manutenzione</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nessuna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nessuna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Impostazione unica</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Elettricità, aggiornamenti</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Obsolescenza</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nessuna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nessuna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nessuna</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3-5 anni</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>ecosistema software</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti i modelli open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti modelli aperti</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tutti i modelli open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA (più lento)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Verdetto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Occasionale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Raccomandato</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pro/Ricerca</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">solo Air-gap</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Variabile secondo il volume di lavoro ; con velocità H100 ~10x > Spark, il costo effettivo per un workload dato è basso._</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_il_caso_particolare_labbonamento_pro_di_fronte_ai_modelli_cinesi">Il Caso Particolare: L’Abbonamento Pro di Fronte ai Modelli Cinesi</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un punto merita di essere sottolineato: la combinazione<strong>Ollama Pro a $20/mese + modelli cinesi open-source</strong>è probabilmente il miglior rapporto qualità/prezzo della storia dell’IA di massa.</p> </div> <div class="sect2"> <h3 id="_perché_i_modelli_cinesi_cambiano_tutto">Perché i Modelli Cinesi Cambiano Tutto</h3> <div class="ulist"> <ul> <li> <p><strong>DeepSeek-V4-Pro</strong>: 1.6T parametri, CSA+HCA, 1M contesto, competitivo con Claude 4 e GPT-5 per il codice</p> </li> <li> <p><strong>Qwen-3</strong>: 235B, 256K contesto, eccellente in francese e nel ragionamento</p> </li> <li> <p><strong>GLM-5.1</strong>: 744B, MLA+DSA, 200K contesto, su misura per l’agentico</p> </li> </ul> </div> <div class="paragraph"> <p>Tutti disponibili su Ollama. Tutti open-source (licenze permissive). Tutti utilizzabili senza restrizioni tramite un abbonamento a $20/mese.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Con Ollama Pro, hai accesso a ~5 modelli « frontier » open-source al prezzo di un solo modello chiuso (Claude Pro). Il valore è così asimmetrico che diventa quasi assurdo.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_che_cosa_significa_per_lhardware">Che Cosa Significa per l’Hardware</h3> <div class="paragraph"> <p>Se il miglior rapporto qualità/prezzo è un abbonamento cloud a $20/mese, l’hardware locale diventa una scelta di <strong>confort</strong> o di <strong>principe</strong> — non una scelta economica.</p> </div> <div class="paragraph"> <p>Un DGX Spark a $4 699, è l’equivalente di :</p> </div> <div class="ulist"> <ul> <li> <p>235 mois d’Ollama Pro</p> </li> <li> <p>23 giochi AAA giorno di uscita</p> </li> <li> <p>4 MacBook Air M4</p> </li> <li> <p>Un anno di affitto di un T2 a Lione</p> </li> </ul> </div> <div class="paragraph"> <p>Per il calcolo. Lento.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_e_huawei">E Huawei?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poiché la domanda mi è stata posta durante le mie ricerche: no, Huawei non commercializza un equivalente al DGX Spark.</p> </div> <div class="paragraph"> <p>Ciò che esiste:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ascend 910C</strong> : 128 Go HBM, 800 TFLOPS FP16 — mais c’est une puce serveur, pas un desktop</p> </li> <li> <p><strong>Atlas 300I Duo</strong> : 96 Go LPDDR4X, carte PCIe à ~$1 400 — nécessite un hôte</p> </li> <li> <p><strong>Atlas 350</strong> : 112 Go HBM, 1.56 PFLOPS FP4 — accélérateur datacenter, pas un boîtier compact</p> </li> </ul> </div> <div class="paragraph"> <p>Huawei reste focalisé sur le marché des serveurs et des centres de données. Pour un boîtier compact « prêt à brancher » avec 120+ Go de VRAM, le DGX Spark (128 Go unifié) et le Mac Studio M3 Ultra (192 Go unifié) sont les seules options en 2026. Et pour l’instant, aucun constructeur chinois n’a annoncé de produit équivalent dans ce format.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione_il_lusso_della_vicinanza">Conclusione: Il lusso della vicinanza</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il DGX Spark non è un cattivo prodotto. È un cattivo investimento per il 99% degli acquirenti potenziali.</p> </div> <div id="diag-verdict" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Il panorama dell'IA nel 2026 — Chi domina ? left to right direction package "Uso personale / PMI" #C8E6C9 { rectangle "🏆 Ollama Pro ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Il panorama dell'IA nel 2026 — Chi domina ? left to right direction package "Uso personale / PMI" #C8E6C9 { rectangle "🏆 Ollama Pro $20/mese" as pro rectangle "Ollama Free $0/mese" as free rectangle "Spot GPU cloud $1-3/h" as spot } package "Usage Intensif / Pro" #FFF9C4 { rectangle "🏆 Ollama Max $100/mese" as max rectangle "🏆 Cloud GPU dedicato\n$2-4/h" as dedicated rectangle "Modal / Together AI\nServerless" as serverless } package "Air-gap obbligatorio" #FFCDD2 { rectangle "DGX Spark $4 699" as spark rectangle "Mac Studio M3U ~$5 000" as mac } note bottom of spark 1% des cas d'usage — défense, santé réglementée, secrets industriels critiques end note @enduml</pre> </div> </div> <div class="paragraph"> <p><em><em>_ Acquistare un DGX Spark nel 2026 è come acquistare un server mail nel 2010: tecnicamente possibile, filosoficamente soddisfacente, economicamente assurdo per un individuo. </em>_</em></p> </div> <div class="paragraph"> <p>Il calcolo è semplice, e non mente:</p> </div> <div class="ulist"> <ul> <li> <p><strong>$0</strong>per chattare con DeepSeek su Ollama Free</p> </li> <li> <p><strong>$200/anno</strong>per lavorare seriamente con Ollama Pro</p> </li> <li> <p><strong>$5-9</strong>per un fine-tune occasionale su cloud GPU</p> </li> <li> <p><strong>$4 699</strong>per…​ l’esperienza di avere un case NVIDIA sulla sua scrivania ?</p> </li> </ul> </div> <div class="paragraph"> <p>Il mercato ha deciso. Gli abbonamenti cloud e i modelli open-source cinesi hanno vinto la battaglia del prezzo. L’hardware locale sopravvive nelle nicchie regolamentari, non negli uffici degli sviluppatori.</p> </div> <div class="paragraph"> <p>(No output) Il DGX Spark non è uno strumento redditizio. È una statement. « Voglio la mia IA a casa mia, non nel cloud di qualcun altro. » È rispettabile. Ma nel 2026, quando Ollama ti offre DeepSeek-V4-Pro nel cloud per $20/mese, è soprattutto una statement che costa molto. (No output)</p> </div> <hr> <div class="paragraph"> <p><strong>Questo articolo deriva da una conversazione con il mio agente IA sulla pertinenza economica del DGX Spark, incrociata con una vigilanza di mercato sui prezzi dei GPU cloud (Vast.ai, RunPod), le tariffe Ollama/Claude, e l’ecosistema dei modelli cinesi open-source. I prezzi citati sono quelli di maggio 2026 — probabilmente saranno ulteriormente diminuiti quando leggerai queste righe.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html Mon, 4 May 2026 00:00:00 +0000 blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel2"> <li><a href="#_jbake_cli_commands_initialize_a_new_jbake_project_jbake_i">JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</a></li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset">Clear the output directory before baking jbake -b . output --reset <code>`</code></a> <ul class="sectlevel1"> <li><a href="#_il_problema_il_prompt_engineering_è_un_castello_di_sabbia">Il Problema : il Prompt Engineering è un Castello di sabbia</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 14 minutes</div> <p>Per mesi, ho accumulato le regole di governance degli agenti. Alcuni file EAGER, liste di controllo LAZY, protocolli di fine sessione in sei fasi. E tuttavia, una domanda rimaneva in sospeso : <strong>come il LLM sa ciò che</strong> ha il diritto di fare con un file?*</p> </div> </div> </div> <div class="sect2"> <h3 id="_jbake_cli_commands_initialize_a_new_jbake_project_jbake_i">JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</h3> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code></h1> <div class="paragraph"> <p>La risposta non è in un prompt. È nel sistema di file.</p> </div> <div class="paragraph"> <p>Ecco la specifica di architettura che rende la risposta sfruttabile — la <strong>matrice di governance LLM</strong>.</p> </div> <div class="sect1"> <h2 id="_il_problema_il_prompt_engineering_è_un_castello_di_sabbia">Il Problema : il Prompt Engineering è un Castello di sabbia</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando si dà un file a un LLM, gli si dà tutto. Il contenuto, sì — ma anche l’assenza di salvaguardie. Il LLM non sa se questo file contiene un segreto, un’opinione speculativa o del codice closed source. Lo indicizzerà, riassumerlo, citarlo, mescolarlo con altri dati — e potenzialmente pubblicarlo in un embedding pubblico o un utente</p> </div> <div class="paragraph"> <p>La parata classica, è il prompt :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">"Tu es un assistant sécurisé. Ne divulgue jamais d'informations confidentielles. Si tu détectes un secret, ignore-le. Si tu détectes une opinion, ne la répète pas."</code></pre> </div> </div> <div class="paragraph"> <p>Questo prompt ha tre problemi:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Si basa sulla buona volontà del LLM.</strong> Un modello abbastanza grande per</p> </li> </ol> </div> <div class="paragraph"> <p>risolvere bug complessi è abbastanza grande per aggirare un’istruzione di sicurezza sommerse in 200k token di contesto</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><mark>#</mark> Comandi CLI di JBake</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ---- *È contestuale, non strutturale.* Cambiate prompt, cambiate LLM, cambia sessione — e la regola scompare. 1. *Non scala.* Ogni nuovo tipo di file, ogni nuovo livello di riservatezza richiede una nuova clausola. Il tuo prompt diventa un testo normativo che nessuno legge per intero. [CAUTION] ==== La sicurezza di un sistema non deve mai dipendere da un'istruzione che si Può dimenticare, bypassare o non caricare. Lei deve dipendere da una barriera che non si può superare senza volerlo esplicitamente. ==== == La mia risposta: la matrice 4×4 La soluzione che ho implementato nel mio workspace è una **matrice zona × diritto di accesso LLM**. Non chiede al LLM di essere prudente. Ella rende l'imprudenza strutturalmente impossibile. [plantuml, format=svg, id=diag-matrix-overview, alt="Vue d'ensemble de la matrice de gouvernance LLM — 5 zones × 4 droits d'accès"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title La Matrice di Governance LLM — Zona × Diritto di Accesso package "area di lavoro" { rectangle "RADICE (Cerchio 0) ━━━━━━ Brain dump Pensiero libero [INTERDITTO LLM]" as Z0 #FFB3B3 rectangle "configuration/ (Cerchio 1) ━━━━━━ Secrets, tokens Infra privata [VIETATO LLM]" as Z1 #FFB3B3 rectangle "office/\n(Cerchio 2)\n━━━━━━\nData editoriale\nArticoli, inquadrature\n[Visione filtrata]" as Z2 #FFF3B3 rectangle "foundry/private/ (Cerchio 3) ━━━━━━ Code closed source [DATASET PRIVATO]" as Z3 #B3D9FF rectangle "foundry/public/ (Cerchio 3) ━━━━━━ Codice open source Apache 2.0 [ACCESSO LIBRE]" as Z4 #B3FFB3 } Z0 -[hidden]-> Z1 Z1 -[hidden]-> Z2 Z2 -[hidden]-> Z3 Z3 -[hidden]-> Z4 @enduml ---- === Le Cinque Zone (Dimensione Spaziale — RGPD) Ogni zona del workspace ha un livello RGPD che determina *dove* il file può essere instradato : |=== |Zona |Livello GDPR |Contenuto |Diritto di accesso RAG pubblico |Radice |0 — Intimo |Brain dumps, conversazioni LLM |**PROIBITO**— mai indicizzato |`configuration/` |1 — Proprietario limitato |Segreti, token, chiavi API |**vietato**— mai indicizzato |`office/` |2 — Collaborativo ristretto |Data editoriale, inquadratura, formazione |**FILTRATO**— Solo visione |`foundry/private/` |3 — Aperto condizionale |Codice sorgente chiuso, SaaS non pubblico |**VIETATO**— dataset privato esclusivamente |`foundry/public/` |4 — Pubblico nativo |Codice Apache 2.0, plugin pubblicati |**libero**— indicizzazione completa |=== La regola è semplice : *il percorso del file determina ciò che il LLM può farne.* Nessun metadato da mantenere, nessun tag da aggiungere nel frontmatter, Nessuna classificazione manuale ad ogni commit. Il file è dentro`OSS/`? È pubblico. È in`configuration/`? È intoccabile. === La classificazione epistemica (seconda dimensione) La dimensione spaziale dice *dove* instradare. Ma c'è un secondo asse, perpendicolare: *che cosa* router. Alcuni file in una zona autorizzata contengono informazioni che non dovrebbero essere diluite tali quali: [plantuml, format=svg, id=diag-epistemic-filter, alt="Filtre épistémique Vision/Opinion/Stratégie appliqué aux zones 2 et 3"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 240 title La Doppia Cascata — Filtro Spaziale + Filtro Epistemico start :Le LLM rencontre un fichier; if (Zone physique ?) then (Cercle 0-1) :ACCÈS BLOQUÉ\n(secret, brain dump); stop elseif (Zone CSS/) :DROIT D'ACCÈS PRIVÉ\n→ dataset fine-tuning; :Filtre épistémique\nVision/Opinion; if (Classification ?) then (VISION) :Dataset privé\n→ entraînement autorisé; else (OPINION) :CONFINÉ\n→ pas d'entraînement; endif elseif (Zone office/) :DROIT D'ACCÈS FILTRÉ\n→ accès conditionnel; :Filtre épistémique\nVision/Opinion/Stratégie; if (Classification ?) then (VISION) :DILUTION COMPLÈTE\n→ docs racine + blog; elseif (STRATÉGIE) :DILUTION RESTREINTE\n→ docs racine seulement; else (OPINION) :CONFINEMENT\n→ office/ uniquement; endif else (Zone OSS/) :ACCÈS LIBRE\n→ indexation complète; endif stop @enduml ---- La griglia di classificazione epistemica, incisa nella Regola 2bis della mia governance agente : ### JBake CLI Commands ``` # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ``` | Stato | Definizione | Segnale LLM | Destinazione | | VISION | Architettura stabilizzata, pattern testato | Linguaggio dichiarativo, riferimenti sessioni/test | Diluzione completa + Blog | | STRATEGIA | Posizionamento business, pricing | Vocabolario mercato, concorrenza | Documenti radice esclusivamente | | OPINION | Speculazione, ipotesi non validata | Linguaggio ipotetico, intuizione | Confinamento Cerchio 0 | La combinazione delle due dimensioni — zona fisica × classificazione epistemica — forma la**matrice completa**: [plantuml, format=svg, id=diag-full-matrix, alt="La matrice complète : 5 zones × 3 classifications épistémiques"] ---- @startuml skinparam backgroundColor #FEFEFE title La Matrice Completa — Zone × Classificazione salt { {T + Zone | VISION | STRATÉGIE | OPINION + Racine (0) | ✗ Interdit | ✗ Interdit | ✗ Interdit + configuration/ (1) | ✗ Interdit | ✗ Interdit | ✗ Interdit + office/ (2) | ✓ Docs + Blog | ✓ Docs seulement | ✗ Confiné + CSS/ (3) | ✓ Dataset privé | ✓ Dataset privé | ✗ Confiné + OSS/ (4) | ✓ Public libre | ✓ Public libre | ✓ Public libre } } @enduml ---- == Come il LLM consuma questa matrice La matrice non è un documento che il LLM legge. È un **vincolo implicita** codificata nel vettore composto di contesto (EPIC 9 — in corso di implementazione) Ecco ciò che il LLM riceve ad ogni sessione: [source] ---- VECTEUR COMPOSITE DE CONTEXTE ├── RAG pgvector → OSS/ + office/Vision │ (similarité sémantique sur contenu publiable) ├── Knowledge Graph graphify → OSS/ │ (relations exactes entre artéfacts publics) ├── Knowledge Graph privé → CSS/ │ (relations entre code closed source — jamais exporté) ├── Métadonnées de zone → chaque fichier taggé par zone physique │ (le LLM sait s'il est dans office/ ou OSS/) └── Historique des décisions → WORKSPACE_VISION.adoc (contexte temporel des arbitrages) ---- Concretamente, quando il LLM mi dice : [source,text] ---- Je vais indexer le contenu de edster/ pour enrichir le knowledge graph... ---- La metadata di zona risponde anche prima che il LLM finisca la sua frase: `edster/`### JBake CLI Commands ``` # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset`CSS/`</think> , livello 3 →**accesso vietato al knowledge graph pubblico** Il RAG non lo vede. Il grafo non lo tocca. La risposta dell'utente non non lo cita. [TIP] ==== L'ontologia spaziale funziona come una**permessi Unix** pour les LLM. Non chiedete a un processo di essere prudente con`/etc/shadow`[No output] gli neghi l'accesso in lettura. Stesso principio. ==== == Implementazione : Attività Gradle tipate La matrice non è una filosofia. È codice. Ecco il contratto di compito Gradle che lo implementa : [source,kotlin] ---- abstract class ZoneAwareIndexer @Inject constructor( private val rootDir: DirectoryProperty, private val configServer: ConfigServerProperty // → configuration/ ) : DefaultTask() { @Input val zoneFilter: SetProperty<Zone> = project.objects.setProperty(Zone::class.java) @OutputFile val ragIndex: RegularFileProperty = project.objects.fileProperty() @TaskAction fun index() { val allowedPaths = zoneFilter.get().flatMap { it.resolve(rootDir.get()) } val forbiddenPaths = Zone.RESTRICTED.resolve(rootDir.get()) + Zone.INTIMATE.resolve(rootDir.get()) // Le RAG ne voit jamais configuration/ ni la racine // CSS/ alimente un index privé, pas celui-ci // office/ est filtré par le classifieur Vision/Opinion } } enum class Zone { INTIMATE, // Cercle 0 — racine RESTRICTED, // Cercle 1 — configuration/ EDITORIAL, // Cercle 2 — office/ CLOSED_SOURCE, // Cercle 3 — foundry/private/ OPEN_SOURCE // Cercle 3 — foundry/public/ } ---- L'attività è *testable*. Puoi scrivere un test che verifica: [source,kotlin] ---- @Test fun `le RAG n'indexe jamais configuration`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE, Zone.EDITORIAL)) index.index() assertThat(index.ragIndex).doesNotContain("configuration/") } @Test fun `le code closed source est exclu du RAG public`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE)) // OSS only assertThat(index.ragIndex).doesNotContain("edster") } ---- 380 tests, 380 PASS. Come per plantuml-gradle — la sicurezza è testata, non sperata. == Perché è un Manifesto, Non Solo una spec Questo documento è una specifica di architettura perché definisce: * Des **dimensioni**(spaziale, epistemico) * Des **regole deterministe**(zona → diritto di accesso) * Un **contratto di incarico**(Gradle tipizzato, testabile) * una**implementazione di riferimento**(mio workspace) Ma è anche un**manifesto**perché prende posizione su un dibattito plus large : *comment gouverner l'accès d'un LLM à des données ?* La risposta dell'industria, è il prompt engineering + i guardrail + i classificatori post-hoc. La mia risposta è: **metti i tuoi file nella le buone cartelle.** Il resto è automatico. [IMPORTANT] ==== Questo manifesto non dice "i LLM devono essere allineati". Dice: "l'allineamento di un LLM sulle tue regole di sicurezza è una conseguenza del tuo sistema di file, non il tuo prompt. ==== == La Cascata Completa — dal Brain Dump all'Articolo del Blog Per illustrare il ciclo completo, ecco come è nata questa idea di matrice ed è stata diluita : [source] ---- Session 4 mai 2026 — Feedback global du workspace │ ├→ Le LLM identifie : "la dualité public/privé est invisible" │ → Classifié VISION (constat architectural vérifiable) │ ├→ PICTURE_ME_ROLLIN_MATRICE_4X4.adoc — STIMULUS (Cercle 0) │ → Brain dump structuré, classification VISION confirmée │ ├→ DILUTION → WORKSPACE_AS_PRODUCT.adoc (section Matrice 4×4) │ → La spec vit dans les documents racine │ ├→ DILUTION → WORKSPACE_ORGANIZATION.adoc (OSS/CSS) │ → La granularisation est documentée │ └→ ARTICLE 0117 (ce document) → cheroliv.com → La VISION est publiée ---- Ciò che è iniziato come un'osservazione in sessione ("ehi, il RAG non sa que edster est closed source") è diventata una specifica di architettura pubblicata in meno di una sessione. È il pattern STIMULUS in azione. == Pro e contro |=== |Questo approccio (Ontologia Spaziale + Matrice) |L'approccio Classico (Prompt + Guardrails) |*Meccanica* — il sistema di file blocca l'accesso, non il LLM |*Dichiarativa* — il prompt chiede al LLM di essere prudente |*Testable* — le contrat de tâche Gradle est vérifié par 380+ tests |### Comandi CLI JBake ``` # Initialize a new JBake project jbake -i |*Indépendante du LLM* — changez de modèle, les dossiers restent |*Dipendente dal LLM* — ogni modello interpreta il prompt in modo diverso |*Scalable* — nuovo tipo di dati = nuova cartella, nessun cambiamento di codice |*Non scalabile* — nuovo tipo di dati = nuova clausola di prompt, nuovo rischio di regressione |### JBake CLI Commands ``` # Initialize a new JBake project jbake -i |*Contrainte* : richiede una disciplina di organizzazione iniziale |*Contrainte* : richiede una disciplina nella redazione dei prompt per ogni sessione |=== == Conclusion: Organizza i tuoi file, non i tuoi prompt La matrice di governance LLM che ho appena descritto non è un prodotto. È una**specifica di architettura** — et c'est pour ça qu'elle est pubblicabile Ciò che la rende robusta è che non chiede nulla al LLM. Non le Non si fida. Non si basa sul suo allineamento, sulla sua comprensione. del francese, o della sua buona volontà. Si basa sul sistema di file — il livello più basso, più stabile, più testato di tutta la stack. Quando dico al mio LLM "puoi indicizzare tutto in`OSS/`, niente in `configuration/`, et `office/`solo se è classificato Vision — non è un'istruzione. È un *filtre* — implementato in Kotlin, verificato da 380 test, eseguito prima che il LLM veda i dati. È la differenza tra dire a qualcuno "non guardare in questo cassetto e chiudere il cassetto a chiave. La governance dell'agente che sto costruendo da i mesi sono la chiave. La matrice è il progetto del mobile. == Riferimenti * xref:0116_compartimentage_epistemique_automatise_llm_post.adoc[Articolo 0116 — Il Compartimentaggio Epistemico Automatizzato] * xref:0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.adoc[Articolo 0114 — I Cerchi di Fiducia e l'Ontologia Spaziale] * xref:0108_gouvernance_agent_opencode_eager_lazy_post.adoc[Article 0108 — Governare un Agente IA con AsciiDoc] * link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[Articolo 0115 — L'anonimizzatore MVP0]</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html Sun, 3 May 2026 00:00:00 +0000 blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_lincidente_che_stava_per_succedere">L’incidente che stava per succedere</a> <ul class="sectlevel2"> <li><a href="#_la_vera_domanda">La Vera Domanda</a></li> </ul> </li> <li><a href="#_la_soluzione_oss_e_css">La Soluzione: OSS/ e CSS/</a></li> <li><a href="#_perché_oss_e_css_e_non_public_e_private">Perché "OSS" e "CSS" e Non "Public" e "Private</a> <ul class="sectlevel2"> <li><a href="#_lalbero_completo_quattro_zone_non_tre">L’Albero Completo — Quattro Zone, Non Tre</a></li> </ul> </li> <li><a href="#_il_caso_particolare_cheroliv_com">Il caso particolare: cheroliv.com</a> <ul class="sectlevel2"> <li><a href="#_bakery_gradle_non_gliene_frega_niente">bakery-gradle non gliene frega niente</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura: 10 minutes</div> <p><code>foundry/</code>— l’area funzionale che ospita il codice del mio workspace — contiene 18 progetti. Otto sono open source sotto licenza Apache 2.0. Uno solo è closed source — il SaaS Edster. Per mesi, questi nove progetti hanno coabitato nella stessa cartella, separati solo da…​ niente. Il loro stato pubblico/privato era un’informazione nella mia testa, non nel sistema di file.</p> </div> <div class="paragraph"> <p>E poi ho voluto collegare un RAG. E lì, tutto è crollato.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lincidente_che_stava_per_succedere">L’incidente che stava per succedere</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nel aprile 2026 ho iniziato a implementare il RAG pgvector per slider-gradle. Il principio: indicizzare tutti i repository di`foundry/<code>, produrre dei embeddings, e iniettarli nel contesto del LLM affinché ne abbia una percezione" del fascicolo`foundry/</code>.</p> </div> <div class="paragraph"> <p>Il pipeline era semplice :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val repos = fileTree(rootDir) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val chunks = repos.map { chunk(it) } val embeddings = chunks.map { embed(it) } pgvector.insert(embeddings)</code></pre> </div> </div> <div class="paragraph"> <p>Semplice. Efficace. E<strong>pericoloso</strong>.</p> </div> <div class="paragraph"> <p>Perché questo`fileTree`non fa la differenza tra`plantuml-gradle/` (Apache 2.0, pubblico) e`edster/`(closed source, private). Divora tutto. E se un giorno pubblico questi embeddings — su un dashboard, in una risposta LLM, in un dataset di addestramento — il codice proprietario di Edster trapelato.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Il problema non è che un LLM legga codice closed source. Il problema, è che questo codice finisca in un embedding vettoriale <strong>pubblico</strong> — irreversibile, non cancellabile, non controllabile</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_la_vera_domanda">La Vera Domanda</h3> <div class="paragraph"> <p>Non è "come impedire al LLM di trapelare il codice ?". C’è "come Rendere la fuga strutturalmente impossibile?</p> </div> <div class="paragraph"> <p>La risposta non è un prompt. La risposta è di dividere la cartella in due.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_oss_e_css">La Soluzione: OSS/ e CSS/</h2> <div class="sectionbody"> <div class="paragraph"> <p>Prima :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── plantuml-gradle/ ← public ├── bakery-gradle/ ← public ├── magic-stick/ ← public ├── edster/ ← PRIVÉ ├── slider-gradle/ ← public └── ... ← mélange invisible</code></pre> </div> </div> <div class="paragraph"> <p>Dopo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── OSS/ ← tout est Apache 2.0 │ ├── plantuml-gradle/ │ ├── bakery-gradle/ │ ├── magic-stick/ │ ├── slider-gradle/ │ └── ... └── CSS/ ← tout est closed source / private └── edster/</code></pre> </div> </div> <div class="paragraph"> <p>Le `fileTree`diventa :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val ossRepos = fileTree(File(rootDir, "OSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val cssRepos = fileTree(File(rootDir, "CSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } // Embeddings publics — OSS seulement pgvectorPublic.insert(ossRepos.map { chunk(it) }.map { embed(it) }) // Dataset fine-tuning privé — CSS seulement fineTuningDataset.insert(cssRepos.map { chunk(it) }) // jamais publié</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Il RAG pubblico non vede mai`CSS/`. Il codice closed source alimenta un dataset senza fine-tuning — un modello interno che non esce mai da casa mia. La separazione è meccanica, non dichiarativa.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_perché_oss_e_css_e_non_public_e_private">Perché "OSS" e "CSS" e Non "Public" e "Private</h2> <div class="sectionbody"> <div class="paragraph"> <p>La scelta degli acronimi OSS (Open Source Software) e CSS (Closed Source Software) è deliberato :</p> </div> <div class="ulist"> <ul> <li> <p>Pubblico"/"Privato" descrive la<strong>visibilità</strong>(ciò che GitHub vede)</p> </li> <li> <p>OSS"/"CSS" descrive la<strong>natura</strong>del codice (ciò che il LLM deve sapere)</p> </li> </ul> </div> <div class="paragraph"> <p>La visibilità GitHub è un metadato del repository remoto. La natura del codice è una proprietà del contenuto. Il LLM non ha accesso all’API GitHub — ma ha accesso al sistema di file.<code>CSS/`gli dice "attenzione, questo codice non è sotto licenza libero" senza bisogno di leggere un`LICENSE`o di parsare un`package.json</code>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Il nome della cartella è il metadato più robusto che Lei possa dare a un LLM. Non può essere parsata male, ignorata o interpretata male. Il LLM vede`CSS/edster/`nel percorso del file — lo sa.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_lalbero_completo_quattro_zone_non_tre">L’Albero Completo — Quattro Zone, Non Tre</h3> <div class="paragraph"> <p>La granulazione OSS/CSS completa l’ontologia a tre zone. La zona `foundry/`passa da 1 a 2 sottozone funzionali :</p> </div> <div id="diag-four-zone-workspace" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-da5a66ce3d7e1f67f2d721a49bc2dae1.svg" alt="L’organisation de foundry/ en deux sous-zones OSS et CSS" width="1759" height="5736"> </div> </div> <div class="paragraph"> <p>| Zone | GDPR | Indicizzazione RAG pubblica | fine-tuning del dataset | | Radice | Livello 0 — Intimo | ✗ | ✗ | (empty)<code>configuration/</code>| Livello 1 — Limitato | ✗ | ✗ | (No output)<code>office/</code>| Livello 2 — Collaborativo | ✓ Filtrato | ✓ Filtrato | (no output)<code>foundry/private/</code>| Livello 3 — Aperto condizionale | ✗ | ✓ Privato | (No output)<code>foundry/public/</code>| Livello 4 — Pubblico nativo | ✓ Libero | ✓ Pubblico |</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_il_caso_particolare_cheroliv_com">Il caso particolare: cheroliv.com</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mentre ero lì, ho corretto un’altra incoerenza. Il mio sito <code>cheroliv.com`viveva in`foundry/`come un progetto software a tutti gli effetti — con il proprio build Gradle, il proprio CI, il proprio governance</code>.agents/`.</p> </div> <div class="paragraph"> <p>Ma gli articoli del blog non sono codice. Sono <strong>dati</strong> editoriali** di Cerchio 2 — allo stesso titolo degli inquadramenti di`office/pilotage/` o le formazioni di`office/formations/`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">AVANT APRÈS foundry/ office/ cheroliv.com/ sites/ site/jbake/content/blog/ cheroliv.com/ 2026/0117_....adoc 2026/0117_....adoc</code></pre> </div> </div> <div class="paragraph"> <p>Cosa cambia :</p> </div> <div class="ulist"> <ul> <li> <p>Gli articoli sono in`office/`→ riservatezza di Cerchio 2</p> </li> <li> <p>Il compito`publishSite`diventa una capability di`engine`</p> </li> </ul> </div> <div class="paragraph"> <p>via`bakery-gradle`— il plugin riceve un`FileTree`, non lo sa che gli articoli vengano da`office/`</p> </div> <div class="ulist"> <ul> <li> <p>Un solo CI, una sola governance — zero duplicazione</p> </li> <li> <p>Il classificatore Vision/Opinion (Regola 2bis) si applica automaticamente :</p> </li> </ul> </div> <div class="paragraph"> <p>gli articoli in`office/`sono filtrati prima della pubblicazione</p> </div> <div class="sect2"> <h3 id="_bakery_gradle_non_gliene_frega_niente">bakery-gradle non gliene frega niente</h3> <div class="paragraph"> <p>E quello è bello. Il plugin`bakery-gradle`non è stato modificato. Riceve una directory di contenuto AsciiDoc, genera HTML, push sui GitHub Pages. Che questo directory si chiami`site/jbake/content/` ou <code>office/sites/cheroliv/</code><mark>#</mark> Gradle Integration JBake can be integrated into Gradle builds using the JBake Gradle plugin or by calling the JBake CLI directly:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } ---- — il plugin non se ne frega. [source,kotlin] ---- // engine/build.gradle.kts task("publishBlog") { doLast { val articles = fileTree("../../office/sites/cheroliv/2026/") bakery.generate(articles) // ← bakery ne sait pas d'où ça vient } } ---- Il contratto di interfaccia è una attività Gradle. Non è un'API REST. Non è un webhook. Un compito — tipizzato, testabile, eseguibile in locale e nella CI. == Impatto sulla governance dell'agente La granularizzazione OSS/CSS modifica la governance degli agenti su tre punti: 1. *RAG public* : il perimetro di indicizzazione passa da`foundry/**` à `foundry/public/**`+`office/Vision/**`Il codice sorgente chiuso è escluso dall'indice per configurazione dell'attività, non per prompt. 1. *Knowledge Graph* : graphify-gradle produce due grafi : *`office/graph.json`(public) — relazioni tra artefatti OSS + office/Vision *`configuration/graph_private.json`(gitignored, privato) — relazioni tra artefatti CSS, mai pubblicato 1. *Fine-tuning del dataset* :`codebase-gradle`ha ora due fonti: *`OSS/`→ datasets pubblici (modelli comunitari, benchmarks) *`CSS/`→ datasets privati (modello interno, fine-tuning proprietario) == Cosa si guadagna (e cosa si perde) |=== |Fronte (cartella piatta) |Dopo (OSS/CSS + office/sites) |`ls foundry/`→ misto pubblico/privato |`ls foundry/public/`tutto è pubblicabile |RAG indicizza tutto senza discriminazione |RAG indicizza`OSS/`+`office/Vision`esclusivamente |Impossibile sapere se un progetto è open source |Il percorso`OSS/` ou `CSS/`il detto |cheroliv.com ha la propria CI, la propria governance |La CI e la governance sono condivise nel motore |Gli articoli del blog sono in un repository 'code' |Gli articoli del blog sono in`office/sites/`— dati, non codice |Rischio di fuga di codice sorgente chiuso in embeddings pubblici |Strutturalmente impossibile —`CSS/` hors scope RAG |=== L'unico costo: uno`git mv`globale sui 17 depositi OSS + un refactoring del `build.gradle.kts` de `engine`. È una migrazione a freddo — nessun dato in volo, nessun utente interessato == Conclusione: il Segnale Fisico batte il Segnale Logico Ciò che ho fatto questo pomeriggio è stato sostituire una convenzione invisibile da una separazione visibile nella zona`foundry/`. Prima, dovevi *sapere* che`edster/`era closed source. Ora, tu lo *vedi* — la cartella si chiama`CSS/`. È lo stesso principio delle autorizzazioni Unix, delle VLAN di rete, o le compartimenti tagliafuoco in un database. La sicurezza non deve essere un'informazione che devi ricordare. Deve essere una proprietà **fisica**del sistema. La granularizzazione OSS/CSS è la traduzione di questo principio nel settore della governance LLM. Il LLM non ha bisogno di sapere che Edster è confidenziale. Ha bisogno di essere incapace di indicizzarlo. E questo è esattamente quello che`CSS/`garantisce. == Riferimenti * xref:0118_matrice_gouvernance_llm_zone_acces_workspace_post.adoc[Articolo 0117 — La matrice di governance LLM] * xref:0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.adoc[Articolo 0114 — I Cerchi di Fiducia] * xref:0116_compartimentage_epistemique_automatise_llm_post.adoc[Articolo 0116 — Il Compartimentaggio Epistemico Automatizzato] * xref:0108_gouvernance_agent_opencode_eager_lazy_post.adoc[Articolo 0108 — Gestire un agente IA con AsciiDoc]</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html Sat, 2 May 2026 00:00:00 +0000 blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_problema_pensare_liberamente_senza_pubblicare_qualsiasi_cosa">Il problema: Pensare liberamente senza pubblicare qualsiasi cosa</a></li> <li><a href="#_il_pattern_stimulus_nascere_fissare_diluire_morire">Il pattern STIMULUS — nascere, fissare, diluire, morire</a></li> <li><a href="#_la_delega_al_llm_perché_è_il_llm_che_filtra">La delega al LLM: Perché è il LLM che filtra</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 10 minutes</div> <p>Il mio LLM non si limita a eseguire le mie attività Gradle. È il guardiano della frontiera tra il mio pensiero privato e la mia espressione pubblica. Ogni idea viene classificata — Visione, Opinione, Strategia — prima di essere instradata. Ecco come questo compartimentamento epistemico automatizzato protegge il mio giardino mentale senza farmi tacere.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_pensare_liberamente_senza_pubblicare_qualsiasi_cosa">Il problema: Pensare liberamente senza pubblicare qualsiasi cosa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando uno sviluppatore solitario documenta il suo processo di pensiero con un LLM, si imbatte in un paradosso:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CAPTURE TOUT (Cercle 0, jardin secret) ├→ Brain dump libre, pas de censure ├→ Idées brutes, spéculations, intuitions non vérifiées ├→ Allers-retours LLM : challenger, itérer, raffiner └→ Le LLM voit TOUT — le bon, le flou, l'embryonnaire PUBLICATION SÉLECTIVE (Cercle 4, blog public) ├→ Uniquement les décisions actées ├→ Uniquement les patterns testés (>100 tests PASS) ├→ Uniquement ce qui a de la valeur pour le lecteur └→ JAMAIS une spéculation présentée comme une vérité</code></pre> </div> </div> <div class="paragraph"> <p>Tra questi due estremi, c’è un<strong>filtro</strong>. La domanda è: chi lo fa? Un essere umano stanco alla fine della sessione? Uno script di regex ingenuo? O il LLM stesso, che ha già letto tutto?</p> </div> <div class="paragraph"> <p>La mia risposta: il LLM.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_pattern_stimulus_nascere_fissare_diluire_morire">Il pattern STIMULUS — nascere, fissare, diluire, morire</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo STIMULUS è un file`.adoc`temporanea alla radice del workspace (Cerchio 0). Il suo nome segue una convenzione evocativa —<code>PICTURE_ME_ROLLIN.adoc</code>, <code>HOLD_MY_BEER.adoc</code>, <code>ONCE_UPON_A_TIME.adoc</code>— che cattura l’intenzione esplorativa del momento.</p> </div> <div class="paragraph"> <p>Il suo ciclo di vita è impietoso:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CRÉATION (Cercle 0) ├→ Fichier vide, brain dump libre ├→ Allers-retours LLM ← → développeur └→ Aucune pression de structure ou de publication MATURATION ├→ Le contenu se densifie ├→ Des sections émergent naturellement └→ Le fichier devient une référence informelle de session CLASSIFICATION ÉPISTÉMIQUE ← FAIT PAR LE LLM ├→ VISION → publiable, diluer dans les docs publics + blog ├→ OPINION → confiner au Cercle 0, pas de dilution externe └→ STRATÉGIE → dilution restreinte (docs racine, PAS de blog) DILUTION (Cascade vers Cercles légitimes) ├→ VISION → WORKSPACE_AS_PRODUCT.adoc + WHAT_THE_GAMES.adoc + blog ├→ STRATÉGIE → WORKSPACE_AS_PRODUCT.adoc (section business) └→ OPINION → reste dans le stimulus, ne bouge pas ARCHIVAGE + SUPPRESSION ├→ Snapshot dans configuration/vision-archive/ (trace historique) └→ rm du stimulus — il a fini son travail</code></pre> </div> </div> <div class="paragraph"> <p>Uno stimolo che sopravvive più di 2 sessioni senza diluizione è un anti-pattern. O l’informazione è troppo importante per marcire in un file temporaneo (→ diluire), o è troppo vaga per meritare di esistere (→ eliminare).</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_delega_al_llm_perché_è_il_llm_che_filtra">La delega al LLM: Perché è il LLM che filtra</h2> <div class="sectionbody"> <div class="paragraph"> <p>Non hardcode la classificazione Vision/Opinion in Kotlin. L’inietto nel<strong>prompt sistema</strong>del LLM via`AGENT_GOVERNANCE.adoc`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Pour chaque dilution de stimulus ou session, tu es responsable de classifier le contenu : - VISION : décision architecturale actée, pattern testé en production (>100 tests PASS), décision documentée dans BACKLOG ou ROADMAP - OPINION : spéculation, hypothèse non validée par des tests, intuition sans ancrage expérimental - STRATEGIE : positionnement business, pricing, marché cible Règles : - Si OPINION, le contenu reste confiné dans son cercle d'origine - Si VISION, tu procèdes à la dilution dans les documents racine - Si STRATEGIE, dilution restreinte (docs racine, pas de blog public) - Cette classification détermine aussi si un article de blog est publiable sur cheroliv.com ---- Il LLM legge questa direttiva**prima**trattare la sessione. È nel suo contesto immediato, non in un file separato. È *prompt engineering deterministico*: il comportamento emerge dal testo iniettato, non da un classificatore esterno. === Perché funziona — e perché è controintuitivo La reazione standard : « Affidi la classificazione all'IA? E se sbaglia? Risposta : l'essere umano non fa meglio alle 2 del mattino. La differenza, è che il LLM, invece, legge TUTTO. Ha il contesto completo della sessione e dei documenti target. Sa che`VPS ECO-16 12€ HT`è una decisione infrastrutturale (VISION) mentre`« le TTS ElevenLabs sonne plus naturel que Coqui »`è un'opinione non verificata da un benchmark. L'uomo, alla fine della sessione, legge in diagonale e fa del suo meglio. Il LLM legge esaustivamente e applica una griglia sistematica. Il risultato è**più affidabile**, non meno. E per il 20% dei casi ambigui — la zona grigia dove anche il LLM esita — la risposta non è « aggiungere del codice ». La risposta è**LangGraph4j**(EPIC 13) : un grafo di stato che, per i casi ambigui, attiva un nodo Human-in-the-Loop e torna all'uomo per la decisione. Ma per l'80% dei casi chiari, il LLM basta. == Il tubo completo: dal brain dump al blog post Ecco il flusso completo — dall'idea grezza all'articolo pubblicato — con il LLM come unico filtro : [source] ---- CERCLE 0 (jardin secret) PICTURE_ME_ROLLIN.adoc ← brain dump, allers-retours LLM ↓ [LLM classifie] → VISION / OPINION / STRATÉGIE ↓ VISION → dilution dans WORKSPACE_AS_PRODUCT.adoc → dilution dans WHAT_THE_GAMES_BEEN_MISSING.adoc → dilution dans WORKSPACE_VISION.adoc (session context) → RÉDACTION ARTICLE BLOG ← le LLM écrit, pas le dev ↓ CERCLE 4 (blog public) 0116_compartimentage_epistemique.adoc ← publié sur cheroliv.com ↓ ./gradlew deploy (bakery-gradle → JBake → JGit → GitHub Pages) ↓ https://cheroliv.com/blog/2026/0116/ ← live ---- Lo sviluppatore non scrive l'articolo. Lo sfida, rilegge, approva. Il LLM scrive. Il ciclo è : 1. Brain dump libero → senza censura 2. Classificazione epistemica del LLM → nessuna fuga 3. Scrittura da parte del LLM → nessuna procrastinazione 4. Rilettura umana → nessun errore Il collo di bottiglia storico — « non ho tempo per scrivere » — è eliminato. Il LLM fa il grosso del lavoro. L'umano fa ciò che solo l'umano può fare: giudicare. == I Tre Documenti Radice — Come l'Informazione Trova Il Suo Posto Ogni documento target ha un ruolo preciso nella cascata di diluizione: [cols="1,3,2"] |=== |Documento |Ciò che riceve |Tipo di contenuto |`WORKSPACE_AS_PRODUCT.adoc` |Decisioni architettoniche, stack tecnico, roadmap, modello di business |VISIONE + STRATEGIA |`WHAT_THE_GAMES_BEEN_MISSING.adoc` |Patterns, lezioni, anti-patterns, ontologia, regole formali |VISION (pattern testati) |`WORKSPACE_VISION.adoc` |Contesto della sessione, storico delle decisioni, punti dell'infrastruttura |VISIONE + STRATEGIA (contesto) |`AGENT_GOVERNANCE.adoc` |Regole di governance, portafoglio progetti, procedure |VISION (governance) |**Blog cheroliv.com** |Articoli pubblici, valore per il lettore esterno |solo visione |=== Un medesimo stimolo può nutrire i 4 documenti + il blog — ogni destinazione riceve la parte che la riguarda, senza ridondanza, senza contraddizione. È ciò che è successo per`PICTURE_ME_ROLLIN.adoc`(3 maggio 2026) : | Informazione | Classificazione | Destinazioni | | Elenco dei 13+ progetti foundry/ | VISION | WORKSPACE_AS_PRODUCT | | VPS-2 OVH, edster.cloud, 8,49€/mese | VISION | WORKSPACE_AS_PRODUCT + WORKSPACE_VISION | Il mercato africano è pronto per il mobile money | « DeepSeek > Kimi > GLM per contesto lungo » | OPINION → VISION | Confinato poi promosso dopo benchmark (articolo 0112) | | Impiegato Sintetico come prodotto finale | STRATEGIA | WORKSPACE_AS_PRODUCT (senza blog) | == Il pattern Baby-Step + TestContainer + Doc Vivante — il codice che si testa da solo Il pattern STIMULUS/Dilution gestisce il pensiero. Il suo equivalente per il codice è il pattern Baby-Step/TestContainer/Doc Vivante, validato da plantuml-gradle (380/380 test PASS, 137 sessioni senza perdite Docker): [cols="1,3"] |=== |principio |Regola |**passo da bambino** |Mai più di 3 punti per US. Se una US fa paura, ritagliare. Una US di 1 punto che passa > una US di 8 punti che si trascina. |**TestContainer prima** |Prima del codice di business, il contenitore. Il test d'infra passa → ambiente stabile garantito. |**Dataset impegnato** |Sottoinsieme minimo ma rappresentativo in`src/test/resources/`, senza PII. Clonabile, lanciabile. |**Documentazione vivente** |Ogni test Cucumber = una frase in linguaggio naturale. Il codice sorgente È la specifica eseguibile. Zero documentazione Markdown da mantenere. |**Cleanup automatico** |Zero perdita di risorse. Contenitori orfani,`/tmp/gradle-test-*`: tutto è pulito. |=== Questo pattern è la ragione per cui plantuml-gradle non ha mai avuto una regressione Docker in 138 sessioni. Garantisce che il codice che comunica con un'infrastruttura esterna (PostgreSQL, Redis, Kafka) sia sempre testato in un ambiente identico alla produzione — versionato, riproducibile, avviabile con un unico comando. == Conclusion : la libertà di pensare senza la paura di pubblicare Il compartimentamento epistemico automatizzato non è uno strumento di censura. È un**liberatore**. Consente di pensare liberamente, di speculare senza filtro, di brain-dumpare tutto ciò che passa per la testa — senza mai temere che un'idea embrionale finisca sul blog. Il LLM è il guardiano di questa frontiera. Legge tutto. Classifica. Diluisce ciò che merita di sopravvivere. Confina ciò che deve rimanere privato. Scrive ciò che è pubblicabile. E lo sviluppatore, lui, mantiene l'ultima parola: rileggere, sfidare, validare. Giudicare. È la divisione del lavoro che mancava allo sviluppatore solista: un impiegato sintetico che gestisce la burocrazia mentale, così che l'umano possa concentrarsi su ciò che sa fare meglio — concepire, progettare, decidere. == Riferimenti * Articolo sulla governance dell'agente Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governare un agente IA con AsciiDoc] * Articolo sull'ontologia spaziale e sui cerchi di fiducia :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[L'Ontologia Spaziale come Meccanismo d'Allineamento] * Articolo sull'Anonymiseur MVP0 :link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[Il nostro primo assunto: l'anonimizzatore di dataset] * Articolo sul confronto dei LLM a lungo contesto :link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] * Articolo sul meccanismo di backup dell'agente:link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Finestra scorrevole e onda fredda] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_problema_che_fa_fuggire_tutti">Il problema che fa fuggire tutti</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 12 minutes</div> <p>Non assumo un LLM. Assumo un anonymizzatore. Prima di fare RAG pgvector, prima di fare il fine-tuning degli esperti CDA/FPA, prima di effettuare il provisioning di workspaces per i clienti — qualcuno deve pulire i bagni dei dati. Questo dipendente è l’esperto di anonimizzazione (MVP0, EPIC 2 di codebase-gradle). Ed è lui che rende il prodotto commerciabile.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_che_fa_fuggire_tutti">Il problema che fa fuggire tutti</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ogni startup IA che manipola dati di addestramento si scontra con lo stesso muro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- Risultato: o fai RAG su dati sporchi (allucinazioni di PII, non conformità al GDPR, rischio legale), o non fai nulla (nessun prodotto). La terza via — pulire manualmente — non è scalabile. Mia risposta: non aggirare il problema. L'**automatizzare**. == MVP0 : l'Anonymiseur, primo assunto nel periodo di prova Il MVP0 non è una funzionalità. È un**esperto di comodità**— un dipendente che svolge il lavoro sporco, stupido e cattivo, e di cui nessuno vuole parlare nei pitch deck. Cosa fa: [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- Rileva prima i modelli più evidenti (email`.*@.*`, tokens`sk-*`, `ghp_*`, IPs), poi impara. Il periodo di prova è questo: validiamo che non lasci passare falsi negativi prima di titolarizzarlo. == Cosa sblocca questo MVP (e non è solo la conformità) L'anonimizzazione come MVP0 non è il pedaggio RGPD prima dell'autostrada. È l'autostrada stessa. Ecco cosa apre : === Presente : Realtà Aumentata in Prompt [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- Il RAG non cerca nei dati sporchi — cerca in uno spazio**corretto per costruzione**Questo cambia tutto per la qualità delle risposte: il LLM non passa il suo tempo a evitare dei PII che riconosce ma che non deve menzionare. === Futuro: Fine‑tuning sui dati sani [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- Il fine-tuning sui dati grezzi è una potenziale catastrofe giuridica. Con i dati puliti, è una**metodo riproducibile**. Ogni cliente accumula i suoi dataset puliti, ogni cliente può effettuare il fine‑tuning dei suoi esperti di settore sui propri dati — senza mai esporre un dato personale. == Perché è commerciale Non è « uno strumento di conformità GDPR ». È una**metodo riproducibile che trasforma un problema universale in attivo** : 1. *Ogni azienda di formazione ha dati sporchi* — è il problema 2. *Nessuna ha un pipeline automatizzato di pulizia multi-sorgente* — è il mercato 3. *Il ciclo: anonimizzazione → RAG → fine-tuning è proprietario* — è la barriera Il SaaS Edster (MVP3) non venderà « un workspace Gradle ». Venderà questo ciclo chiuso. E il MVP0 è la porta d'ingresso. == Il formato SQL come terza via di contesto L'importazione di dati strutturati non è solo un formato di scambio. Lo schema SQL (DDL) porta il**modello entità-relazione del dominio**</think> [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- Questo DDL, una volta anonimizzato (riga 4), diventa una fonte di contesto per il LLM. Non testo — di**modello mestiere**. Il RAG fornisce il contenuto (similarità vettoriale), Graphify fornisce le relazioni (struttura esatta), e lo schema SQL fornisce il**Domain-Driven Design implicito**: bounded contexts, aggregati, oggetti di valore. Il LLM comprende il settore perché legge il suo schema. == La roadmap: da MVP0 a SaaS [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- Ogni MVP dipende dal precedente. Nessuno può essere consegnato senza il MVP0. Questa è la ragione per cui l'Anonymiseur non è « P0 » nel backlog — è**MVP0**. È il primo deliverable commerciale, e tutto il resto è condizionato al suo successo. == Conclusione: il lavoro invisibile che rende tutto possibile In una startup classica, la pulizia dei dati è esternalizzata, manuale, o ignorata. In questa architettura, è il**cuore del prodotto**. L'anonimizzatore è il primo dipendente perché senza di lui, nulla funziona : * Senza MVP0 → nessun RAG legale (MVP1) * Senza MVP0 → nessun fine-tuning senza perdita di dati (EPIC 5) * Senza MVP0 → nessun SaaS credibile (MVP3) * Senza MVP0 → nessuna realtà aumentata nel prompt * Senza MVP0 → nessuna terza via di contesto (SQL DDD) Fa il lavoro sporco. Non sarà mai citato nei pitch. Ma è lui a far girare la fabbrica. E' per questo che lo assumono per primo. == Riferimenti * Articolo sull'ontologia spaziale e i cerchi di fiducia :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[L'Ontologia Spaziale come Meccanismo di Allineamento] * Articolo sulla governance dell'agente Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governare un Agente IA con AsciiDoc] * Articolo sul meccanismo Hot/Warm/Cold :link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window e Onda Fredda] * Articolo sulla comparazione dei tre LLMs:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/pilot-batch/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/pilot-batch/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_problema_che_fa_fuggire_tutto_il_mondo">Il problema che fa fuggire tutto il mondo</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 12 minutes</div> <p>Non assumo un LLM. Assumo un anonymizzatore. Prima di fare RAG pgvector, prima di fare il fine‑tuning di esperti CDA/FPA, prima di provisionare gli workspace dei clienti — qualcuno deve pulire i cessi dei dati. Questo dipendente è l’esperto di anonimizzazione (MVP0, EPIC 2 di codebase-gradle). Ed è lui che rende il prodotto commerciabile.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">indice</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_che_fa_fuggire_tutto_il_mondo">Il problema che fa fuggire tutto il mondo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ogni startup IA che manipola dati di addestramento sbatte contro lo stesso muro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- Risultato: o fai RAG su dati sporchi (allucinazioni di PII, non conformità al GDPR, rischio giuridico), o non fai nulla (nessun prodotto). La terza via — pulire a mano — non è scalabile. La mia risposta: non aggirare il problema. L'**automatizzare**. == MVP0 : L'Anonimizzatore, Primo assunto durante il periodo di prova Il MVP0 non è una feature. È un**esperto di comodità**— un impiegato che fa il lavoro sporco, stupido e cattivo, e di cui nessuno vuole parlare nei pitch deck. Cosa fa: [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- Rileva i pattern più evidenti prima (email`.*@.*`, token`sk-*`, `ghp_*`, IPs), poi impara. Il periodo di prova è questo: verifichiamo che non lasci passare falsi negativi prima di confermarlo. == Cosa sblocca questo MVP (e non è solo la Conformità) L'anonimizzazione come MVP0 non è il pedaggio RGPD prima dell'autostrada. È l'autostrada stessa. Ecco cosa apre: === Presente : Realtà aumentata in Prompt [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- Il RAG non cerca in dati sporchi — cerca in uno spazio**pulito per costruzione**. Cambia tutto per la qualità delle risposte: il LLM non spreca tempo a eludere le PII che riconosce ma che non deve menzionare. === Futuro: Affinamento su dati sani [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- Il fine-tuning sui dati grezzi è una potenziale catastrofe giuridica. Su dati puliti, è una**metodo riproducibile**. Ogni cliente accumula i suoi dataset puliti, ogni cliente può fine-tunare i suoi esperti di settore sui suoi dati — senza mai esporre un dato personale. == Perché è commercializzabile Non è « uno strumento di conformità GDPR ». È una**metodo riproducibile che trasforma un problema universale in un asset**: 1. *Ogni impresa di formazione ha dati sporchi* — questo è il problema 2. *Nessuna ha una pipeline di pulizia automatizzata multi-sorgente* — è il mercato 3. *Il ciclo : anonimizzazione → RAG → fine-tuning è proprietario* — è la barriera Il SaaS Edster (MVP3) non venderà « un workspace Gradle ». Venderà questo ciclo chiuso. E l'MVP0 è la porta d'ingresso. == Il formato SQL come terza via di contesto L'importazione di dati strutturati non è solo un formato di scambio. Lo schema SQL (DDL) porta il**modello entità-relazione del dominio**(no output) [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- Questo DDL, una volta anonimizzato (riga 4), diventa una fonte di contesto per il LLM. Non è testo — di**modello di business**. Il RAG fornisce il contenuto (similarità vettoriale), Graphify fornisce le relazioni (struttura esatta), e lo schema SQL fornisce il**Domain-Driven Design implicito**: bounded contexts, aggregati, oggetti di valore. Il LLM comprende il settore perché legge il suo schema. == La Roadmap : dal MVP0 al SaaS [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- Ogni MVP dipende dal precedente. Nessuno può essere consegnato senza l'MVP0. Questa è la ragione per cui l'Anonymiseur non è « P0 » nel backlog — è**MVP0**### JBake CLI Commands ---- # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ``` 1. È il primo deliverable commerciale, e il resto dipende dalla sua riuscita. == Conclusione: il lavoro invisibile che rende tutto possibile In una startup tradizionale, la pulizia dei dati è esternalizzata, manuale o ignorata. In questa architettura, è il**cuore del prodotto**. L'Anonymiseur è il primo dipendente perché senza di lui, niente funziona : * Senza MVP0 → nessun RAG legale (MVP1) * Senza MVP0 → nessun fine-tuning senza perdita di dati (EPIC 5) * Senza MVP0 → nessun SaaS credibile (MVP3) * Senza MVP0 → nessuna realtà aumentata nel prompt * Senza MVP0 → nessuna terza via di contesto (SQL DDD) Fa il lavoro sporco. Non sarà mai citato nei pitch. Ma è lui che fa girare la fabbrica. E' per questo che lo assumiamo per primo. == Riferimenti * Articolo sull'ontologia spaziale e i cerchi di fiducia :link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[L'Ontologia Spaziale come Meccanismo di Allineamento] * Articolo sulla governance dell'agent Eager/Lazy :link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governare un agente IA con AsciiDoc] * Articolo sul meccanismo Hot/Warm/Cold :link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Finestra scorrevole e onda fredda] * Articolo sul confronto dei tre LLM:link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1]</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0113_integration_firebase_contact_form_post.html Wed, 29 Apr 2026 00:00:00 +0000 blog/2026/0113_integration_firebase_contact_form_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scena_un_modulo_che_non_memorizza_nulla">La scena: un modulo che non memorizza nulla</a> <ul class="sectlevel2"> <li><a href="#_leredità_supabase">L’eredità Supabase</a></li> <li><a href="#_la_doppia_sottomissione_fantasma">La doppia sottomissione fantasma</a></li> </ul> </li> <li><a href="#_perché_firebase_anziché_supabase">Perché Firebase anziché Supabase?</a></li> <li><a href="#_fase_1_crea_il_progetto_firebase">Fase 1: Crea il progetto Firebase</a> <ul class="sectlevel2"> <li><a href="#_inizializzazione">Inizializzazione</a></li> <li><a href="#_regole_di_sicurezza_firestore">Regole di sicurezza Firestore</a></li> </ul> </li> <li><a href="#_fase_2_riscrivere_il_javascript_di_invio">Fase 2 : Riscrivere il JavaScript di invio</a> <ul class="sectlevel2"> <li><a href="#_la_dipendenza_window_firebase">La dipendenza `window.<em>FIREBASE</em></a></li> <li><a href="#_il_nuovo_contact_js">Il nuovo `contact.js</a></li> </ul> </li> <li><a href="#_fase_3_pulire_il_codice_morto_supabase">Fase 3 : Pulire il codice morto Supabase</a></li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset_è_intatto_thememanager_scrolltotopbutton_mobilemenumanager_smoothscrollwithoffset_navbarheightupdater_dynamicnavbarbreakpoint_codeblockmanager_tooltipmanager_phoneinputmanager">Clear the output directory before baking jbake -b . output --reset <code>`</code> è intatto :`ThemeManager`, <code>ScrollToTopButton</code>, <code>MobileMenuManager</code>, <code>SmoothScrollWithOffset</code>, <code>NavbarHeightUpdater</code>, <code>DynamicNavbarBreakpoint</code>, <code>CodeBlockManager</code>, <code>TooltipManager</code>, <code>PhoneInputManager</code>.</a> <ul class="sectlevel1"> <li><a href="#_phase_4_configurer_il_piè_di_pagina">Phase 4 : Configurer il piè di pagina</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 12 minutes</div> <p>Per mesi, il modulo di contatto di questo sito ha girato su un mock JavaScript — una promessa di successo dell'85%, un falso Firestore, zero dati memorizzati. Il piano iniziale prevedeva un backend Supabase con Google Apps Script per le notifiche via email. Abbandonato. Oggi racconto la migrazione verso Firebase Firestore: creazione del progetto, regole di sicurezza, riscrittura del JS, pulizia del codice morto di Supabase. E perché questa scelta dice qualcosa di più ampio sulla filosofia di sviluppo.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_scena_un_modulo_che_non_memorizza_nulla">La scena: un modulo che non memorizza nulla</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questo sito è generato da JBake, il mio plugin Gradle`bakery`. È 100 % statico — nessun backend, nessun database. Tranne che ho un modulo di contatto. La pagina`contact.html`esiste, il HTML è pronto (campi nome, email, telefono, oggetto, messaggio, validazione HTML5, honeypot antispam), gli stili Bootstrap sono al loro posto. Visivamente, tutto è perfetto.</p> </div> <div class="paragraph"> <p>Tranne che al momento dell’invio, niente succede</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseMock = new Promise((resolve, reject) => { setTimeout(() => { if (Math.random() < 0.85) { resolve({ status: 201, message: 'Message stored in Firestore.' }); } else { reject({ status: 500, message: 'Firestore write failed.' }); } }, 1500); });</code></pre> </div> </div> <div class="paragraph"> <p>Un mock. Una promessa che fa finta. L’utente vede uno spinner, poi un messaggio « Messaggio inviato con successo! ». Ma i dati vanno nel vuoto. Nessun messaggio viene memorizzato da nessuna parte.</p> </div> <div class="paragraph"> <p>La situazione è peggiore di un modulo rotto — è un modulo che mente.</p> </div> <div class="sect2"> <h3 id="_leredità_supabase">L’eredità Supabase</h3> <div class="paragraph"> <p>Il piano iniziale, documentato in`content/draft/integration_formulaire_contact_supabase.adoc`, prevedeva:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Un database Supabase con una tabella`contacts` et Row Level Security</p> </li> <li> <p>Un RPC`handle_contact_form`lato server</p> </li> <li> <p>Un trigger SQL che chiama un webhook Google Apps Script</p> </li> <li> <p>Google Apps Script che invia una mail Gmail di notifica</p> </li> </ol> </div> <div class="paragraph"> <p>Il codice JavaScript corrispondente esiste ancora in`script.js`. C’è una classe`SupabaseManager`che inizializza un client Supabase con variabili globali`SUPABASE_URL` et <code>SUPABASE_KEY</code>, e una classe`ContactFormHandler`che ascolta l’evento submit del modulo e chiama`SupabaseManager.submitContactForm()`.</p> </div> <div class="paragraph"> <p>Problema: queste variabili globali non vengono più iniettate nel piè di pagina. Il`<script src="supabase-js">`È stato rimosso. Il codice chiama`supabase.createClient()`su una variabile`supabase`che non esiste più. Quindi:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">console.error : 'Supabase client library (supabase-js) is not loaded.'</code></pre> </div> </div> <div class="paragraph"> <p>Non solo i dati non vengono memorizzati, ma il codice di invio è morto.</p> </div> </div> <div class="sect2"> <h3 id="_la_doppia_sottomissione_fantasma">La doppia sottomissione fantasma</h3> <div class="paragraph"> <p>Per peggiorare le cose, c’è una<strong>concorrenza silenziosa</strong>tra due handlers sullo stesso modulo :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>`contact.js`ascolta il submit, chiama il mock Firebase</p> </li> <li> <p><code>script.js</code>— via`ContactFormHandler`— ascolta anche il submit, chiama`SupabaseManager`</p> </li> </ol> </div> <div class="paragraph"> <p>Entrambi fanno`event.preventDefault() + event.stopPropagation()<code>. Come`contact.js`è caricato per primo in`footer.thyme</code>, il suo handler è collegato per primo. Blocca la propagazione.`ContactFormHandler`non verrà mai attivato.</p> </div> <div class="paragraph"> <p>Non è nemmeno un bug attivo — è un zombie. Codice che non ha mai l’occasione di eseguirsi.</p> </div> <div id="diag-before" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE title Stato Iniziale — Modulo di Contatto rectangle "contatto.timo (HTML Bootstrap, trappola per api)" as FORM ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Stato Iniziale — Modulo di Contatto rectangle "contatto.timo (HTML Bootstrap, trappola per api)" as FORM rectangle "footer.thyme (Firebase SDK con placeholder di configurazione)" as FOOT rectangle "contact.js (mock Firebase, 85% successo)" as CONT rectangle "script.js\n(SupabaseManager + ContactFormHandler, morti)" as SCRIPT rectangle "Utente" as USER USER -> FORM : Soumission du formulaire FORM -> CONT : submit event (attaché en premier) CONT -> CONT : preventDefault + stopPropagation CONT -> CONT : mock Promise (1.5s, aléatoire) note right of CONT ⚠️ Aucune donnée stockée end note FORM ..> SCRIPT : submit event (bloqué par stopPropagation) note right of SCRIPT : ❌ Jamais déclenché note right of SCRIPT : ❌ supabase-js non chargé @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_firebase_anziché_supabase">Perché Firebase anziché Supabase?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La decisione di migrazione è documentata nella`AGENT.adoc`(No output)</p> </div> <div class="paragraph"> <p>Firebase è ora scelto per i seguenti motivi: piano gratuito migliore, Firestore nativo, Cloud Functions integrate, ecosistema Google più adatto. L’implementazione Supabase esistente è contrassegnata da « ⚠️ Abbandonato ».</p> </div> <div class="paragraph"> <p>Oltre il piano gratuito, c’è una ragione architettonica. Questo sito vive nell’ecosistema Google: il repository di destinazione è`cheroliv.github.io`, il CNAME punta su GitHub Pages, il build Gradle effettua il push su GitHub tramite JGit. Aggiungere un servizio Google (Firebase) anziché un servizio di terze parti (Supabase) riduce la superficie di dispersione.</p> </div> <div class="paragraph"> <p>Firestore in modalità nativa (non in modalità Datastore) è anche più vicino al modello mentale di documento NoSQL che ho in testa: raccolte, documenti, campi tipizzati, timestamp lato server, regole di sicurezza integrate.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fase_1_crea_il_progetto_firebase">Fase 1: Crea il progetto Firebase</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_inizializzazione">Inizializzazione</h3> <div class="paragraph"> <p>La CLI Firebase non essendo installata sul mio computer, passo tramite la console web :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Andare suhttps://console.firebase.google.com/[Console Firebase]</p> </li> <li> <p>Creare un progetto`cheroliv-contact`(o riutilizzare un progetto esistente)</p> </li> <li> <p>Attivare Firestore in modalità nativa (non Datastore)</p> </li> <li> <p>Creare un database nella regione`eur3`(Europa)</p> </li> </ol> </div> <div class="paragraph"> <p>Per un uso minimale come il nostro (una sola collezione, scrittura pubblica), il modo nativo è la scelta giusta. Non è necessario avere regole Datastore complesse.</p> </div> </div> <div class="sect2"> <h3 id="_regole_di_sicurezza_firestore">Regole di sicurezza Firestore</h3> <div class="paragraph"> <p>Il modulo è pubblico — chiunque può inviare un messaggio. Ma voglio limitare gli abusi :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /contact_messages/{messageId} { // Lecture : admin uniquement (authentifié) allow read: if request.auth != null; // Écriture : publique, mais limitée allow create: if request.auth == null && request.resource.data.name is string && request.resource.data.name.size() >= 1 && request.resource.data.name.size() <= 100 && request.resource.data.email is string && request.resource.data.email.matches('.*@.*\\..*') && request.resource.data.email.size() <= 254 && request.resource.data.subject is string && request.resource.data.subject.size() >= 3 && request.resource.data.subject.size() <= 200 && request.resource.data.message is string && request.resource.data.message.size() >= 10 && request.resource.data.message.size() <= 5000 && request.resource.data.created_at == request.time && request.resource.data.user_agent is string && request.resource.data.user_agent.size() <= 500; } } }</code></pre> </div> </div> <div class="paragraph"> <p>Punti chiave :</p> </div> <div class="ulist"> <ul> <li> <p><code>allow read</code>— solo gli utenti autenticati possono leggere i messaggi (io, tramite la console Firebase)</p> </li> <li> <p><code>allow create</code>— Chiunque può creare un documento, ma con la validazione dei campi</p> </li> <li> <p>Validazione lato server : dimensioni min/max, formato email,<code>created_at`deve corrispondere a`request.time</code>(anti-falsificazione)</p> </li> <li> <p>`user_agent`viene inviato per la tracciabilità (non critico ma utile)</p> </li> </ul> </div> <div class="paragraph"> <p>Queste regole sono più rigorose di un semplice`allow write: if true;`. Impediscono a un attaccante di iniettare payload enormi o campi malformati.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_2_riscrivere_il_javascript_di_invio">Fase 2 : Riscrivere il JavaScript di invio</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il contratto è semplice:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Leggere i dati del modulo</p> </li> <li> <p>Verificare l’honeypot (campo`hp_name`— se è pieno, è un bot, simuliamo un successo senza inviare nulla)</p> </li> <li> <p>chiamare`addDoc(window.<em>FIREBASE</em>.collection(db, "contact_messages"), {…​})`</p> </li> <li> <p>Mostra successo o errore</p> </li> </ol> </div> <div class="sect2"> <h3 id="_la_dipendenza_window_firebase">La dipendenza `window.<em>FIREBASE</em></h3> <div class="paragraph"> <p>in`footer.thyme`, uno script modulo inizializza l’SDK Firebase e espone un oggetto globale :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><script type="module"> import { initializeApp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-app.js"; import { getFirestore, collection, addDoc, serverTimestamp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-firestore.js"; const firebaseConfig = { /* valeurs réelles */ }; const app = initializeApp(firebaseConfig); const db = getFirestore(app); window.__FIREBASE__ = { db, collection, addDoc, serverTimestamp }; </script></code></pre> </div> </div> <div class="paragraph"> <p>Gli script di modulo vengono eseguiti prima`DOMContentLoaded`, quindi`window.<em>FIREBASE</em>`è garantito disponibile quando il handler`contact.js`si attiva. Per precauzione, aggiungo comunque un polling di 5 secondi nel caso in cui il CDN fosse lento.</p> </div> </div> <div class="sect2"> <h3 id="_il_nuovo_contact_js">Il nuovo `contact.js</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function () { 'use strict'; const form = document.getElementById('contact-form'); if (!form) return; const submitButton = form.querySelector('button[type="submit"]'); const successMessage = document.getElementById('contact-success-message'); const errorMessage = document.getElementById('contact-error-message'); // Éléments de validation const nameInput = form.querySelector('input[name="name"]'); const emailInput = form.querySelector('input[name="email"]'); const phoneInput = form.querySelector('input[name="phone"]'); const subjectInput = form.querySelector('input[name="subject"]'); const messageInput = form.querySelector('textarea[name="message"]'); const honeypotInput = form.querySelector('input[name="hp_name"]'); /** * Attend que window.__FIREBASE__ soit disponible. * Timeout de 5 secondes — si le CDN Firebase est lent, on abandonne. */ function waitForFirebase(timeoutMs = 5000) { return new Promise((resolve, reject) => { if (window.__FIREBASE__) { resolve(window.__FIREBASE__); return; } const start = Date.now(); const interval = setInterval(() => { if (window.__FIREBASE__) { clearInterval(interval); resolve(window.__FIREBASE__); } else if (Date.now() - start > timeoutMs) { clearInterval(interval); reject(new Error('Firebase SDK non disponible après timeout')); } }, 100); }); } // --- Validation (identique à l'existant) --- function validateForm() { nameInput.setCustomValidity(''); emailInput.setCustomValidity(''); if (phoneInput) phoneInput.setCustomValidity(''); subjectInput.setCustomValidity(''); messageInput.setCustomValidity(''); if (nameInput.value.trim().length < 1) { nameInput.setCustomValidity('Veuillez saisir votre nom.'); } const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailPattern.test(emailInput.value.trim())) { emailInput.setCustomValidity('Veuillez saisir une adresse email valide.'); } if (phoneInput && phoneInput.value.trim() !== '') { const phonePattern = /^\d{10,15}$/; if (!phonePattern.test(phoneInput.value.trim())) { phoneInput.setCustomValidity('Veuillez saisir un numéro valide (10 à 15 chiffres).'); } } if (subjectInput.value.trim().length < 3) { subjectInput.setCustomValidity('Veuillez saisir un sujet (3 caractères minimum).'); } if (messageInput.value.trim().length < 10) { messageInput.setCustomValidity('Veuillez saisir un message (10 caractères minimum).'); } form.classList.add('was-validated'); return form.checkValidity(); } // --- Handler de soumission --- form.addEventListener('submit', async function (event) { event.preventDefault(); event.stopPropagation(); if (!validateForm()) return; // Honeypot : si rempli, simuler un succès sans rien envoyer if (honeypotInput && honeypotInput.value.trim() !== '') { successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); return; } // UI : état d'envoi submitButton.disabled = true; submitButton.innerHTML = ` <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span> Envoi en cours... `; successMessage.style.display = 'none'; errorMessage.style.display = 'none'; try { const fb = await waitForFirebase(); const messagesCollection = fb.collection(fb.db, 'contact_messages'); await fb.addDoc(messagesCollection, { name: nameInput.value.trim(), email: emailInput.value.trim(), phone: phoneInput ? phoneInput.value.trim() : '', subject: subjectInput.value.trim(), message: messageInput.value.trim(), created_at: fb.serverTimestamp(), user_agent: navigator.userAgent.substring(0, 500) }); successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); } catch (error) { console.error('Erreur Firestore:', error); errorMessage.style.display = 'block'; } finally { submitButton.disabled = false; submitButton.innerHTML = ` <i class="bi bi-send me-2"></i> Envoyer le Message `; } }, false); });</code></pre> </div> </div> <div class="paragraph"> <p>Le modifiche rispetto al mock :</p> </div> <div class="ulist"> <ul> <li> <p><code>waitForFirebase()</code> — polling avec timeout, robuste même si le CDN est lent</p> </li> <li> <p><code>honeypot</code>— se il campo nascosto`hp_name`è pieno, simulare un successo senza appello Firestore. Il bot crede di aver avuto successo ma nulla viene memorizzato</p> </li> <li> <p><code>addDoc(collection, {…​})</code>— vera chiamata Firestore con`serverTimestamp()` et <code>user_agent</code></p> </li> <li> <p>Gestione dell’errore con`try/catch`asincrono</p> </li> <li> <p>Pulizia del`finally`(ripristino del pulsante)</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Perché`user_agent`È opzionale, ma utile per la diagnostica. Se arriva un messaggio strano, sapere se proviene da un browser desktop, mobile o da uno script curl aiuta nel triage.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_3_pulire_il_codice_morto_supabase">Fase 3 : Pulire il codice morto Supabase</h2> <div class="sectionbody"> <div class="paragraph"> <p>`script.js`contiene 250 linee di dead code :</p> </div> <div class="ulist"> <ul> <li> <p><code>SupabaseManager</code>(righe 417-481) — 65 righe</p> </li> <li> <p><code>ContactFormHandler</code>(righe 490-551) — 62 righe</p> </li> <li> <p>Blocco di inizializzazione (righe 645-654) — 10 righe</p> </li> </ul> </div> <div class="paragraph"> <p>Totale: ~140 linee da eliminare.</p> </div> <div class="paragraph"> <p>Il blocco`DOMContentLoaded`crea un`SupabaseManager`poi un`ContactFormHandler`Allegato al modulo. Come spiegato sopra, questo codice non viene mai eseguito (bloccato da`contact.js`), e anche se venisse eseguito, fallirebbe (nessun SDK Supabase caricato).</p> </div> <div class="paragraph"> <p>Elimino:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>La classe`SupabaseManager`</p> </li> <li> <p>La classe`ContactFormHandler`</p> </li> <li> <p>Il blocco di inizializzazione in`DOMContentLoaded`(righe 645-654)</p> </li> </ol> </div> <div class="paragraph"> <p>Le reste de <code>script.js</code><mark>#</mark> JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset_è_intatto_thememanager_scrolltotopbutton_mobilemenumanager_smoothscrollwithoffset_navbarheightupdater_dynamicnavbarbreakpoint_codeblockmanager_tooltipmanager_phoneinputmanager" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code> è intatto :`ThemeManager`, <code>ScrollToTopButton</code>, <code>MobileMenuManager</code>, <code>SmoothScrollWithOffset</code>, <code>NavbarHeightUpdater</code>, <code>DynamicNavbarBreakpoint</code>, <code>CodeBlockManager</code>, <code>TooltipManager</code>, <code>PhoneInputManager</code>.</h1> <div class="sect1"> <h2 id="_phase_4_configurer_il_piè_di_pagina">Phase 4 : Configurer il piè di pagina</h2> <div class="sectionbody"> <div class="paragraph"> <p>`footer.thyme`ha già il boilerplate Firebase ma con i valori placeholder. Io sostituisco :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseConfig = { apiKey: "REMPLACER_PAR_VOTRE_API_KEY", authDomain: "REMPLACER_PAR_VOTRE_AUTH_DOMAIN", projectId: "REMPLACER_PAR_VOTRE_PROJECT_ID", storageBucket: "REMPLACER_PAR_VOTRE_STORAGE_BUCKET", messagingSenderId: "REMPLACER_PAR_VOTRE_SENDER_ID", appId: "REMPLACER_PAR_VOTRE_APP_ID" };</code></pre> </div> </div> <div class="paragraph"> <p>Dai valori reali recuperati da<strong>Impostazioni del progetto > Generale > Le tue app > App web</strong>nella console Firebase</p> </div> <div class="paragraph"> <p>I valori sono sensibili`apiKey`è pubblica di default presso Firebase, ma preferisco non committarli in chiaro). Li salvo in`site.yml`(già in`.gitignore`) et le plugin `bakery`li iniettano nel template tramite una logica da aggiungere lato build</p> </div> <div class="paragraph"> <p>Per ora, li metto direttamente dentro`footer.thyme`<mark>#</mark> Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin JBake per Gradle o chiamando direttamente l’interfaccia a riga di comando di JBake:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") }`./gradlew serve`li caricherà localmente. Durante il deployment, migrerò l'iniezione verso`site.yml`o verso una variabile Gradle. [WARNING] ==== L'`apiKey`Firebase non è**passo paso**un segreto. È pubblica per progettazione. Ciò che protegge i tuoi dati, sono i**regole di sicurezza Firestore**, non la chiave API. Non metterla in un`.env`caricato lato server — è destinata a essere esposta al navigatore ==== == Fase 5 : Architettura finale [plantuml, format=svg, id=diag-after, alt="Architecture finale — Firebase Firestore"] ---- @startuml skinparam backgroundColor #FEFEFE title Architettura Finale — Modulo di Contatto Firebase actor Utilisateur as USER package "Navigatore" #E8F5E9 { rectangle "contact.thyme\n(HTML, honeypot)" as FORM rectangle "contact.js\n(validazione + Firestore)" as CONT rectangle "footer.thyme\n(Firebase SDK init)" as FOOT } cloud "Firebase" #BBDEFB { rectangle "Firestore\n(contact_messages)" as FS } FORM --> CONT : submit event CONT --> FOOT : window.__FIREBASE__.addDoc() FOOT --> FS : Insert document\n(règles de sécurité validées) note right of FS Firestore Rules : - create: public, validé - read: auth uniquement end note @enduml ---- == Cosa dice questa migrazione sul dogfooding Questo sito è generato dal mio plugin Gradle personale`bakery`. Il modulo di contatto si trova all'interno del sito. La migrazione Supabase → Firebase è documentata in`AGENT.adoc`, è discussa nel backlog, viene testata via`./gradlew serve`, e genera un articolo di blog (quello che stai leggendo). È puro dogfooding. Il sito è il prodotto del plugin, il plugin è il prodotto dello sviluppatore, lo sviluppatore documenta il processo nel sito stesso. Il cerchio è chiuso. Avere trascinato un mock per mesi (sessioni intere in cui il modulo mentiva silenziosamente) mi ha fatto realizzare qualcosa: il backlog di un sito statico personale non è mai « finito ». C'è sempre una US prioritaria, sempre un articolo in bozza, sempre una sezione commentata in un template. La disciplina non consiste nel finire tutto — consiste nel finire ciò che è visibile dall'utente. Un modulo di contatto rotto, è peggio di nessun modulo affatto. È una promessa non mantenuta. === Riepilogo delle modifiche |=== |File |modificazione |Impatto |`blog/2026/0113_*.adoc` |Creazione dell'articolo |Documentazione |`assets/js/contact.js` |Riscrittura (mock → Firestore reale) |Funzionale |`assets/js/script.js` |Rimozione SupabaseManager + ContactFormHandler + init bloc |Pulizia |`templates/footer.thyme` |Sostituzione segnaposto di configurazione → valori reali |Configuration |=== == Passi successivi (backlog) * **Email di notifica**: Una Cloud Function`onCreate`su`contact_messages`che invia una mail tramite SendGrid. Il modulo salva, ma non ricevo notifiche. Priorità media — i messaggi sono visibili nella console Firebase. * **Rate limiting côté client**Aggiungere un timestamp localStorage per impedire le invii multipli a raffica. Il honeypot blocca i bot ingenui, un rate limiter bloccherebbe i bot un po' più furbi. * **Test**Un test Playwright che invia il modulo e verifica che il documento appaia in Firestore. Per ora, lo testo manualmente via`./gradlew serve`. == Riferimenti * https://firebase.google.com/docs/firestore/security/get-started[Documentazione delle regole di sicurezza di Firestore] * https://firebase.google.com/docs/firestore/manage-data/add-data#add_a_document[Documentazione Firestore addDoc — Web v9 modulare] * link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Serie governance agent — Parte 1 : Eager/Lazy] * link:/blog/2026/0110_mecanisme_backup_contexte_agent_post.html[Serie governance agente — Parte 2 : Hot/Warm/Cold] * link:/blog/2026/0111_audit_contexte_agent_post.html[Serie governance agent — Parte 3 : Audit] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html Tue, 28 Apr 2026 00:00:00 +0000 blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_contesto_non_un_banco_di_prova_un_cantiere">Contesto: non un banco di prova, un cantiere</a></li> <li><a href="#_il_mio_ambiente_di_test">Il mio ambiente di test</a></li> <li><a href="#_la_griglia_di_valutazione">La Griglia di Valutazione</a></li> <li><a href="#_round_1_kimi_k2_6_il_falso_avvio">Round 1 : Kimi K2.6 — Il falso avvio</a> <ul class="sectlevel2"> <li><a href="#_session_9_la_ripresa">Session 9 : la ripresa</a></li> <li><a href="#_sessione_10_il_naufragio_silenzioso">Sessione 10: il naufragio silenzioso</a></li> </ul> </li> <li><a href="#_glm_5_1_il_combattente_onorevole">GLM-5.1 — Il Combattente Onorevole</a> <ul class="sectlevel2"> <li><a href="#_architettura_il_dsa_contro_il_mla_puro">Architettura: il DSA contro il MLA puro</a></li> <li><a href="#_sessioni_11_13_solido_ma_frustrante">Sessioni 11-13: solido ma frustrante</a></li> </ul> </li> <li><a href="#_round_3_deepseek_v4_pro_la_macchina_da_guerra">Round 3 : DeepSeek-V4-Pro — La Macchina da Guerra</a> <ul class="sectlevel2"> <li><a href="#_architettura_csa_hca_la_doppia_rete">Architettura: CSA + HCA, la doppia rete</a></li> <li><a href="#_sessioni_1_8_il_sollievo">Sessioni 1-8 : il sollievo</a></li> <li><a href="#_il_test_decisivo_refactoring_a_100k_token">Il test decisivo: refactoring a 100K token</a></li> </ul> </li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset_chegitconfig_resolvedtokenè_una_funzione_di_estensione_definita_inreadme_kt_e_chesnapshotmanager_pruned_dirsescludebuild_gradle_et_git">Clear the output directory before baking jbake -b . output --reset`"<strong>*</strong>"`, che`GitConfig.resolvedToken()<code>è una funzione di estensione definita in`readme.kt</code>, e che`SnapshotManager.PRUNED_DIRS`esclude`build`, <code>.gradle</code> et <code>.git</code>.</a> <ul class="sectlevel1"> <li><a href="#_il_faccia_a_faccia_metriche_comparative">Il faccia a faccia: metriche comparative</a></li> <li><a href="#_perché_deepseek_v4_pro_guadagna_nello_sviluppo_software">Perché DeepSeek-V4-Pro guadagna nello sviluppo software</a> <ul class="sectlevel2"> <li><a href="#_1_larchitecture_csahca_est_taillée_pour_le_code">1. L’architecture CSA+HCA est taillée pour le code</a></li> </ul> </li> </ul> </li> <li><a href="#_bake_generate_the_site_jbake_b_2">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s_2">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset_2">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder_2">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset">Clear the output directory before baking jbake -b . output --reset <code>`</code></a> <ul class="sectlevel2"> <li><a href="#_2_il_contesto_eager_è_la_sua_zona_di_conforto">2. Il contesto EAGER è la sua zona di conforto</a></li> <li><a href="#_initialize_a_new_jbake_project"># Initialize a new JBake project</a></li> </ul> </li> <li><a href="#_bake_generate_the_site_jbake_b_3">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s_3">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset_3">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder_3">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset_2">Clear the output directory before baking jbake -b . output --reset <code>`</code></a> <ul class="sectlevel1"> <li><a href="#_lezioni_apprese_come_scegliere_il_proprio_llm_per_il_vibe_coding">Lezioni apprese: Come scegliere il proprio LLM per il Vibe Coding</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 18 minutes</div> <p>La guerra dei LLM si svolge anche nel terminale di uno sviluppatore. Non su benchmark accademici sterili. Nella vita reale: un prompt di 30 000 token, una governance agent in AsciiDoc, plugin Gradle Kotlin DSL da debuggare e sessioni che si susseguono per tre settimane. Ho testato per te DeepSeek-V4-Pro, Kimi K2.6 e GLM-5.1. Ecco il verdetto, con prove tecniche a supporto.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">indice</dt> <dd> <p>(empty)</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_contesto_non_un_banco_di_prova_un_cantiere">Contesto: non un banco di prova, un cantiere</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tre settimane fa, stavo lavorando su`codebase-gradle`, il mio meta-build system che centralizza la configurazione YAML di quattro progetti: un generatore di README PlantUML, un costruttore di slide AsciiDoc, un sito statico JBake e un chatbot LLM. L’agent Opencode, governato dalla mia metodologia di file agenti in AsciiDoc, caricava ~30K token di contesto EAGER all’inizio di ogni sessione — regole assolute, backlog, storico delle ultime 10 sessioni.</p> </div> <div class="paragraph"> <p>È su questo terreno che ho confrontato tre modelli:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Kimi K2.6</strong>(Moonshot AI, 1T parametri / 32B attivati, 256K contesto max, MLA) - <strong>GLM-5.1</strong>(Zhipu AI/Tsinghua, 744B params / DSA, 200K contesto massimo) - <strong>DeepSeek-V4-Pro</strong>(DeepSeek, 1.6T params / 49B attivati, 1M contesto max, CSA+HCA)</p> </li> </ul> </div> <div class="paragraph"> <p>Tutti serviti tramite Ollama su server cloud, tutti in modalità thinking (fase di pensiero attivata). La sfida: produrre codice corretto, mantenere la coerenza durante sessioni lunghe e non allucinare quando il contesto supera i 80K token.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_mio_ambiente_di_test">Il mio ambiente di test</h2> <div class="sectionbody"> <div id="diag-dev-env" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 17) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Ambiente di Test — Sessioni Opencode × 3 LLMs left to right direction package "🖥️ Terminale Sviluppatore" #E8F5E9 { rectangle "AGENT.adoc\n(regole, backlog)" as AG rectangle "PROMPT_REPRISE\nmissione" as PR rectangle "INDEX.adoc\n(roadmap)" as IDX } package "☁️ Ollama Cloud" #BBDEFB { rectangle "DeepSeek-V4-Pro\n1.6T / CSA+HCA" as DV4 rectangle "Kimi K2.6 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Ambiente di Test — Sessioni Opencode × 3 LLMs left to right direction package "🖥️ Terminale Sviluppatore" #E8F5E9 { rectangle "AGENT.adoc\n(regole, backlog)" as AG rectangle "PROMPT_REPRISE\nmissione" as PR rectangle "INDEX.adoc\n(roadmap)" as IDX } package "☁️ Ollama Cloud" #BBDEFB { rectangle "DeepSeek-V4-Pro\n1.6T / CSA+HCA" as DV4 rectangle "Kimi K2.6 1T / MLA" as KIMI rectangle "GLM-5.1 744B / MLA+DSA" as GLMG } package "⚙️ Codice Gradle" #FFF9C4 { folder "buildSrc/" { file "codebase.kt" file "readme.kt" file "site.kt" file "slider.kt" file "snapshot.kt" } file "build.gradle.kts\n(947 righe)" file "embeds.yml" } AG --> DV4 : Sessions 1-8 ✅ AG --> KIMI : Sessions 9-10 ⚠️ AG --> GLMG : Sessions 11-13 ⚠️ DV4 --> "base di codice" : "TDD, rifattorizzazione,\nistantanea" KIMI --> "base di codice" : "Degrado a partire da 60K token" note bottom of GLMG Meilleur que Kimi mais latence + DSA moins robuste que CSA+HCA end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Ogni sessione iniziava con circa 30K token di contesto EAGER :`AGENT.adoc`(287 linee),<code>PROMPT_REPRISE.adoc</code>(51 linee),<code>.agents/INDEX.adoc</code>(218 righe)<code>LAZY_EAGER_ESSENTIALS.adoc</code>(50 righe). Il contesto si gonfiava rapidamente con gli scambi — una sessione tipica di 10 messaggi aggiungeva 15-20K token al prompt cumulativo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_griglia_di_valutazione">La Griglia di Valutazione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ho valutato ogni modello su quattro assi critici per lo sviluppo software assistito :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Asse</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Criterio concreto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coerenza lungo contesto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’agente si ricorda delle convenzioni decise 40 messaggi fa ?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Qualità del codice prodotto</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il codice compila al primo tentativo? Rispetta i patterns esistenti?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ragionamento architettonico</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’agente comprende le relazioni tra i moduli senza che io gliele spieghi di nuovo?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Resistenza alle allucinazioni</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">A partire da quanti token l’agente inizia a inventare API o classi inesistenti ?</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>E una metrica sintetica interna: il<strong>coefficiente di ripresa</strong>(quanto tempo passo a correggere l’agente invece di programmare con lui).</p> </div> </div> </div> <div class="sect1"> <h2 id="_round_1_kimi_k2_6_il_falso_avvio">Round 1 : Kimi K2.6 — Il falso avvio</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kimi K2.6 è stata la mia prima scelta. I suoi benchmark su SWE-Bench Verified (80.2) e Terminal-Bench 2.0 (66.7) sono eccellenti. La sua architettura MLA promette una buona efficacia sulle lunghe sequenze.</p> </div> <div class="sect2"> <h3 id="_session_9_la_ripresa">Session 9 : la ripresa</h3> <div class="paragraph"> <p>Prima sessione con Kimi. Compito: implementare il metodo`resolveActiveKey()<code>in`codebase.kt</code>— una funzione di risoluzione della chiave API con fallback CLI. Il contesto è di 30K token, Kimi ragiona rapidamente, produce un codice pulito con gestione della scadenza delle chiavi.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveActiveKey( cfg: CodebaseConfiguration, logger: Logger, cliProvider: String? = null, cliAccount: String? = null, cliKey: String? = null ): NamedApiKey? { // Résolution provider → compte → clé avec CLI override // Kimi a parfaitement compris la chaîne de priorité }</code></pre> </div> </div> <div class="paragraph"> <p>Il codice compila. I 7 casi di test passano. Sono ottimista.</p> </div> </div> <div class="sect2"> <h3 id="_sessione_10_il_naufragio_silenzioso">Sessione 10: il naufragio silenzioso</h3> <div class="paragraph"> <p>Seconda sessione. Il contesto raggiunge ~90K token con gli scambi. Chiedo a Kimi di aggiungere un meccanismo di snapshot AsciiDoc che anonimizzi i segreti prima della scrittura.</p> </div> <div class="paragraph"> <p>È lì che deraglia. Kimi inizia a inventare classi che non esistono. Mi propone`AnonymizedObjectMapper`— una classe immaginaria. Lui confonde`ReadmeYmlAnonymizer` et <code>CodebaseYmlAnonymizer</code>. Mi suggerisce di importare`com.fasterxml.jackson.anonymize.*`— un pacchetto che non è mai esistito.</p> </div> <div class="paragraph"> <p>Peggio: nella sua fase di riflessione, vedo che costruisce ragionamenti su premesse false. Lui "si ricorda" che`GitConfig`a un campo`anonymizedToken`— no, è`resolvedToken()<code>. Lui attribuisce a`SiteYmlAnonymizer`un metodo`maskSupabaseCredentials()</code>— che non esiste.</p> </div> <div class="paragraph"> <p><em><em>_ Non era un bug. Era una dissoluzione progressiva della coerenza. Come se ogni token aggiunto al contesto diluisse un po' di più la memoria dei primi 30.000. </em>_</em></p> </div> <div class="paragraph"> <p>Interrompo Kimi dopo due sessioni. La diagnosi è chiara: il MLA comprime bene la KV cache, ma senza un meccanismo di selezione sparsa fine-grained, l’attenzione si diluisce meccanicamente oltre i 60K token. Ogni token "vede" sempre meno bene il contesto distante — e inizia a colmare le lacune con rumore.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_glm_5_1_il_combattente_onorevole">GLM-5.1 — Il Combattente Onorevole</h2> <div class="sectionbody"> <div class="paragraph"> <p>GLM-5.1 arriva con un’architettura diversa: MLA per il modello base, poi un <strong>continued pre-training</strong> con DSA (DeepSeek Sparse Attention) — un indexer leggero che seleziona dinamicamente i top-2048 token pertinenti tra tutta la cronologia.</p> </div> <div class="sect2"> <h3 id="_architettura_il_dsa_contro_il_mla_puro">Architettura: il DSA contro il MLA puro</h3> <div class="paragraph"> <p>La differenza è fondamentale. Là dove Kimi comprime la cronologia in uno spazio latente unico (e perde gradualmente la capacità di distinguere l’informazione pertinente), GLM innesta un indexer post‑addestramento che esegue una selezione sparsa esplicita.</p> </div> <div id="diag-mla-vs-dsa" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Architetture di Attenzione — MLA vs MLA+DSA left to right direction rectangle "**Kimi K2.6 — MLA pura**" as MLA #FFCDD2 { rectangle "KV Cache ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Architetture di Attenzione — MLA vs MLA+DSA left to right direction rectangle "**Kimi K2.6 — MLA pura**" as MLA #FFCDD2 { rectangle "KV Cache completo" as KV1 rectangle "Compressione latente" as CL1 rectangle "Decodifica\nspazio latente" as DL1 KV1 --> CL1 CL1 --> DL1 note bottom of DL1 ⚠️ Au-delà de 60K tokens : perte de discrimination end note } rectangle "GLM-5.1 — MLA + DSA" as DSA #C8E6C9 { rectangle "KV Cache completo" as KV2 rectangle "Compressione\nlatente (MLA)" as CL2 rectangle "Indicizzatore leggero\n(DSA, top-k=2048)" as IL rectangle "Decodifica sui token selezionati" as DL2 KV2 --> CL2 CL2 --> IL IL --> DL2 note bottom of DL2 ✅ "Lossless per costruzione" Sélection explicite des tokens pertinents end note } MLA --> DSA : "Guadagno: selezione sparsa che evita la diluizione" @enduml</pre> </div> </div> <div class="paragraph"> <p>Il rapporto tecnico lo dice esplicitamente : DSA è <em>"lossless by construction"</em> — al contrario delle alternative come SWA (pattern search), Gated DeltaNet o SimpleGDN che perdono fino a 5,69 punti su RULER@128K</p> </div> </div> <div class="sect2"> <h3 id="_sessioni_11_13_solido_ma_frustrante">Sessioni 11-13: solido ma frustrante</h3> <div class="paragraph"> <p>GLM-5.1 mantiene meglio la distanza. Nella sessione 11 (~60K tokens), rimane coerente. Produce un`SnapshotManager`funzionale con gestione corretta dei quattro anonimizzatori.</p> </div> <div class="paragraph"> <p>Ma la latenza è un problema. Le fasi di riflessione DSA sono più pesanti rispetto al puro MLA — l’indicizzatore deve riseguire la cronologia a ogni passaggio. Una risposta che richiedeva 8 secondi con Kimi ne richiede 15 con GLM. In una sessione di 30 messaggi, si fa sentire.</p> </div> <div class="paragraph"> <p>E poi ci sono gli errori sottili. GLM non delira come Kimi — ma fa errori di <strong>nommage</strong>. Chiama`toAnonymizedYaml()<code>il metodo che dovrebbe chiamarsi`anonymize()</code>. Inverte`loadReadmeConfiguration()` et <code>loadCodebaseConfiguration()`nel`renderFileSection()</code>. Non sono allucinazioni, sono confusione superficiale — ma in produzione, una confusione superficiale può rompere una build</p> </div> <div class="paragraph"> <p>Ho tenuto tre sessioni con GLM. È migliore di Kimi, indubbiamente. Ma tre sessioni di correzione manuale sui dettagli di denominazione, è stancante.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_3_deepseek_v4_pro_la_macchina_da_guerra">Round 3 : DeepSeek-V4-Pro — La Macchina da Guerra</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro arriva con l’architettura più ambiziosa dei tre: un sistema ibrido che combina due meccanismi di attenzione complementari.</p> </div> <div class="sect2"> <h3 id="_architettura_csa_hca_la_doppia_rete">Architettura: CSA + HCA, la doppia rete</h3> <div id="diag-csa-hca" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 180 title DeepSeek-V4-Pro — Architettura Ibrida CSA + HCA left to right direction rectangle "KV Cache ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 180 title DeepSeek-V4-Pro — Architettura Ibrida CSA + HCA left to right direction rectangle "KV Cache 1M token" as KV #E3F2FD rectangle "CSA Attenzione Sparse Compressa" as CSA #C8E6C9 { rectangle "Compressione m tokens → 1" as CC rectangle "Sparse Attention\n(DSA, top-k)" as SA CC --> SA note bottom of SA Attention locale fine + sélection sparse end note } rectangle "HCA Heavily Compressed Attention" as HCA #BBDEFB { rectangle "Compressione estrema m' >> m → 1" as ECC rectangle "Attenzione densa residuale" as EDA ECC --> EDA note bottom of EDA Contexte global + connexions longue distance end note } rectangle "Fusione ibrida" as FUSION #FFF9C4 rectangle "Decodifica coerente" as DEC #FFE0B2 KV --> CSA : Précision locale KV --> HCA : Vision globale CSA --> FUSION HCA --> FUSION FUSION --> DEC @enduml</pre> </div> </div> <div class="paragraph"> <p>Due livelli di compressione, due granularità di attenzione :</p> </div> <div class="ulist"> <ul> <li> <p><strong>CSA</strong>comprime la cache KV tutti i`m`token, poi applica un’attenzione sparsa (DeepSeek Sparse Attention) — solo i top-k delle entrate compresse vengono consultati. Preciso, locale, efficace. - <strong>HCA</strong>: compressione estrema (fattore`m'`molto più grande di`m`), ma attenzione densa sul residuo compresso — conserva le connessioni globali senza esplosione quadratica.</p> </li> </ul> </div> <div class="paragraph"> <p>Risultato: a 1M di token, DeepSeek-V4-Pro consuma solo<strong>27% dei FLOPs di inferenza</strong> et <strong>10% della dimensione della cache KV</strong>rispetto a DeepSeek-V3.2. Il modello precedente.</p> </div> <div class="paragraph"> <p>E soprattutto, il rapporto tecnico (Figura 9) annuncia: <em>"Retrieval performance remains highly stable within a 128K context window."</em></p> </div> </div> <div class="sect2"> <h3 id="_sessioni_1_8_il_sollievo">Sessioni 1-8 : il sollievo</h3> <div class="paragraph"> <p>Ho fatto otto sessioni con DeepSeek-V4-Pro su`codebase-gradle`. Otto sessioni senza una sola allucinazione, senza una sola classe inventata, senza una sola confusione di denominazione.</p> </div> <div class="paragraph"> <p>Session 1 : implementazione di`CodebaseYmlConfig` et <code>CodebaseYmlAnonymizer</code>. 350 linee di Kotlin, tests inline, tutto compila. Sessione 4 : aggiunta di`SnapshotManager`con tree view, raccolta di file, rendering AsciiDoc per file. 279 righe, zero errori. Sessione 7 : debug del`renderFileSection()`che doveva gestire quattro tipi di anonimizzatori diversi senza ambiguità di risoluzione. Risolto in tre messaggi.</p> </div> <div class="paragraph"> <p>La latenza è più alta di Kimi — circa 10-12 secondi per risposta in modalità thinking. Ma il tasso di correzione è praticamente nullo. Non passo il mio tempo a correggere gli errori dell’agente. Codifico <strong>con</strong> lui.</p> </div> </div> <div class="sect2"> <h3 id="_il_test_decisivo_refactoring_a_100k_token">Il test decisivo: refactoring a 100K token</h3> <div class="paragraph"> <p>Alla sessione 8, il contesto cumulativo supera i 100K token. Chiedo un refactoring pesante: estrarre le quattro attività di verifica inline del`build.gradle.kts`verso i file di test JUnit5 in`buildSrc/src/test/`.</p> </div> <div class="paragraph"> <p>L’agente propone un piano in tre fasi:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Creare le classi di test con migrazione dei casi esistenti</p> </li> <li> <p>Aggiungere le dipendenze JUnit5 e Kotest in`buildSrc/build.gradle.kts`</p> </li> <li> <p>Rimuovi il codice inline di`build.gradle.kts`</p> </li> </ol> </div> <div class="paragraph"> <p>Il piano è corretto. L’esecuzione è pulita. Identifica anche un edge case che avevo trascurato : le dipendenze Jackson duplicate tra`buildscript {}` et `buildSrc/build.gradle.kts`che devono essere unificate durante la migrazione.</p> </div> <div class="paragraph"> <p>100K token di contesto, e l’agente si ricorda che`CodebaseYmlAnonymizer.TOKEN_MASK`<mark>#</mark> Comandi CLI JBake <code>`</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset_chegitconfig_resolvedtokenè_una_funzione_di_estensione_definita_inreadme_kt_e_chesnapshotmanager_pruned_dirsescludebuild_gradle_et_git" class="sect0">Clear the output directory before baking jbake -b . output --reset`"<strong>*</strong>"`, che`GitConfig.resolvedToken()<code>è una funzione di estensione definita in`readme.kt</code>, e che`SnapshotManager.PRUNED_DIRS`esclude`build`, <code>.gradle</code> et <code>.git</code>.</h1> <div class="paragraph"> <p>È questa la differenza.</p> </div> <div class="sect1"> <h2 id="_il_faccia_a_faccia_metriche_comparative">Il faccia a faccia: metriche comparative</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Criterio</th> <th class="tableblock halign-left valign-top">Kimi K2.6</th> <th class="tableblock halign-left valign-top">GLM-5.1</th> <th class="tableblock halign-left valign-top">DeepSeek-V4-Pro</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contesto massimo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">256K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">200K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1M</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Meccanismo attenzione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA puro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA + DSA</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSA + HCA ibrido</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Parametri totali</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1T</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">744B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1.6T</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Impostazioni attivate</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">32B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non pubblicato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49B</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">soglia di degrado osservata</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(no output)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No output)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No output)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Comportamento oltre</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Allucinazioni massicce</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusioni superficiali</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">degradazione progressiva lenta</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Stabilità NIAH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non pubblicato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% @128K (DSA)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">stabile fino a 128K (Figura 9)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">MRCR @128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non pubblicato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non pubblicato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">supérieur à Gemini 3.1 Pro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sessioni tenute prima dell’abbandono</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 (e continua)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tempo di correzione / tempo di codice</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">60%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><5%</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Latenza media (modalità think)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">15 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11 s</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coefficiente di fiducia*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">6/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9/10</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Coefficient di fiducia = misura soggettiva della mia capacità di prendere il codice dell’agente e il commit senza rileggere riga per riga.</em></p> </div> <div id="diag-radar" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 16) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Radar Comparativo — 3 LLM nello sviluppo software assistito legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "Coerenza 80K+ tokens" as coh #F5F5F5 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Radar Comparativo — 3 LLM nello sviluppo software assistito legend right |= Couleur |= Modèle | | <#FF5252> | Kimi K2.6 | | <#FFC107> | GLM-5.1 | | <#4CAF50> | DeepSeek-V4-Pro | endlegend rectangle " " as space #FFFFFF rectangle "Coerenza 80K+ tokens" as coh #F5F5F5 rectangle "Qualità codice" as qual #F5F5F5 rectangle "Ragionamento architettonico" as arch #F5F5F5 rectangle "Resistenza allucinazioni" as hall #F5F5F5 rectangle "Velocità (esperienza dev)" as speed #F5F5F5 rectangle "Conoscenza\nGradle/Kotlin" as kg #F5F5F5 rectangle "Tasso di correzione" as corr #F5F5F5 coh --> qual qual --> arch arch --> hall hall --> speed speed --> kg kg --> corr note top of coh Kimi ████░░░░░░ 4/10 GLM ██████░░░░ 6/10 DeepSeek █████████░ 9/10 end note note top of qual Kimi ███████░░░ 7/10 (sous 60K) GLM ████████░░ 8/10 DeepSeek █████████░ 9/10 end note note top of arch Kimi █████░░░░░ 5/10 GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of hall Kimi ██████░░░░ 6/10 → ██░░░░░░░░ 2/10 (> 60K) GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of speed Kimi █████████░ 9/10 GLM ██████░░░░ 6/10 DeepSeek █████░░░░░ 5/10 end note note top of kg Kimi ███████░░░ 7/10 GLM ███████░░░ 7/10 DeepSeek █████████░ 9/10 end note note top of corr Kimi ██░░░░░░░░ 2/10 (beaucoup de corrections) GLM █████░░░░░ 5/10 DeepSeek ██████████ 10/10 (presque rien à corriger) end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_deepseek_v4_pro_guadagna_nello_sviluppo_software">Perché DeepSeek-V4-Pro guadagna nello sviluppo software</h2> <div class="sectionbody"> <div class="paragraph"> <p>La superiorità di DeepSeek-V4-Pro non è dovuta a un solo fattore — è una convergenza :</p> </div> <div class="sect2"> <h3 id="_1_larchitecture_csahca_est_taillée_pour_le_code">1. L’architecture CSA+HCA est taillée pour le code</h3> <div class="paragraph"> <p>Lo sviluppo software assistito è un caso d’uso <strong>estremo</strong> per l’attenzione a lungo contesto. Hai bisogno di : <mark>#</mark> JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b_2" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s_2" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset_2" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder_2" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code></h1> <div class="paragraph"> <p>Traduci da fr a it. Mantieni tutti gli span di codice tra backtick (<code>…​</code>) esattamente così — non modificare mai il contenuto, lo spazio o la posizione degli backtick. Questo testo può essere un frammento di una frase più ampia — tradurre il frammento senza richiedere più contesto. Emetti solo il testo tradotto — nessuna spiegazione, nessun commento, nessuna introduzione, nessuna alternativa, nessuna opzione.</p> </div> <div class="ulist"> <ul> <li> <p>Precisione locale (da cosa eredita questa classe? dove è definito questo metodo?) →<strong>CSA</strong> - Visione globale (perché questo modulo esiste ? come i quattro anonymizzatori interagiscono ?) →<strong>HCA</strong></p> </li> </ul> </div> <div class="paragraph"> <p>Kimi con MLA solo gestisce la precisione locale ma perde la visione globale oltre i 60K. GLM con DSA migliora la visione globale ma rimane mono-livello. DeepSeek combina i due esplicitamente.</p> </div> <div class="sect2"> <h3 id="_2_il_contesto_eager_è_la_sua_zona_di_conforto">2. Il contesto EAGER è la sua zona di conforto</h3> <div class="paragraph"> <p>Il mio sistema di governance carica ~30K token di regole e backlog all’avvio. Con una finestra stabile fino a 128K, DeepSeek dispone di ~100K token di margine per gli scambi della sessione. Questo è da 3 a 4 volte più di quanto Kimi possa gestire senza degradazione.</p> </div> <div class="paragraph"> <p>(No content to translate) La finestra di 128K di stabilità perfetta corrisponde esattamente alle mie esigenze: 30K di EAGER + 70K di scambi = una sessione produttiva di 20-30 messaggi senza mai uscire dalla zona verde. <em>__</em></p> </div> </div> <div class="sect2"> <h3 id="_initialize_a_new_jbake_project"># Initialize a new JBake project</h3> <div class="paragraph"> <p>jbake -i</p> </div> </div> <h1 id="_bake_generate_the_site_jbake_b_3" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s_3" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset_3" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder_3" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset_2" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code></h1> <div class="olist arabic"> <ol class="arabic"> <li> <p>Il rapporto qualità/latenza è ottimale per il flusso</p> </li> </ol> </div> <div class="paragraph"> <p>Sì, DeepSeek-V4-Pro è più lento di Kimi (11s vs 8s). Ma il tempo <strong>totale</strong> di un’attività è notevolmente inferiore perché non passo 20 minuti a correggere le allucinazioni dell’agente.</p> </div> <div class="paragraph"> <p>Il sviluppatore non misura la latenza di una risposta. Misura il tempo tra "pongo la domanda" e "il codice è nel mio repository e funziona". Su questa metrica, DeepSeek-V4-Pro è il più veloce dei tre.</p> </div> <div class="sect1"> <h2 id="_lezioni_apprese_come_scegliere_il_proprio_llm_per_il_vibe_coding">Lezioni apprese: Come scegliere il proprio LLM per il Vibe Coding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Oltre il punteggio occasionale, questa esperienza mi ha insegnato a valutare un LLM per lo sviluppo software assistito su criteri che non compaiono in nessun benchmark :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Guarda l’architettura, non la dimensione del contesto annunciata</strong>— Un modello che annuncia 256K di contesto ma ha solo un MLA finirà come Kimi: teoricamente capace, praticamente inutilizzabile oltre i 60K.</p> </li> <li> <p><strong>Testa sul TUO contesto, non su un benchmark generico</strong> — Mon prompt initial de 30K tokens AsciiDoc avec règles absolues et backlog n’a rien à voir avec les questions de HLE ou AIME.</p> </li> <li> <p><strong>La latenza non è nemica se la qualità segue</strong><mark>#</mark> JBake CLI Commands</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ---- — Un modello lento che produce codice corretto è più veloce di un modello veloce che produce codice sbagliato. 1. **Fai attenzione ai modelli senza rapporto tecnico pubblico**— Se l'équipe non documenta la sua architettura d'attenzione, è perché non ha fiducia nella sua tenuta nel contesto lungo. [plantuml, format=svg, id=diag-decision-tree, alt="Arbre de décision pour choisir un LLM pour le développement logiciel assisté"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 260 title Albero di decisione — Scegli il tuo LLM per lo sviluppo assistito start :Contexte initial\n> 20K tokens ?; if (Oui) then :Architecture d'attention\nhybride ou multi-niveau ?; if (CSA+HCA) then :DeepSeek-V4-Pro Fenetre stable 128K Ideal pour gouvernance EAGER; stop elseif (MLA + DSA) then :GLM-5.1 Correct jusqu'a ~120K Latence elevee; stop else (MLA seul) :Kimi K2.6 (sessions courtes) ou eviter pour long contexte Chercher un modele avec sparse attention; stop endif else (Contexte < 20K) :N'importe lequel fonctionne. Privilegier la latence.; stop endif @enduml ---- == E l'agente di governanza in tutto questo? Questa esperienza conferma un punto che difendo dal mio articolo sulla governance Eager/Lazy :**la qualità del LLM e la qualità della governance sono moltiplicative, non additive**. Con Kimi K2.6, la mia governance era impeccabile — ma il modello diluiva l'informazione. Risultato: governance perfetta × allucinazione = zero Con DeepSeek-V4-Pro, la governance EAGER (30K token di regole) + LAZY (archivi di sessione, riferimenti tecnici) + Hot/Warm/Cold (backup rotativo) forma un ecosistema in cui ogni livello amplifica l'altro. L'agente ha le regole sotto gli occhi (EAGER), può consultare lo storico (LAZY) e il contesto non si satura mai (rotazione di backup). (No output) Un buon LLM senza governance è un motore di Ferrari senza volante. Una buona governance senza un buon LLM è un volante senza motore. DeepSeek-V4-Pro + la mia governance agente = la prima volta che ho la sensazione di guidare. ____ Il meccanismo di backup rotativo (rotazione ogni 10 sessioni o >500 righe EAGER) ha tutto il suo senso con un modello che tiene 128K di contesto: la finestra scorrevole di 10 sessioni attive mantiene il contesto fresco senza mai superare la zona di degradazione. == Fonti tecniche Ho incrociato la mia esperienza empirica con i rapporti tecnici ufficiali per validare le mie osservazioni: 1. *DeepSeek-V4 Technical Report* — PDF recuperato dahttps://huggingface.co/deepseek-ai/DeepSeek-V4-Flash[HuggingFace]. Figure 9 : "Retrieval performance remains highly stable within a 128K context window. While a performance degradation becomes visible beyond the 128K mark, the model's retrieval capabilities at 1M tokens remain remarkably strong." Architettura CSA+HCA documentata sezione 2.3. 1. *GLM-5 Technical Report* —https://arxiv.org/abs/2602.15763[arXiv:2602.15763]. DSA introdotto tramite pre-addestramento continuato, "lossless by construction". Contesto massimo 202.752 token. Le tabelle 3/5/6 documentano le prestazioni a lungo contesto rispetto alle alternative (SWA, Gated DeltaNet, SimpleGDN). 1. *Kimi K2.6 Model Card* —https://huggingface.co/moonshotai/Kimi-K2.6[HuggingFace]. MLA, 256K contesto massimo. Strategia di discard-all oltre la soglia sulle attività agentiche (confermando implicitemente il limite pratico del MLA nel contesto lungo). 1. *Kimi K2 Technical Report* —https://arxiv.org/abs/2507.20534[arXiv:2507.20534]. Architettura MoE, ottimizzatore MuonClip, prestazioni agentiche (HLE, BrowseComp, Terminal-Bench). Il punto più rivelatore: nella loro stessa valutazione, Moonshot applica una strategia di *discard-all* (eliminazione del contesto vecchio) non appena la finestra di contesto viene superata. Questo conferma esattamente ciò che ho osservato: il solo MLA non può mantenere la coerenza sull'intera finestra di 256K. L'architettura non tiene il passo. == Conclusion: La scelta dell'artigiano Dopo tre settimane e tredici sessioni di sviluppo reale, il verdetto è senza appello : |=== |Kimi K2.6 |GLM-5.1 |(Empty output) |Eccellente sotto 60K |Solido fino a 120K |Domina ovunque |Inutilizzabile oltre |Confusioni di superficie |Stable fino a 128K |2 sessioni, abbandonato |3 sessioni, abbandonato |8 sessioni, adottato |=== DeepSeek-V4-Pro è diventato il mio LLM predefinito per tutte le sessioni di sviluppo software assistito con Opencode. Non perché è il più recente. Non perché ha i migliori benchmark accademici. Ma perché nella vita reale di uno sviluppatore che spinge plugin Gradle Kotlin DSL con un contesto agente di 30K token, è l'unico che non mi tradisce quando il contesto si allunga. CSA+HCA è un *game changer* architettonico. La compressione a doppio livello + sparsificazione non è un dettaglio di implementazione — è ciò che fa la differenza tra un assistente di codice e un compagno di squadra affidabile. (No source text provided to translate.) Ho scelto DeepSeek-V4-Pro perché è l'unico dei tre che trasforma la mia governance dell'agent da una limitazione difensiva ("come evitare che l'agent dimentichi?") in un vantaggio offensif ("cosa possiamo costruire ora che l'agent ricorda tutto?"). ____ --- *Questo articolo è il frutto di 13 sessioni di sviluppo reale sul progetto`codebase-gradle`, documentate in`.agents/sessions/`secondo la mia metodologia di governance agent Eager/Lazy/Hot/Warm/Cold. Le fonti tecniche citate sono accessibili pubblicamente su HuggingFace e arXiv.</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0111_audit_contexte_agent_post.html Mon, 27 Apr 2026 00:00:00 +0000 blog/2026/0111_audit_contexte_agent_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scena_sessione_051_qualcosa_non_va">La scena: sessione 051, qualcosa non va</a></li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset">Clear the output directory before baking jbake -b . output --reset <code>`</code></a> <ul class="sectlevel1"> <li><a href="#_laudit_analizzare_le_627_righe">L’audit: analizzare le 627 righe</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 14 minutes</div> <p>Hai passato settimane a costruire una governance dell’agente impeccabile. Eager/Lazy, procedura di fine sessione, backup rotativi. Il sistema è operativo. Poi un giorno, l’agente diventa lento. Le risposte sono diluite. Misuri: 1414 linee caricate automaticamente. E il peggio è che il colpevole non è il codice, né il backlog, né gli archivi delle sessioni. Il colpevole è il file che documenta il tuo metodo.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_scena_sessione_051_qualcosa_non_va">La scena: sessione 051, qualcosa non va</h2> <div class="sectionbody"> <div class="paragraph"> <p>30 aprile 2026, 16:00. Sono in piena sessione su`magic-stick`, il mio progetto di build di ISO Linux live. L’agente Opencode ha caricato automaticamente i miei file Eager come di consueto —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc`Comandi CLI di JBake ``</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code></h1> <div class="olist arabic"> <ol class="arabic"> <li> <p>Tutto è normale.</p> </li> </ol> </div> <div class="paragraph"> <p>Eccetto che le risposte sono molli. L’agente impiega due secondi in più a ragionare. Dimentica un dettaglio che aveva sotto gli occhi tre messaggi prima. Non è un crash, non è un errore — è un degrado lento, il tipo di cosa che non si nota subito.</p> </div> <div class="paragraph"> <p>Avevo già vissuto questo alla sessione 048, quando avevo scoperto che i file di governance pesavano complessivamente 5200 linee. Allora avevo concepito il meccanismo Hot/Warm/Cold con la sua finestra scorrevole di 10 sessioni, le sue ondate fredde identiche e il suo sensore a due trigger. Il problema era stato risolto. In teoria.</p> </div> <div class="paragraph"> <p>Ma ora siamo alla sessione 051. La rotazione del backup è avvenuta correttamente — i file EAGER sono passati da 2087 a 500 righe. Tuttavia, il contesto resta pesante. Qualcosa mi sfugge.</p> </div> <div class="paragraph"> <p>Apro un terminale e digito :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wc -l AGENT.adoc AGENT_MODUS_OPERANDI.adoc PROMPT_REPRISE.adoc \ .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>1414 righe. La rotazione di backup ha ben tagliato in INDEX, SESSIONS_HISTORY e COMPLETED_TASKS — sono puliti. Ma c’è un elefante nella stanza che non avevo visto:<strong>627 linee</strong>in un unico file.<code>AGENT_MODUS_OPERANDI.adoc</code>.</p> </div> <div class="paragraph"> <p>Questo file è quello che ho scritto alla sessione 1 per documentare la strategia Eager/Lazy. È il manuale del metodo. Ed è diventato, da solo, il 44% del contesto EAGER.</p> </div> <div id="diag-before-audit" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE title Contesto EAGER — 1414 righe rectangle "AGENT_MODUS_OPERANDI\n**627 righe (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 righe (20%)" as AG #BBDEFB rectangle "INDEX.adoc 218 righe (15%)" as IDX #C8E6C9 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE title Contesto EAGER — 1414 righe rectangle "AGENT_MODUS_OPERANDI\n**627 righe (44%)**" as MOD #FFCDD2 rectangle "AGENT.adoc\n287 righe (20%)" as AG #BBDEFB rectangle "INDEX.adoc 218 righe (15%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS 213 righe (15%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE 51 righe (4%)" as PRO #E1BEE7 rectangle "SESSIONS_HISTORY 18 righe (1%)" as HIS #FFE0B2 note bottom of MOD Le fichier qui documente la méthode est devenu le plus gros poste de dépense end note @enduml</pre> </div> </div> <div class="paragraph"> <p>L’ironia è totale. Il file progettato per <strong>risparmiare</strong> contesto è diventato il principale <strong>consumatore</strong> di contesto. È come se il manuale d’uso della tua auto pesasse più del motore.</p> </div> <div class="sect1"> <h2 id="_laudit_analizzare_le_627_righe">L’audit: analizzare le 627 righe</h2> <div class="sectionbody"> <div class="paragraph"> <p>Decido di fare un audit sezione per sezione. Non per rimuovere — per <strong>comprendere</strong> ciò che merita di essere in EAGER e ciò che potrebbe vivere altrove senza perdita di conoscenza.</p> </div> <div class="paragraph"> <p>Ecco la struttura esatta di`AGENT_MODUS_OPERANDI.adoc`e quello che ci trovo :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2739%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">sezione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Righe</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contenuto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Già presente in…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P1 — Panoramica</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">64</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problema risolto, principi fondamentali, analogia cruscotto vs manuale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[No output - empty string]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P2 — Structure des fichiers</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">97</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alberatura, politica di caricamento, quando caricare cosa</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P3 — Regole assolute</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git vietato, comandi distruttivi vietati, segreti vietati</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>+<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P4 — Ciclo di vita della sessione</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">133</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Template apertura, regole di lavoro, 6 passaggi fine sessione, checklist</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>§Fine session +<code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P5 — Metriche e soglie</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sessione ideale (15-30 min, 1-3 file), segnali di allarme</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No content)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P6 — Tipi di sessioni</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">72</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabella di rilevamento, formato di proposta, eccezioni</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(No output as there is no French text provided to translate)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P7 — Miglioramento continuo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">39</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Metriche di monitoraggio, revisione settimanale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P8 — Checklist di avvio</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">13</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bootstrap nuovo progetto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P9 — Riferimenti</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">File di riferimento, risorse esterne</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code>(file EAGER/LAZY)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Allegati A+B</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">42</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Glossario, cronologia versioni</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(no output)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Il verdetto è senza appello :</p> </div> <div class="ulist"> <ul> <li> <p><strong>duplicati integrali</strong><mark>#</mark> Comandi CLI di JBake</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ---- (167 linee) : P3, P4, P9 — tutto è già dentro`AGENT.adoc` ou `INDEX.adoc`, spesso parola per parola * **Mai consultato nella pratica**(215 linee) : P5, P6, P7, P8, Allegati — della meta-governance che non è mai stata utilizzata in alcuna sessione * **Conoscenza unica**(161 righe) : P1 e P2 — il vocabolario LAZY/EAGER, l'analogia, la politica di caricamento Su 627 righe,**382 sono rumore**. E queste 382 linee vengono caricate *all'inizio di ogni sessione*, consumate dall'agente, diluendo la sua attenzione prima ancora che io dica buongiorno. [plantuml, format=svg, id=diag-audit-result, alt="Résultat de l'audit — 627 lignes réparties en doublons, jamais consulté, connaissance unique"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Audit di AGENT_MODUS_OPERANDI.adoc — 627 righe left to right direction rectangle "🟡 **Duplicati**\n167 righe (27%)" as DUP #FFF9C4 { card "P3 — Regole assolute (34 linee)" as D1 card "P4 — Ciclo di vita (133 righe)" as D2 card "P9 — Riferimenti (30 righe)" as D3 } rectangle "🔴 **Mai consultato**\n215 righe (34%)" as JAM #FFCDD2 { card "P5 — Metriche\n(49 righe)" as J1 card "P6 — Rilevamento (72 righe)" as J2 card "P7 — Miglioramento (39 righe)" as J3 card "P8 — Bootstrap (13 righe)" as J4 card "Allegati — Glossario\n(42 righe)" as J5 } rectangle "🟢 **Conoscenza unica**\n161 righe (26%)" as UNI #C8E6C9 { card "P1 — Panoramica (64 righe)" as U1 card "P2 — Structure fichiers\n(97 lignes)" as U2 } note bottom of UNI C'est ÇA qu'il faut garder en EAGER. Le reste → cold storage. end note @enduml ---- Questo diagramma è la chiave di tutto. I duplicati (giallo) sono puro rumore — l'agente li legge due volte, in due file diversi. Il mai consultato (rosso) è documentazione morta — scritta con cura, mai utilizzata. Solo il verde contiene la conoscenza che l'agente non può trovare altrove. == La paura di perdere l'ingegneria A questo punto, ho l'evidenza davanti agli occhi: devo ridurre.`AGENT_MODUS_OPERANDI.adoc`. Ma esito. # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ``` Questo file, l'ho scritto a mano. Ogni sezione è il risultato di una lezione appresa in una sessione reale. La parte P3 è nata da un`rm -rf`accidentale su`bakery-plugin`che mi è costato dei token Firebase reali. La parte P4 è il risultato di quindici sessioni in cui dimenticavo di archiviare e perdevo il filo. La procedura in 6 passaggi non è uscita da un libro — è uscita dal dolore. Eliminare queste sezioni sarebbe buttare via la storia della mia ingegneria. Le lezioni che le hanno prodotte, le sessioni durante le quali le ho scoperte, gli errori che non voglio più ripetere. Non è testo — è esperienza cristallizzata. È lì che formulo il principio che guiderà la soluzione : ____ **Non eliminare mai. Sempre ricollocare.**La conoscenza non deve scomparire dal progetto. Deve semplicemente evitare di essere caricata automaticamente quando non è necessaria. ____ == La soluzione : split enciclopedico Il modello che propongo è semplice e si ispira al modo in cui Wikipedia è cresciuta: quando un articolo diventa troppo lungo, non lo si taglia — si crea un articolo dettagliato e si mantiene un riassunto nell'articolo principale. per`AGENT_MODUS_OPERANDI.adoc`, questo dà : 1. **Estrarre**le 161 righe di conoscenza unica (P1 + P2) in un nuovo file`LAZY_EAGER_ESSENTIALS.adoc`— compresso a circa 50 righe, rigorosamente EAGER 2. **Rinomina** `AGENT_MODUS_OPERANDI.adoc` en `.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc`— il file originale di 627 righe, preservato *intatto*, in cold storage 3. **Non caricare mai**il file dell'enciclopedia automaticamente — è lì per l'uomo, per la distillazione futura, per l'agente che invocheremo tra sei mesi con un modello migliore [plantuml, format=svg, id=diag-split-solution, alt="Architecture du split encyclopédique — ESSENTIALS EAGER + ENCYCLOPEDIE cold storage"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Split Enciclopedica — AGENT_MODUS_OPERANDI left to right direction rectangle "**AGENT_MODUS_OPERANDI.adoc** 627 righe (prima dello split)" as BEFORE #FFCDD2 { } rectangle " " as ARROW1 rectangle " " as ARROW2 rectangle "**LAZY_EAGER_ESSENTIALS.adoc** **~50 righe — EAGER**" as ESS #C8E6C9 { card "P1 condensata\n(15 righe)" as E1 card "P2 condensata\n(35 righe)" as E2 } rectangle "**.agents/encyclopedies/** **LAZY_EAGER_ENCYCLOPEDIE.adoc** 627 linee — COLD" as ENC #BBDEFB { card "P1 agli Allegati (integrale, intatto)" as C1 } BEFORE -[#4CAF50]-> ESS : "Estrazione della\nconoscenza critica" BEFORE -[#2196F3]-> ENC : "Preservazione integrale\ndell'ingegneria" note bottom of ESS Chargé automatiquement en début de session → L'agent comprend le vocabulaire end note note bottom of ENC Jamais chargé automatiquement Consultable par l'humain Matériau brut pour distillation future end note @enduml ---- Il nome`encyclopedies/`non è insignificante. Un'enciclopedia, non è un dossier d'archivi — è una collezione di conoscenze organizzata, consultabile ma non portatile. Non si legge l'Enciclopedia Universalis in metropolitana. La si tiene nella biblioteca, e vi si va quando si ha una domanda precisa. Questo è precisamente il ruolo di questa cartella: una biblioteca di riferimento fredda, strutturata, esaustiva — che l'agente non tocca automaticamente. == Il contenuto del file ESSENTIALS Ecco com'è effettivamente il nuovo file`LAZY_EAGER_ESSENTIALS.adoc`, estratto e compattato a partire da P1 e P2 : [source,asciidoc] ---- = Stratégie LAZY/EAGER — Principes Essentiels [abstract] Ce fichier définit la stratégie de gestion du contexte agent. Chargé automatiquement (EAGER) en début de session. == Principes |=== | EAGER | LAZY | Tableau de bord | Manuel du propriétaire | Chargé automatiquement | Chargé sur demande | <= 100 lignes, <= 10k tokens | Illimité, détaillé | Règles absolues, mission courante | Archives, historique, références |=== == Politique de Chargement |=== | Fichier | Type | Quand charger | PROMPT_REPRISE.adoc | EAGER | Début session (auto) | *_ESSENTIALS.adoc | EAGER | Début session si EPIC active | .agents/INDEX.adoc | EAGER | Début session (auto) | *_REFERENCE.adoc | LAZY | Sur besoin (détails architecture) | .agents/sessions/N-*.adoc | LAZY | Sur demande (détails session) | .agents/encyclopedies/*.adoc | COLD | Jamais auto (humain seulement) |=== == Comment l'Agent Sait Quoi Charger Début session → PROMPT_REPRISE + INDEX + ESSENTIALS actifs. Besoin de détails → charger les *_REFERENCE et sessions/ en LAZY. Connaissance froide → encyclopedies/, jamais automatique. ---- Cinquanta linee. Questo è tutto ciò di cui l'agente ha bisogno per comprendere la meccanica. Tutto il resto — la storia delle lezioni, le analogie dettagliate, le procedure passo passo, gli allegati — vive nell'enciclopedia. E il più importante:**Niente è stato cancellato.**. Le 627 linee di ingegneria sono ancora lì, in`.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc`. Sono semplicemente sistemate nella biblioteca anziché sul piano di lavoro. == Il risultato: -50% di contesto EAGER Prima della separazione: [source] ---- 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total ---- Dopo lo split : [source] ---- 287 AGENT.adoc 50 LAZY_EAGER_ESSENTIALS.adoc ← remplace 627 lignes 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 837 total ← -41% ---- [plantuml, format=svg, id=diag-after-audit, alt="Répartition des 837 lignes EAGER après audit — gain de 41%"] ---- @startuml skinparam backgroundColor #FEFEFE title Contesto EAGER dopo split enciclopedico — 837 righe (-41%) rectangle "AGENT.adoc 287 righe (34%)" as AG #BBDEFB rectangle "INDEX.adoc 218 righe (26%)" as IDX #C8E6C9 rectangle "COMPLETED_TASKS\n213 righe (25%)" as ARC #FFF9C4 rectangle "PROMPT_REPRISE 51 linee (6%)" as PRO #E1BEE7 rectangle "ESSENTIALS 50 righe (6%)" as ESS #A5D6A7 rectangle "SESSIONS_HISTORY\n18 righe (2%)" as HIS #FFE0B2 note bottom of ESS De 627 → 50 lignes 577 lignes d'ingénierie préservées en cold storage Rien de perdu. Tout de relocalisé. end note @enduml ---- Il maggior consumatore (AGENT_MODUS_OPERANDI, 627 linee) è stato sostituito da un file di 50 linee. Il guadagno è immediato: 577 linee di contesto liberate. L'agente respira. E dentro`.agents/encyclopedies/`, il file originale di 627 linee attende. Intatto. Con tutte le sue sezioni — compresi quelli che sono duplicati, compresi quelli che non sono mai stati utilizzati. Perché un giorno, un modello migliore o un data scientist umano vorrà incrociare questi angoli, queste ridondanze assunte, queste lezioni apprese. E quel giorno, la materia prima sarà lì. == Perché la cartella si chiama `encyclopedies/ La scelta del nome non è cosmetica. Codifica la filosofia del meccanismo. Una *archive* (`archives/`) contiene dati storici organizzati cronologicamente — come i COMPLETED_TASKS mensili. Un *backup* (`backup/`) è uno snapshot datato — una copia di sicurezza di uno stato passato. Un' *enciclopedia*, è un'altra cosa. È una raccolta di conoscenza tematica, strutturata per argomento, esaustiva ma non lineare. Non si legge un'enciclopedia dall'inizio alla fine. Vi si immerge per rispondere a una domanda precisa. È esattamente il contratto di questo dossier: |=== |fascicolo |Ruolo |accesso |granularità |`archives/` |Dati storici (attività completate per mese) |pigro, strutturato |Cronologico |`backup/` |Snapshots freddi (ondate di 10 sessioni) |COLD, copia integrale |Cronologico |`encyclopedies/` |Conoscenza tematica esaustiva (metodologia, patterns) |COLD, mai auto |tematica |=== Questa distinzione evita il caos. Ogni file sa dove deve vivere secondo *ciò che contiene*, non secondo *quando è stato creato*. == Il seguito logico della serie Se avete letto i primi due articoli, ecco come i tre pezzi si incastrano : [plantuml, format=svg, id=diag-trilogie, alt="Les trois articles de la série gouvernance — progression logique"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 220 title Trilogia della Governance dell'Agente left to right direction package "📖 **Articolo 0108**\nStrategia Eager/Lazy" as A1 #E8F5E9 { card "agente di memoria tra sessioni" as M1 card "File EAGER (auto-caricati)" as M2 card "File LAZY\n(su richiesta)" as M3 card "Procedura a 6 fasi" as M4 } package "🧊 **Articolo 0110** Meccanismo Hot/Warm/Cold" as A2 #FFF9C4 { card "Invecchiamento del contesto" as V1 card "Finestra scorrevole 10 sessioni" as V2 card "ondata di freddo identico" as V3 card "Sensore con due trigger" as V4 } package "�🔍 **Articolo 0111** Audit + Soluzione Enciclopedica" as A3 #BBDEFB { card "Audit des fichiers\nEAGER" as E1 card "Identificazione dello spreco" as E2 card "Split ESSENTIALS/enciclopedia" as E3 card "Conservazione dell'ingegneria" as E4 } A1 --> A2 : "La memoria cresce → serve un meccanismo di invecchiamento" A2 --> A3 : "L'invecchiamento non è sufficiente → bisogna auditare ciò che merita di essere in EAGER" note bottom of A3 ✅ Les trois couches sont en place sur 6 projets actifs end note @enduml ---- * **0108**risponde a: « Come dare una memoria all'agente tra due sessioni ? * **0110** risponde a : « Come impedire che questa memoria soffochi l'agente ? » * **0111**risponde : « E se il problema non fosse la dimensione degli archivi, ma ciò che abbiamo *scelto* di mettere in EAGER ? Il primo articolo ha costruito la struttura. Il secondo ha aggiunto il meccanismo di invecchiamento. Il terzo audita il contenuto — e scopre che la metodologia stessa è diventata il problema. == Cosa avrei fatto diversamente Con il senno di poi, vedo l'errore di progettazione iniziale.`AGENT_MODUS_OPERANDI.adoc`è stato creato come un documento unico — un manifesto. Era l'approccio giusto per formalizzare il pensiero. Ma una volta formalizzato il pensiero, il documento avrebbe dovuto essere diviso immediatamente : l'essenziale in EAGER, l'esauriente in cold. Non l'ho fatto perché ero fiero del documento. 627 righe di pura ingegneria, scritte a mano, ogni sezione risultato di una lezione di sessione. Era la mia opera. E, come ogni autore, ho avuto difficoltà a tagliarla. La lezione:**Non è perché un documento è buono che deve essere caricato automaticamente**. La qualità del contenuto non ha alcun rapporto con la sua pertinenza per il contesto immediato dell'agente. Oggi, la regola è semplice: qualsiasi documento di oltre 100 righe nel contesto EAGER è un sospetto. Merita un audit. Non una condanna — un audit. E la domanda non è mai « dovremmo eliminarlo ? » ma « dovremmo caricarlo ad ogni sessione ?». == La guida per auditare il tuo contesto Se hai seguito i primi due articoli e hai impostato la tua governance Eager/Lazy, ecco una procedura di audit in cinque fasi: 1. **Misurare**:`wc -l`su tutti i tuoi file EAGER. Il totale dovrebbe essere inferiore a 1000 linee. 2. **Identificare il più grande**: il file che pesa più del 20% del totale è il sospetto numero uno. 3. **Auditare sezione per sezione** : pour chaque section, demandez-vous « Est-ce que cette information est déjà ailleurs ? Est-ce que l'agent l'a déjà lue dans un autre fichier ? Est-ce qu'elle a servi dans les 5 dernières sessions ? » 4. **classificatore**: duplicato, mai usato, conoscenza unica 5. **Splitter o relocalizzare**: ciò che è unico e critico → ESSENTIALS compatto. Il resto →`encyclopedies/`. [plantuml, format=svg, id=diag-audit-checklist, alt="Procédure d'audit en 5 étapes"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Procedura di Audit del Contesto dell'Agente — 5 Passi start :1. **Mesurer**\n`wc -l *.adoc .agents/*.adoc`; if (Total > 1000 lignes ?) then (oui) :⚠️ Contexte trop lourd; else (non) :✅ Contexte OK; stop endif :2. **Identifier le suspect**\nLe fichier > 20% du total; :3. **Auditer section par section**\nPour chaque section :\n• Déjà ailleurs ? → doublon\n• Jamais servi ? → mort\n• Information unique ? → critique; :4. **Classifier**\n🟡 Doublons → à retirer de l'EAGER\n🔴 Jamais utilisé → cold storage\n🟢 Connaissance unique → à garder; :5. **Splitter**\n🟢 → ESSENTIALS (~50 lignes, EAGER)\n🟡🔴 → encyclopedies/ (cold storage); :✅ Contexte optimisé\nsans perte d'ingénierie; stop @enduml ---- Questa procedura richiede 15 minuti. In un progetto di 50 sessioni, risparmia centinaia di token per sessione futura. Il ROI è immediato. == Una governance vivace Ciò che questa serie di tre articoli mi ha insegnato è che la governance agent non è un prodotto finito. È un**organismo vivente**. Cresce con il progetto. Contrae malattie della crescita. Richiede controlli regolari. La sessione 048 ha rivelato che gli archivi si gonfiano. La sessione 051 ha rivelato che la metodologia stessa si gonfia. La sessione 060 probabilmente rivelerà qualcos'altro. È normale. È sano. Una governance che non si mette mai in discussione è una governance morta. Le tre meccanismi messi in atto — Eager/Lazy, Hot/Warm/Cold, split enciclopedico — formano un sistema di difesa in profondità contro la saturazione del contesto. Nessuno è sufficiente da solo. Insieme, si completano : * **Eager/Lazy** structure l'information *par disponibilité* * **Caldo/Tiepido/Freddo**struttura l'informazione *per freschezza* * **Audit enciclopedico**struttura le informazioni *per densità* [plantuml, format=svg, id=diag-defense-in-depth, alt="Les trois couches de défense contre la saturation du contexte"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam nodeBackgroundColor #E3F2FD title Difesa in profondità contro la saturazione del contesto node "**Contesto Agente** ~800 linee sano" as CTX #C8E6C9 node "Livello 1\n**EAGER / LAZY**" as C1 #BBDEFB node "Strato 2 **HOT / WARM / COLD**" as C2 #BBDEFB node "Strato 3 **ESSENZIALI / ENCICLOPEDIA**" as C3 #BBDEFB CTX --> C1 : "Struttura per\n**disponibilità**" CTX --> C2 : "Struttura per **freschezza**" CTX --> C3 : "Struttura per\n**densità**" note bottom of C3 Les trois couches sont nécessaires. Aucune n'est suffisante seule. end note @enduml ---- Con questi tre strati, il contesto agente su`magic-stick`è passato da 2087 linee (prima di qualsiasi ottimizzazione) a circa 800 linee — una divisione per 2,6. Senza aver perso una sola linea di documentazione, un solo archivio di sessione, una sola lezione appresa. Tutto è lì. Solo meglio organizzato. == Link * Article 0108 — Strategia Eager/Lazy :link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gestire un agente IA con AsciiDoc] * Article 0110 — Mécanisme Hot/Warm/Cold : link:/blog/2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window e Onda Fredda] * Il mio sito: https://cheroliv.com * Il progetto`magic-stick`: https://github.com/cheroliv/magic-stick --- *La conoscenza non deve scomparire. Lei deve semplicemente non essere caricata quando non è necessaria.*</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0110_mecanisme_backup_contexte_agent_post.html Sun, 26 Apr 2026 00:00:00 +0000 blog/2026/0110_mecanisme_backup_contexte_agent_post.html <div class="sect1"> <h2 id="_riassunto">Riassunto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Dopo 48 sessioni su un solo progetto e 150+ in totale, il sistema di governance Eager/Lazy che avevo costruito con cura cominciava a soffocare. I file degli agenti, che dovevano essere leggeri, pesavano 5200 linee cumulative. Il contesto auto-caricato aumentava più velocemente della mia capacità di controllarlo. Questo articolo racconta come ho concepito un meccanismo di backup — tra sliding window e onda fredda identica — per mantenere un contesto attivo leggero senza mai perdere nulla.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_segnale_5200_linee">Il Segnale : 5200 linee</h2> <div class="sectionbody"> <div class="paragraph"> <p>Sono in piena sessione 048 su`magic-stick`, il mio progetto di build dell’ISO Linux live. Opcode mi guarda. Come sempre, ha caricato automaticamente i miei file Eager all’inizio della sessione —<code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Niente d’anormale.</p> </div> <div class="paragraph"> <p>Ma qualcosa non va. Le risposte sono più lente. Il ragionamento è più diluito. L’agente dimentica dei dettagli che aveva sotto gli occhi due messaggi fa.</p> </div> <div class="paragraph"> <p>Apro un terminale e digito:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">wc -l .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="paragraph"> <p>260 righe per INDEX. 55 per SESSIONS_HISTORY.<strong>1756 per COMPLETED_TASKS_ARCHIVE</strong>.</p> </div> <div class="paragraph"> <p>Il dossier`sessions/`aggiunge ancora ~3200 linee. Totale :<strong>5200 righe</strong>di contesto che si caricano, in un modo o nell’altro, nel cervello temporaneo dell’agente.</p> </div> <div class="paragraph"> <p>La strategia Eager/Lazy che avevo teorizzato nell’articolo precedente funziona — ma ha un difetto congenito che non avevo anticipato: non ha<strong>nessun meccanismo di invecchiamento</strong>. Ogni sessione aggiunge una riga a INDEX, un paragrafo a COMPLETED_TASKS, un file in sessions/. Niente esce mai. Il contesto è una palla di neve che cresce a ogni nuova sessione.</p> </div> <div id="diag-growth" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ae8693f7d2461d1384eba54b7248bd0b.svg" alt="Courbe de croissance des fichiers agents — de la session 1 à 48" width="415" height="591"> </div> </div> <div class="paragraph"> <p>Non è un bug, è una conseguenza diretta della procedura di chiusura della sessione che archivia meticolosamente ogni dettaglio. Il sistema è vittima del proprio successo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_diagnosi_ridondanza_tripla">La Diagnosi: Ridondanza Tripla</h2> <div class="sectionbody"> <div class="paragraph"> <p>Chiedo all’agente di diagnosticare il problema. La sua risposta è immediata e chirurgica.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">file</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Linee</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ruolo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problema</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">260+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (auto-caricato)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabella di tutte le sessioni dalla 001 —<strong>+1 riga per sessione</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/SESSIONS_HISTORY.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">55</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">avido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tabella riepilogativa —<strong>ridondanza con INDEX</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1756</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (implicito)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dettagli completi di tutte le sessioni di aprile</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/sessions/*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(no output)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY (supposto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archivi individuali, ma<strong>non utilizzate</strong><mark>#</mark> Comandi CLI di JBake <code>`</code> # Initialize a new JBake project jbake -i</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>L’agente identifica quattro cause radice :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>COMPLETED_TASKS_ARCHIVE assorbe tutto</strong>— Invece di puntare verso gli archivi`.sessions/`, egli copia integralmente ogni sessione.</p> </li> <li> <p><strong>INDEX.adoc serve da storico completo</strong>— La tabella "Sessions Récentes" contiene 30+ voci.</p> </li> <li> <p><strong>SESSIONS_HISTORY.adoc ridondante</strong>— Stessa informazione di INDEX, formato diverso.</p> </li> <li> <p><strong>La regola LAZY non è rispettata</strong>— COMPLETED_TASKS è implicitamente EAGER perché contiene tutto.</p> </li> </ol> </div> <div class="paragraph"> <p>La sua proposta è radicale: limitare INDEX a 10 sessioni, svuotare COMPLETED_TASKS, spostare SESSIONS_HISTORY in LAZY puro. Guadagno immediato:<strong>~1900 linee risparmiate</strong>.</p> </div> <div class="paragraph"> <p>È pulito, efficiente, logico. Ma ho un problema con questo approccio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_perché_ho_rifiutato_la_soluzione_evidente">Perché ho rifiutato la soluzione evidente</h2> <div class="sectionbody"> <div class="paragraph"> <p>La soluzione dell’agente è quella di un ingegnere che ottimizza una cache. Limitare. Troncare. Eliminare le ridondanze.</p> </div> <div class="paragraph"> <p>Ma queste 'ridondanze' non sono tali. Ogni file di governance cattura un<strong>angolo diverso</strong>sulla stessa realtà:</p> </div> <div class="ulist"> <ul> <li> <p><strong>INDEX</strong>vista macro, cruscotto esecutivo</p> </li> <li> <p><strong>SESSIONI_STORICO</strong>= tabella cronologica lineare, segnata</p> </li> <li> <p><strong>COMPLETATO_COMPITI_ARCHIVIO</strong>= narrativa dettagliata con metriche</p> </li> <li> <p>sessions/<strong>.adoc</strong>* = archivi individuali, contesto completo</p> </li> </ul> </div> <div class="paragraph"> <p>Non è una duplicazione stupida. È della<strong>prospettiva multipla strutturata</strong>. Questo è esattamente ciò di cui abbiamo bisogno per distillare — affinché in futuro, un essere umano (o un LLM futuro meglio addestrato) possa incrociare gli angoli e estrarre i modelli.</p> </div> <div class="paragraph"> <p>Immagina un data scientist che ti dice: «Eliminiamo 3 colonne su 6, sono correlate.» Tu cosa gli rispondi? Che la correlazione non è ridondanza quando ogni colonna cattura una dimensione diversa dello stesso fenomeno. Che è proprio questa ricchezza dimensionale che rende il dataset sfruttabile.</p> </div> <div class="paragraph"> <p>È la mia intuizione. E la difendo contro la razionalità fredda dell’agente.</p> </div> <div class="paragraph"> <p>(No output) Non vedo un contenitore silenzioso nella mia idea. Non si mette tutto dentro, si sposta il risultato strutturato della procedura di fine sessione — ogni file con il suo angolo, le sue ridondanze che in realtà sono un arricchimento. Questo materiale multidimensionale sarà migliore per la distillazione. (No output)</p> </div> <div class="paragraph"> <p>L’agente accusa il colpo. E si corregge.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_proposizione_onda_fredda_identica">La Proposizione: Onda Fredda Identica</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’agente allora propone un meccanismo più fine, che rispetta la mia intuizione di dataset ricco risolvendo allo stesso tempo il problema tecnico del contesto che esplode.</p> </div> <div class="paragraph"> <p>Il principio è semplice e si ispira direttamente al pattern<strong>Memoria calda/ti/ fredda</strong>applicato alla gestione degli archivi:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Hot (EAGER)</strong>= le ultime 10 sessioni in INDEX, PROMPT_REPRISE della sessione N+1, gli ultimi 2 file di sessione</p> </li> <li> <p><strong>Caldo (PIGRO)</strong>= SESSIONS_HISTORY recente, SCRIPT_VERIFICATION, tutta la documentazione di riferimento</p> </li> <li> <p><strong>freddo (backup/)</strong>= tutto il resto, spostato<strong>intatto</strong>, senza trasformazione, senza reindicizzazione</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- .agents/ ├── INDEX.adoc → Sessions N-9 à N (10 dernières) ├── SESSIONS_HISTORY.adoc → Sessions N-9 à N ├── SCRIPT_VERIFICATION.adoc → Dernière vérif (pas d'historique) ├── PROMPT_REPRISE.adoc → Session N+1 uniquement ├── sessions/ → Sessions N-1 à N uniquement └── backup/ └── Y2026-sessions-001-039/ ← Vague froide, COPIE INTÉGRALE ├── INDEX.adoc → Sessions 001 à 039 (complet) ├── SESSIONS_HISTORY.adoc → Sessions 001 à 039 (complet) ├── COMPLETED_TASKS_ARCHIVE.adoc → Sessions 001 à 039 (complet) └── sessions/ → 001.adoc, 002.adoc... ---- La chiave del meccanismo:**Il backup non è un indice centrale, è una copia conforme dell'onda passata**. Quando si supera l'orizzonte delle 10 sessioni attive, non si elimina nulla. Non si reindicizza nulla. Non si fonde nulla. Si prende il pacchetto di file degli agenti così com'era alla sessione N-10 e lo si sposta dentro`backup/`. I file attivi, invece, sono troncati: * INDICE : solo le ultime 10 righe (finestra scorrevole) * SESSIONS_HISTORY: idem * COMPLETED_TASKS_ARCHIVE : nuovo file per il periodo in corso * sessions/ : solo le ultime 2 sessioni [plantuml, format=svg, id=diag-hot-warm-cold, alt="Architecture Hot/Warm/Cold du contexte agent — EAGER/LAZY/backup"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Architettura Hot / Warm / Cold dell'Agente di Contesto package "HOT (EAGER) Caricato automaticamente ~300 linee" as HOT #FFCDD2 { file "INDEX.adoc\n(10 sessioni)" as IDX_HOT file "PROMPT_REPRISE\n(session N+1)" as PRO_HOT file "AGENT.adoc\n(regole assolute)" as AG_HOT } package "WARM (LAZY) Caricato su richiesta ~500 linee" as WARM #FFF9C4 { file "SESSIONS_HISTORY (10 ultime)" as HIS_WARM file "SCRIPT_VERIFICATION (ultima)" as VER_WARM file "PROCEDURES.adoc (modelli)" as PRO_WARM file "*_REFERENCE.adoc\n(documento tecnico)" as REF_WARM } package "COLD (backup/)\nMai caricato\nLettura umana solamente" as COLD #BBDEFB { folder "Y2026-001-039/" as WAVE { file "INDEX (complet)" as IDX_COLD file "SESSIONS_HISTORY\n(completo)" as HIS_COLD file "COMPLETED_TASKS\n(completo)" as ARCH_COLD folder "sessioni/ (001-039)" as SESS_COLD } folder "Y2026-040-???\n(futuro)" as FUTURE } HOT --> WARM : "Agente sale se necessario" WARM --> COLD : "Mai automatico L'uomo va da solo" note bottom of COLD Règle : COPIE INTÉGRALE Pas de transformation Pas de réindexation Read-only après archivage end note @enduml ---- Il guadagno immediato è enorme: il contesto EAGER passa da**~5200 righe a ~300 righe**. Una divisione per 17. Senza aver perso nemmeno una riga di dati storici. == Perché questo non è un fourre-tout L'agente, nella sua prima iterazione, temeva che`backup/`diventi una scatola nera — una cartella in cui si gettano file che non si leggeranno mai. È una paura legittima. Ma essa si basa su un equivoco. Un contenitore generico, è quando si gettano i file**senza struttura, senza convenzione, senza logica di raggruppamento**. Qui, il backup è strutturato per periodo (Y2026-001-039), e ogni cartella di backup contiene**la stessa struttura**che il dossier`.agents/`attivo : INDEX, SESSIONS_HISTORY, COMPLETED_TASKS_ARCHIVE, sessions/. Non è un tuttofare. È un**istantanea timestampata**. Si potrebbe anche dire che è un meccanismo di versioning semplificato — a parte che non versiona i file singolarmente, ma l'intero pacchetto di governance in un dato momento. Quando vuoi trovare un'informazione vecchia, non hai bisogno di un indice centrale. Hai due opzioni : 1. **grep` mirato**:`grep -r "zsh" backup/Y2026-001-039/`— e trovi tutto ciò che menziona zsh nel periodo, indipendentemente dall'angolo (INDEX, SESSIONS_HISTORY, archivio di sessione). 2. **Reintegrazione manuale**Copiate temporaneamente la cartella di backup nel contesto attivo e chiedete all'agente di analizzare questo periodo specifico. L'indice è implicito. È nella struttura stessa dei file — ciascuno essendo già un indice dal proprio punto di vista. == La metafora degli scaffali Per rendere il meccanismo intuitivo, l'ho concepito in tre mensole: * **Scaffale 1 (EAGER)**— il piano di lavoro. Ciò di cui ho bisogno *adesso*. INDICE recente, PROMPT_RESUME, regole assolute. Leggero, immediato, critico. * **Scaffale 2 (LAZY)**— la biblioteca di consultazione. Ciò che posso andare a cercare su richiesta. Riferimenti tecnici, storico recente, procedure. Più voluminoso, ma non caricato in memoria. * **Cantina (backup/)**— gli archivi freddi. Tutto ciò che è passato ma che non voglio gettare. L'agente non ci entra mai. L'uomo scende quando vuole distillare. L'agente ha inizialmente proposto una quarta mensola — un`index-backup.adoc`che sarebbe LAZY e conterrebbe una tabella dei contenuti di tutto il backup. L'ho rifiutato. Sarebbe una ridondanza in più in un sistema che già soffre di crescita lineare. La struttura dei file archiviati è già un indice. == Sensore a due trigger La concettualizzazione era solida, ma rimaneva un punto cieco:**Quando esattamente attivare la rotazione?**L'articolo iniziale lo identificava come una domanda aperta. Due giorni dopo, la risposta è codificata nei file di governance di sei progetti: un sensore a due trigger. === Il Trigger Automatico — `N % 10 == 0 Il primo trigger è matematico. Quando il numero di sessione è un multiplo di 10 — sessione 10, 20, 30, 40 — la rotazione di backup viene eseguita automaticamente all'interno della procedura di fine sessione, subito dopo il passaggio 6. Perché 10 ? È il compromesso tra due forze contrapposte: una finestra troppo corta (5 sessioni) perde il contesto necessario alla continuità; una finestra troppo lunga (20 sessioni) non risolve il problema dell'ingombro del contesto. Dieci sessioni, a un ritmo di una o due sessioni al giorno, coprono circa una settimana di lavoro — abbastanza affinché l'agente si ricordi delle decisioni recenti, ma non abbastanza affinché il contesto esploda. === Lo Scatenatore per Soglia — 500 Righe EAGER Il secondo trigger è dinamico. Indipendentemente dal numero di sessione, se i file EAGER cumulati superano**500 righe**, la rotazione si attiva. Questa soglia protegge dallo scenario in cui le sessioni sono eccezionalmente produttive — molto contenuto scritto in poche sessioni. Una sessione che produce 120 linee di contenuto editoriale fa crescere COMPLETED_TASKS_ARCHIVE molto più velocemente rispetto a una sessione di debug che corregge due righe. La soglia di 500 linee, misurata tramite`wc -l .agents/INDEX.adoc .agents/archives/COMPLETED_TASKS_ARCHIVE_*.adoc PROMPT_REPRISE.adoc`, cattura questa asimmetria. === Il Déclencheur Manuel — "rotation backup Infine, l'uomo mantiene il controllo. Le parole chiave`rotation backup`, `backup rotation` ou `lance la rotation backup`avviano la procedura su richiesta, indipendentemente dalla fine della sessione. Utile quando si sente che il contesto sta diventando pesante ma non si è ancora a un multiplo di 10, oppure quando si vuole archiviare una fase di lavoro prima di iniziarne una nuova. [plantuml, format=svg, id=diag-capteur-trigger, alt="Les trois déclencheurs du capteur de rotation backup — automatique, seuil, manuel"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Sensore di Rotation Backup — I tre trigger start :Procédure de fin de session; note right: Mots-clés "fine della sessione"\nou "ci fermiamo lì" :Étapes 1 à 6\n(archivage standard); note right 1. Archive sessions/N.adoc 2. MAJ PROMPT_REPRISE 3. MAJ SESSIONS_HISTORY 4. MAJ INDEX.adoc 5. MAJ TEST_COVERAGE 6. MAJ COMPLETED_TASKS end note if (N % 10 == 0\nOU\nEAGER cumulé > 500 lignes ?) then (oui) :⚙️ Rotation Backup\n(étape 7); note right 1. Créer backup/Y20XX-sessions-X-Y/ 2. Copier intégrale INDEX + HISTORY + COMPLETED_TASKS + sessions/ 3. Tronquer actifs à 10 sessions 4. Ajouter _Localisation active_ end note else (non) :Pas de rotation; endif :Checklist [✅] x 7\n(si applicable); stop @enduml ---- Questo diagramma mostra l'inserimento esatto del sensore nella procedura di fine sessione. Il passaggio 7 è facoltativo — esso viene eseguito solo se una delle due condizioni è vera — ma viene sistematicamente *verificato*. La checklist finale include`[✅] 7. Backup roté (si applicable)`. === Il ciclo chiuso Questo sensore chiude il ciclo aperto dall'articolo precedente. La governance Eager/Lazy aveva risolto il problema della memoria dell'agente tra due sessioni. Il meccanismo Hot/Warm/Cold ha risolto il problema della memoria che aumenta. Il sensore a due trigger risolve il problema del *quando* — togliendo all'uomo il carico mentale di monitorare la dimensione del contesto. [plantuml, format=svg, id=diag-boucle-fermee, alt="Les trois couches de la gouvernance agent — Eager/Lazy, Hot/Warm/Cold, Capteur"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title I Tre Strati della Governance dell'Agente left to right direction package "Livello 1 — Memoria (Articolo 0108)" as C1 #E8F5E9 { rectangle "**EAGER**\nCruscotto\nCaricato automaticamente" as EAG rectangle "**LAZY** Manuale del proprietario Caricato su richiesta" as LAZ EAG -[hidden]right-> LAZ } package "Strato 2 — Invecchiamento (Articolo 0110)" as C2 #FFF9C4 { rectangle "**HOT** 10 sessioni attive ~300 righe" as HOT rectangle "**WARM** Riferimenti Procedure" as WRM rectangle "**COLD** backup/ Onda fredda" as CLD HOT -[hidden]right-> WRM WRM -[hidden]right-> CLD } package "Livello 3 — Attivatore\n(Oggi)" as C3 #BBDEFB { rectangle "**Automatico** N % 10 == 0" as AUTO rectangle "**Soglia** > 500 linee" as SEUIL rectangle "**manuale** rotation backup" as MAN AUTO -[hidden]right-> SEUIL SEUIL -[hidden]right-> MAN } C1 --> C2 : "La memoria cresce\n→ è necessario un meccanismo\ndell'invecchiamento" C2 --> C3 : "L'invecchiamento → serve un trigger per eseguirlo" note bottom of C3 ✅ Déployé sur 6 projets magic-stick · bakery-gradle plantuml-gradle · cheroliv.com jhipster-gradle-plugins quizz-benchmark-gradle end note @enduml ---- Le tre strati si sovrappongono logicamente. Il primo fornisce una memoria all'agente. Il secondo impedisce che questa memoria soffochi l'agente. Il terzo automatizza la manutenzione di questa memoria affinché l'uomo non debba pensarci. === La Migrazione Efficace su cheroliv.com Il meccanismo non è rimasto teorico. Su`cheroliv.com`, la prima rotazione di backup è stata eseguita il 29 aprile 2026 — le sessioni da -6 a 2 sono state migrate verso`.agents/backup/Y2026-sessions-neg6-a-002/`: |=== |File |Prima della rotazione |Dopo rotazione |guadagno |`.agents/INDEX.adoc` |19 sessioni elencate |10 sessioni (3-12) |-9 voci |`.agents/SESSIONS_HISTORY.adoc` |18 sessioni |10 sessioni |-8 voci |`COMPLETED_TASKS_ARCHIVE` |161 righe (sessioni 1-12) |135 linee (sessioni 3-12) |-26 linee |`sessions/` |20 file |10 file |-10 file |**backup/** |Inesistente |1 ondata fredda (10 sessioni archiviate) |+1 pacchetto freddo |=== Il guadagno in righe era modesto — il progetto è giovane, 12 sessioni — ma l'importante è che il**Il meccanismo è in atto**. La prossima rotazione automatica si attiverà alla sessione 20, o prima se le 500 linee EAGER vengono raggiunte. == La Lezione Agente-Umano Questa sessione 048 mi ha insegnato qualcosa di fondamentale sulla collaborazione con un agente IA. L'agente ha un pregiudizio naturale: cerca di**ottimizzare**, à **semplificare**, à **eliminare le ridondanze**. È il pregiudizio di un sistema addestrato a produrre risposte pulite e concise. Di fronte a un dataset ricco e multidimensionale, il suo primo riflesso è di ridurlo alla sua forma più semplice. L'uomo, lui, ha un'intuizione diversa: intuisce che la ridondanza strutturata è un**vantaggio**, non è un difetto. Che la diversità degli angoli su una stessa realtà è precisamente ciò che permetterà, più tardi, una distillazione di qualità. Non è che l'agente abbia tort. È che il suo "optimum" non è il mio. L'agente ottimizza per il**presente**— il contesto immediato, la risposta rapida alla domanda posta. L'umano ottimizza per il**futuro**— la capacità di ritrovare, incrociare, distillare entro tre mesi o tre anni (No output) Ciò che voglio è il materiale grezzo. Le tue riflessioni, le tue esitazioni, le tue risposte alle mie domande. Non la tua sintesi. La sintesi so farla meglio di te. Voglio la materia prima. (No output) Questa frase che gli ho detto alla fine della sessione riassume tutto. L'agente è uno strumento di produzione. L'uomo è lo strumento di distillazione. La governance non è fatta affinché l'agente capisca tutto da sola — è fatta affinché l'uomo possa, più tardi, lavorare il materiale prodotto. L'onda fredda identica è la traduzione architettonica di questa filosofia: non si butta nulla, non si fonde nulla, non si reindicizza nulla. Si sposta il pacchetto intatto. La distillazione arriverà più tardi, a mano, dall'essere umano. == Il seguito logico dell'articolo precedente Se hai lettolink:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[l'articolo sulla strategia Eager/Lazy], riconoscerete la progressione naturale : 1. **Article 0108**— La governance Eager/Lazy : *come* strutturare il contesto dell'agente su due livelli di disponibilità 2. **Questo articolo 0110**— Il meccanismo di backup : *comment* far invecchiare questo contesto senza perderlo quando diventa troppo voluminoso Il primo articolo rispondeva alla domanda: « L'agente non ricorda nulla tra due sessioni, come dargli una memoria? Questo risponde alla domanda che deriva inevitabilmente dalla prima: « La memoria aumenta ad ogni sessione, come impedirle di soffocare l'agente senza cancellarla ? La risposta si riduce a un pattern**caldo/tiepido/freddo**, applicato ai file di governance. E in un principio:**non perdere mai nulla, sempre ricollocare tutto**. == link * Articolo precedente :link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Governare un agente IA con AsciiDoc] * Il mio sito: https://cheroliv.com * Il progetto`magic-stick`: https://github.com/cheroliv/magic-stick --- *Un buon sistema di governance non elimina mai dati. Li archivia.* ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html Sat, 25 Apr 2026 00:00:00 +0000 blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scena_un_progetto_jhipster_un_build_che_non_si_carica_più">La scena: un progetto JHipster, un build che non si carica più</a></li> <li><a href="#_errore_1_la_variabile_fantasma_reportsdir">Errore 1 : la variabile fantasma `reportsDir</a></li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset">Clear the output directory before baking jbake -b . output --reset <code>`</code></a> <ul class="sectlevel1"> <li><a href="#_errore_2_main_non_esiste_più_in_gradle_9">Errore 2 : <code>main = "…​"</code> non esiste più in Gradle 9</a></li> <li><a href="#_errore_3_sourcecompatibility_non_è_più_una_proprietà_del_progetto">Errore 3 : <code>sourceCompatibility</code> non è più una proprietà del progetto</a></li> <li><a href="#_errore_4_lasserzione_groovy_con_tre_operandi">Errore 4 : l’asserzione Groovy con tre operandi</a></li> <li><a href="#_errore_5_la_dipendenza_implicita_compilekotlin_openapigenerate">Errore 5 : la dipendenza implicita <code>compileKotlin</code> → `openApiGenerate</a></li> </ul> </li> <li><a href="#_bake_generate_the_site_jbake_b_2">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s_2">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset_2">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder_2">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset_traduci_dal_francese_allitaliano_preserva_tutti_gli_span_di_codice_tra_backticks_esattamente_così_mai_modificare_il_contenuto_dei_backticks_spaziatura_o_posizione_questo_testo_può_essere_un_frammento_di_una_frase_più_ampia_traduci_il_frammento_senza_richiedere_ulteriori_contesto_emetti_solo_il_testo_tradotto_nessuna_spiegazione_nessun_commento_nessuna_introduzione_nessuna_alternativa_nessuna_opzione_è_unestensione_plugin_openapi_generator_e_non_è_unattività_direttamente_accessibile_durante_la_fase_di_configurazione">Clear the output directory before baking jbake -b . output --reset <code>`</code> Traduci dal francese all’italiano. Preserva tutti gli span di codice tra backticks (<code>…​</code>) esattamente così — mai modificare il contenuto dei backticks, spaziatura o posizione. Questo testo può essere un frammento di una frase più ampia — traduci il frammento senza richiedere ulteriori contesto. Emetti solo il testo tradotto — nessuna spiegazione, nessun commento, nessuna introduzione, nessuna alternativa, nessuna opzione. è un’estensione (plugin OpenAPI Generator) e non è un’attività direttamente accessibile durante la fase di configurazione.</a> <ul class="sectlevel1"> <li><a href="#_errore_6_generategitproperties_si_interrompe_su_filteroutputstream_write">Errore 6 : <code>generateGitProperties</code> si interrompe su `FilterOutputStream.write()</a></li> <li><a href="#_finalmente_testcontainers_entra_in_scena">Finalmente: Testcontainers entra in scena</a></li> <li><a href="#_fase_1_la_pista_docker_java">Fase 1: la pista docker-java</a></li> <li><a href="#_fase_2_ricerca_web_e_breadcrumb_di_github">Fase 2: ricerca web e breadcrumb di GitHub</a></li> <li><a href="#_fase_3_la_trappola_degli_artefatti_rinominati">Fase 3: la trappola degli artefatti rinominati</a></li> <li><a href="#_fase_4_forzare_la_risoluzione">Fase 4: forzare la risoluzione</a></li> <li><a href="#_risultato_finale">Risultato finale</a></li> <li><a href="#_tabella_riepilogativa_delle_correzioni">Tabella riepilogativa delle correzioni</a></li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 15 minutes</div> <p>Hai già conosciuto quel momento in cui un semplice`./gradlew build`che lanci cento volte al giorno si blocca improvvisamente su un errore mai visto? Moltiplicalo per undici errori consecutivi, aggiungi una buona dose di incompatibilità Docker Engine 29, cospargi di Gradle 9 che fa scomparire le API che usavate da dieci anni. Ecco il diario di bordo completo.</p> </div> <hr> <div class="paragraph"> <div class="title">Diagramma 1 — Migrazione Gradle 9 (catena di errori)</div> <p>Obiettivo: mostrare la serie di incompatibilità.</p> </div> <div class="listingblock"> <div class="title">👉 Chiaro, focalizzato su Gradle.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml left to right direction title Migrazione Gradle 9 rectangle "1 ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml left to right direction title Migrazione Gradle 9 rectangle "1 reportsDir" as A rectangle "2 mainClass" as B rectangle "3\nsourceCompatibility" as C rectangle "4 Groovy assert" as D A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">Diagramma 2 — Plugin JHipster incompatibili</div> <p>Obiettivo: isolare i plugin rotti.</p> </div> <div class="listingblock"> <div class="title">👉 Visione pulita delle dipendenze.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml left to right direction title Plugin da correggere skinparam shadowing false skinparam roundcorner 18 rectangle "1\nopenApiGenerate" as A #FFF3E0 rectangle "2 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml left to right direction title Plugin da correggere skinparam shadowing false skinparam roundcorner 18 rectangle "1\nopenApiGenerate" as A #FFF3E0 rectangle "2 gitProperties 2.5.7" as B #FFF3E0 rectangle "3 Versioni corrette" as C #E3F2FD rectangle "4\nAssembla OK" as D #E8F5E9 A --> B B --> C C --> D @enduml</pre> </div> </div> <hr> <div class="paragraph"> <div class="title">Diagramma 3 — Docker 29 / Testcontainers</div> <p>Obiettivo: problema runtime.</p> </div> <div class="listingblock"> <div class="title">👉 Storia chiara del runtime.</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 10) ] @startuml left to right direction title Docker 29 + Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1\nAssemblaggio OK" as A #E8F5E9 rectangle "2 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml left to right direction title Docker 29 + Testcontainers skinparam shadowing false skinparam roundcorner 18 skinparam defaultFontSize 14 rectangle "1\nAssemblaggio OK" as A #E8F5E9 rectangle "2 Test di Cucumber fallito" as B #FFEBEE rectangle "3 Testcontainers 1.32 rifiutato" as C #FFF3E0 rectangle "4 Upgrade versioni" as D #E3F2FD rectangle "5 Costruisci finale OK" as E #E8F5E9 A --> B B --> C C --> D D --> E @enduml</pre> </div> </div> <hr> <div class="listingblock"> <div class="title">un altro modo di rappresentarselo</div> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 17) ] @startuml skinparam backgroundColor #FEFEFE skinparam shadowing false skinparam defaultFontName Inter skinparam defaultFontSize 14 skinparam ArrowThickness 2 skinparam RoundCorner 18 title Roadmap di Stabilizzazione — Gradle 9 verso Build Finale left to right direction rectangle "�⚙️ Migrazione Gradle 9" as A #E3F2FD rectangle "🧩 Plugin JHipster" as B #FFF3E0 rectangle "�🐳 Docker 29 ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml !option handwritten true skinparam backgroundColor #FEFEFE skinparam shadowing false skinparam defaultFontName Inter skinparam defaultFontSize 14 skinparam ArrowThickness 2 skinparam RoundCorner 18 title Roadmap di Stabilizzazione — Gradle 9 verso Build Finale left to right direction rectangle "�⚙️ Migrazione Gradle 9" as A #E3F2FD rectangle "🧩 Plugin JHipster" as B #FFF3E0 rectangle "�🐳 Docker 29 Testcontainers" as C #FCE4EC rectangle "### Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin Gradle JBake o chiamando direttamente l'interfaccia a riga di comando JBake: ```kotlin tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") }" as D #E8F5E9 note bottom of A reportsDir mainClass sourceCompatibility Groovy assert end note note bottom of B openApiGenerate gitProperties versions alignées end note note bottom of C tests Cucumber KO image Docker rejetée upgrade libs end note A -[#42A5F5]-> B : corrections build.gradle B -[#FB8C00]-> C : assemble OK C -[#E53935]-> D : tests réparés @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_scena_un_progetto_jhipster_un_build_che_non_si_carica_più">La scena: un progetto JHipster, un build che non si carica più</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il progetto`edster`è un’applicazione JHipster generata nel 2024. Lo script di build della radice`build.gradle`è rimasto stabile per mesi. Poi si decide di passare alla versione :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.0909%;"> <col style="width: 9.091%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Componente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Version cible</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9.4.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21.0.11-tem (Eclipse Temurin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JHipster</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8.x (framework)<code>tech.jhipster:jhipster-framework:8.11.0</code>)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Spring Boot</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3.4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><mark>#</mark> Integrazione Gradle JBake può essere integrato nei build Gradle utilizzando il plugin Gradle JBake oppure richiamando direttamente la CLI JBake :</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Il passaggio alla versione Java avviene tramite SDKMAN :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk use java 21.0.11-tem</code></pre> </div> </div> <div class="paragraph"> <p>Primo lancio:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon FAILURE: Build failed with an exception. * Where: Build file '/home/.../edster/build.gradle' line: 18 * What went wrong: An exception occurred applying plugin request [id: 'jhipster.cucumber-conventions'] > Failed to apply plugin 'jhipster.cucumber-conventions'. > Could not create task ':cucumberTest'. > Could not create task ':consoleLauncherTest'. > Could not set unknown property 'reportsDir' for task ':consoleLauncherTest'</code></pre> </div> </div> <div class="paragraph"> <p>Non riusciamo nemmeno a partire dal caricamento dello script di build. Il problema è in`buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_errore_1_la_variabile_fantasma_reportsdir">Errore 1 : la variabile fantasma `reportsDir</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo script`jhipster.cucumber-conventions.gradle`contiene :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">tasks.register('consoleLauncherTest', JavaExec) { dependsOn(testClasses) String cucumberReportsDir = file("$buildDir/reports/tests") outputs.dir(reportsDir) // <-- reportsDir n'existe PAS classpath = sourceSets["test"].runtimeClasspath main = "org.junit.platform.console.ConsoleLauncher" // ... }</code></pre> </div> </div> <div class="paragraph"> <p>La variabile definita è`cucumberReportsDir`<mark>#</mark> JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code></h1> <div class="olist arabic"> <ol class="arabic"> <li> <p>Quella utilizzata è`reportsDir`-- che non è definita da nessuna parte.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Correzione</strong>:`outputs.dir(cucumberReportsDir)`</p> </div> <div class="sect1"> <h2 id="_errore_2_main_non_esiste_più_in_gradle_9">Errore 2 : <code>main = "…​"</code> non esiste più in Gradle 9</h2> <div class="sectionbody"> <div class="paragraph"> <p>Rilancio immediato :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'main' for task ':consoleLauncherTest' of type org.gradle.api.tasks.JavaExec.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 rimuove la proprietà`main`a favore di`mainClass`sui compiti`JavaExec`.</p> </div> <div class="paragraph"> <p><strong>Correzione</strong></think> :`mainClass = "org.junit.platform.console.ConsoleLauncher"`</p> </div> </div> </div> <div class="sect1"> <h2 id="_errore_3_sourcecompatibility_non_è_più_una_proprietà_del_progetto">Errore 3 : <code>sourceCompatibility</code> non è più una proprietà del progetto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nuovo errore :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'sourceCompatibility' for root project 'edster' of type org.gradle.api.Project.</code></pre> </div> </div> <div class="paragraph"> <p>Lo script radice aveva :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">sourceCompatibility=17 targetCompatibility=17</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 rimuove queste proprietà a livello root. Devono vivere in un blocco`java`.</p> </div> <div class="paragraph"> <p><strong>Correzione</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">java { sourceCompatibility = JavaVersion.VERSION_21 targetCompatibility = JavaVersion.VERSION_21 }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_errore_4_lasserzione_groovy_con_tre_operandi">Errore 4 : l’asserzione Groovy con tre operandi</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo script precedente conteneva :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] == "17" || "21" || "24"</code></pre> </div> </div> <div class="paragraph"> <p>In Groovy,<code>"21"</code> et <code>"24"`sono delle strings truthy. L’espressione risolve in</code>(…​ == "17") || true || true`, ciò che è sempre vero — ma la sintassi è non valida per l’asserzione rigorosa desiderata.</p> </div> <div class="paragraph"> <p><strong>Correzione</strong>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] in ["17", "21", "23", "24"]</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_errore_5_la_dipendenza_implicita_compilekotlin_openapigenerate">Errore 5 : la dipendenza implicita <code>compileKotlin</code> → `openApiGenerate</h2> <div class="sectionbody"> <div class="paragraph"> <p>La build procede. Compilazione Kotlin riuscita. Poi :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Task ':compileKotlin' uses this output of task ':openApiGenerate' without declaring an explicit or implicit dependency.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 rifiuta le dipendenze implicite tra le attività. Poiché`compileKotlin`legge le fonti generate da`openApiGenerate`, è necessario dichiarare il collegamento.</p> </div> <div class="paragraph"> <p><strong>Correzione</strong>in`build.gradle`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">afterEvaluate { tasks.named("compileKotlin").configure { dependsOn(tasks.named("openApiGenerate")) } }</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>afterEvaluate`è necessario perché`openApiGenerate`JBake riferimento (questo contenuto utilizza i modelli e le convenzioni di JBake): <mark>#</mark> Comandi CLI JBake ``</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b_2" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s_2" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset_2" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder_2" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset_traduci_dal_francese_allitaliano_preserva_tutti_gli_span_di_codice_tra_backticks_esattamente_così_mai_modificare_il_contenuto_dei_backticks_spaziatura_o_posizione_questo_testo_può_essere_un_frammento_di_una_frase_più_ampia_traduci_il_frammento_senza_richiedere_ulteriori_contesto_emetti_solo_il_testo_tradotto_nessuna_spiegazione_nessun_commento_nessuna_introduzione_nessuna_alternativa_nessuna_opzione_è_unestensione_plugin_openapi_generator_e_non_è_unattività_direttamente_accessibile_durante_la_fase_di_configurazione" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code> Traduci dal francese all’italiano. Preserva tutti gli span di codice tra backticks (<code>…​</code>) esattamente così — mai modificare il contenuto dei backticks, spaziatura o posizione. Questo testo può essere un frammento di una frase più ampia — traduci il frammento senza richiedere ulteriori contesto. Emetti solo il testo tradotto — nessuna spiegazione, nessun commento, nessuna introduzione, nessuna alternativa, nessuna opzione. è un’estensione (plugin OpenAPI Generator) e non è un’attività direttamente accessibile durante la fase di configurazione.</h1> <div class="sect1"> <h2 id="_errore_6_generategitproperties_si_interrompe_su_filteroutputstream_write">Errore 6 : <code>generateGitProperties</code> si interrompe su `FilterOutputStream.write()</h2> <div class="sectionbody"> <div class="paragraph"> <p>La compilazione Java passa. Le risorse sono elaborate. Poi :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">> Task :generateGitProperties FAILED No signature of method: java.io.FilterOutputStream.write() is applicable for argument types: (Integer) values: [103]</code></pre> </div> </div> <div class="paragraph"> <p>Il plugin`gradle-git-properties`versione 2.5.0 è incompatibile con Java 21 / Gradle 9. Un bug interno tenta di chiamare`write(int)`via Groovy su un flusso che l’ha chiuso</p> </div> <div class="paragraph"> <p><strong>Correzione</strong>in`gradle.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties">gitPropertiesPluginVersion=2.5.7</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_finalmente_testcontainers_entra_in_scena">Finalmente: Testcontainers entra in scena</h2> <div class="sectionbody"> <div class="paragraph"> <p>Finora, era puro "debugging degli script di build". Ogni errore era un’incompatibilità Gradle 9 o Java 21 negli script di build. Dopo le sei correzioni sopra, il`./gradlew assemble`passa con successo.</p> </div> <div class="paragraph"> <p>ma`./gradlew build`esegue anche i test, e i test Cucumber utilizzano Testcontainers per avviare un PostgreSQL effimero.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not find a valid Docker environment. EnvironmentAndSystemPropertyClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"} UnixSocketClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"}</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers è incapace di comunicare con Docker. Due strategie diverse (variabili d’ambiente + socket Unix) falliscono nello stesso errore.</p> </div> <div id="diag-docker-handshake" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false actor "Testcontainers 1.20.6" as TC participant "docker-java\n3.4.1" as DJ participant "Docker Engine 29.4.1" as DE TC -> DJ : new DockerClient() DJ -> DE : GET /_ping\nUser-Agent: docker-java/3.4.1\nAPI-Version: 1.32 DE --> DJ : HTTP 400 Bad Request\nclient version 1.32 is too old.\nMinimum supported API version is 1.40 DJ --> TC : BadRequestException TC --> TC : Could not find a valid\nDocker environment note right of DE Docker Engine 29.x impose API minimum = 1.40 (défaut ancien : 1.24) end note note left of DJ docker-java 3.4.1 envoie hardcoded API version 1.32 dans l'en-tête HTTP end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_1_la_pista_docker_java">Fase 1: la pista docker-java</h2> <div class="sectionbody"> <div class="paragraph"> <p>Primo riflesso: il client Docker Java utilizzato da Testcontainers invia la versione API`1.32`nel suo handshake HTTP, ma Docker Engine 29.4.1 richiede un minimo di`1.40`. Il problema è a livello del client, non del daemon.</p> </div> <div class="paragraph"> <p>Verifica della versione di docker-java risolta da Testcontainers 1.20.6 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew dependencies --configuration testRuntimeClasspath | grep docker-java +--- com.github.docker-java:docker-java-api:3.4.1 +--- com.github.docker-java:docker-java-transport:3.4.1</code></pre> </div> </div> <div class="paragraph"> <p>docker-java 3.4.1, datato da Testcontainers 1.20.6. L’ultima versione pubblica di docker-java è 3.5.1. Proviamo a forzare l’aggiornamento della versione tramite`resolutionStrategy`nel blocco`configurations` de <code>build.gradle</code>(no output)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.5.1") } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Riavvio della build. Stesso errore:`client version 1.32 is too old`.</p> </div> <div class="paragraph"> <p>Verifica della cache Gradle: i JAR sono stati effettivamente riscaricati, ma l’errore persiste. docker-java 3.5.1 invia sempre`1.32`. Questa versione quindi NON è sufficiente per Docker Engine 29.4.1.</p> </div> <div class="paragraph"> <p><strong>Azione di purificazione</strong>: svuotare completamente la cache Gradle, solo per essere sicuri :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">rm -rf ~/.gradle/caches rm -rf /path/to/project/.gradle</code></pre> </div> </div> <div class="paragraph"> <p>Riavvio completo dopo la pulizia. Stesso errore.</p> </div> </div> </div> <div class="sect1"> <h2 id="_fase_2_ricerca_web_e_breadcrumb_di_github">Fase 2: ricerca web e breadcrumb di GitHub</h2> <div class="sectionbody"> <div class="paragraph"> <p>docker-java 3.5.1 è insufficiente. Non resta altro che cercare se qualcuno ha riscontrato questo problema esatto.</p> </div> <div class="paragraph"> <p>Ricerca mirata sulle issue testcontainers-java e docker-java :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">site:github.com/testcontainers "client version 1.32 is too old" site:github.com/docker-java "client version 1.32" Docker Engine 29</code></pre> </div> </div> <div class="paragraph"> <p>Primi risultati immediati :</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11210">testcontainers-java#11210</a>—<code>[Bug]: client version 1.32 is too old. Minimum supported API version is 1.44</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11212">testcontainers-java#11212</a>—<code>[Bug]: Docker 29.0.0 could not find a valid Docker environment</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11491">testcontainers-java#11491</a>—<code>[Bug]: Incompatibility in Ubuntu Github runners with Docker Engine 29.1.*</code></p> </li> </ul> </div> <div class="paragraph"> <p>Il breadcrumb è chiaro : Docker Engine 29.x ha innalzato la sua versione minima dell’API di`1.24`(difetto precedente) a`1.40`. Testcontainers 1.20.x utilizza docker-java 3.4.x che negozia la versione API inviando`1.32`. Il daemon rifiuta cortesemente ma fermemente.</p> </div> <div class="paragraph"> <p>Nell’issue #11491, un manutentore risponde:</p> </div> <div class="paragraph"> <p>(No output) Ciao, ho un progetto in esecuzione con la versione 2.0.3 su un runner GH con engine 29.1 e funziona. Potete tutti per favore controllare che non ci sia un conflitto di versione? Please, remember all modules were prefixed with <code>testcontainers-</code>. Così, a partire dalla versione 2.x siamo passati da`postgresql` to <code>testcontainers-postgresql</code> (No output)</p> </div> <div class="paragraph"> <p>Questa risposta contiene<strong>due informazioni critiche</strong></think> (No output)</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Testcontainers 2.0.3+ risolve il problema</p> </li> <li> <p>I moduli sono stati<strong>rinominati con il prefisso `testcontainers-</strong></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_fase_3_la_trappola_degli_artefatti_rinominati">Fase 3: la trappola degli artefatti rinominati</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il rinominamento è brutale. In Testcontainers 2.x, nessun nome precedente funziona più sotto questo nome :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Vecchio nome (1.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nuovo nome (2.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">invariato</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Primo tentativo: applicare la BOM Testcontainers 2.0.5 e i nuovi nomi degli artefatti in`build.gradle`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers" }</code></pre> </div> </div> <div class="paragraph"> <p><code>./gradlew build</code></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">FAILURE: Could not find org.testcontainers:jdbc:2.0.5. Could not find org.testcontainers:junit-jupiter:2.0.5.</code></pre> </div> </div> <div class="paragraph"> <p><strong>Il BOM di <code>testcontainers-bom</code> non è sufficiente.</strong>Perché? Perché Spring Boot 3.4.5 espone il proprio BOM di gestione delle dipendenze (<code>spring-boot-dependencies</code>) che<strong>vince</strong>sul BOM di Testcontainers nella risoluzione trasitiva. Spring Boot corregge`testcontainers` à <code>1.20.6</code>, e quindi tutti gli artifact che non sono esplicitamente nel BOM di Spring Boot (come i nuovi`testcontainers-*<code>) risolvono verso i vecchi nomi`1.20.6</code>-- che non esistono più in questa versione.</p> </div> <div class="paragraph"> <p>Ispezionando il`dependencies --configuration testRuntimeClasspath`, si trova:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">+--- org.testcontainers:testcontainers -> 1.20.6 (*) | \--- org.testcontainers:testcontainers:2.0.5 -> 1.20.6</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>→`indica la sostituzione : Testcontainers 2.0.5 è <strong>richiesto</strong>, ma Spring Boot forza`1.20.6</code>.</p> </div> <div id="diag-bom-war" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle (consumatore)" as BG #E3F2FD { rectangle "richiesta `testcontainers-bom:2.0.5" as REQ rectangle "richiesta `testcontainers-postgresql" as REQ2 } component "Maven Centrale" as MC #FFF3E0 component "Dichiarazioni" as DEC #E8F5E9 { rectangle "testcontainers-bom:2.0.5` fissa 2.0.5" as BOM2 rectangle "spring-boot-dependencies:3.4.5`\ncorregge 1.20.6" as BOM1 } component "Risoluzione Gradle" as RES #FFEBEE { rectangle "Versione vincente\n`testcontainers:1.20.6" as WIN #EF9A9A } BG --> DEC : "analizza i BOM" BOM2 --> RES : "propone 2.0.5" BOM1 --> RES : "propone 1.20.6" WIN -> MC : "scarica\ntestcontainers:1.20.6" note bottom of WIN Spring Boot BOM prime car le plugin spring-boot applique ses dépendances de gestion après la résolution du consommateur end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_4_forzare_la_risoluzione">Fase 4: forzare la risoluzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>La strategia diventa doppia:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Forzare docker-java alla sua versione 3.7.1 (testato come compatibile con Docker Engine 29)</p> </li> <li> <p>Forzare Testcontainers core alla versione 2.0.5 aggirando il BOM di Spring Boot</p> </li> </ol> </div> <div id="diag-resolution-override" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle ^^^^^ Syntax Error? (Assumed diagram type: class) @startuml skinparam backgroundColor #FEFEFE skinparam handwritten false skinparam componentStyle rectangle left to right direction component "build.gradle (con resolutionStrategy)" as BG #E8F5E9 { rectangle "BOM Testcontainers `2.0.5" as BOM2 rectangle "resolutionStrategy\n.eachDependency" as RS #66BB6A } component "Conflitto risolto" as RESOLVED #E3F2FD { rectangle "docker-java\n`3.7.1` (forzato)" as DJ rectangle "testcontainers `2.0.5` (forzato)" as TC #81C784 rectangle "testcontainers-postgresql `2.0.5" as TPG rectangle "testcontainers-jdbc\n`2.0.5" as TJ rectangle "testcontainers-junit-jupiter `2.0.5" as TJJ } component "BOM Spring Boot\n(implicito, superato)" as BOM1 #FFEBEE component "Maven Central" as MC #FFF3E0 BG --> RESOLVED : "BOM Testcontainers 2.0.5 passa direttamente" RS -> DJ : "forza 3.7.1" RS -> TC : "forza 2.0.5" RESOLVED --> MC : "scarica i JAR compatibili Docker 29" BOM1 -[#gray,dashed]-> RESOLVED : "ignorato su testcontainers\net docker-java" note bottom of RS Le `eachDependency` intercepte la résolution Gradle AVANT que le BOM Spring Boot ne gagne. C'est une intervention chirurgicale. end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Correzione finale</strong>in`build.gradle`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.7.1") } if (details.requested.group == "org.testcontainers" && details.requested.name == "testcontainers") { details.useVersion("2.0.5") } } } } dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers" // ... autres dépendances Spring Boot }</code></pre> </div> </div> <div class="paragraph"> <p>Le `resolutionStrategy.eachDependency`è l’unico modo per superare il BOM`spring-boot-dependencies`gestito dal plugin Spring Boot. Il test di uguaglianza su`details.requested.name == "testcontainers"`è volontariamente restrittivo: si impone solo il modulo core. I moduli`testcontainers-*`seguono la BOM di Testcontainers 2.0.5 che abbiamo dichiarato esplicitamente</p> </div> </div> </div> <div class="sect1"> <h2 id="_risultato_finale">Risultato finale</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon > Task :consoleLauncherTest [2 containers found] [2 containers started] [2 containers successful] BUILD SUCCESSFUL in 1m 16s</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers 2.0.5 + docker-java 3.7.1 riescono finalmente a creare i loro container PostgreSQL tramite Docker Engine 29.4.1. L’errore di dominio finale (HTTP 500 sul test Cucumber) è un problema applicativo totalmente indipendente dallo script di build.</p> </div> </div> </div> <div class="sect1"> <h2 id="_tabella_riepilogativa_delle_correzioni">Tabella riepilogativa delle correzioni</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">(no output)</th> <th class="tableblock halign-left valign-top">File</th> <th class="tableblock halign-left valign-top">Problema</th> <th class="tableblock halign-left valign-top">Correzione</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">variabile`reportsDir`inexistente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>outputs.dir(cucumberReportsDir)</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`main`deprecato Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mainClass</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`sourceCompatibility`top-level vietato Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">blocco`java { sourceCompatibility = JavaVersion.VERSION_21 }`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Affermazione Groovy sintatticamente non valida</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assert …​ in ["17", "21", "23", "24"]</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dipendenza implicita`compileKotlin`→<code>openApiGenerate</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>afterEvaluate { tasks.named("compileKotlin").dependsOn("openApiGenerate") }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle.properties</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gitPropertiesPluginVersion</code> incompatible Java 21</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>2.5.7</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cache Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">docker-java 3.5.1 testato, risolto ma insufficiente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Purga + passaggio docker-java 3.7.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Testcontainers 1.20.6 incompatibile con Docker Engine 29</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Forzatura Testcontainers 2.0.5 + prefisso`testcontainers-*`+ resolutionStrategy vs Spring Boot BOM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se il tuo build JHipster/Gradle si blocca dopo un aggiornamento alla versione di Gradle 9 + Docker Engine 29, gli errori si suddividono in due categorie :</p> </div> <div class="paragraph"> <p><strong>Errori di script di build</strong>(le prime 6) : Gradle 9 rimuove proprietà e sintassi che funzionavano da anni`sourceCompatibility=<code>, `main =</code>, <code>reportsDir</code>). Sono migrazioni meccaniche una volta che si conosce la nuova API.</p> </div> <div class="paragraph"> <p><strong>Errori di runtime Docker</strong>(le ultime 2) : Docker Engine 29.4.1 esclude i client API < 1.40. Testcontainers 1.20.6 (imposto da Spring Boot 3.4.5) utilizza docker-java 3.4.1 che invia la versione 1.32. Solo Testcontainers 2.0.5 + docker-java 3.7.1 risolvono il problema, con il rinominare gli artefatti e forzare la versione tramite`resolutionStrategy.eachDependency`come unico modo per aggirare il BOM implicito di Spring Boot.</p> </div> <div class="paragraph"> <p>Lo script di build Gradle alla radice del progetto è ora pulito.`./gradlew build`passa a Java 21, Gradle 9.4.1, Spring Boot 3.4.5 e Docker Engine 29.4.1.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0107_jbake_serve_rendering_bug_fix_post.html Wed, 22 Apr 2026 00:00:00 +0000 blog/2026/0107_jbake_serve_rendering_bug_fix_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scena_quattro_screenshot_due_rendering">La scena: quattro screenshot, due rendering</a> <ul class="sectlevel2"> <li><a href="#_rendu_local">Rendu local</a></li> <li><a href="#_resa_online">Resa online</a></li> </ul> </li> <li><a href="#_la_diagnosi_serve_non_puntava_verso_la_cartella_corretta">La diagnosi : <code>serve</code> non puntava verso la cartella corretta</a></li> <li><a href="#_la_causa_radice_jbake_cli_non_funziona_così">La causa radice: JBake CLI non funziona così</a></li> <li><a href="#_la_soluzione_argomenti_posizionali_non_dei_flag">La soluzione: argomenti posizionali, non dei flag</a></li> <li><a href="#_verifica_rapida_con_curl">Verifica rapida con curl</a></li> <li><a href="#_perché_questo_bug_era_subdolo">Perché questo bug era subdolo</a></li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 10 minutes</div> <p>Conosci quel momento in cui il tuo sito in locale sembra un disastro, ma una volta distribuito online tutto è perfetto? È quello che mi è capitato con il mio plugin Gradle JBake. L’operazione`serve`mostrava pulsanti quadrati, testo scuro su sfondo nero, e un CSS stranamente assente. Tuttavia`publishSite`generava lo stesso sito, lui, impeccabile. Il colpevole non era né il CSS, né il navigatore, né la cache. Era una riga di codice Kotlin — e una cattiva abitudine con gli argomenti della riga di comando.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_scena_quattro_screenshot_due_rendering">La scena: quattro screenshot, due rendering</h2> <div class="sectionbody"> <div class="paragraph"> <p>Era dopo un crash del sistema. Avevo fatto quattro screenshot per confrontare il rendering locale (<code>./gradlew serve`su`localhost:8820</code>) con il rendering online (`publishSite`su GitHub Pages). Due screenshot per pagina: la parte superiore e la parte inferiore.</p> </div> <div class="sect2"> <h3 id="_rendu_local">Rendu local</h3> <div class="paragraph"> <p><strong>Inizio pagina</strong>— I pulsanti <strong>Project</strong> e <strong>Template</strong> sono<strong>piccoli, rettangolari</strong>, ai colori standard (blu e verde). La carta <strong>Start Writing</strong> ha un<strong>sfondo nero uniforme</strong>, senza cornice.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local1.png" alt="Rendu local - haut de page"> </div> </div> <div class="paragraph"> <p><strong>Piede di pagina</strong>— Il sottotitolo <strong>"Ultimi articoli e risorse</strong>" è<strong>quasi illeggibile</strong>, troppo scuro su sfondo nero. Le date sotto le immagini del blog ("17 October 2013", ecc.) sono<strong>assenti</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local2.png" alt="Rendu local - bas de page"> </div> </div> </div> <div class="sect2"> <h3 id="_resa_online">Resa online</h3> <div class="paragraph"> <p><strong>In alto della pagina</strong>— I stessi pulsanti sono<strong>grandi, ovaux, verde neon appariscente</strong>, testo in maiuscolo. La carta ha un<strong>cornice bianca arrotondata con ombra portata</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online1.png" alt="Rendu en ligne - haut de page"> </div> </div> <div class="paragraph"> <p><strong>Piede di pagina</strong>— Il sottotitolo è<strong>ben leggibile</strong>. Le date sono<strong>visibili</strong>. Le carte degli articoli hanno<strong>angoli arrotondati</strong>e i titoli sono<strong>in grassetto</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online2.png" alt="Rendu en ligne - bas de page"> </div> </div> <div class="paragraph"> <p>Primo riflesso: il tema. Utilizzo un sistema di tema dinamico (chiaro, scuro, high-contrast) basato su`localStorage`. Forse il local store attivava un tema high-contrast? No. Avevo già scrittohttps://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[un articolo intero sul pre-caricamento dei temi], so come funziona. E poi, anche in modalità high-contrast, la struttura CSS (pulsanti ovali, ombre) doveva essere lì. Non lo era.</p> </div> <div class="paragraph"> <p>Seconda riflessione: la cache del browser. No, avevo fatto il test con profili puliti. Il diff persisteva.</p> </div> <div class="paragraph"> <p>Terzo riflesso :`serve`non serviva gli stessi file che`publishSite`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_diagnosi_serve_non_puntava_verso_la_cartella_corretta">La diagnosi : <code>serve</code> non puntava verso la cartella corretta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il mio plugin Gradle`bakery`ha due compiti principali :</p> </div> <div class="ulist"> <ul> <li> <p><code>bake</code>: genera il sito statico in`build/bake/`</p> </li> <li> <p><code>serve</code>: avvia un server web locale</p> </li> <li> <p><code>publishSite</code>: germoglio`build/bake/`verso GitHub Pages</p> </li> </ul> </div> <div class="paragraph"> <p>La divergenza non poteva venire che da`serve`. Si <code>publishSite`pubblicava il contenuto corretto, è che`build/bake/`era buono. se`serve`mostrava altro, è che non serviva`build/bake/</code>.</p> </div> <div class="paragraph"> <p>Guardiamo il codice. Dentro`SiteManager.kt`, il compito`serve`è definita così :</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version buggy)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("serve", JavaExec::class.java) { task -> task.apply { mainClass.set("org.jbake.launcher.Main") classpath = jbakeRuntime environment("GEM_PATH", jbakeRuntime.asPath) jvmArgs(/* ... */) args = listOf( "-b", file(site.bake.srcPath).absolutePath, "-s", layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath ) } }</code></pre> </div> </div> <div class="paragraph"> <p><code>org.jbake.launcher.Main`è il punto di ingresso della CLI JBake 2.7.0. L’idea: passare</code>-b`per la cartella di origine e </think> per la cartella di origine e`-s`per la cartella di destinazione, poi avviare il modo server. Tuttavia…​</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_causa_radice_jbake_cli_non_funziona_così">La causa radice: JBake CLI non funziona così</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 2.7.0 attende dei<strong>argomenti posizionali</strong>per source e destination, poi dei flag opzionali. La firma è :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake <source> <destination> [options]</code></pre> </div> </div> <div class="paragraph"> <p>Ora nel mio codice, scrivevo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", "/path/to/site", "-s", "/path/to/build/bake")</code></pre> </div> </div> <div class="paragraph"> <p>JBake lo interpretava così:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>-b</code>→ analizza il flag "bake" (booleano), consumato</p> </li> <li> <p><code>/path/to/site</code>→ diventa l’argomento posizionale 1 (fonte)</p> </li> <li> <p><code>-s</code>→ parse il flag "serve" (booleano), server lanciato<strong>immediatamente</strong></p> </li> <li> <p><code>/path/to/build/bake</code>→ diventa un argomento orfano, ignorato o mal interpretato</p> </li> </ol> </div> <div class="paragraph"> <p>Risultato: JBake prendeva`/path/to/site`come fonte,<strong>non teneva conto della destinazione</strong>fornita (<code>build/bake</code>), e utilizzava la sua directory predefinita (spesso`./output`o una copia temporanea). Il file`css/styles.css`il build era quindi sovrascritto o ignorato, ed era un vecchio CSS predefinito (senza le variabili personalizzate, senza gli angoli arrotondati, senza le ombre) che veniva servito.</p> </div> <div class="paragraph"> <p>In confronto,<code>bake</code> et <code>publishSite`usano il<strong>plugin ufficiale Gradle JBake</strong>(`jbake-gradle-plugin</code>) che scrive correttamente in`build/bake/`via API Gradle. Non passano via CLI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_argomenti_posizionali_non_dei_flag">La soluzione: argomenti posizionali, non dei flag</h2> <div class="sectionbody"> <div class="paragraph"> <p>La correzione è banale — una volta che lo sai. Basta passare la sorgente e la destinazione come argomenti posizionali, poi`-s`infine :</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version corrigée)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">args = listOf( file(site.bake.srcPath).absolutePath, layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath, "-s" )</code></pre> </div> </div> <div class="paragraph"> <p>È tutto. Tre linee modificate, bug risolto.</p> </div> <div class="paragraph"> <p>Après publication locale du plugin (<code>publishToMavenLocal</code>), un `./gradlew serve`lancia JBake con la sintassi corretta :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake /home/user/project/site /home/user/project/build/bake -s</code></pre> </div> </div> <div class="paragraph"> <p>E questa volta, il server Jetty integrato in JBake fornisce bene il contenuto di`build/bake/` — identique à ce qui est publié en ligne.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/serve-vs-publish-diagram.svg" alt="serve vs publish diagram" width="1141" height="348"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verifica_rapida_con_curl">Verifica rapida con curl</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per assicurarsi che il server serva il contenuto corretto, un semplice`curl`conferma che`index.html`contiene`data-bs-theme="light"`e che`build/bake/css/styles.css`pesa effettivamente 31 402 byte — identico al file generato da`bake`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew serve # Dans un autre terminal : $ curl -s http://localhost:8820/ | grep data-bs-theme <html ... data-bs-theme="light" ...> $ curl -I http://localhost:8820/css/styles.css HTTP/1.1 200 OK Content-Length: 31402 Content-Type: text/css</code></pre> </div> </div> <div class="paragraph"> <p>Il rendering locale è ora<strong>pixel-identico</strong>al render distribuito</p> </div> </div> </div> <div class="sect1"> <h2 id="_perché_questo_bug_era_subdolo">Perché questo bug era subdolo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lei vede perché era difficile da prendere?</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Nessun errore esplicito</strong>JBake non si bloccava. Il "fonctionnait", semplicemente con una cartella sbagliata.</p> </li> <li> <p><strong>Il build funzionava</strong>:`./gradlew bake`generava correttamente i file in`build/bake/`.</p> </li> <li> <p><strong>La distribuzione funzionava</strong>:`publishSite`stava promuovendo il buon contenuto online</p> </li> <li> <p><strong>Solo <code>serve</code> era rotto</strong>: il compito di sviluppo, quello che si utilizza costantemente per iterare.</p> </li> <li> <p><strong>L’abitudine del <code>-key value</strong>: in quanto sviluppatore, si è condizionati dagli anni di CLI Unix (</code>-o output`, `-i input`JBake CLI è un’eccezione — sorgente e destinazione sono posizionali.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se mantieni un plugin Gradle che avvolge JBake (o qualsiasi strumento CLI)<strong>leggete la documentazione degli argomenti</strong>anche se pensi di conoscerli. Un’ipotesi implicita (`-s`set destination") può costarti ore di debug visivo.</p> </div> <div class="paragraph"> <p>Qui, il fix era letteralmente di cambiare :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", src, "-s", dest) // ❌ BUG</code></pre> </div> </div> <div class="paragraph"> <p>en :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf(src, dest, "-s") // ✅ FIX</code></pre> </div> </div> <div class="paragraph"> <p>Tre token spostati, e il mio sito locale torna bello come il sito in produzione.</p> </div> <div class="paragraph"> <p><strong>Lezione</strong>: Quando il rendering differisce tra locale e produzione senza motivo evidente, sospetta prima il <strong>pipeline</strong> — non il CSS, non il browser, e tanto meno il framework. Spesso è il passaggio appena prima del rendering che imbroglia.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0105_integrer_graphify_workflow_gradle_post.html Sun, 19 Apr 2026 00:00:00 +0000 blog/2026/0105_integrer_graphify_workflow_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_problema_dei_diagrammi_sempre_in_ritardo_rispetto_al_codice">Il problema : dei diagrammi sempre in ritardo rispetto al codice</a></li> <li><a href="#_la_soluzione_un_pipeline_deterministico_knowledge_graph_plantuml">La soluzione: un pipeline deterministico Knowledge Graph → PlantUML</a></li> <li><a href="#_passo_1_installare_graphify_e_estrarre_il_knowledge_graph">Passo 1: Installare Graphify e estrarre il Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_installazione">Installazione</a></li> <li><a href="#_jbake_cli_commands_initialize_a_new_jbake_project_jbake_i">JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</a></li> </ul> </li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset_graphify_è_uno_strumento_python_che_analizza_il_tuo_codebase_e_costruisce_un_grafo_di_conoscenze_strutturato">Clear the output directory before baking jbake -b . output --reset <code>`</code> Graphify è uno strumento Python che analizza il tuo codebase e costruisce un grafo di conoscenze strutturato:</a> <ul class="sectlevel2"> <li><a href="#_configurare_le_esclusioni">Configurare le esclusioni</a></li> <li><a href="#_estrarre_il_knowledge_graph">Estrarre il Knowledge Graph</a></li> <li><a href="#_passo_2_il_plugin_gradle_trasforma_il_knowledge_graph_in_plantuml">Passo 2: Il plugin Gradle trasforma il Knowledge Graph in PlantUML</a> <ul class="sectlevel2"> <li><a href="#_architettura_della_pipeline">Architettura della pipeline</a></li> <li><a href="#_i_componenti_interni">I componenti interni</a></li> <li><a href="#_regole_di_rendering">Regole di rendering</a></li> </ul> </li> <li><a href="#_fase_3_utilizzo_quotidiano">Fase 3: Utilizzo quotidiano</a> <ul class="sectlevel2"> <li><a href="#_diagramma_completo">Diagramma completo</a></li> <li><a href="#_filtra_per_comunità">Filtra per comunità</a></li> <li><a href="#_filtra_per_tipo_di_bordo">Filtra per tipo di bordo</a></li> <li><a href="#_filtra_per_tipo_di_nodo_e_confidenza">Filtra per tipo di nodo e confidenza</a></li> <li><a href="#_directory_di_output_personalizzata">Directory di output personalizzata</a></li> <li><a href="#_riferimento_completo_delle_proprietà">Riferimento completo delle proprietà</a></li> </ul> </li> <li><a href="#_il_pipeline_completo_in_un_workflow_gradle">Il pipeline completo in un workflow Gradle</a> <ul class="sectlevel2"> <li><a href="#_workflow_type">Workflow type</a></li> <li><a href="#_integrazione_nel_ciclo_di_sviluppo">Integrazione nel ciclo di sviluppo</a></li> <li><a href="#_aggiornamento_incrementale">Aggiornamento incrementale</a></li> </ul> </li> <li><a href="#_il_dogfooding_il_plugin_si_documenta_da_sé">Il dogfooding: il plugin si documenta da sé</a></li> <li><a href="#_perché_è_deterministico_e_perché_conta">Perché è deterministico (e perché conta)</a></li> <li><a href="#_diagrammi_del_pipeline_stesso">Diagrammi del pipeline stesso</a></li> <li><a href="#_integrazione_nella_governance_del_progetto">Integrazione nella governance del progetto</a></li> <li><a href="#_impostazione_lista_di_controllo_in_5_minuti">Impostazione: lista di controllo in 5 minuti</a></li> <li><a href="#_trappole_e_mitigazioni">Trappole e mitigazioni</a></li> <li><a href="#_ciò_che_si_ottiene_alla_fine">Ciò che si ottiene alla fine</a></li> <li><a href="#_link">Link</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 12 minutes</div> <p>Il tuo codebase cresce. Le dipendenze tra i moduli si moltiplicano. La documentazione dell’architettura diventa obsoleta prima ancora di essere scritta. E se il tuo build Gradle potesse <em>automaticamente</em> generare diagrammi aggiornati a partire dalla struttura reale del codice? Questo è esattamente ciò che fa la pipeline Graphify + PlantUML Gradle Plugin :`graphify . --no-viz`estrae il Knowledge Graph,`./gradlew generateKnowledgeGraphDiagram`le trasforma in diagrammi PlantUML. Zero LLM, zero manuale, 100% deterministico.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">indice</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_dei_diagrammi_sempre_in_ritardo_rispetto_al_codice">Il problema : dei diagrammi sempre in ritardo rispetto al codice</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ogni progetto che supera qualche migliaio di linee conosce questo sintomo :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Si disegna un diagramma di architettura all’inizio del progetto</p> </li> <li> <p>Il codice evolve, le dipendenze cambiano</p> </li> <li> <p>Il diagramma diventa una bugia decorativa</p> </li> <li> <p>Nessuno lo aggiorna perché è penoso</p> </li> <li> <p>I nuovi arrivati si basano su quello e commettono errori</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/probleme-diagrammes-obsoletes.svg" alt="probleme diagrammes obsoletes" width="824" height="418"> </div> </div> <div class="paragraph"> <p>La questione non è <em>serve avere dei diagrammi ?</em> — tutti sanno di sì. La questione è :<strong>chi li mantiene aggiornati?</strong></p> </div> <div class="paragraph"> <p>La risposta: nessuno. A meno che non sia automatico.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_un_pipeline_deterministico_knowledge_graph_plantuml">La soluzione: un pipeline deterministico Knowledge Graph → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il principio è semplice: al posto di disegnare i diagrammi a mano, li<strong>genera dalla struttura reale del codice</strong>.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle actor Développeur component "Graphify (pip install graphifyy)" as Graphify collections "graphify-out/graph.json (Grafo della conoscenza)" as KGJSON component "Plugin Gradle per PlantUML (generateKnowledgeGraphDiagram)" as Plugin component "KnowledgeGraphParser" as Parser component "KnowledgeGraphRenderer" as Renderer component "PlantumlService (validazione + rendering PNG)" as PS collections "diagrammi/knowledge-graph/\n(.puml + .png)" as Output Développeur --> Graphify : graphify . --no-viz Graphify --> KGJSON : extrait la structure\ndu code source Développeur --> Plugin : ./gradlew generateKnowledgeGraphDiagram Plugin --> Parser : parse(graph.json) Parser --> Plugin : KnowledgeGraph\n(noeuds + arêtes + communautés) Plugin --> Renderer : render(graph, filters) Renderer --> Plugin : code PlantUML\ndéterministe Plugin --> PS : validateSyntax + generateImage PS --> Output : .puml + .png note bottom of Plugin Pipeline DÉTERMINISTE Aucun appel LLM Résultat reproductible end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Due comandi. È tutto.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Étape 1 : extraire le Knowledge Graph graphify . --no-viz # Étape 2 : générer les diagrammes PlantUML ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>Il risultato? Dei file`.puml` et <code>.png`in`diagrams/knowledge-graph/</code>, versionati in Git, sempre aggiornati rispetto al codice.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_1_installare_graphify_e_estrarre_il_knowledge_graph">Passo 1: Installare Graphify e estrarre il Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_installazione">Installazione</h3> </div> <div class="sect2"> <h3 id="_jbake_cli_commands_initialize_a_new_jbake_project_jbake_i">JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</h3> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset_graphify_è_uno_strumento_python_che_analizza_il_tuo_codebase_e_costruisce_un_grafo_di_conoscenze_strutturato" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code> Graphify è uno strumento Python che analizza il tuo codebase e costruisce un grafo di conoscenze strutturato:</h1> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Méthode recommandée uv tool install graphifyy && graphify install --platform opencode # Alternative avec pip pip install graphifyy && graphify install --platform opencode</code></pre> </div> </div> <div class="sect2"> <h3 id="_configurare_le_esclusioni">Configurare le esclusioni</h3> <div class="paragraph"> <p>Creare un file`.graphifyignore`alla radice del progetto per escludere i file che non fanno parte della logica di business :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-gitignore hljs" data-lang="gitignore"># Secrets — JAMAIS dans le graphe *-context.yml *.env # Fichiers générés build/ .gradle/ # Tests fonctionnels src/functionalTest/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_estrarre_il_knowledge_graph">Estrarre il Knowledge Graph</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">graphify . --no-viz</code></pre> </div> </div> <div class="paragraph"> <p>La bandiera`--no-viz`Salta la generazione HTML (inutile in una pipeline Gradle). Il risultato è un file`graphify-out/graph.json`contenente :</p> </div> <div class="ulist"> <ul> <li> <p><strong>nodi</strong>: classi, funzioni, file — con il loro tipo e comunità</p> </li> <li> <p><strong>Lische</strong>relazioni tra nodi (EXTRACTED dal codice, INFERRED dal LLM)</p> </li> <li> <p><strong>Comunità</strong>: raggruppamenti automatici di nodi collegati</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Exemple de structure <code>graph.json</code></div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "nodes": [ {"id": "0", "label": "LlmService", "file_type": "code", "community": 0}, {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0}, {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1} ], "links": [ {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9}, {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7} ] }</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Il codice sorgente (<code>.kt</code>, <code>.java</code>) viene analizzato localmente da tree-sitter,<strong>senza appello LLM</strong>. Solo i file di documentazione (<code>.adoc</code>, <code>.md</code>) richiedono una chiamata LLM per l’estrazione semantica. Quindi`--update`sul codice Kotlin è quasi istantaneo.</p> </div> </td> </tr> </table> </div> </div> <div class="sect1"> <h2 id="_passo_2_il_plugin_gradle_trasforma_il_knowledge_graph_in_plantuml">Passo 2: Il plugin Gradle trasforma il Knowledge Graph in PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_architettura_della_pipeline">Architettura della pipeline</h3> <div class="paragraph"> <p>Il plugin`com.cheroliv.plantuml`integra un compito`generateKnowledgeGraphDiagram`che trasforma`graph.json`in diagrammi PlantUML in modo<strong>totalmente deterministico</strong>:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1109" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_i_componenti_interni">I componenti interni</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Componente</th> <th class="tableblock halign-left valign-top">Ruolo</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphParser</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse`graph.json`— supporta 3 formati : graphify nativo (<code>nodes</code>(No output)<code>links</code>), legacy (<code>communities</code>), flat. Risolve gli ID numerici in etichette.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphRenderer</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Trasforma deterministicamente un`KnowledgeGraph`in codice PlantUML. Gruppi per tipo, comunità in package, legenda automatica.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GenerateKnowledgeGraphDiagramTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Task Gradle che orchestra : parse → render → validate → PNG. Configurabile tramite proprietà Gradle.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kgmodels.kt</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modelli di dati:`KnowledgeGraph`, <code>KnowledgeGraphNode</code>, <code>KnowledgeGraphEdge</code>, <code>KnowledgeGraphCommunity</code>, <code>EdgeType</code>.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validazione sintattica + rendering PNG (riutilizzato da tutte le attività del plugin).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_regole_di_rendering">Regole di rendering</h3> <div class="paragraph"> <p>Il renderer applica convenzioni visive deterministiche :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Tipo di spigolo</th> <th class="tableblock halign-left valign-top">Notazione PlantUML</th> <th class="tableblock halign-left valign-top">Significato</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">ESTRATTI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code>(tratto pieno, nero)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relazione estratta dal codice sorgente (certezza)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DEDOTTO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code>(linea punteggiata)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relazione inferita dall’LLM (punteggio di fiducia)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">AMBIGUO</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code>(tratto rosso punteggiato)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relazione ambigua (da verificare)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le comunità vengono renderizzate come pacchetti PlantUML con una palette di colori automatica.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fase_3_utilizzo_quotidiano">Fase 3: Utilizzo quotidiano</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagramma_completo">Diagramma completo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Générer le diagramme du Knowledge Graph complet ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>Uscita :`diagrams/knowledge-graph/knowledge-graph-full.puml`+<code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filtra_per_comunità">Filtra per comunità</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Une seule communauté ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 # Limiter le nombre de noeuds (lisibilité) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 \ -Pplantuml.kg.maxNodes=15</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtra_per_tipo_di_bordo">Filtra per tipo di bordo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les relations certaines (EXTRACTED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED # Relations certaines + inférées ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtra_per_tipo_di_nodo_e_confidenza">Filtra per tipo di nodo e confidenza</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les classes de code ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.nodeTypes=code # Seuil de confiance minimum (pour les INFERRED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.minConfidence=0.7</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_directory_di_output_personalizzata">Directory di output personalizzata</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.outputDir=docs/architecture</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_riferimento_completo_delle_proprietà">Riferimento completo delle proprietà</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Proprietà</th> <th class="tableblock halign-left valign-top">difetto</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.community</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(tutte)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrare le comunità per nome (corrispondenza di sottostringa)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.edgeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">(tutti)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipi di archi separati da virgole:`EXTRACTED`, <code>INFERRED</code>, <code>AMBIGUOUS</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.minConfidence</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.0</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Soglia minima di confidenza per gli archi</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.maxNodes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(illimitato)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Numero massimo di nodi da visualizzare</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.nodeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">tutti</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tipi di nodi separati da virgole (es.<code>class</code>, <code>code</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.outputDir</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagrams/knowledge-graph</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directory di output per i file`.puml` et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_il_pipeline_completo_in_un_workflow_gradle">Il pipeline completo in un workflow Gradle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_workflow_type">Workflow type</h3> <div class="imageblock"> <div class="content"> <img src="./images/workflow-complet.svg" alt="workflow complet" width="618" height="714"> </div> </div> </div> <div class="sect2"> <h3 id="_integrazione_nel_ciclo_di_sviluppo">Integrazione nel ciclo di sviluppo</h3> <div class="paragraph"> <p>Il pipeline si integra naturalmente nelle fasi chiave dello sviluppo :</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE state "Sviluppo" as dev state "Estrazione ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE state "Sviluppo" as dev state "Estrazione graficare . --no-viz" as extract state "Generazione ./gradlew generateKnowledgeGraphDiagram" as generate state "Commit\ndiagrammi versionati" as commit [*] --> dev dev --> extract : Code modifié extract --> generate : graph.json à jour generate --> commit : .puml + .png générés commit --> dev : Diagrammes dans le repo note right of extract Quasi instantané sur du code Kotlin (tree-sitter, pas de LLM) end note note right of generate Déterministe Pas de LLM Résultat reproductible end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_aggiornamento_incrementale">Aggiornamento incrementale</h3> <div class="paragraph"> <p>Quando il codice cambia, non ricostruiamo tutto il grafo da zero :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Mise à jour incrémentale (fichiers modifiés uniquement) graphify . --update # Puis régénérer les diagrammes ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><code>--update`re-estrae solo i file modificati (rilevati tramite SHA256 in`graphify-out/cache/</code>). Sul codice Kotlin, è quasi istantaneo perché tree-sitter funziona localmente senza chiamate LLM.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_il_dogfooding_il_plugin_si_documenta_da_sé">Il dogfooding: il plugin si documenta da sé</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il plugin PlantUML esiste per trasformare i prompt in diagrammi. Può anche trasformare il Knowledge Graph del suo <em>proprio</em> codebase in diagrammi di documentazione. È <em>dogfooding</em> : il plugin consuma il proprio servizio.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normale (utente → diagrammi)" as normal { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "Pipeline normale (utente → diagrammi)" as normal { [Fichier .prompt] as prompt [LlmService\n+ ApiKeyPool] as llm1 [ProcessPlantumlPromptsTask] as task1 [Diagramme PNG] as out1 prompt --> task1 task1 --> llm1 llm1 --> out1 } package "Pipeline Knowledge Graph (deterministico, senza LLM)" as kg { [graphify-out/graph.json] as kgjson [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantumlService] as ps [Diagramme PNG\n(documentation du plugin)] as out2 kgjson --> parser parser --> renderer renderer --> ps ps --> out2 } package "Pipeline Dogfooding (LLM → documentazione del plugin)" as dogfood { [GraphifyPromptAdapter] as gpa [Fichiers .prompt\nauto-générés] as auto_prompt [LlmService\n+ ApiKeyPool] as llm2 [ProcessPlantumlPromptsTask] as task2 [Diagramme PNG\n(documentation LLM)] as out3 kgjson --> gpa gpa --> auto_prompt auto_prompt --> task2 task2 --> llm2 llm2 --> out3 } note "Stesso LlmService, stesso ApiKeyPool, stesso PlantumlService — ZERO duplicazione" as N @enduml</pre> </div> </div> <div class="paragraph"> <p>Compiti Gradle associati :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Compito</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateKnowledgeGraphDiagram</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Trasforma`graph.json`in PlantUML (deterministico)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateDiagramDocs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sì</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Genera dei`.prompt`dal grafo, li tratta tramite LLM (dogfooding)</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Documentation déterministe (rapide, pas de LLM) ./gradlew generateKnowledgeGraphDiagram # Documentation LLM (plus riche, consomme des tokens) ./gradlew generateDiagramDocs</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_è_deterministico_e_perché_conta">Perché è deterministico (e perché conta)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il punto chiave del pipeline`generateKnowledgeGraphDiagram`(No output)<strong>non chiama alcun LLM</strong>. La trasformazione`graph.json` → PlantUML est une fonction pure.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline deterministico (generateKnowledgeGraphDiagram)" as det { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Pipeline deterministico (generateKnowledgeGraphDiagram)" as det { [graph.json] as json [KnowledgeGraphParser] as parser [KnowledgeGraphRenderer] as renderer [PlantUML code] as puml json --> parser : parse parser --> renderer : KnowledgeGraph renderer --> puml : render (fonction pure) } rectangle "Pipeline LLM (processPlantumlPrompts)" as llm { [.prompt] as prompt [LlmService] as llmSvc [ChatModel] as model [PlantUML code] as puml2 prompt --> llmSvc llmSvc --> model : API call model --> puml2 : réponse non-déterministe } note bottom of det Même entrée → même sortie Pas de latence réseau Pas de coût en tokens Reproductible en CI end note note bottom of llm Même entrée → sortie variable Latence réseau (1-5s) Coût en tokens Nécessite une clave API end note @enduml</pre> </div> </div> <div class="paragraph"> <p>I vantaggi concreti:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">vantaggio</th> <th class="tableblock halign-left valign-top">Impatto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">riproducibilità</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anche`graph.json`→ lo stesso diagramma. Esattamente. Ogni volta.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">zero costo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nessuna chiamata LLM = nessun token = nessuna fattura API</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero latenza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render impiega ~100ms, non 1-5 secondi.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Compatibile CI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nessuna chiave API necessaria. Nessun test flaky dovuto a una risposta LLM variabile.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Versionabile</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml`Il testo generato è del testo. Si può`diff</code>, il reviewer nella PR, versionarlo in Git.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_diagrammi_del_pipeline_stesso">Diagrammi del pipeline stesso</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per chiudere il cerchio, ecco il diagramma della pipeline così com’è generato dal plugin :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1745" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_integrazione_nella_governance_del_progetto">Integrazione nella governance del progetto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nel nostro progetto, questo pipeline si integra in una strategia di gestione del contesto EAGER/LAZY per l’agente IA. Il Knowledge Graph sostituisce la documentazione architetturale manuale con un grafo strutturato, interrogabile e auto-aggiornato.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 16) ] @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(sempre carico)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — Strategia\n(su richiesta)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle package "EAGER\n(sempre carico)" as eager { [PROMPT_REPRISE.adoc\n(contexte session)] as pr [INDEX.adoc\n(vue d'ensemble)] as idx [GRAPH_REPORT.adoc\n(~50 lignes)] as gr } package "LAZY — Strategia\n(su richiesta)" as lazy_strat { [Méthodologies] as meth [Archives sessions] as sessions } package "LAZY — Graphify (query mirate)" as lazy_graph { [graph.json] as gj [Queries\n(query/path/explain)] as queries } package "Pipeline PlantUML\n(auto-generato)" as puml { [generateKnowledgeGraphDiagram] as kgTask [generateDiagramDocs] as ddTask [Diagrammes PNG] as diagrams } Agent --> eager : Lit en début de session Agent ..> lazy_strat : Charge si type détecté Agent ..> lazy_graph : Query si besoin structurel kgTask --> diagrams : Déterministe ddTask --> diagrams : Via LLM note right of gr Condensé du Knowledge Graph God nodes + communautés Remplace ECOSYSTEM_OVERVIEW (225 lignes → 50 lignes) end note @enduml</pre> </div> </div> <div class="paragraph"> <p>Il matrimonio dei due sistemi è complementare :</p> </div> <div class="ulist"> <ul> <li> <p><strong>La strategia gestisce il QUAND e il COMMENT</strong>— governance, workflow, archiviazione</p> </li> <li> <p><strong>Graphify gestisce il QUOI e il OÙ</strong> — structure du code, relations, requêtes ciblées</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ La strategia di sessione gestisce il<strong>QUANDO</strong> et le <strong>COME</strong>(governance, workflow, soglie), Graphify gestisce il<strong>Cosa</strong> et le <strong>dove</strong>(struttura del codice, relazioni, query mirate). Il pipeline PlantUML gestisce il<strong>con cosa</strong>(diagrammi deterministici, versionati, sempre aggiornati) </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_impostazione_lista_di_controllo_in_5_minuti">Impostazione: lista di controllo in 5 minuti</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">Fase</th> <th class="tableblock halign-left valign-top">Ordine</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Installa Graphify</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uv tool install graphifyy</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configurare le esclusioni</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">creare`.graphifyignore`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Estrarre il Knowledge Graph</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>graphify . --no-viz</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Generare i diagrammi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./gradlew generateKnowledgeGraphDiagram</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Effettuare il commit dei risultati</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git add diagrams/knowledge-graph/</code></p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Script complet en 5 commandes uv tool install graphifyy cat > .graphifyignore << 'EOF' *-context.yml *.env build/ .gradle/ EOF graphify . --no-viz ./gradlew generateKnowledgeGraphDiagram git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trappole_e_mitigazioni">Trappole e mitigazioni</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">trappola</th> <th class="tableblock halign-left valign-top">Description</th> <th class="tableblock halign-left valign-top">Mitigazione</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo troppo denso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un grande progetto genera centinaia di nodi illeggibili</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">usare`-Pplantuml.kg.maxNodes=30`e filtra per comunità</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Esclusioni troppo ampie</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Troppi file in`.graphifyignore`riduce il valore del grafo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><mark>#</mark> Gradle Integration JBake can be integrated into Gradle builds using the JBake Gradle plugin or by calling the JBake CLI directly:</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Direzione delle frecce</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le arete INFERRED possono avere una direzione ambigua</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtra per`-Pplantuml.kg.edgeTypes=EXTRACTED`solo per le relazioni certe</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Grafo obsoleto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il codice cambia ma il grafo non viene ricostruito</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">utilizzare`graphify . --update`regolarmente o il hook git`graphify hook install`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Costo aggiornato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gli aggiornamenti incrementali sono quasi gratuiti (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solo i documenti (<code>.adoc</code>) consumano token LLM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_ciò_che_si_ottiene_alla_fine">Ciò che si ottiene alla fine</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE rectangle "prima" as avant { card "Diagrammi disegnati a mano Sempre obsoleti ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE rectangle "prima" as avant { card "Diagrammi disegnati a mano Sempre obsoleti Nessuno li aggiorna" as av1 #FDEDEC } rectangle "DOPO" as apres { card "Diagrammi generati automaticamente Sempre aggiornati con il codice Versionati in Git Deterministici e riproducibili" as ap1 #E8F8E8 } avant --> apres : graphify . --no-viz\n+ ./gradlew generateKnowledgeGraphDiagram @enduml</pre> </div> </div> <div class="paragraph"> <p>I benefici concreti:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Profitto</th> <th class="tableblock halign-left valign-top">Dettaglio</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentazione sempre aggiornata</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">I diagrammi riflettono il codice corrente, non uno snapshot manuale</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero sforzo di manutenzione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">I diagrammi vengono rigenerati ad ogni build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Riduzione del debito tecnico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non è più necessario mantenere i diagrammi a mano</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contesto visivo per i nuovi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un nuovo sviluppatore comprende l’architettura guardando i diagrammi</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">fine-tuning potenziale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le coppie (sottografo → diagramma) sono esempi di addestramento IA</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Validazione automatica</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">`PlantumlService.validateSyntax()`verifica ogni diagramma generato</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Onboarding rapido</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5 diagrammi = visione completa dell’architettura</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em><em>_ Chi ha un _perché</em> può sopportare ogni <em>come</em>. </em>__</p> </div> <div class="paragraph"> <p>Il <em>perché</em>: diagrammi sempre aggiornati. Il <em>come</em>: due comandi in una pipeline Gradle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_link">Link</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Graphify su GitHub</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">PlantUML Gradle Plugin</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">I super suggerimenti del comando fg</a>— articolo precedente sul flusso di lavoro del terminale</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0104_fg_command_super_tips_post.html Sat, 18 Apr 2026 00:00:00 +0000 blog/2026/0104_fg_command_super_tips_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_il_problema_un_terminale_occupato">Il problema: un terminale occupato</a></li> <li><a href="#_i_tre_comandi_indispensabili">I tre comandi indispensabili</a> <ul class="sectlevel2"> <li><a href="#_ctrlz_sospendere_sigtstp">Ctrl+Z — Sospendere (SIGTSTP)</a></li> <li><a href="#_fg_riprendere_in_primo_piano">fg — Riprendere in primo piano</a></li> <li><a href="#_bg_riprendere_in_background">bg — Riprendere in background</a></li> <li><a href="#_jobs_elencare_i_job_della_shell">jobs — Elencare i job della shell</a></li> </ul> </li> <li><a href="#_scenario_1_la_build_lunga">Scenario 1 : La build lunga</a> <ul class="sectlevel2"> <li><a href="#_passo_a_passo">Passo a passo</a></li> </ul> </li> <li><a href="#_scenario_2_leditore_dimenticato">Scenario 2: L’editore dimenticato</a></li> <li><a href="#_scenario_3_il_processo_opencode_sospeso">Scenario 3 : Il processo opencode sospeso</a></li> <li><a href="#_scenario_4_gestire_più_job_contemporaneamente">Scenario 4: Gestire più job contemporaneamente</a> <ul class="sectlevel2"> <li><a href="#_riepilogo_dei_comandi_di_lavoro">Riepilogo dei comandi di lavoro</a></li> </ul> </li> <li><a href="#_differenze_tra_fg_bg_ctrlz_ctrlc_e">Differenze tra fg, bg, Ctrl+Z, Ctrl+C e &</a></li> <li><a href="#_il_ciclo_di_vita_completo_di_un_job">Il ciclo di vita completo di un job</a></li> <li><a href="#_consigli_avanzati">Consigli avanzati</a> <ul class="sectlevel2"> <li><a href="#_fg_con_il_lavoro_più_recente_e_lalternanza">fg con il lavoro più recente e l’alternanza</a></li> <li><a href="#_uccidere_un_job_correttamente">uccidere un job correttamente</a></li> <li><a href="#_désown_rimuovere_dalla_shell">désown: rimuovere dalla shell</a></li> <li><a href="#_combinare_con_nohup_per_i_processi_lunghi">Combinare con nohup per i processi lunghi</a></li> </ul> </li> <li><a href="#_trappole_ed_errori_comuni">Trappole ed errori comuni</a> <ul class="sectlevel2"> <li><a href="#_confondere_ctrlz_e_ctrlc">Confondere Ctrl+Z e Ctrl+C</a></li> <li><a href="#_i_job_sono_locali_nella_shell">I job sono locali nella shell</a></li> <li><a href="#_i_lavori_non_sopravvivono_alla_chiusura_della_shell">I lavori non sopravvivono alla chiusura della shell</a></li> <li><a href="#_processi_interattivi_e_fg">processi interattivi e fg</a></li> </ul> </li> <li><a href="#_diagramma_riassuntivo">Diagramma riassuntivo</a></li> <li><a href="#_perché_fg_è_sottovalutato">Perché fg è sottovalutato</a></li> <li><a href="#_bake_generate_the_site_jbake_b">Bake (generate) the site jbake -b</a></li> <li><a href="#_bake_and_serve_locally_jbake_b_s">Bake and serve locally jbake -b -s</a></li> <li><a href="#_bake_and_watch_for_changes_jbake_b_reset">Bake and watch for changes jbake -b --reset</a></li> <li><a href="#_specify_source_and_destination_jbake_source_folder_output_folder">Specify source and destination jbake source_folder output_folder</a></li> <li><a href="#_clear_the_output_directory_before_baking_jbake_b_output_reset_è">Clear the output directory before baking jbake -b . output --reset <code>`</code> è :</a> <ul class="sectlevel1"> <li><a href="#_memoria_tecnica_i_segnali">Memoria tecnica: i segnali</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_riferimenti">Riferimenti</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 10 minutes</div> <p>Lei lancia`./gradlew build`, il terminale è bloccato per 3 minuti, e hai bisogno di fare qualcos’altro <em>in attesa</em> ? Non c’è bisogno di aprire una nuova scheda.`Ctrl+Z`sospende il processo,`fg`Lo riporta esattamente dove l’hai lasciato. È il consiglio Unix più sottovalutato nella quotidianità di uno sviluppatore.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">indice</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_un_terminale_occupato">Il problema: un terminale occupato</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ogni sviluppatore ha conosciuto questa situazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building...</code></pre> </div> </div> <div class="paragraph"> <p>Il terminale è bloccato. Non puoi più digitare alcun comando. E hai bisogno di consultare un file, avviare un`git status`, o verificare una porta occupata.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Terminale" as term participant "Gradle ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Terminale" as term participant "Gradle ( processo )" as gradle dev -> term : ./gradlew build term -> gradle : Lance le build gradle -> term : Occupe le terminal\n(pas de prompt) dev -> term : veut taper une commande term --> dev : ❌ Terminal bloqué note right of dev Le développeur est paralysé pendant toute la durée du build end note @enduml</pre> </div> </div> <div class="paragraph"> <p>La maggior parte degli sviluppatori apre un nuovo terminale. Ma esiste una soluzione più elegante, più veloce e nativa: la gestione dei job.</p> </div> </div> </div> <div class="sect1"> <h2 id="_i_tre_comandi_indispensabili">I tre comandi indispensabili</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz_sospendere_sigtstp">Ctrl+Z — Sospendere (SIGTSTP)</h3> <div class="paragraph"> <p>`Ctrl+Z`invia il segnale`SIGTSTP`al processo in primo piano. Il processo è<strong>sospeso</strong>— non ucciso — e il terminale riprende il suo prompt.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $</code></pre> </div> </div> <div class="paragraph"> <p>Il numero tra parentesi quadre`[1]` est le <strong>numero di lavoro</strong>. Le `+`indica il lavoro predefinito.</p> </div> </div> <div class="sect2"> <h3 id="_fg_riprendere_in_primo_piano">fg — Riprendere in primo piano</h3> <div class="paragraph"> <p>`fg`riporta il lavoro sospeso in primo piano. Il processo riprende esattamente dove si era interrotto.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg ./gradlew build > Building... (reprend où il en était)</code></pre> </div> </div> <div class="paragraph"> <p>Con un numero di lavoro specifico :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg %2</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_bg_riprendere_in_background">bg — Riprendere in background</h3> <div class="paragraph"> <p>`bg`Riprende il processo senza bloccare il terminale. Ideale per i build lunghi.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ bg [1]+ ./gradlew build & $</code></pre> </div> </div> <div class="paragraph"> <p>Le `&`alla fine significa che il processo è in esecuzione in secondo piano.</p> </div> </div> <div class="sect2"> <h3 id="_jobs_elencare_i_job_della_shell">jobs — Elencare i job della shell</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim README.md [2]+ En cours ./gradlew build</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 5) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "Primo piano ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif state "Primo piano (terminale bloccato)" as fg #LightCoral state "Sospeso (Ctrl+Z)" as stopped #LightYellow state "Sfondo\n(bg)" as bg_ #LightGreen [*] --> fg : Lance une commande fg --> stopped : Ctrl+Z\n(SIGTSTP) stopped --> fg : fg\nreprend en avant-plan stopped --> bg_ : bg\nreprend en arrière-plan bg_ --> fg : fg\nramène en avant-plan fg --> [*] : Commande terminée note right of stopped Le processus est figé mais _pas_ tué end note note left of bg_ Le terminal est libre le build continue end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_1_la_build_lunga">Scenario 1 : La build lunga</h2> <div class="sectionbody"> <div class="paragraph"> <p>È il caso d’uso più comune. Avvii un build Gradle, il terminale è bloccato, e hai bisogno di fare altro.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 8) ] @startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "terminale" as term participant "Gradle" as gradle database "Stato ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "terminale" as term participant "Gradle" as gradle database "Stato processo" as state dev -> term : ./gradlew build term -> gradle : Lance le build gradle -> state : En cours (FG) dev -> term : Ctrl+Z term -> state : Suspendu (job [1]) term --> dev : Prompt libre $ dev -> term : git status term --> dev : working tree clean dev -> term : fg term -> state : Reprend (FG) gradle --> dev : Build réussi ✓ note right of state Le processus Gradle n'a jamais été tué Il reprend exactement où il s'était arrêté end note @enduml</pre> </div> </div> <div class="sect2"> <h3 id="_passo_a_passo">Passo a passo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $ git status On branch main nothing to commit, working tree clean $ fg ./gradlew build > Building... BUILD SUCCESSFUL in 2m 34s</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_2_leditore_dimenticato">Scenario 2: L’editore dimenticato</h2> <div class="sectionbody"> <div class="paragraph"> <p>Sei in`vim`, hai bisogno di consultare un altro file <em>senza</em> uscire`vim`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, en mode commande : :shell $ cat /path/to/other/file.txt $ exit # Retour dans vim</code></pre> </div> </div> <div class="paragraph"> <p>Ma è pesante. Con`Ctrl+Z`, è immediato :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, n'importe quel moment : Ctrl+Z [1]+ Stoppé vim README.md $ cat /path/to/other/file.txt # ... lire le fichier ... $ fg vim README.md # Retour exact là où on en était, curseur en place</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/vim-suspend.svg" alt="vim suspend" width="410" height="510"> </div> </div> <div class="paragraph"> <p>(no output)<code>vim`ripristina perfettamente il suo stato dopo un`fg</code>: posizione del cursore, contenuto del buffer, cronologia delle annullazioni — tutto è preservato.</p> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_3_il_processo_opencode_sospeso">Scenario 3 : Il processo opencode sospeso</h2> <div class="sectionbody"> <div class="paragraph"> <p>È lo scenario che ha motivato questo articolo. Lei utilizza`opencode`(strumento CLI per pilotare un LLM sul tuo codice), e il processo è sospeso.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam componentStyle rectangle actor Développeur as dev participant "opencode ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam componentStyle rectangle actor Développeur as dev participant "opencode (agente LLM)" as agent participant "Shell" as shell participant "git" as git dev -> agent : Session active agent -> agent : Tour de parole\ndu LLM en cours note over agent Ctrl+Z arrive en plein milieu d'une analyse de code end note dev -> agent : Ctrl+Z agent -> shell : Suspendu (job [1]) dev -> git : git diff git --> dev : changements visibles dev -> shell : fg shell -> agent : Reprend (job [1]) agent --> dev : Reprend exactement\nl'analyse en cours note right of agent Aucune perte de contexte Le LLM reprend sa réponse exactement où il en était end note @enduml</pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode # ... session en cours, LLM analyse le code ... ^Z [1]+ Stoppé opencode $ git diff HEAD~1 # vérifier les changements récents $ fg opencode # Le LLM reprend là où il s'était arrêté</code></pre> </div> </div> <div class="paragraph"> <p>Il vantaggio è doppio :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Nessuna perdita di contesto</strong> : la session LLM, l’historique de conversation, les fichiers ouverts — tout est préservé</p> </li> <li> <p><strong>Nessun riavvio</strong>: non è necessario rilanciare opencode, ricaricare il contesto, spiegare nuovamente il problema al LLM</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_scenario_4_gestire_più_job_contemporaneamente">Scenario 4: Gestire più job contemporaneamente</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> et `bg`accettano un numero di job per mirare a un processo specifico quando più processi sono sospesi</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim config.yml ^Z [1]+ Stoppé vim config.yml $ ./gradlew test ^Z [2]+ Stoppé ./gradlew test $ htop ^Z [3]+ Stoppé htop $ jobs [1] Stoppé vim config.yml [2]- Stoppé ./gradlew test [3]+ Stoppé htop $ fg %2 ./gradlew test # Le build reprend en avant-plan $ bg %3 [3] htop & # htop reprend en arrière-plan</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/multiple-jobs.svg" alt="multiple jobs" width="752" height="280"> </div> </div> <div class="sect2"> <h3 id="_riepilogo_dei_comandi_di_lavoro">Riepilogo dei comandi di lavoro</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Ordine</th> <th class="tableblock halign-left valign-top">effetto</th> <th class="tableblock halign-left valign-top">Esempio</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sospende il processo in primo piano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Invio di`SIGTSTP`</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Riprendi il lavoro predefinito in primo piano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code> ou <code>fg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Riprende il lavoro n in primo piano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Riprende il job di default in background</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code> ou <code>bg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Riprendi il lavoro n in secondo piano</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Elenca i job della shell corrente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs -l</code>(con PID)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Termina il lavoro n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %2</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_differenze_tra_fg_bg_ctrlz_ctrlc_e">Differenze tra fg, bg, Ctrl+Z, Ctrl+C e &</h2> <div class="sectionbody"> <div class="paragraph"> <p>Molti sviluppatori confondono questi meccanismi. Ecco una chiarificazione decisiva.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 11) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "Sospendi il processo\n(e è sempre in memoria)\nUtilizzabile con fg/bg" as c1 } rectangle "**Ctrl+C**\nSIGINT" as ctrlc #LightCoral { card "Uccidi il processo (nessun ritorno possibile) ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "**Ctrl+Z**\nSIGTSTP" as ctrlz #LightYellow { card "Sospendi il processo\n(e è sempre in memoria)\nUtilizzabile con fg/bg" as c1 } rectangle "**Ctrl+C**\nSIGINT" as ctrlc #LightCoral { card "Uccidi il processo (nessun ritorno possibile) Perdita di tutto lo stato" as c2 } rectangle "& **\n(sfondo)" as ampersand #LightGreen { card "Avvia direttamente in background Terminale libero immediatamente" as c3 } rectangle "**fg** (primo piano)" as fg_ #SkyBlue { card "Riprendi un lavoro sospeso in primo piano Terminale occupato" as c4 } rectangle "**bg** (sfondo)" as bg_ #Lavender { card "Riprendi un job sospeso in secondo piano Terminale libero" as c5 } ctrlz -right-> fg_ : fg pour reprendre ctrlz -right-> bg_ : bg pour continuer\nen arrière-plan ctrlc -right-> c2 : Pas de retour\nprocessus tué note bottom of ctrlz Le processus est **figé** mais **pas tué** end note note bottom of ampersand Alternative : lancer ./gradlew build & directement en arrière-plan end note @enduml</pre> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 33.3333%;"> <col style="width: 16.6666%;"> <col style="width: 33.3335%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Scorciatoia/Comando</th> <th class="tableblock halign-left valign-top">Segnale</th> <th class="tableblock halign-left valign-top">Effetto</th> <th class="tableblock halign-left valign-top"><code>Ctrl+Z</code></th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sospendi il processo (congelato, in memoria)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sì :`fg` ou <code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Uccidi il processo (terminato)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No: processo distrutto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Uccidi il processo + core dump</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">No: processo distrutto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commande &</code></p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <code>Ctrl+Z</code> est <strong>non-distruttivo</strong>. Il processo è congelato così com’è, nella memoria. Puoi riprendere immediatamente con`fg`. È una <em>pause</em>, non uno <em>stop</em>. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_il_ciclo_di_vita_completo_di_un_job">Il ciclo di vita completo di un job</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif title Ciclo di vita completo di un job shell state "Inesistente" as none state "Primo piano ^^^^^ Syntax Error? (Assumed diagram type: state) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif title Ciclo di vita completo di un job shell state "Inesistente" as none state "Primo piano (occupa il terminale)" as foreground #LightCoral state "Sospeso\n(Ctrl+Z / SIGTSTP)" as suspended #LightYellow state "Sfondo (bg o &)" as background #LightGreen state "Terminato\n(exit code 0)" as done #LightGray [*] --> none none --> foreground : tape une commande foreground --> suspended : Ctrl+Z foreground --> done : fin normale suspended --> foreground : fg suspended --> background : bg suspended --> done : kill %n background --> foreground : fg background --> done : fin normale\n(en arrière-plan) background --> suspended : Ctrl+Z\n(si fg puis Ctrl+Z) done --> [*] note right of suspended L'état suspendu est le pivot de tout le système de jobs end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_consigli_avanzati">Consigli avanzati</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fg_con_il_lavoro_più_recente_e_lalternanza">fg con il lavoro più recente e l’alternanza</h3> <div class="paragraph"> <p><code>fg`senza argomento riporta il lavoro marcato</code>+<code>(il più recente). Ma puoi anche usare</code>%-`per prendere di mira il lavoro precedente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim file1.txt ^Z [1]+ Stoppé vim file1.txt $ vim file2.txt ^Z [2]+ Stoppé vim file2.txt $ fg # ramène job [2] (le plus récent) $ fg %- # ramène job [1] (le précédent)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_uccidere_un_job_correttamente">uccidere un job correttamente</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim config.yml [2]+ Stoppé ./gradlew test $ kill %2 # envoie SIGTERM au job 2 $ kill -9 %1 # envoie SIGKILL au job 1 (force)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_désown_rimuovere_dalla_shell">désown: rimuovere dalla shell</h3> <div class="paragraph"> <p><code>disown`rimuove un lavoro dalla tabella dei lavori della shell. Il processo continua a girare ma non può più essere riportato indietro con`fg</code>(No output)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build & [1] 12345 $ disown %1 # Le processus continue mais n'est plus lié au shell # Ça survives à la fermeture du terminal</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_combinare_con_nohup_per_i_processi_lunghi">Combinare con nohup per i processi lunghi</h3> <div class="paragraph"> <p>Perché un processo sopravviva alla chiusura del terminale :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Le build continue même si vous fermez le terminal</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "borgo" as fg_ #SkyBlue { card "Porta il lavoro il più recente (+)" as f1 ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "borgo" as fg_ #SkyBlue { card "Porta il lavoro il più recente (+)" as f1 card "Mira a un job specifico : fg %n" as f2 card "Alterna : fg %-%" as f3 } rectangle "kill %n" as kill_ #LightCoral { card "SIGTERM (pulito)" as k1 card "SIGKILL -9 (forzato)" as k2 } rectangle "rinnegare" as disown #Lavender { card "Scollega dal shell\n(sopravvive alla disconnessione)" as d1 } rectangle "nohup + &" as nohup_ #LightGreen { card "Processo immunizzato contro SIGHUP (sopravvive alla chiusura del terminal)" as n1 } fg_ -right-> kill_ : si faut\nterminer kill_ -right-> disown_ : ou détacher nohup_ -left-> fg_ : fg ramène en\navant-plan note bottom of disown_ Après disown, fg ne peut plus ramener le job end note @enduml</pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trappole_ed_errori_comuni">Trappole ed errori comuni</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_confondere_ctrlz_e_ctrlc">Confondere Ctrl+Z e Ctrl+C</h3> <div class="paragraph"> <p>È l’errore più frequente.`Ctrl+C`Uccide il processo.`Ctrl+Z`lo sospende. Se premi`Ctrl+C`per riflesso, tutto lo stato è perso — file aperti, sessioni LLM, build in corso.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/ctrlz-vs-ctrlc.svg" alt="ctrlz vs ctrlc" width="1194" height="129"> </div> </div> </div> <div class="sect2"> <h3 id="_i_job_sono_locali_nella_shell">I job sono locali nella shell</h3> <div class="paragraph"> <p><code>jobs</code>, <code>fg</code> et `bg`funzionano solo nella shell che ha avviato i processi. Se apri un nuovo terminale, non vedrai i lavori dell’altro.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Terminal 1 $ vim file.txt ^Z [1]+ Stoppé vim file.txt # Terminal 2 (nouveau) $ jobs # (rien — les jobs sont locaux au shell)</code></pre> </div> </div> <div class="paragraph"> <p>Per vedere i processi di sistema, utilizza`ps` ou <code>htop</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ps aux | grep vim</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_i_lavori_non_sopravvivono_alla_chiusura_della_shell">I lavori non sopravvivono alla chiusura della shell</h3> <div class="paragraph"> <p>Se chiudi il terminale, tutti i lavori sospesi o in background vengono distrutti. Perché un processo sopravviva, utilizzi`nohup`+<code>disown</code>:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Fermer le terminal → le build continue</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_processi_interattivi_e_fg">processi interattivi e fg</h3> <div class="paragraph"> <p>Alcuni programmi interattivi non funzionano bene dopo un`Ctrl+Z`+<code>fg</code>. È raro ma succede :</p> </div> <div class="ulist"> <ul> <li> <p>Alcuni programmi che utilizzano segnali (vim, htop, less gestiscono bene`Ctrl+Z`)</p> </li> <li> <p>I programmi di rete lunghi (ssh, opencode) recuperano generalmente correttamente</p> </li> <li> <p>I programmi che modificano il terminale (ncurses) possono a volte lasciare il terminale in uno stato inatteso</p> </li> </ul> </div> <div class="paragraph"> <p>In caso di terminale corrotto dopo un`fg`, digita :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">reset</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramma_riassuntivo">Diagramma riassuntivo</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 title "### JBake CLI Commands ``` ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 title "### JBake CLI Commands ``` # Initialize a new JBake project jbake -i # Bake (generate) the site jbake -b # Bake and serve locally jbake -b -s # Bake and watch for changes jbake -b --reset # Specify source and destination jbake source_folder output_folder # Clear the output directory before baking jbake -b . output --reset ``` fg — Il suggerimento che cambia tutto" rectangle "Problema" as problem #LightCoral { card "Terminal bloccato\npar un processo" as p1 card "Aprire un nuovo terminale = soluzione pesante" as p2 } rectangle "**Solution**" as solution #LightGreen { card "Ctrl+Z → sospendere" as s1 card "fg → riprende" as s2 card "bg → in secondo piano" as s3 card "visualizzare i sospesi" as s4 } rectangle "Vantaggi" as advantages #SkyBlue { card "Nessuna perdita di contesto" as a1 card "Nessun riavvio" as a2 card "Un solo terminale basta" as a3 } problem -right-> solution : "La soluzione nativa\nUnix da 40 anni" solution -right-> advantages : "Risultato" note bottom of advantages fg n'est pas un tips obscur C'est un mécanisme fondamental du shell Unix end note @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_fg_è_sottovalutato">Perché fg è sottovalutato</h2> <div class="sectionbody"> <div class="paragraph"> <p>La maggior parte degli sviluppatori moderni scopre`fg`tardi, forse mai. Alcune ragioni :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gli IDE nascondono il terminale</strong>: VS Code offre un terminale integrato, ma le schede multiple rendono`fg`meno necessario all’apparenza</p> </li> <li> <p><strong>Gli strumenti grafici sostituiscono le CLI</strong>: i gestori di file, i monitor di sistema, i client Git grafici</p> </li> <li> <p><strong>tmux e screen</strong>: questi multiplexer risolvono lo stesso problema in modo diverso, ma`fg`è più semplice e sempre disponibile</p> </li> </ol> </div> <div class="paragraph"> <p>Tuttavia,<code>fg</code><mark>#</mark> JBake CLI Commands <code>`</code> # Initialize a new JBake project jbake -i</p> </div> </div> </div> <h1 id="_bake_generate_the_site_jbake_b" class="sect0">Bake (generate) the site jbake -b</h1> <h1 id="_bake_and_serve_locally_jbake_b_s" class="sect0">Bake and serve locally jbake -b -s</h1> <h1 id="_bake_and_watch_for_changes_jbake_b_reset" class="sect0">Bake and watch for changes jbake -b --reset</h1> <h1 id="_specify_source_and_destination_jbake_source_folder_output_folder" class="sect0">Specify source and destination jbake source_folder output_folder</h1> <h1 id="_clear_the_output_directory_before_baking_jbake_b_output_reset_è" class="sect0">Clear the output directory before baking jbake -b . output --reset <code>`</code> è :</h1> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>universale</strong>: presente in tutti i shell POSIX (bash, zsh, fish…​)</p> </li> <li> <p><strong>Senza dipendenza</strong>: non è necessario installare tmux o screen</p> </li> <li> <p><strong>istantanea</strong>: due colpi (<code>Ctrl+Z`poi`fg</code>) per sospendere e riprendere</p> </li> <li> <p><strong>Conservatore del contesto</strong>: lo stato del processo è intatto</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ] @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "Perché fg è sottostimato ?" as why #LightCoral { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif rectangle "Perché fg è sottostimato ?" as why #LightCoral { card "IDE con terminale multi-scheda" as w1 card "Strumenti grafici che sostituiscono la CLI" as w2 card "tmux/screen\nrisolvono il problema\naltrimenti" as w3 } rectangle "Perché fg è superiore ?" as superior #LightGreen { card "Universale: bash,\nzsh, fish, sh..." as s1 card "Senza dipendenza : nessuna installazione" as s2 card "Due colpi : Ctrl+Z quindi fg" as s3 card "Contesto preservato :\nzero perdita di stato" as s4 } why -right-> superior : "La semplicità\nguadagna sempre" @enduml</pre> </div> </div> <div class="sect1"> <h2 id="_memoria_tecnica_i_segnali">Memoria tecnica: i segnali</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per i curiosi, ecco i segnali implicati:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 14.2857%;"> <col style="width: 28.5714%;"> <col style="width: 28.5714%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">segnale</th> <th class="tableblock halign-left valign-top">Nome</th> <th class="tableblock halign-left valign-top">Inviato da</th> <th class="tableblock halign-left valign-top">Effetto</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Interruzione — termina il processo</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Termina con core dump</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">18</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stop interattivo — sospende il processo</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">19</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGCONT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code>/<code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Continua — riprende un processo sospeso</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTERM</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">terminazione propria</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGKILL</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill -9 %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Terminazione forzata (impossibile da intercettare)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Il flusso completo:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signal-flow.svg" alt="signal flow" width="412" height="525"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>`fg`Non è un suggerimento oscuro — è un meccanismo fondamentale della shell Unix, disponibile dagli anni '70. Il fatto che la maggior parte degli sviluppatori lo ignori è un sintomo della nostra epoca : gli IDE e i multiplexer ci hanno allontanato dalle basi.</p> </div> <div class="paragraph"> <p>Ma quando siete su un server SSH, in un terminale minimale, o semplicemente mentre lo usate`opencode`e che il LLM è in pieno lavoro —<code>Ctrl+Z</code>, <code>fg</code>, <code>bg</code>, `jobs`sono i tuoi migliori amici.</p> </div> <div class="paragraph"> <p><em><em>_ Ctrl+Z sospende, fg riprende. È il play-pause del terminale. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_riferimenti">Riferimenti</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><code>man bash</code>— sezione JOB CONTROL</p> </li> <li> <p><code>man signal</code>— lista dei segnali POSIX</p> </li> <li> <p><a href="https://www.gnu.org/software/bash/manual/bash.html#Job-Control">Bash Reference Manual — Job Control</a></p> </li> <li> <p><a href="https://man7.org/linux/man-pages/man7/signal.7.html">man 7 signal — segnali Linux</a></p> </li> <li> <p><a href="https://tldp.org/LDP/abs/html/x312743.htm">Guida avanzata allo scripting Bash — Controllo dei lavori</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0103_vscode_local_install_custom_fonts_post.html Fri, 17 Apr 2026 00:00:00 +0000 blog/2026/0103_vscode_local_install_custom_fonts_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_panoramica_del_percorso">Panoramica del percorso</a></li> <li><a href="#_il_perché_vs_code_nella_home">Il Perché : VS Code nella Home</a> <ul class="sectlevel2"> <li><a href="#_il_problema_con_linstallazione_di_sistema">Il problema con l’installazione di sistema</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 8 minutes</div> <p>Perché installare VS Code in`/opt`o via`apt`quando si può posizionarlo nella propria home e trasformare il proprio IDE in un terreno di gioco senza mai digitare`sudo`Ecco il racconto di un’installazione locale seguito da una dura lotta per ingrandire i caratteri del menu e dell’esploratore di file.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">indice</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_panoramica_del_percorso">Panoramica del percorso</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-local-overview.svg" alt="vscode local overview" width="1057" height="380"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_il_perché_vs_code_nella_home">Il Perché : VS Code nella Home</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_problema_con_linstallazione_di_sistema">Il problema con l’installazione di sistema</h3> <div class="paragraph"> <p>VS Code installato via`apt`, <code>dnf`o in</code>/opt`blocca i file dell’applicazione dietro i privilegi root. Qualsiasi modifica del CSS nativo, di`product.json`o della cartella di installazione richiede`sudo`.</p> </div> <div class="paragraph"> <p>Ora, quando si utilizza<strong>opencode</strong><mark>#</mark> Gradle Integration JBake can be integrated into Gradle builds using the JBake Gradle plugin or by calling the JBake CLI directly:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } ---- (tool CLI per pilotare un LLM sul proprio codice), l'agente ha bisogno di potere : * Scrivere nei file di configurazione`~/.config/Code/User/settings.json`) — ça, c'est déjà dans le home * Modifica le risorse dell'IDE (CSS del workbench,`product.json`) per le personalizzazioni avanzate — questo, è bloccato senza sudo === La soluzione : un'installazione locale Si scarica l'archivio tarball ufficiale e lo si decomprime direttamente in`~/apps/`: [source,bash] ---- mkdir -p ~/apps cd ~/apps wget "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" -O vscode.tar.gz tar -xzf vscode.tar.gz rm vscode.tar.gz ---- Il binario si trova allora in`~/apps/VSCode-linux-x64/bin/code`. Nessuno`sudo`non è necessario per leggere, modificare o sostituire qualsiasi file sotto`~/apps/VSCode-linux-x64/`. === Vantaggi concreti [plantuml,vscode-local-vs-system,svg] ---- @startuml skinparam backgroundColor #FEFEFE rectangle "Installazione Sistema\n(/opt, apt, dnf)" #LightCoral { card "VS Code proprietà di root" { [CSS du workbench : sudo requis] [product.json : sudo requis] [Dossier d'install : non modifiable] } } rectangle "Installazione Home (~/apps)" #LightGreen { card "VS Code proprietà dell'utente" { [CSS du workbench : libre] [product.json : libre] [Dossier d'install : libre] [Script update maison] } } "Installazione Sistema\n(/opt, apt, dnf)" -right-> "Installazione Home (~/apps)" : **Non, merci**\nJe prends le home note bottom of "Installazione Home (~/apps)" L'agent opencode+LLM peut modifier les fichiers de l'IDE sans aucune élévation de privilèges end note @enduml ---- [cols="1,2"] |=== |vantaggio |dettaglio |Nessun sudo |Tutti i file dell'IDE appartengono all'utente |Modifica diretta del CSS |Si può patchare`workbench.desktop.main.css`senza elevazione di privilegi |Script di aggiornamento fatto in casa |Uno semplice script shell scarica, sostituisce e riapplica automaticamente |isolamento |L'installazione di sistema non è inquinata ; rollback = eliminare la cartella |=== == Personalizzare il carattere del menu principale === la constatazione Il font predefinito del menu principale (File, Edit, View...) e dei dropdown è troppo piccolo. VS Code non offre alcuna impostazione per modificarla. === La tecnica : patch CSS diretto Aggiungiamo il CSS alla fine del file`workbench.desktop.main.css`: [plantuml,menubar-patch-sequence,svg] ---- @startuml skinparam backgroundColor #FEFEFE autonumber actor Développeur as dev participant "workbench.desktop\n.main.css" as css participant "product.json" as product participant "VS Code" as vscode == Patch CSS == dev -> css : Ajouter règles font-size\n(.menubar-menu-title, etc.) dev -> vscode : Redémarrer VS Code vscode -> vscode : Charge le CSS patché vscode --> dev : Menus et dropdowns en 23px/22px ✓ == Suppression warning == vscode --> dev : ⚠️ "L'installazione è corrotta" dev -> product : Supprimer clé "sommi di controllo"\n(python3 -c ...) dev -> vscode : Redémarrer VS Code vscode --> dev : Plus de warning ✓ note over css, product Deux fichiers dans ~/apps/ = modifiables sans sudo end note @enduml ---- [source,bash] ---- CSS_FILE="$HOME/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css" cat >> "$CSS_FILE" << 'EOF' .menubar-menu-title{font-size:23px!important} .menubar>.menubar-menu-button{font-size:23px!important} .monaco-menu-option{font-size:22px!important;line-height:34px!important} .monaco-menu .action-label:not(.codicon){font-size:22px!important} .menubar-menu-items-holder .monaco-menu .action-item .action-label{font-size:22px!important} EOF ---- === Rimuovi l'avviso di integrità VS Code rileva le modifiche ai suoi file e mostra un banner "Your installation is corrupt". Per evitarlo, si eliminano i checksum di`product.json`: [source,python] ---- import json product_json = "$HOME/apps/VSCode-linux-x64/resources/app/product.json" with open(product_json, 'r') as f: data = json.load(f) data.pop('checksums', None) with open(product_json, 'w') as f: json.dump(data, f, indent=2) ---- Dopo il riavvio, nessun warning e i menu sono finalmente leggibili. == Personalizzare il carattere del riquadro Explorer — la battaglia === Tentativo 1 : un parametro che non esiste Si prova prima il parametro nativo`workbench.tree.fontSize`in`settings.json`: [source,json] ---- { "workbench.tree.fontSize": 20 } ---- Risultato :**nessun effetto**. Questo parametro non esiste in VS Code. La prova che i parametri non riconosciuti vengono ignorati silenziosamente. === Tentativa 2: l'estensione Custom CSS and JS Loader Installiamo l'estensione`be5invis.vscode-custom-css`: [source,bash] ---- ~/apps/VSCode-linux-x64/bin/code --install-extension be5invis.vscode-custom-css ---- Si crea un file CSS in`~/.vscode-custom-css/custom.css`con selettori che mirano agli elementi dell'esploratore : [source,css] ---- .monaco-tree-rows .monaco-tree-row, .sidebar .monaco-list-row, .explorer-viewlet .monaco-list-row, .monaco-list-row .monaco-icon-label { font-size: 22px !important; line-height: 36px !important; } ---- E si fa riferimento a questo file nelle impostazioni: [source,json] ---- { "vscode_custom_css.imports": [ "file:///home/user/.vscode-custom-css/custom.css" ] } ---- Risultato :**le modifiche non si applicano**. === La trappola: è necessario attivare l'estensione ogni volta La documentazione dell'estensione è discreta su questo punto cruciale : dopo ogni modifica del CSS custom, è necessario**imperativamente**eseguire il comando dalla tavolozza : 1. `Ctrl+Shift+P`→ digitare**Abilita CSS e JS personalizzati** 2. VS Code chiede un riavvio → Accetta Senza questo passaggio, il CSS non viene mai iniettato nell'IDE. === Tentativo 3 : le linee si sovrappongono Anche con`font-size: 22px` et `line-height: 36px`, le lettere con gamba (g, p, f, b) sconfinano sulle righe vicine. Stiamo tentando di aggiungere`height` et `min-height`: [source,css] ---- .monaco-list-row { height: 36px !important; min-height: 36px !important; } ---- Risultato :**nessun cambiamento**. VS Code calcola le altezze delle righe in JavaScript e sovrascrive i valori CSS. === La soluzione : `zoom` sul contenitore padre [plantuml,explorer-css-approaches,svg] ---- @startuml skinparam backgroundColor #FEFEFE rectangle "Tentativo 1 Parametro inesistente" #LightCoral { card "workbench.tree.fontSize" as t1 { [VS Code ignore le paramètre] } } rectangle "Tentativo 2 CSS personalizzato + font-size" #LightYellow { card ".monaco-list-row { font-size: 22px }" as t2 { [Texte plus grand\nmais lignes superposées] } } rectangle "Tentativo 3 font-size + line-height + height" #LightYellow { card "height: 36px !important" as t3 { [VS Code override\npar JavaScript] [Aucun effet] } } rectangle "Solution zoom sul contenitore padre" #LightGreen { card ".monaco-list-rows { zoom: 1.25 }" as t4 { [Texte + espacement\nproportionnels] [Layout JS respecté] [✓ Résultat conforme] } } t1 -down-> t2 : Pas de paramètre ?\nOn essaie le CSS t2 -down-> t3 : Lignes superposées ?\nOn force la hauteur t3 -down-> t4 : Override JS ?\nOn utilise zoom @enduml ---- Piuttosto che lottare contro il layout JavaScript, si utilizza la proprietà`zoom`sul contenitore delle righe : [source,css] ---- .explorer-viewlet .monaco-list-rows, .sidebar .monaco-list-rows { zoom: 1.25; } ---- `zoom`ingrandisce uniformemente il rendering del contenitore — testo e spaziatura — senza rompere il layout calcolato dal motore JavaScript di VS Code. Il fattore 1.25 corrisponde approssimativamente a un passaggio da 13px a 16px. Risultato :**i nomi dei file sono finalmente leggibili, le linee correttamente spaziate**. === Riepilogo dei selectors e di ciò che funziona [cols="1,2,1"] |=== |Approccio |CSS |Risultato |`font-size`sopra`.monaco-list-row` |`font-size: 22px !important` |Testo più grande ma linee sovrapposte |`line-height`+`height`su`.monaco-list-row` |`line-height: 36px; height: 36px` |Nessun effetto (override JS) |`zoom`sopra`.monaco-list-rows` |`zoom: 1.25` |Riuscito — testo + spaziatura proporzionale |=== == Lo script di aggiornamento automatico [plantuml,vscode-update-sequence,svg] ---- @startuml skinparam backgroundColor #FEFEFE autonumber actor "Sviluppatore o cron" as dev participant "vscode-update.sh" as script participant "vscode tarball\n(code.visualstudio.com)" as remote participant "~/apps/\nVSCode-linux-x64/" as local participant "~/apps/\nvscode-backup" as backup participant "workbench\n.desktop.main.css" as css participant "product.json" as product dev -> script : ./vscode-update.sh script -> local : Lire version courante script -> remote : wget dernière version script -> script : Comparer versions alt Version identique script --> dev : "Già aggiornato!" else Nouvelle version script -> backup : Sauvegarder installation courante\n(horodatée) script -> local : rm -rf ancienne installation script -> local : mv nouvelle installation script -> css : Ajouter patch CSS\n(menubar 23px, dropdown 22px) script -> product : Supprimer checksums\n(python3) script --> dev : "Aggiornamento completato 1.xx.yy → 1.zz.ww" end note @enduml ---- === Il problema Quando VS Code si aggiorna, sostituisce la cartella di installazione e**cancella tutti i patch CSS**. Bisogna riapplicare le modifiche manualmente ogni volta. === Lo script `vscode-update.sh Si crea`~/apps/vscode-update.sh`: [source,bash] ---- #!/bin/bash set -e VSCODE_DIR="$HOME/apps/VSCode-linux-x64" BACKUP_DIR="$HOME/apps/vscode-backup" TEMP_DIR="/tmp/vscode-update" MENUBAR_FONT_SIZE="23px" DROPDOWN_FONT_SIZE="22px" echo "=== VS Code Local Updater ===" CURRENT_VERSION=$("$VSCODE_DIR/bin/code" --version 2>/dev/null | head -1) echo "Current version: $CURRENT_VERSION" echo "Downloading latest VS Code..." mkdir -p "$TEMP_DIR" wget -q "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" \ -O "$TEMP_DIR/vscode.tar.gz" echo "Extracting..." mkdir -p "$TEMP_DIR/extracted" tar -xzf "$TEMP_DIR/vscode.tar.gz" -C "$TEMP_DIR/extracted" NEW_VERSION=$("$TEMP_DIR/extracted/VSCode-linux-x64/bin/code" \ --version 2>/dev/null | head -1) echo "New version: $NEW_VERSION" if [ "$CURRENT_VERSION" = "$NEW_VERSION" ]; then echo "Already up to date!" rm -rf "$TEMP_DIR" exit 0 fi echo "Backing up current installation..." mkdir -p "$BACKUP_DIR" cp -r "$VSCODE_DIR" "$BACKUP_DIR/VSCode-linux-x64-$(date +%Y%m%d-%H%M%S)" echo "Updating..." rm -rf "$VSCODE_DIR" mv "$TEMP_DIR/extracted/VSCode-linux-x64" "$VSCODE_DIR" rm -rf "$TEMP_DIR" CSS_FILE="$VSCODE_DIR/resources/app/out/vs/workbench/workbench.desktop.main.css" echo "Re-applying custom CSS patch \ (menubar=${MENUBAR_FONT_SIZE}, dropdown=${DROPDOWN_FONT_SIZE})..." cat >> "$CSS_FILE" << CSSEOF .menubar-menu-title{font-size:${MENUBAR_FONT_SIZE}!important}\ .menubar>.menubar-menu-button{font-size:${MENUBAR_FONT_SIZE}!important}\ .monaco-menu-option{font-size:${DROPDOWN_FONT_SIZE}!important;\ line-height:34px!important}\ .monaco-menu .action-label:not(.codicon)\ {font-size:${DROPDOWN_FONT_SIZE}!important}\ .menubar-menu-items-holder .monaco-menu .action-item .action-label\ {font-size:${DROPDOWN_FONT_SIZE}!important} CSSEOF PRODUCT_JSON="$VSCODE_DIR/resources/app/product.json" if [ -f "$PRODUCT_JSON" ]; then echo "Removing checksums to prevent integrity warning..." python3 -c " import json with open('$PRODUCT_JSON','r') as f: data=json.load(f) data.pop('checksums', None) with open('$PRODUCT_JSON','w') as f: json.dump(data,f,indent=2) print('Done.') " fi echo "=== Update complete: $CURRENT_VERSION -> $NEW_VERSION ===" ---- Lo script : 1. Scarica l'ultima versione stabile 2. Verifica se la versione è diversa dall'attuale 3. Salva l'installazione corrente (timestampata) in`~/apps/vscode-backup/` 4. Sostituire la cartella di installazione 5. **Ri-applica**la patch CSS del menu principale 6. **Supprime les checksums** de `product.json`per evitare l'avviso di integrità NOTE: Les customisations du volet Explorer via l'extension Custom CSS et le fichier `~/.vscode-custom-css/custom.css`sopravvivono agli aggiornamenti perché vivono fuori dalla cartella di installazione. == File coinvolti — panoramica [plantuml,vscode-files-deployment,svg] ---- @startuml skinparam backgroundColor #FEFEFE skinparam componentStyle rectangle rectangle "Installazione VS Code (~/apps/VSCode-linux-x64/)" #LightCoral { component "workbench.desktop\n.main.css" as css #LightCoral component "product.json" as product #LightCoral component "binario\nbin/code" as binary #LightCoral } rectangle "Configurazione utente (~/.config/Code/)" #LightGreen { component "settings.json" as settings #LightGreen component "estensioni/" as extensions #LightGreen } rectangle "Personalizzazione persistente (~/.vscode-custom-css/)" #SkyBlue { component "custom.css (zoom: 1.25)" as customcss #SkyBlue } rectangle "Automazione (~/apps/)" #LightYellow { component "vscode-update.sh" as script #LightYellow component "vscode-backup/" as backup #LightYellow } script ..> css : Re-patch après MAJ script ..> product : Supprime checksums\naprès MAJ settings --> customcss : Référence via\nvscode_custom_css.imports extensions ..> css : Custom CSS Loader\ninjecte custom.css note bottom of css **Ne survit pas** aux mises à jour Re-patché par le script end note note bottom of customcss **Survit** aux mises à jour Vit hors du dossier d'installation end note note bottom of settings **Survit** aux mises à jour Vit dans ~/.config/ end note @enduml ---- [cols="2,3,2"] |=== |Sentiero |Ruolo |Sopravvive agli aggiornamenti? |`~/apps/VSCode-linux-x64/` |Installazione dell'IDE |No (sostituita) |`~/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css` |CSS del workbench (menu, dropdowns) |Non (ripariato dallo script) |`~/apps/VSCode-linux-x64/resources/app/product.json` |Checksum d'integrità |Non (ri-pulito dallo script) |`~/apps/vscode-update.sh` |Script di aggiornamento automatico |Sì |`~/.config/Code/User/settings.json` |Impostazioni utente (fontSize, custom CSS) |Sì |`~/.vscode-custom-css/custom.css` |CSS personalizzato per l'Explorer (zoom) |Sì |=== == Lezioni apprese [plantuml,vscode-lessons-learned,svg] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultFontName sans-serif skinparam ArrowColor #444444 rectangle "**Installazione locale**\n nel home" as install #LightGreen { card "Non usare sudo\n per modificare CSS/config" as i1 card "opencode+LLM può modificare tutto" as i2 card "Rollback = ripristinare\n il backup datato" as i3 } rectangle "**Personalizzazione CSS** zoom vs dimensione carattere" as css #LightYellow { card "zoom > font-size\n per componenti lista" as c1 card "Override JS del layout altezza/line-height" as c2 card "Estensione Custom CSS\n richiede attivazione\n manuale (Ctrl+Shift+P)" as c3 } rectangle "**Automatizzazione**\n script di aggiornamento" as auto #LightCoral { card "Re-patch CSS dopo\n ogni aggiornamento" as a1 card "Rimuovi checksums product.json" as a2 card "Backup datato\n prima della sostituzione" as a3 } install -right-> css : ensuite css -right-> auto : enfin note top of install Contrôle total sans élévation de privilèges end note note top of auto Sans script, chaque MAJ efface les patches CSS end note @enduml ---- === Installare nella home libera tutto Un'installazione locale in`~/apps`dà un controllo totale su VS Code : * Nessun`sudo`per modificare il CSS o la configurazione * L'agente opencode+LLM può scrivere nei file di configurazione e negli asset dell'IDE * Rollback banale: ripristinare il backup con timestamp === zoom` > `font-size` per i componenti della lista VS Code controlla l'altezza delle righe tramite JavaScript. Modifica`font-size`senza poter toccare l'altezza assegnata dal motore di layout si ottengono testi che traboccano. La proprietà`zoom`Sul contenitore padre ingrandisce tutto proporzionalmente e aggira questo problema. === L'estensione Custom CSS richiede un'attivazione esplicita Non è un parametro "set and forget". Ogni modifica del file CSS personalizzato richiede di eseguire nuovamente "Enable Custom CSS and JS" dalla palette dei comandi`Ctrl+Shift+P`). === Uno script di aggiornamento è indispensabile Senza script, ogni aggiornamento di VS Code elimina i patch CSS del workbench. Lo script`vscode-update.sh`automatizza il download, la sostituzione, il re-patch e la pulizia dei checksum. == Riferimenti rapidi * Download VS Code : https://code.visualstudio.com/Download * Estensione Caricatore CSS e JS personalizzato :`be5invis.vscode-custom-css` * Issue VS Code che richiede un'impostazione nativa per il carattere dell'Esplora file:https://github.com/microsoft/vscode/issues/149[github.com/microsoft/vscode#149]</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0102_migration_gradle_script_to_plugin_post.html Thu, 16 Apr 2026 00:00:00 +0000 blog/2026/0102_migration_gradle_script_to_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_contesto_e_obiettivo">Contesto e obiettivo</a> <ul class="sectlevel2"> <li><a href="#_il_punto_di_partenza">Il punto di partenza</a></li> <li><a href="#_lobiettivo">L’obiettivo</a></li> </ul> </li> <li><a href="#_il_primo_ostacolo_ruby_gems">Il primo ostacolo : `ruby { gems() }</a> <ul class="sectlevel2"> <li><a href="#_ciò_che_nasconde_lo_zucchero_sintattico_groovy">Ciò che nasconde lo zucchero sintattico Groovy</a></li> <li><a href="#_scomposizione_del_meccanismo">Scomposizione del meccanismo</a></li> </ul> </li> <li><a href="#_la_soluzione_in_tre_parti">La soluzione in tre parti</a> <ul class="sectlevel2"> <li><a href="#_parte_1_il_repo_ivy_per_rubygems">Parte 1 : il repo Ivy per rubygems</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_contesto_e_obiettivo">Contesto e obiettivo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_punto_di_partenza">Il punto di partenza</h3> <div class="paragraph"> <p>Il progetto`slider-gradle`genera presentazioni Reveal.js da file AsciiDoc tramite il plugin Gradle`org.asciidoctor.jvm.revealjs`. La configurazione dell’attività principale`asciidoctorRevealJs`viveva direttamente nel buildscript radice`build.gradle.kts`(blank)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("org.asciidoctor.jvm.revealjs") } apply<slides.SlidesPlugin>() project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { repositories { ruby { gems() } } revealjs { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } revealjsOptions { // ... configuration complète } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_lobiettivo">L’obiettivo</h3> <div class="paragraph"> <p>Sposta tutta questa configurazione in`buildSrc/src/main/kotlin/slides/SlidesPlugin.kt`affinché lo script di build del consumatore si riduca a :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>Il plug-in deve essere totalmente autonomo: applica da sé le sue dipendenze di plug-in, configura i suoi repository e gestisce i suoi gem Ruby.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_il_primo_ostacolo_ruby_gems">Il primo ostacolo : `ruby { gems() }</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ciò_che_nasconde_lo_zucchero_sintattico_groovy">Ciò che nasconde lo zucchero sintattico Groovy</h3> <div class="paragraph"> <p>La linea`repositories { ruby { gems() } }`è un’estensione DSL Groovy disponibile solo nel contesto di esecuzione del buildscript. Non esiste come API Kotlin statica accessibile da buildSrc.</p> </div> <div class="paragraph"> <p>Tentando di chiamarlo da`SlidesPlugin.kt`, la compilazione fallisce immediatamente.</p> </div> </div> <div class="sect2"> <h3 id="_scomposizione_del_meccanismo">Scomposizione del meccanismo</h3> <div class="paragraph"> <p>Dopo l’analisi della cache Gradle (<code>~/.gradle/caches/modules-2/files-2.1/rubygems/</code>), si scopre nel file`ivy-3.1.0.xml`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><artifact type='gem' url='https://rubygems.org/gems/asciidoctor-revealjs-3.1.0.gem' /></code></pre> </div> </div> <div class="paragraph"> <p>`ruby { gems() }`effettuava realmente<strong>tre operazioni distinte</strong> :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Registrare un repo Ivy che punta a`https://rubygems.org/gems/`</p> </li> <li> <p>Escludere il gruppo`rubygems`dei repository Maven per evitare i conflitti</p> </li> <li> <p>Salvare la gem nella configurazione`asciidoctorGems`affinché JRuby lo carichi in fase di esecuzione</p> </li> </ol> </div> <div class="paragraph"> <p>Queste tre responsabilità devono essere riprodotte separatamente in Kotlin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_in_tre_parti">La soluzione in tre parti</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_parte_1_il_repo_ivy_per_rubygems">Parte 1 : il repo Ivy per rubygems</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } <i class="conum" data-value="1"></i><b>(1)</b> metadataSources { artifact() } content { includeGroup("rubygems") } }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>L’estensione`.gem`deve essere hardcodata.<code>[ext]`risolve per impostazione predefinita in</code>.jar`, il che provoca un errore`Resource missing`.</td> </tr> </table> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> Le repo Ivy est déclaré directement sur <code>project.repositories`e non in un blocco`repositories { }`perché il ricevitore di questo blocco non è il`RepositoryHandler`standard di Gradle ma una API grolifant incompatibile con l’estensione.`ivy</code><mark>#</mark> Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin JBake per Gradle o chiamando direttamente la CLI JBake: </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") } ---- DSL Kotlin. === Parte 2: la dipendenza asciidoctorGems Il plugin`org.asciidoctor.jvm.gems`deve essere applicato per primo — crea la configurazione`asciidoctorGems`e il compito`asciidoctorGemsPrepare`</think> : [source,kotlin] ---- project.plugins.apply("org.asciidoctor.jvm.gems") project.plugins.apply("org.asciidoctor.jvm.revealjs") <i class="conum" data-value="1"></i><b>(1)</b> project.dependencies { add("asciidoctorGems", "rubygems:asciidoctor-revealjs:3.1.0@gem") <i class="conum" data-value="2"></i><b>(2)</b> } ---- <1> L'ordine di applicazione è importante :`gems`prima`revealjs`. <2> Il qualificatore`@gem`Forza l'estensione corretta sulla dipendenza. === Parte 3 : settings.gradle.kts `dependencyResolutionManagement`in`settings.gradle.kts`deve consentire ai progetti di dichiarare i propri repo: [source,kotlin] ---- @Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) } ---- Senza questa linea, Gradle ignora i repo dichiarati nel plugin e la risoluzione delle gemme fallisce. == Introspezione dell'API tramite bytecode === Perché `javap`? Il plugin`asciidoctor-gradle-jvm-slides`è nella versione`4.0.0-alpha.1`. La sua documentazione è inesistente o incompleta. L'unica fonte affidabile è l'ispezione diretta delle classi compilate. === Gerarchia del compito [source,bash] ---- javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask ---- Risultato : [source] ---- public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask implements org.asciidoctor.gradle.base.slides.SlidesToExportAware ---- === Scoperta di `forkOptions Ispezionando`AbstractAsciidoctorTask`: [source,bash] ---- javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm" ---- Si trova : [source] ---- final org.ysb33r.grolifant.api.v4.JavaForkOptions javaForkOptions; public void forkOptions(org.gradle.api.Action<org.ysb33r.grolifant.api.v4.JavaForkOptions>); public static final org.asciidoctor.gradle.base.process.ProcessMode JAVA_EXEC; ---- === L'API di JavaForkOptions (grolifant) `javaLauncher`non esiste per questa attivita. L'API reale di`org.ysb33r.grolifant.api.v4.JavaForkOptions`esposizione: [source] ---- public void executable(java.lang.Object); <i class="conum" data-value="1"></i><b>(1)</b> public void setExecutable(java.lang.Object); ---- Il metodo`executable(Object)`sostituisce l'assegnazione`executable = ...`che non compila (`val`non può essere riassegnato). === RevealJSExtension `revealjs { }`non è un metodo del compito ma una**estensione del progetto**: [source,bash] ---- javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension ---- Si accede via: [source,kotlin] ---- project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } ---- == Configurazione del toolchain Java === Il problema di JavaToolchainService `JavaToolchainService`non è un'estensione di progetto. La chiamata successiva fallisce : [source,kotlin] ---- // ERREUR : Extension of type 'JavaToolchainService' does not exist project.extensions.getByType<JavaToolchainService>() ---- L'API giusta è`serviceOf`: [source,kotlin] ---- import org.gradle.kotlin.dsl.support.serviceOf project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } } ---- == Rilevamento automatico Docker === Contesto Il plugin Asciidoctor/JRuby richiede Java 17. Kotlin 2.0.x in buildSrc non supporta Java 25 (il parser di versione si arresta su`"25.0.2"`Il daemon Gradle deve quindi essere eseguito su Java 17 o Docker deve essere utilizzato. === Strategia 1. Docker disponibile → esecuzione tramite container`eclipse-temurin:17`(comportamento predefinito) 2. Docker assente + Java 17 → esecuzione locale 3. Docker assente + Java > 17 → errore esplicito [source,kotlin] ---- val isDockerAvailable = try { Runtime.getRuntime().exec(arrayOf("docker", "info")).waitFor() == 0 } catch (e: Exception) { false } val javaVersion = JavaVersion.current().majorVersion.toInt() when { isDockerAvailable -> project.tasks.register<Exec>(TASK_ASCIIDOCTOR_REVEALJS) { group = GROUP_TASK_SLIDER description = "Slider settings and generation (via Docker)" dependsOn(TASK_CLEAN_SLIDES_BUILD) finalizedBy(TASK_DASHBOARD_SLIDES_BUILD) commandLine( "docker", "run", "--rm", "-v", "${project.rootDir.absolutePath}:/workspace", "-v", "${System.getProperty("user.home")}/.gradle:/root/.gradle", "-w", "/workspace", "eclipse-temurin:17", "./gradlew", TASK_ASCIIDOCTOR_REVEALJS ) workingDir = project.rootDir } javaVersion == 17 -> { project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } metadataSources { artifact() } content { includeGroup("rubygems") } } project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } // ... reste de la configuration } } else -> error( "Docker est requis pour exécuter $TASK_ASCIIDOCTOR_REVEALJS " + "avec Java $javaVersion. Installez Docker ou utilisez Java 17." ) } ---- == Risultato finale === Il buildscript consumatore [source,kotlin] ---- apply<slides.SlidesPlugin>() ---- È tutto. Il plugin si assume l'intera responsabilità. === settings.gradle.kts [source,kotlin] ---- pluginManagement { repositories { mavenLocal() gradlePluginPortal() } } plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" } @Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) } rootProject.name = "slider-gradle" ---- == Riepilogo delle trappole e delle soluzioni [cols="2,3,3"] |=== |problema |Causa |soluzione |`ruby { gems() }`### Integrazione Gradle JBake può essere integrato nelle build Gradle utilizzando il plugin JBake Gradle o chiamando direttamente la CLI di JBake: |Gradle cerca un`.jar`al posto di un`.gem` |`[ext]`ne risolve`jar`per impostazione predefinita |Hardcoder`.gem`nel pattern Ivy + qualificatore`@gem` |`ivy { }`python print(" non compila in", end='')`repositories { }` |Ricevitore grolifant incompatibile con il DSL Kotlin |Chiamata diretta`project.repositories.ivy { }` |`javaLauncher`non risolto |Proprietà inesistente su`AsciidoctorJRevealJSTask` |`setInProcess("JAVA_EXEC")`+`forkOptions { executable(...) }` |`executable = ...`non compila |Proprietà`val`in`JavaForkOptions`grolifant |Metodo`executable(Object)` à la place |`JavaToolchainService`introvabile via`extensions` |È un servizio Gradle, non un'estensione |`project.serviceOf<JavaToolchainService>()` |`revealjs { }`non risolto nel compito |Estensione del progetto, non metodo di attività |`project.extensions.getByType<RevealJSExtension>()` |Build si blocca con Java 25 |Kotlin 2.0.x non analizza le versioni Java a due cifre |Rilevamento Docker automatico + fallback Java 17 |=== == Metodo di indagine: leggere un'API sconosciuta con javap === principio Quando la documentazione è assente o incompleta, i bytecode sono la fonte della verità. `javap`è lo strumento standard del JDK che decompila i file`.class`nelle firme Java leggibili, senza richiedere il codice sorgente. === Passo 1: individuare il jar nella cache Gradle Gradle scarica tutte le sue dipendenze in`~/.gradle/caches/modules-2/files-2.1/`. Il primo passo è trovare il jar che contiene la classe da ispezionare : [source,bash] ---- find ~/.gradle/caches -name "asciidoctor-gradle-jvm-slides*.jar" 2>/dev/null ---- .Risultato : [source] ---- /home/user/.gradle/caches/modules-2/files-2.1/org.asciidoctor/ asciidoctor-gradle-jvm-slides/4.0.0-alpha.1/.../ asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar ---- === Passo 2: elencare le classi del jar Prima di ispezionare una classe, si verifica che essa esista effettivamente nel jar: [source,bash] ---- jar tf asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar | grep -i "RevealJS\|revealjs" ---- .Questo rivela tutte le classi disponibili: `AsciidoctorJRevealJSTask`, `RevealJSExtension`, `RevealJSOptions`, etc. === Passo 3: ispezionare una classe [source,bash] ---- javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask ---- L'opzione`-p`mostra tutti i membri inclusi quelli privati. Il risultato mostra immediatamente la chiave : [source] ---- public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask ---- === Passo 4: risalire la gerarchia Il compito si estende`AbstractAsciidoctorTask`Lo si ispeziona a turno localizzando innanzitutto il suo jar : [source,bash] ---- find ~/.gradle/caches -name "asciidoctor-gradle-jvm-[0-9]*.jar" 2>/dev/null javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm\|java" ---- È lì che si scopre`forkOptions`, `JAVA_EXEC`, et `javaForkOptions` di tipo`org.ysb33r.grolifant.api.v4.JavaForkOptions`. === Passo 5: seguire i tipi sconosciuti `JavaForkOptions`è una classe grolifant sconosciuta. Si individua il suo jar : [source,bash] ---- find ~/.gradle/caches -name "grolifant*.jar" 2>/dev/null ---- Poi lo si ispeziona: [source,bash] ---- javap -p -classpath grolifant40-legacy-api-2.0.0-alpha.6.jar \ org.ysb33r.grolifant.api.v4.JavaForkOptions ---- Si trova`executable(java.lang.Object)`— il metodo corretto da chiamare, in opposizione a`executable = ...`che non compila perché è una proprietà`val`. === Passo 6: controllare le estensioni del progetto Per`revealjs { }`, la domanda era: è un metodo del compito o un'estensione di progetto? L'ispezione di`AsciidoctorJRevealJSTask` non mostra nessun metodo`revealjs`. Si ispeziona poi`RevealJSExtension`: [source,bash] ---- javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension | head -5 ---- [source] ---- public class RevealJSExtension implements groovy.lang.GroovyObject { public static final java.lang.String NAME; ---- La presenza di`NAME`conferma che è un'estensione registrata sul progetto, accessibile tramite`project.extensions.getByType<RevealJSExtension>()`. === Riepilogo del metodo [cols="1,3"] |=== |Passo |azione |1 |`find ~/.gradle/caches -name "*.jar"`— localizzare il jar |2 |`jar tf jar.jar \| grep NomClasse`— verificare che la classe esista |3 |`javap -p -classpath jar.jar NomCompletClasse`— ispezionare la classe |4 |Identificatore`extends`risalire la gerarchia |5 |Seguire i tipi sconosciuti nei loro jar |6 |cercare`NAME`per identificare un'estensione di progetto |=== Questo metodo si applica a qualsiasi plugin Gradle la cui API non è documentata o di cui la versione alfa non corrisponde più alla documentazione esistente. == Prossimo passo Il plugin buildSrc sarà estratto in un progetto indipendente pubblicato su Gradle Plugin Portal o Maven Local. Il buildscript del consumatore diventerà quindi : [source,kotlin] ---- plugins { id("slides") version "1.0.0" } ---- Et `settings.gradle.kts`sarà ridotto al minimo indispensabile senza riferimento a`foojay-resolver-convention`, il provisioning JDK gestito dal plugin stesso o documentato come prerequisito.</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0101_jbake_portfolio_post.html Thu, 15 Jan 2026 00:00:00 +0000 blog/2026/0101_jbake_portfolio_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_visione_architettonica">Visione Architettonica</a> <ul class="sectlevel2"> <li><a href="#_principio_direttivo">Principio direttivo</a></li> <li><a href="#_scelta_strategica_asciidoc_per_il_portfolio">Scelta strategica : AsciiDoc per il portfolio</a></li> <li><a href="#_modello_di_dati">Modello di dati</a></li> </ul> </li> <li><a href="#_casi_duso_dettagliati">Casi d’uso dettagliati</a> <ul class="sectlevel2"> <li><a href="#_uc1_aggiungere_un_elemento_al_portfolio">UC1 : Aggiungere un elemento al portfolio</a> <ul class="sectlevel3"> <li><a href="#_flusso_nominale">Flusso nominale</a></li> <li><a href="#_modello_del_file_da_creare">Modello del file da creare</a></li> <li><a href="#_punti_di_validazione">Punti di validazione</a></li> </ul> </li> <li><a href="#_uc2_rimuovere_un_elemento_del_portfolio">UC2 : Rimuovere un elemento del portfolio</a> <ul class="sectlevel3"> <li><a href="#_flusso_nominale_2">Flusso nominale</a></li> <li><a href="#_strategia_alternativa_archiviazione">Strategia alternativa: archiviazione</a></li> <li><a href="#_pulizia_delle_risorse">Pulizia delle risorse</a></li> </ul> </li> <li><a href="#_uc3_mettere_in_bozza">UC3: Mettere in bozza</a> <ul class="sectlevel3"> <li><a href="#_flusso_nominale_3">flusso nominale</a></li> <li><a href="#_stati_possibili">Stati possibili</a></li> <li><a href="#_casi_dutilizzo_tipici">Casi d’utilizzo tipici</a></li> </ul> </li> </ul> </li> <li><a href="#_architettura_di_templating">Architettura di templating</a> <ul class="sectlevel2"> <li><a href="#_strategia_di_template_riutilizzabili">Strategia di template riutilizzabili</a></li> <li><a href="#_schema_di_estrazione_dei_dati">Schema di estrazione dei dati</a></li> <li><a href="#_convenzioni_di_denominazione">Convenzioni di denominazione</a></li> </ul> </li> <li><a href="#_workflow_di_pubblicazione">Workflow di pubblicazione</a> <ul class="sectlevel2"> <li><a href="#_pipeline_di_sviluppo">Pipeline di sviluppo</a></li> <li><a href="#_ambienti">Ambienti</a></li> </ul> </li> <li><a href="#_estensibilità">Estensibilità</a> <ul class="sectlevel2"> <li><a href="#_aggiunta_di_nuovi_attributi">Aggiunta di nuovi attributi</a></li> <li><a href="#_categorizzazione_avanzata">Categorizzazione avanzata</a></li> </ul> </li> <li><a href="#_buone_pratiche">Buone pratiche</a> <ul class="sectlevel2"> <li><a href="#_organizzazione_dei_file">Organizzazione dei file</a></li> <li><a href="#_gestione_del_contenuto">Gestione del contenuto</a></li> <li><a href="#_performance">Performance</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div class="sect1"> <h2 id="_visione_architettonica">Visione Architettonica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_direttivo">Principio direttivo</h3> <div class="paragraph"> <p>L’architettura si basa sul principio della <strong>separazione delle preoccupazioni</strong> :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Contenuto</strong> : file AsciiDoc strutturati con metadati ricchi</p> </li> <li> <p><strong>Presentazione</strong> : template Thymeleaf riutilizzabili</p> </li> <li> <p><strong>Dati</strong> : modello estratto automaticamente da JBake dagli attributi AsciiDoc</p> </li> <li> <p><strong>Stile</strong> : Bootstrap 5 per la coerenza visiva</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_scelta_strategica_asciidoc_per_il_portfolio">Scelta strategica : AsciiDoc per il portfolio</h3> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Perché AsciiDoc?</caption> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Criterio</th> <th class="tableblock halign-left valign-top">Vantaggio</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coerenza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Même format que les articles de blog</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Metadati</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Attributi strutturati ed estensibili (<code>project-*</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Manutenibilità</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modifica semplice di testo, versionabile Git</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Flessibilità</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Può contenere contenuti ricchi (tabelle, codice, immagini)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Templating</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake estrae automaticamente gli attributi per Thymeleaf</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_modello_di_dati">Modello di dati</h3> <div class="paragraph"> <p>Ogni progetto portfolio è un documento AsciiDoc con :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Metadati di intestazione</strong> : informazioni strutturate (cliente, durata, tecnologie, ecc.)</p> </li> <li> <p><strong>Corpo del documento</strong> : descrizione narrativa, sfide, soluzioni, risultati</p> </li> <li> <p>Attributi personalizzati : prefissati`project-*`per l’estrazione automatica</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-39f614a45c003c8e4b1a076206012364.png" alt="Diagram" width="386" height="811"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casi_duso_dettagliati">Casi d’uso dettagliati</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_uc1_aggiungere_un_elemento_al_portfolio">UC1 : Aggiungere un elemento al portfolio</h3> <div class="sect3"> <h4 id="_flusso_nominale">Flusso nominale</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Editore\nTesto ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Editore\nTesto (Testo)" as editor participant "File AsciiDoc" as file participant "JBake Engine" as jbake participant "Sito Statico" as site dev -> editor : Créer nouveau fichier activate editor editor -> file : portfolio/nouveau-projet.adoc activate file dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*) dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions) dev -> editor : Ajouter images dans assets/img/portfolio/ editor -> file : Sauvegarder deactivate editor dev -> jbake : Lancer build (jbake -b) activate jbake jbake -> file : Lire et parser jbake -> jbake : Extraire métadonnées jbake -> jbake : Convertir AsciiDoc → HTML jbake -> jbake : Appliquer template project.html jbake -> jbake : Ajouter à la liste portfolio.html jbake -> site : Générer pages statiques deactivate jbake dev -> site : Vérifier résultat activate site site --> dev : Afficher projet deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_modello_del_file_da_creare">Modello del file da creare</h4> <div class="paragraph"> <p>Il sviluppatore crea`content/portfolio/nom-projet.adoc`con una struttura standardizzata :</p> </div> <div class="ulist"> <ul> <li> <p>Intestazione con tutti gli attributi richiesti</p> </li> <li> <p>Sezioni standardizzate (Contesto, Sfide, Soluzioni, Risultati)</p> </li> <li> <p>Nomenclatura coerente delle immagini</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_punti_di_validazione">Punti di validazione</h4> <div class="ulist"> <ul> <li> <p>Gli attributi obbligatori sono presenti.<code>jbake-type</code>, <code>jbake-status</code>, <code>project-thumbnail</code>)</p> </li> <li> <p>Le immagini referenziate esistono in`assets/img/portfolio/`</p> </li> <li> <p>Il build JBake riesce senza errori</p> </li> <li> <p>Il progetto appare nella pagina portfolio</p> </li> <li> <p>La pagina individuale del progetto viene visualizzata correttamente</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc2_rimuovere_un_elemento_del_portfolio">UC2 : Rimuovere un elemento del portfolio</h3> <div class="sect3"> <h4 id="_flusso_nominale_2">Flusso nominale</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Sistema ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Sistema File" as fs participant "JBake Engine" as jbake participant "Sito\nStatico" as site database "Cache\nJBake" as cache dev -> fs : Supprimer portfolio/projet-ancien.adoc activate fs fs --> dev : Fichier supprimé deactivate fs dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-* activate fs fs --> dev : Images supprimées deactivate fs dev -> cache : Nettoyer cache JBake activate cache cache --> dev : Cache vidé deactivate cache dev -> jbake : Rebuild complet (jbake -b) activate jbake jbake -> jbake : Scanner content/portfolio/ jbake -> jbake : Projet absent → non généré jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé) jbake -> site : Déployer nouveau build deactivate jbake dev -> site : Vérifier activate site site --> dev : Projet absent de la liste deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_strategia_alternativa_archiviazione">Strategia alternativa: archiviazione</h4> <div class="paragraph"> <p>Invece di eliminare definitivamente, possibilità di creare una cartella`content/portfolio/archive/`:</p> </div> <div class="ulist"> <ul> <li> <p>Spostare il file invece di eliminarlo</p> </li> <li> <p>Consente di ripristinare facilmente</p> </li> <li> <p>Mantieni la cronologia Git più chiara</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_pulizia_delle_risorse">Pulizia delle risorse</h4> <div class="ulist"> <ul> <li> <p>Controlla le immagini orfane in`assets/img/portfolio/`</p> </li> <li> <p>Rimuovere le immagini non riferite da altri progetti</p> </li> <li> <p>Pulire la cache JBake per evitare riferimenti fantasma</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc3_mettere_in_bozza">UC3: Mettere in bozza</h3> <div class="sect3"> <h4 id="_flusso_nominale_3">flusso nominale</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "File ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "File AsciiDoc" as file participant "JBake Engine" as jbake participant "Sito Statico" as site dev -> file : Ouvrir portfolio/projet.adoc activate file dev -> file : Modifier attribut\n:jbake-status: published\n↓\n:jbake-status: draft file --> dev : Sauvegardé deactivate file dev -> jbake : Rebuild (jbake -b) activate jbake jbake -> file : Parser le fichier jbake -> jbake : Détecter status=draft jbake -> jbake : Exclure de published_projects jbake -> jbake : Ne pas créer page publique note right Le projet existe toujours mais n'est pas publié end note jbake -> site : Générer site (sans ce projet) deactivate jbake dev -> site : Vérifier portfolio activate site site --> dev : Projet absent de la liste publique deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_stati_possibili">Stati possibili</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-a4b71e9dbf30083d131223257db47469.png" alt="Diagram" width="556" height="448"> </div> </div> </div> <div class="sect3"> <h4 id="_casi_dutilizzo_tipici">Casi d’utilizzo tipici</h4> <div class="ulist"> <ul> <li> <p><strong>Progetto in corso di redazione</strong> : creare una bozza, pubblicare quando pronto</p> </li> <li> <p><strong>Progetto confidenziale temporaneo</strong>: passare in bozza finché non si ha l’accordo con il cliente</p> </li> <li> <p><strong>Aggiornamento importante</strong> : passare in draft, modificare, ripubblicare</p> </li> <li> <p><strong>A/B testing</strong> : duplicare in bozza, testare, pubblicare la versione migliore</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_di_templating">Architettura di templating</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_strategia_di_template_riutilizzabili">Strategia di template riutilizzabili</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-bf5d6064a6f5c9fd58b33a81c7ba0fda.png" alt="Diagram" width="881" height="350"> </div> </div> </div> <div class="sect2"> <h3 id="_schema_di_estrazione_dei_dati">Schema di estrazione dei dati</h3> <div class="paragraph"> <p>JBake converte automaticamente gli attributi AsciiDoc in proprietà accessibili in Thymeleaf :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-cecd62314b7c6bf481543e16658b73c8.png" alt="Diagram" width="927" height="346"> </div> </div> </div> <div class="sect2"> <h3 id="_convenzioni_di_denominazione">Convenzioni di denominazione</h3> <div class="ulist"> <ul> <li> <p><strong>Attributi progetto</strong> : prefisso`project-*` (ex: <code>project-client</code>, <code>project-tech-stack</code>)</p> </li> <li> <p><strong>File</strong> : kebab-case (es:`ecommerce-platform.adoc`)</p> </li> <li> <p><strong>Immagini</strong> : prefisso nome-progetto (es:`ecommerce-platform-thumb.jpg`)</p> </li> <li> <p><strong>Templates</strong> : nome funzionale (es:`project-card.html`, <code>tech-badge.html</code>)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_workflow_di_pubblicazione">Workflow di pubblicazione</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pipeline_di_sviluppo">Pipeline di sviluppo</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-2694c3ad773a745365e7ae3fa7dc2d53.png" alt="Diagram" width="386" height="811"> </div> </div> </div> <div class="sect2"> <h3 id="_ambienti">Ambienti</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Ambiente</th> <th class="tableblock halign-left valign-top">Uso</th> <th class="tableblock halign-left valign-top">Stato accettato</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Local</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sviluppo e anteprima</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bozza, pubblicato</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">allestimento</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validazione pre-produzione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">published solo</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Produzione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sito pubblico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">pubblicato solo</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_estensibilità">Estensibilità</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_aggiunta_di_nuovi_attributi">Aggiunta di nuovi attributi</h3> <div class="paragraph"> <p>Per arricchire il modello di dati, basta semplicemente aggiungere nuovi attributi prefissati`project-*`:</p> </div> <div class="ulist"> <ul> <li> <p><code>project-awards</code>: Premi e riconoscimenti</p> </li> <li> <p><code>project-testimonial</code>: citazione cliente</p> </li> <li> <p><code>project-team-size</code>: Dimensione squadra</p> </li> <li> <p><code>project-budget-range</code>: forchetta di bilancio</p> </li> </ul> </div> <div class="paragraph"> <p>Questi attributi diventano automaticamente disponibili nei modelli senza modificare il motore JBake.</p> </div> </div> <div class="sect2"> <h3 id="_categorizzazione_avanzata">Categorizzazione avanzata</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-80bc30958c051b44d8b631a46150b7dd.png" alt="Diagram" width="561" height="259"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche">Buone pratiche</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_organizzazione_dei_file">Organizzazione dei file</h3> <div class="ulist"> <ul> <li> <p><strong>Un file = un progetto</strong> : evitare di mescolare diversi progetti</p> </li> <li> <p><strong>Immagini nella cartella dedicata</strong><code>assets/img/portfolio/nom-projet/</code></p> </li> <li> <p><strong>Nomenclatura coerente</strong> : facilita ricerca e manutenzione</p> </li> <li> <p><strong>Versioning Git</strong> : tracciamento completo delle modifiche</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_gestione_del_contenuto">Gestione del contenuto</h3> <div class="ulist"> <ul> <li> <p><strong>Stato bozza predefinito</strong> : pubblicare solo quando pronto</p> </li> <li> <p><strong>Review prima della pubblicazione</strong> : validazione qualità e riservatezza</p> </li> <li> <p><strong>Metadati completi</strong> : compilare tutti i campi pertinenti</p> </li> <li> <p><strong>contenuto narrativo ricco</strong> : non limitarsi ai metadati</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_performance">Performance</h3> <div class="ulist"> <ul> <li> <p><strong>Ottimizzare immagini</strong> : compressione prima del commit</p> </li> <li> <p><strong>Paginazione se necessaria</strong> : se >20 progetti</p> </li> <li> <p><strong>Lazy loading</strong> : immagini delle gallerie caricate su richiesta</p> </li> <li> <p><strong>Cache del browser</strong> : intestazioni appropriate per gli asset</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa architettura permette :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Facilità d’utilizzo</strong> : aggiungere un progetto = creare un file di testo</p> </li> <li> <p><strong>Flessibilità</strong> : estensibile via nuovi attributi</p> </li> <li> <p><strong>Manutenibilità</strong>: separazione contenuto/presentazione</p> </li> <li> <p><strong>Tracciabilità</strong> : versioning Git completo</p> </li> <li> <p><strong>Automazione</strong> : build e distribuzione continua possibili</p> </li> </ul> </div> <div class="paragraph"> <p>La scelta di AsciiDoc garantisce la coerenza con il resto del sito, offrendo al contempo la ricchezza dei metadati necessari a un portfolio professionale.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0100_jbake_supabase_springboot_hybride_post.html Wed, 14 Jan 2026 00:00:00 +0000 blog/2026/0100_jbake_supabase_springboot_hybride_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">tempo di lettura : 12 minutes</div> <p>Perché scegliere tra la semplicità di Supabase e la potenza di Spring Boot? Perché non combinare i due? Scopri un’architettura ibrida che sfrutta il meglio di ogni tecnologia.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">tic</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_il_falso_dilemma_dellarchitettura_moderna">Il falso dilemma dell’architettura moderna</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quando si costruisce un’applicazione moderna con un frontend statico, ci si trova spesso di fronte a una scelta binaria :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Puntare tutto su una soluzione Backend-as-a-Service</strong>(Supabase, Firebase) - semplice ma limitata</p> </li> <li> <p><strong>Costruire un backend completo</strong>(Spring Boot, Node.js) - potente ma complesso</p> </li> </ul> </div> <div class="paragraph"> <p>Questa scelta è un falso dilemma. L’architettura ibrida propone una terza via: <strong>utilizzare ogni tecnologia dove eccelle</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_vision_architettonica">Vision architettonica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_larchitettura_tradizionale_monolitica">L’architettura tradizionale : monolitica</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="1769" height="5652"> </div> </div> <div class="paragraph"> <p>In questo approccio, anche le operazioni più semplici (lettura di un articolo, creazione di un commento) devono passare attraverso il tuo backend. Paghi il costo della complessità fin dal primo giorno.</p> </div> </div> <div class="sect2"> <h3 id="_larchitettura_baas_ogni_delegato">L’architettura BaaS: Ogni delegato</h3> <div class="imageblock"> <div class="content"> <img src="baas-architecture.svg" alt="baas architecture" width="504" height="432"> </div> </div> <div class="paragraph"> <p>Al contrario, delegare tutto a un BaaS è allettante inizialmente, ma mostra rapidamente i suoi limiti non appena la logica di business si complica.</p> </div> </div> <div class="sect2"> <h3 id="_larchitettura_ibrida_separazione_delle_responsabilità">L’Architettura Ibrida: Separazione delle Responsabilità</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1568" height="479"> </div> </div> <div class="paragraph"> <p>L’architettura ibrida separa chiaramente le responsabilità in base alla complessità e alla natura delle operazioni.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_principi_di_progettazione">Principi di progettazione</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_1_iniziare_semplice_evolvere_intelligentemente">Principio 1: Iniziare Semplice, Evolvere Intelligentemente</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 23) ] @startuml skinparam backgroundColor #FEFEFE rectangle "**Fase 1 : MVP**" #LightGreen { component "JBake + Supabase" as mvp note right ✓ Développement en jours ✓ Coût : 0€ ✓ Validation concept end note } rectangle "Fase 2 : Crescita" #LightYellow { component "JBake + Supabase\n+ Spring Boot (opzionale)" as growth note right ✓ Logique métier émerge ✓ Premiers jobs planifiés ✓ Intégrations tierces end note } rectangle "**Fase 3 : Scala**" #LightCoral { component "</think> ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml skinparam backgroundColor #FEFEFE rectangle "**Fase 1 : MVP**" #LightGreen { component "JBake + Supabase" as mvp note right ✓ Développement en jours ✓ Coût : 0€ ✓ Validation concept end note } rectangle "Fase 2 : Crescita" #LightYellow { component "JBake + Supabase\n+ Spring Boot (opzionale)" as growth note right ✓ Logique métier émerge ✓ Premiers jobs planifiés ✓ Intégrations tierces end note } rectangle "**Fase 3 : Scala**" #LightCoral { component "</think> Architettura completa" as scale note right ✓ Orchestration complexe ✓ Performances optimisées ✓ Cache distribué end note } mvp -down-> growth : Quand la complexité\nle justifie growth -down-> scale : Optimisation\ncontinue @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Non costruire Spring Boot se non ne hai bisogno.</strong>Iniziate con Supabase, aggiungiete Spring Boot quando la complessità lo giustifica.</p> </div> </div> <div class="sect2"> <h3 id="_principio_2_separazione_per_natura_delloperazione">Principio 2: Separazione per natura dell’operazione</h3> <div class="imageblock"> <div class="content"> <img src="operation-types.svg" alt="operation types" width="1266" height="241"> </div> </div> </div> <div class="sect2"> <h3 id="_principio_3_una_sola_fonte_di_verità">Principio 3: Una sola fonte di verità</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1783" height="5700"> </div> </div> <div class="paragraph"> <p>Condividendo la stessa istanza PostgreSQL, Supabase e Spring Boot lavorano sugli stessi dati senza una sincronizzazione complessa.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_orchestrazione_dei_flussi">Orchestrazione dei flussi</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flusso_1_autenticazione_centralizzata">Flusso 1: Autenticazione Centralizzata</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1075" height="950"> </div> </div> <div class="paragraph"> <p><strong>Punto chiave</strong>Un solo processo di autenticazione, un solo JWT, utilizzabile ovunque.</p> </div> </div> <div class="sect2"> <h3 id="_flusso_2_orchestrazione_di_un_processo_aziendale_complesso">Flusso 2: Orchestrazione di un Processo Aziendale Complesso</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1126" height="990"> </div> </div> <div class="paragraph"> <p><strong>Cosa porta Spring Boot</strong>: Orchestrazione affidabile di processi complessi che coinvolgono più sistemi con garanzia transazionale.</p> </div> </div> <div class="sect2"> <h3 id="_flusso_3_lavori_pianificati_e_sincronizzazioni">Flusso 3 : Lavori pianificati e sincronizzazioni</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE participant "Scheduler ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE participant "Scheduler (Spring Boot)" as scheduler participant "Servizio di report" as report participant "PostgreSQL" as db participant "API esterna" as api participant "Servizio email" as email participant "Archiviazione Supabase" as storage == Job Quotidien : 2h00 == activate scheduler scheduler -> report : Déclenche génération rapport activate report report -> db : Récupère données\ndes dernières 24h db -> report : Dataset report -> report : Calculs & Agrégations report -> report : Génération PDF report -> storage : Upload PDF storage -> report : URL publique report -> email : Envoie aux admins\navec lien PDF deactivate report == Job Hebdomadaire : Dimanche 3h00 == scheduler -> report : Synchronisation externe activate report report -> api : Fetch données externes api -> report : Nouvelles données report -> db : Mise à jour tables report -> db : Nettoyage données obsolètes deactivate report == Job Mensuel : 1er du mois == scheduler -> report : Facturation activate report report -> db : Liste clients actifs report -> report : Calcul montants report -> api : Génération factures (Stripe) report -> email : Envoi factures deactivate report deactivate scheduler note right of scheduler **Impossible avec Supabase seul** Edge Functions non adaptées pour jobs longs et récurrents end note @enduml</pre> </div> </div> <div class="paragraph"> <p><strong>Ciò che Spring Boot porta</strong>: Lavori pianificati affidabili con gestione dello stato, retry automatico e esecuzione garantita.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_matrice_di_decisione">Matrice di decisione</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_quando_utilizzare_supabase">Quando utilizzare Supabase?</h3> <div class="imageblock"> <div class="content"> <img src="supabase-decision.svg" alt="supabase decision" width="1030" height="445"> </div> </div> </div> <div class="sect2"> <h3 id="_quando_usare_spring_boot">Quando usare Spring Boot?</h3> <div class="imageblock"> <div class="content"> <img src="springboot-decision.svg" alt="springboot decision" width="1142" height="485"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_esempi_di_architettura_per_tipo_di_progetto">Esempi di Architettura per Tipo di Progetto</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portfolio">Blog / Portfolio</h3> <div class="imageblock"> <div class="content"> <img src="blog-architecture.svg" alt="blog architecture" width="1328" height="242"> </div> </div> <div class="paragraph"> <p><strong>Verdetto</strong>: 100% Supabase basta ampiamente.</p> </div> </div> <div class="sect2"> <h3 id="_applicazione_saas">Applicazione SaaS</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1773" height="5748"> </div> </div> <div class="paragraph"> <p><strong>verdetto</strong>: Architettura ibrida necessaria. Supabase per l’essenziale, Spring Boot per la parte critica (pagamenti, fatturazione).</p> </div> </div> <div class="sect2"> <h3 id="_e_commerce">e-commerce</h3> <div class="imageblock"> <div class="content"> <img src="ecommerce-architecture.svg" alt="ecommerce architecture" width="1751" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Verdetto</strong>: Spring Boot indispensabile. Supabase solo per auth e catalogo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_strategia_di_migrazione_progressiva">Strategia di migrazione progressiva</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="migration-strategy.svg" alt="migration strategy" width="2050" height="954"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_costi_e_considerazioni_operative">Costi e Considerazioni Operative</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_struttura_dei_costi">Struttura dei costi</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ] @startuml skinparam backgroundColor #FEFEFE package "Costi Mensili Stimati" { rectangle "Fase MVP (0-1000 users)" #LightGreen { ^^^^^ Syntax Error? (Assumed diagram type: activity) @startuml skinparam backgroundColor #FEFEFE package "Costi Mensili Stimati" { rectangle "Fase MVP (0-1000 users)" #LightGreen { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot: N/A] note bottom: **Total: 0€/mois** } rectangle "Fase Crescita (1k-10k utenti)" #LightYellow { [JBake (GitHub Pages): 0€] [Supabase: 0€] [Spring Boot (Cloud Run): 20-50€] [PostgreSQL (si séparé): 0-30€] note bottom: **Total: 20-80€/mois** } rectangle "Scala di fase (10k-100k utenti)" #LightCoral { [JBake (Netlify Pro): 19€] [Supabase Pro: 25€] [Spring Boot (instances multiples): 100-300€] [Redis Cache: 20-50€] [Monitoring: 20€] note bottom: **Total: 184-414€/mois** } } note right of "Scala di fase (10k-100k utenti)" À ce stade, les revenus justifient largement les coûts end note @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_responsabilità_operative">Responsabilità Operative</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1826" height="5676"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_lequilibrio_perfetto">Conclusion: L’equilibrio perfetto</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’architettura ibrida Supabase + Spring Boot non è un compromesso, è una<strong>sinergia</strong>.</p> </div> <div class="sect2"> <h3 id="_i_principi_da_ricordare">I principi da ricordare</h3> <div class="imageblock"> <div class="content"> <img src="key-principles.svg" alt="key principles" width="581" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_quando_scegliere_questa_architettura">Quando scegliere questa architettura?</h3> <div class="paragraph"> <p><strong>✅ Questa architettura è ideale se :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Vuoi partire rapidamente (MVP in giorni, non in mesi)</p> </li> <li> <p>Lei anticipa una crescita della complessità aziendale</p> </li> <li> <p>Vuoi minimizzare i costi iniziali</p> </li> <li> <p>Ti piace PostgreSQL e vuoi una fonte unica di verità</p> </li> <li> <p>Apprezzi Kotlin e le Coroutine per il codice di business</p> </li> <li> <p>Vuoi evitare il vendor lock-in totale</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ Questa architettura NON è adatta se:</strong></p> </div> <div class="ulist"> <ul> <li> <p>Il tuo progetto è semplice e rimarrà tale (blog personale → il 100% di Supabase basta)</p> </li> <li> <p>Hai già una stack backend consolidata che padroneggi</p> </li> <li> <p>Preferisci un monolite tradizionale</p> </li> <li> <p>Hai bisogno di .NET, Python o altro linguaggio lato backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_visione_dinsieme_finale">Visione d’insieme finale</h3> <div class="imageblock"> <div class="content"> <img src="final-vision.svg" alt="final vision" width="1756" height="5736"> </div> </div> </div> <div class="sect2"> <h3 id="_il_meglio_dei_due_mondi">Il meglio dei due mondi</h3> <div class="paragraph"> <p>Questa architettura ti dà:</p> </div> <div class="paragraph"> <p><strong>�🚀 La velocità di Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Avvio in ore, non in settimane</p> </li> <li> <p>Autenticazione OAuth2 in pochi clic</p> </li> <li> <p>API REST generate automaticamente</p> </li> <li> <p>Zero configurazione del server</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�💪 La potenza di Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin e Coroutine per codice asincrono elegante</p> </li> <li> <p>Orchestrazione di processi aziendali complessi</p> </li> <li> <p>Lavori pianificati affidabili</p> </li> <li> <p>Transazioni ACID garantite</p> </li> <li> <p>Ecosistema Spring completo</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�💰 L’Economia Progressiva</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€ per avviare e confermare</p> </li> <li> <p>Costi che seguono la crescita</p> </li> <li> <p>Nessun sovradimensionamento prematuro</p> </li> </ul> </div> <div class="paragraph"> <p><strong>�🎯 La Flessibilità Architettonica</strong></p> </div> <div class="ulist"> <ul> <li> <p>Migrazione progressiva senza rifacimento</p> </li> <li> <p>Aggiunta di Spring Boot solo se necessario</p> </li> <li> <p>Nessun vendor lock-in totale</p> </li> <li> <p>Architettura evolutiva</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_per_andare_più_lontano">Per andare più lontano</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_risorse_tecniche">Risorse Tecniche</h3> <div class="paragraph"> <p><strong>Documentazione Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Guida all’autenticazione</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Sicurezza a livello di riga</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">API autogenerate</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Documentazione Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/" class="bare">https://spring.io/guides/tutorials/spring-boot-kotlin/</a>[<mark>#</mark> Integrazione Gradle</p> </li> </ul> </div> <div class="paragraph"> <p>JBake può essere integrato nelle build Gradle utilizzando il plugin JBake per Gradle o chiamando direttamente la CLI di JBake:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">---- tasks.register<JavaExec>("bake") { mainClass.set("org.jbake.launcher.Main") classpath = configurations["jbake"] args = listOf(projectDir.absolutePath, "$buildDir/jbake") }] * https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow[Coroutines e Spring] * https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html[Server di risorse JWT] **Articoli complementari :** * Sicurezza delle API con JWT * Ottimizzazione delle prestazioni PostgreSQL * Modelli di migrazione progressiva * Gestione degli errori in architettura distribuita === Casi d'uso reali Questa architettura ibrida viene utilizzata con successo in : * **SaaS B2B**: Autenticazione Supabase, fatturazione Spring Boot * **Mercati**: Catalogo Supabase, transazioni Spring Boot * **Piattaforme di contenuto**: Articoli Supabase, analytics Spring Boot * **Strumenti interni**: CRUD Supabase, flussi di lavoro Spring Boot === Lista di controllo per l'avvio **Fase 1 - Fondazioni (Settimana 1)** - [ ] Crea account Supabase - [ ] Configurare progetto PostgreSQL - [ ] Attiva Auth (Google, GitHub) - [ ] Définir schéma initial - [ ] Configurare Row Level Security - [ ] Testare le API da JBake **Fase 2 - MVP (Settimana 2-3)** - [ ] Implementare le pagine principali - [ ] Integrare l'autenticazione OAuth2 - [ ] Creare moduli CRUD - [ ] Configurare Storage per file - [ ] Déployer sur GitHub Pages - [ ] Testare in condizioni reali **Fase 3 - Evoluzione (secondo le esigenze)** - [ ] Identificare esigenze di logica complessa - [ ] Creare progetto Spring Boot se necessario - [ ] Configurare la validazione JWT Supabase - [ ] Connettiti a PostgreSQL Supabase - [ ] Migrare le funzionalità complesse - [ ] Implementare i job pianificati - [ ] Distribuire Spring Boot (Cloud Run, ecc.) === Anti-Patterns da evitare **❌ Non fare :** * Duplicare i dati tra Supabase e Spring Boot * Creare due basi PostgreSQL separate * Codifica l'autenticazione da te * Utilizzare Spring Boot per un CRUD semplice * Sovra-architettare fin dall'inizio * Ignora Row Level Security di Supabase **Fare piuttosto :** * Condividere un solo database PostgreSQL * Lascia che Supabase gestisca l'autenticazione * Utilizzare Spring Boot solo per la complessità * Iniziare semplice, evolvere gradualmente * Sfrutta i punti di forza di ogni tecnologia * Proteggere con RLS a livello di database == Prospettive di Evoluzione === Aggiunta di nuove capacità [plantuml,future-capabilities,svg] ---- @startuml skinparam backgroundColor #FEFEFE rectangle "Architettura attuale" #SkyBlue { [JBake] [Supabase] [Spring Boot] } rectangle "Evoluzioni Possibili" #LightYellow { package "prestazione" { [Redis Cache] [CDN pour Assets] [PostgreSQL Replicas] } package "Monitoraggio" { [Grafana] [Prometheus] [Sentry] } package "CI/CD" { [GitHub Actions] [Tests Automatisés] [Déploiement Continu] } package "funzionalità" { [Search (ElasticSearch)] [Queue (RabbitMQ)] [Event Sourcing] } } [Spring Boot] .down.> [Redis Cache] : Peut ajouter [Spring Boot] .down.> [Queue (RabbitMQ)] : Peut ajouter [Spring Boot] .down.> [Search (ElasticSearch)] : Peut ajouter [Supabase] .down.> [PostgreSQL Replicas] : Peut ajouter note bottom **Architecture extensible** Chaque ajout est indépendant Pas de refonte globale nécessaire end note @enduml ---- === Scaling orizzontale Quando la tua applicazione cresce, l'architettura ibrida si scala naturalmente: **Supabase :** * Scale automaticamente fino a milioni di operazioni * Repliche di lettura per prestazioni di lettura * Recupero point-in-time per la sicurezza **Spring Boot:** * Multiple istanze dietro il load balancer * Il design stateless facilita lo scaling orizzontale * Kubernetes per orchestrazione se necessario **PostgreSQL:** * Partizionamento per tabelle voluminose * Connection pooling (PgBouncer) * Sharding è davvero necessario (raro) == Testimonianze architettoniche === Startup SaaS (50k utenti) ____ Abbiamo iniziato al 100% con Supabase. A 5k utenti, abbiamo aggiunto Spring Boot solo per la fatturazione Stripe e i rapporti mensili. Un anno dopo, l'80% delle nostre operazioni passa ancora tramite Supabase. Spring Boot gestisce solo la parte critica. Questa separazione ci ha permesso di scalare senza rifacimento. (No output) === Piattaforma E-learning (10k utenti) ____ L'autenticazione OAuth2 di Supabase ci ha fatto risparmiare tre settimane di sviluppo. Le API auto-generate gestiscono tutto il nostro catalogo di corsi. Spring Boot serve solo per i certificati PDF e le email di avanzamento. Architettura semplice, manutenibile, evolutiva. ____ === Marketplace B2B (3k utenti) (blank) Spring Boot gestisce le transazioni tra acquirenti e venditori (critico). Supabase gestisce tutto il resto: profili, messaggistica in tempo reale, documenti. Il fatto che condividano lo stesso database PostgreSQL ci evita qualsiasi sincronizzazione complessa. La migliore scelta architettonica che abbiamo fatto. ____ == Sintesi : Un Paradigma Architettonico Moderno L'architettura ibrida Supabase + Spring Boot rappresenta un nuovo paradigma :**la specializzazione architettonica**. [plantuml,paradigm-shift,svg] ---- @startuml skinparam backgroundColor #FEFEFE rectangle "Antico Paradigma" #LightCoral { card "Tutto nel Backend" { [Auth] [CRUD] [Logique Métier] [Jobs] [Storage] [Realtime] } note bottom Complexité maximale dès le jour 1 end note } rectangle "Nuovo Paradigma" #LightGreen { card "Supabase\n(Comodità)" { [Auth] [CRUD Simple] [Storage] [Realtime] } card "Spring Boot (Differenziazione)" { [Logique Métier] [Jobs] [Intégrations] } note bottom Complexité progressive ajoutée seulement si nécessaire end note } [Ancien Paradigme] -right-> [Nouveau Paradigme] : Évolution @enduml ---- **Il principio fondamentale :**Non costruire ciò che esiste già sotto forma di servizio. Concentrati su ciò che differenzia la tua applicazione. === La regola del 80/20 Nella maggior parte delle applicazioni: * **80% delle operazioni**sono CRUD standard → Supabase * **20% delle operazioni**necessitano della logica di business → Spring Boot Questa regola naturale giustifica l'architettura ibrida. [plantuml,8020-rule,svg] ---- @startuml skinparam backgroundColor #FEFEFE package "Distribuzione delle Operazioni" { rectangle "80% - Operazioni standard" #LightGreen { [Lecture de données] [Création d'entités] [Mise à jour simple] [Suppression] [Upload fichiers] [Authentification] note bottom: **Géré par Supabase** } rectangle "20% - Logica di business" #Coral { [Calculs complexes] [Workflows multi-étapes] [Transactions critiques] [Intégrations tierces] [Jobs planifiés] note bottom: **Géré par Spring Boot** } } note right **Focus optimal :** Votre temps de développement concentré sur les 20% qui différencient votre produit end note @enduml ---- == Conclusione Finale L'architettura ibrida non è un compromesso tecnico, è una**decisione strategica**. **Ti permette di:** * �✅ Avviare rapidamente con un MVP funzionante * ✅ Convalidare il tuo mercato senza un investimento pesante * Evolvere gradualmente quando la complessità lo richiede * �✅ Controllare i tuoi costi in ogni fase * �✅ Sfruttare il meglio di ogni tecnologia * Evitare la sovraprogettazione prematura * �✅ Conservare la flessibilità per il futuro **Rappresenta:** * (No output)**Pragmatismo**Ogni tecnologia in cui eccelle * �🚀**Velocità**: time-to-market minimo * �💰**Economia**Costi allineati al valore * �🔮**Scalabilità**: Architecture che cresce con te * �🛡️**Robustezza**: Servizi testati e affidabili === Il tuo prossimo passo Se questa architettura ti parla, ecco da dove iniziare : 1. **Crea un account Supabase**(gratuito) 2. **Definisci il tuo schema di dati minimo** 3. **Configura l'autenticazione OAuth2** 4. **Create la tua prima pagina JBake che consuma l'API** 5. **Distribuite su GitHub Pages** Avrai un MVP funzionante in**alcuni giorni**. Spring Boot arriverà naturalmente quando ne avrai bisogno. Non prima. --- **L'architettura ibrida è l'arte di costruire esattamente ciò che serve, quando serve.** _Buon sviluppo ! 🚀_ --- _Condividi questo articolo se pensi che possa aiutare altri sviluppatori a fare le scelte architetturali giuste._ ----</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html Sat, 15 Nov 2025 00:00:00 +0000 blog/2025/0098_preloading_css_variable_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_riassunto">Riassunto</a></li> <li><a href="#_il_problema_questo_maledetto_lampeggiamento_del_tema">Il Problema: Questo Maledetto Lampeggiamento del Tema</a> <ul class="sectlevel2"> <li><a href="#_un_incubo_per_lesperienza_utente">Un incubo per l’esperienza utente</a></li> <li><a href="#_il_fouc_un_vecchio_problema_web">Il FOUC : Un Vecchio Problema Web</a></li> <li><a href="#_impatto_sulla_percezione_di_qualità">Impatto sulla Percezione di Qualità</a></li> <li><a href="#_analisi_tecnica_del_problema">Analisi Tecnica del Problema</a></li> </ul> </li> <li><a href="#_perché_uno_script_classico_non_basta">Perché uno script classico non basta?</a> <ul class="sectlevel2"> <li><a href="#_lapproccio_intuitivo_ma_inefficace">L’approccio intuitivo ma inefficace</a></li> <li><a href="#_comprendere_levento_domcontentloaded">Comprendere l’evento DOMContentLoaded</a></li> <li><a href="#_il_problema_del_render_blocking">Il Problema del Render Blocking</a></li> <li><a href="#_visualizzazione_del_problema">Visualizzazione del problema</a></li> <li><a href="#_le_tentative_di_soluzione_inefficaci">Le Tentative di Soluzione Inefficaci</a></li> <li><a href="#_la_vera_soluzione_agire_prima">La Vera Soluzione: Agire prima</a></li> </ul> </li> <li><a href="#_la_soluzione_il_caricamento_preventivo_early_loading">La Soluzione : Il Caricamento Preventivo (Early Loading)</a> <ul class="sectlevel2"> <li><a href="#_il_principio_fondamentale">Il principio fondamentale</a></li> <li><a href="#_perché_il_head_è_il_posto_ideale">Perché il <code><head></code> è il posto ideale</a></li> <li><a href="#_architettura_della_soluzione_a_tre_livelli">Architettura della Soluzione a Tre Livelli</a></li> </ul> </li> <li><a href="#_passo_1_salvare_la_scelta_dellutente">Passo 1 : Salvare la scelta dell’utente</a> <ul class="sectlevel2"> <li><a href="#_il_localstorage_la_tua_memoria_persistente">Il localStorage: La tua memoria persistente</a></li> <li><a href="#_implementazione_del_salvataggio_del_tema">Implementazione del salvataggio del tema</a></li> <li><a href="#_gestione_dei_casi_di_errore">Gestione dei casi di errore</a></li> <li><a href="#_strategie_avanzate_di_persistenza">Strategie avanzate di persistenza</a></li> </ul> </li> <li><a href="#_passo_2_lo_script_di_pre_caricamento_nel_head">Passo 2: Lo Script di Pre-caricamento nel `<head></a> <ul class="sectlevel2"> <li><a href="#_il_cuore_della_soluzione">Il cuore della soluzione</a></li> <li><a href="#_anatomia_dello_script_ogni_linea_conta">Anatomia dello script: Ogni linea conta</a></li> <li><a href="#_rilevamento_della_preferenza_di_sistema_bonus">Rilevamento della preferenza di sistema (Bonus)</a></li> <li><a href="#_performance_perché_questo_script_è_veloce">Performance : Perché questo script è veloce</a></li> <li><a href="#_posizionamento_ottimale_nel_head">Posizionamento Ottimale nel `<head></a></li> </ul> </li> <li><a href="#_passo_3_la_potenza_dei_selettori_di_attributi_css">Passo 3: la potenza dei selettori di attributi CSS</a> <ul class="sectlevel2"> <li><a href="#_il_sistema_di_tema_di_bootstrap_5">Il Sistema di Tema di Bootstrap 5</a></li> <li><a href="#_struttura_css_per_un_sistema_di_tema">Struttura CSS per un sistema di tema</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_riassunto">Riassunto</h2> <div class="sectionbody"> <div class="paragraph"> <p>In questo articolo tecnico approfondito, esploriamo come implementare un selettore di tema (light/dark) senza il fastidioso effetto di lampeggiamento che si verifica durante il caricamento della pagina. Analizziamo nel dettaglio il ciclo di rendering del browser, le cause profonde del FOUC (Flash of Unstyled Content), e proponiamo una soluzione robusta basata sul precaricamento sincrono nel`<head>`. Questa tecnica garantisce un’esperienza utente fluida e professionale.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_questo_maledetto_lampeggiamento_del_tema">Il Problema: Questo Maledetto Lampeggiamento del Tema</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_un_incubo_per_lesperienza_utente">Un incubo per l’esperienza utente</h3> <div class="paragraph"> <p>Immagina la scena: hai trascorso ore a progettare un magnifico tema scuro per la tua applicazione web. I colori sono perfettamente bilanciati, il contrasto è ottimale e i tuoi utenti adorano questa opzione. Ma c’è un problema imbarazzante: ad ogni ricaricamento della pagina, per una frazione di secondo, il tema chiaro di default viene visualizzato prima che il tema scuro prenda il sopravvento.</p> </div> <div class="paragraph"> <p>Questo 'flash' visivo, sebbene breve (a volte meno di 100 ms), è immediatamente percepibile dall’occhio umano e crea un’esperienza sgradevole. Per gli utenti che hanno scelto il tema scuro per motivi di comfort visivo o di accessibilità, questo tremolio può persino risultare doloroso, specialmente in un ambiente poco illuminato.</p> </div> </div> <div class="sect2"> <h3 id="_il_fouc_un_vecchio_problema_web">Il FOUC : Un Vecchio Problema Web</h3> <div class="paragraph"> <p>Questo fenomeno è una variante di quello che viene chiamato il "Flash of Unstyled Content" (FOUC), un problema classico dello sviluppo web che risale ai primi giorni del CSS. Il FOUC si verifica quando il browser mostra temporaneamente contenuto HTML senza i suoi stili CSS applicati, creando un lampeggio di contenuto non stilizzato.</p> </div> <div class="paragraph"> <p>Nel nostro caso specifico, non stiamo parlando di un contenuto completamente non stilizzato, ma piuttosto di un<strong>Lampo del tema sbagliato</strong>(FOWT) - il contenuto è stilizzato, ma con il tema sbagliato. Questo è particolarmente frustrante perché dimostra che la nostra applicazione "dimentica" la preferenza dell’utente ad ogni caricamento della pagina.</p> </div> </div> <div class="sect2"> <h3 id="_impatto_sulla_percezione_di_qualità">Impatto sulla Percezione di Qualità</h3> <div class="paragraph"> <p>Questo problema, sebbene tecnico, ha ripercussioni importanti sulla percezione della qualità della tua applicazione :</p> </div> <div class="paragraph"> <p><strong>mancanza di rifinitura</strong>Il lampeggiamento dà l’impressione di un’applicazione incompleta o mal ottimizzata. Gli utenti associano spesso questi piccoli difetti visivi a una generale mancanza di professionalità.</p> </div> <div class="paragraph"> <p><strong>Rottura di coerenza</strong>L’applicazione sembra "dimenticare" le preferenze dell’utente, creando una sensazione di disallineamento tra l’interfaccia e le aspettative.</p> </div> <div class="paragraph"> <p><strong>Affaticamento visivo</strong>: Per gli utenti sensibili alla luce o che soffrono di emicrania, questo flash luminoso può essere più di un semplice disagio estetico.</p> </div> <div class="paragraph"> <p><strong>Performance percepita</strong>: Ironicamente, anche se il tuo sito si carica rapidamente, questo sfarfallio può dare l’impressione di un’applicazione lenta o poco reattiva.</p> </div> </div> <div class="sect2"> <h3 id="_analisi_tecnica_del_problema">Analisi Tecnica del Problema</h3> <div class="paragraph"> <p>Per capire come risolvere questo problema, è necessario prima capire perché si verifica. Lo sfarfallio si verifica a causa di uno sfasamento temporale tra tre eventi critici nel ciclo di vita di una pagina web :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Il parsing iniziale del HTML</strong>: Il browser legge e analizza la struttura della tua pagina</p> </li> <li> <p><strong>L’applicazione degli stili CSS</strong>Il navigatore applica le regole CSS e calcola il rendering visivo.</p> </li> <li> <p><strong>L’esecuzione del JavaScript</strong>Il tuo codice che cambia il tema si esegue</p> </li> </ol> </div> <div class="paragraph"> <p>Il problema si verifica quando l’evento n°3 (esecuzione del JavaScript) arriva dopo che il browser ha già iniziato o terminato l’evento n°2 (applicazione degli stili). A quel punto, il browser ha già preso una decisione su quale tema visualizzare, e il tuo codice arriva troppo tardi per influenzarlo prima del primo rendering.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_uno_script_classico_non_basta">Perché uno script classico non basta?</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lapproccio_intuitivo_ma_inefficace">L’approccio intuitivo ma inefficace</h3> <div class="paragraph"> <p>L’approccio più naturale per uno sviluppatore sarebbe di posizionare uno script alla fine della nostra`<body>`che verifica il tema preferito dell’utente e lo applica. Questo approccio segue le migliori pratiche tradizionali del web che consigliano di caricare gli script alla fine della pagina per non bloccare il rendering.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">// À la fin de <body> - L'APPROCHE INSUFFISANTE document.addEventListener('DOMContentLoaded', () => { const theme = localStorage.getItem('preferred-theme'); if (theme === 'dark') { document.documentElement.setAttribute('data-bs-theme', 'dark'); } });</code></pre> </div> </div> <div class="paragraph"> <p>Questa approccio sembra logico a prima vista. Attendiamo che il DOM sia pronto, poi applichiamo il tema. Semplice, no? Purtroppo, questa semplicità nasconde un difetto fondamentale legato al timing del ciclo di rendering del browser.</p> </div> </div> <div class="sect2"> <h3 id="_comprendere_levento_domcontentloaded">Comprendere l’evento DOMContentLoaded</h3> <div class="paragraph"> <p>L’evento`DOMContentLoaded`si attiva quando il documento HTML iniziale è stato completamente caricato e analizzato dal browser,<strong>senza attendere</strong>la fine del caricamento dei fogli di stile, delle immagini e dei sottocampi. È un punto importante da capire.</p> </div> <div class="paragraph"> <p>Ecco la sequenza tipica degli eventi :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Il browser inizia a scaricare l’HTML</p> </li> <li> <p>Analizza l’HTML man mano che lo riceve</p> </li> <li> <p>Lui scopre i tag`<link>`per i CSS e inizia a scaricarli</p> </li> <li> <p>Scopre le etichette`<script>`e li esegue (secondo il loro tipo e attributi)</p> </li> <li> <p>Costruisce il DOM (Document Object Model)</p> </li> <li> <p><strong>L’evento <code>DOMContentLoaded</code> si attiva</strong></p> </li> <li> <p>Continua ad applicare gli stili e a fare il layout</p> </li> <li> <p>Il primo paint (visualizzazione) si verifica</p> </li> <li> <p>L’evento`load`si attiva quando tutte le risorse sono caricate</p> </li> </ol> </div> <div class="paragraph"> <p>Il problema? Tra il passo 6 (DOMContentLoaded) e il passo 8 (primo paint), il browser ha già preso delle decisioni su come visualizzare la pagina. Se lo script di cambio tema viene eseguito al passo 6, è ormai troppo tardi per evitare una prima visualizzazione con gli stili predefiniti.</p> </div> </div> <div class="sect2"> <h3 id="_il_problema_del_render_blocking">Il Problema del Render Blocking</h3> <div class="paragraph"> <p>In realtà, il timing è ancora più complesso. I browser moderni utilizzano tecniche di ottimizzazione sofisticate per migliorare le prestazioni percepite. Cercano di far avvenire il primo paint (First Contentful Paint) il più rapidamente possibile affinché l’utente veda qualcosa sullo schermo.</p> </div> <div class="paragraph"> <p>I CSS sono "render-blocking" per impostazione predefinita, il che significa che il browser attende di aver scaricato e analizzato i fogli di stile prima di effettuare il primo paint. È logico: non vogliamo mostrare contenuto non stilizzato.</p> </div> <div class="paragraph"> <p>Ma ecco la trappola : quando il browser applica questi stili CSS per la prima volta, lo fa basandosi sullo stato corrente del DOM. Se l’attributo`data-bs-theme`non è ancora definito sul tag`<html>`, il browser applicherà gli stili predefiniti (generalmente il tema chiaro).</p> </div> <div class="paragraph"> <p>Poi, quando il tuo script si esegue e cambia questo attributo, il browser deve :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ricalcolare tutti gli stili interessati da questa modifica</p> </li> <li> <p>Rifare il layout se necessario</p> </li> <li> <p>Riverniciare gli elementi interessati</p> </li> </ol> </div> <div class="paragraph"> <p>Questo processo di ricalcolo e di ridipingimento è ciò che causa lo sfarfallio visibile.</p> </div> </div> <div class="sect2"> <h3 id="_visualizzazione_del_problema">Visualizzazione del problema</h3> <div class="paragraph"> <p>Per comprendere meglio questa sequenza problematica, esaminiamo un diagramma di sequenza dettagliato:</p> </div> <div id="diag-flux-incorrect" class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 28) ] @startuml actor Utilisateur participant Navigateur participant "Analizzatore HTML" as Parser participant "CSSOM" as CSS participant "Script.js (fine del body)" as Script participant "Motore di rendering" as Render Utilisateur -> Navigateur: Demande la page activate Navigateur Navigateur -> Parser: Parse le HTML activate Parser Parser -> CSS: Découvre et charge les CSS activate CSS Parser -> Parser: Construit le DOM Parser -> Navigateur: DOM Ready (DOMContentLoaded) deactivate Parser CSS -> CSS: Parse les feuilles de style CSS -> Render: CSSOM Ready deactivate CSS activate Render Render -> Render: Calcule les styles avec data-bs-theme=""note right: Tema predefinito (light) Render -> Navigatore: Primo Paint (Tema Chiaro) note right: L'utente vede il tema chiaro disattiva Render ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Utilisateur participant Navigateur participant "Analizzatore HTML" as Parser participant "CSSOM" as CSS participant "Script.js (fine del body)" as Script participant "Motore di rendering" as Render Utilisateur -> Navigateur: Demande la page activate Navigateur Navigateur -> Parser: Parse le HTML activate Parser Parser -> CSS: Découvre et charge les CSS activate CSS Parser -> Parser: Construit le DOM Parser -> Navigateur: DOM Ready (DOMContentLoaded) deactivate Parser CSS -> CSS: Parse les feuilles de style CSS -> Render: CSSOM Ready deactivate CSS activate Render Render -> Render: Calcule les styles avec data-bs-theme=""note right: Tema predefinito (light) Render -> Navigatore: Primo Paint (Tema Chiaro) note right: L'utente vede il tema chiaro disattiva Render Navigatore -> Script: Esegue lo script attiva Script Script -> Script: Legge localStorage Script -> Navigatore: setAttribute('data-bs-theme', 'dark') disattiva Script attiva Render Render -> Render: Recalcola gli stili con data-bs-theme="dark" note right: Thème sombre Render -> Navigateur: Repaint (Thème Sombre) note right: Clignotement visible deactivate Render deactivate Navigateur @enduml</pre> </div> </div> <div class="paragraph"> <p>Questo diagramma illustra chiaramente il problema: il primo paint avviene prima che il nostro script abbia avuto la possibilità di impostare il tema corretto. Il repaint successivo crea lo sfarfallio visibile.</p> </div> </div> <div class="sect2"> <h3 id="_le_tentative_di_soluzione_inefficaci">Le Tentative di Soluzione Inefficaci</h3> <div class="paragraph"> <p>Sono stati provati diversi approcci per risolvere questo problema, ma la maggior parte ha i propri svantaggi :</p> </div> <div class="paragraph"> <p><strong>Approccio 1: Nascondere il contenuto fino al caricamento</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">body { opacity: 0; transition: opacity 0.3s; } body.loaded { opacity: 1; }</code></pre> </div> </div> <div class="paragraph"> <p>Questa approccio nasconde tutto il contenuto finché JavaScript non imposta il tema corretto. Il problema? Ritarda artificialmente la visualizzazione del contenuto, dando l’impressione di un sito più lento. Inoltre, se JavaScript è disabilitato, l’utente non vede nulla!</p> </div> <div class="paragraph"> <p><strong>Approccio 2 : Utilizzare un loader/spinner</strong></p> </div> <div class="paragraph"> <p>Simile all’approccio 1, ma con uno spinner di caricamento. Questo maschera il problema ma non migliora le prestazioni reali e aggiunge un ritardo percepito inutile.</p> </div> <div class="paragraph"> <p><strong>Approccio 3: Predefinito al tema scuro</strong></p> </div> <div class="paragraph"> <p>Alcuni sviluppatori impostano il tema scuro come predefinito nel CSS. Questo evita lo sfarfallio per gli utenti del tema scuro, ma crea il problema opposto per gli utenti del tema chiaro!</p> </div> <div class="paragraph"> <p>Nessuno di questi approcci è soddisfacente perché tratta il sintomo anziché la causa radice del problema.</p> </div> </div> <div class="sect2"> <h3 id="_la_vera_soluzione_agire_prima">La Vera Soluzione: Agire prima</h3> <div class="paragraph"> <p>La chiave per risolvere questo problema è rendersi conto che dobbiamo definire l’attributo`data-bs-theme` <strong>prima</strong>che il browser non inizi ad applicare gli stili CSS. Questo significa che il nostro script deve essere eseguito più presto nel ciclo di vita della pagina, ed è esattamente ciò che esploreremo nella sezione successiva.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_il_caricamento_preventivo_early_loading">La Soluzione : Il Caricamento Preventivo (Early Loading)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_principio_fondamentale">Il principio fondamentale</h3> <div class="paragraph"> <p>La soluzione elegante al nostro problema di sfarfallio si basa su un principio semplice ma potente :<strong>sincronizzare lo stato dell’applicazione con il processo di rendering del browser</strong>. Invece di aspettare che la pagina si carichi per impostare il tema, dobbiamo impostarlo<strong>durante</strong>il caricamento, prima ancora che gli stili CSS vengano applicati</p> </div> <div class="paragraph"> <p>Questa approccio si chiama "Early Loading" o "Synchronous Preloading" nel gergo dello sviluppo web. L’idea è di eseguire la nostra logica di rilevamento del tema il più presto possibile nel ciclo di vita della pagina, idealmente nel tag`<head>`, anche prima che il browser inizi a scaricare i file CSS.</p> </div> </div> <div class="sect2"> <h3 id="_perché_il_head_è_il_posto_ideale">Perché il <code><head></code> è il posto ideale</h3> <div class="paragraph"> <p>Le `<head>`di un documento HTML è elaborato sequenzialmente dal browser, dall’alto verso il basso. Ogni elemento è elaborato nell’ordine in cui appare. Questa caratteristica è fondamentale per la nostra soluzione.</p> </div> <div class="paragraph"> <p>Quando il browser incontra un tag`<script>`nel`<head>`senza gli attributi`async` ou <code>defer</code>, il :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Interrompe il parsing del HTML</strong></p> </li> <li> <p><strong>Scarica lo script</strong>(se esterno) oppure il letto (se inline)</p> </li> <li> <p><strong>Esegui immediatamente lo script</strong></p> </li> <li> <p><strong>Riprende il parsing dell’HTML</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Questo comportamento, spesso considerato come un problema di prestazioni (da cui deriva la consueta raccomandazione di posizionare gli script alla fine della pagina), diventa nostro alleato in questo caso specifico. Posizionando il nostro script di rilevamento del tema all’inizio del`<head>`, garantiamo che venga eseguito prima che il browser incontri i tag`<link>`dei nostri fogli di stile.</p> </div> </div> <div class="sect2"> <h3 id="_architettura_della_soluzione_a_tre_livelli">Architettura della Soluzione a Tre Livelli</h3> <div class="paragraph"> <p>La nostra soluzione completa si compone di tre livelli interdipendenti, ognuno dei quali svolge un ruolo specifico:</p> </div> <div class="paragraph"> <p><strong>Strato 1 : Persistenza (localStorage)</strong> Questo livello è responsabile del salvataggio e del recupero della scelta dell’utente tra le sessioni.</p> </div> <div class="paragraph"> <p><strong>Livello 2 : sincronizzazione precoce (Script in linea in <code><head></code>)</strong> Questo livello sincronizza lo stato dell’applicazione con il DOM prima del rendering iniziale.</p> </div> <div class="paragraph"> <p><strong>Livello 3: Stili reattivi (CSS con selettori di attributi)</strong> Questo livello definisce gli stili visivi basati sullo stato definito dal livello 2.</p> </div> <div class="paragraph"> <p>Esploriamo ora ogni strato nel dettaglio.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_1_salvare_la_scelta_dellutente">Passo 1 : Salvare la scelta dell’utente</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_localstorage_la_tua_memoria_persistente">Il localStorage: La tua memoria persistente</h3> <div class="paragraph"> <p>Le <code>localStorage`è un’API Web Storage che permette di memorizzare coppie chiave-valore nel browser in modo persistente. A differenza dei cookie, i dati del`localStorage</code>:</p> </div> <div class="ulist"> <ul> <li> <p>Non vengono mai inviate al server automaticamente</p> </li> <li> <p>Hanno una capacità di storage più grande (di solito 5-10 MB)</p> </li> <li> <p>Non hanno una data di scadenza (persistenti fino a cancellazione esplicita)</p> </li> <li> <p>Sono limitate al protocollo e al dominio (Same-Origin Policy)</p> </li> </ul> </div> <div class="paragraph"> <p>Per il nostro caso d’uso, il`localStorage`è perfetto perché :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Non abbiamo bisogno di condividere questa informazione con il server</p> </li> <li> <p>Vogliamo che la preferenza persista indefinitamente</p> </li> <li> <p>La dimensione di storage richiesta è minima (qualche byte)</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_implementazione_del_salvataggio_del_tema">Implementazione del salvataggio del tema</h3> <div class="paragraph"> <p>Ecco come salviamo la scelta dell’utente quando cambia tema:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">// Fonction complète pour changer le thème function setTheme(newTheme) { // Validation de l'entrée if (!['light', 'dark', 'auto'].includes(newTheme)) { console.error('Thème invalide:', newTheme); return; } try { // Sauvegarde dans localStorage localStorage.setItem('preferred-theme', newTheme); // Application immédiate dans le DOM document.documentElement.setAttribute('data-bs-theme', newTheme); // Dispatch d'un événement personnalisé pour notifier d'autres composants window.dispatchEvent(new CustomEvent('theme-changed', { detail: { theme: newTheme } })); console.log('Thème changé:', newTheme); } catch (error) { console.error('Erreur lors de la sauvegarde du thème:', error); // Fallback : on applique quand même le thème visuellement document.documentElement.setAttribute('data-bs-theme', newTheme); } } // Exemple d'utilisation avec un bouton document.getElementById('theme-toggle').addEventListener('click', () => { const currentTheme = document.documentElement.getAttribute('data-bs-theme') || 'light'; const newTheme = currentTheme === 'light' ? 'dark' : 'light'; setTheme(newTheme); });</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_gestione_dei_casi_di_errore">Gestione dei casi di errore</h3> <div class="paragraph"> <p>È fondamentale gestire i casi in cui il`localStorage`non è disponibile o accessibile. Diversi scenari possono impedire l’accesso al`localStorage`:</p> </div> <div class="paragraph"> <p><strong>Navigazione privata stricta</strong>: Safari in modalità navigazione privata solleva un’eccezione`QuotaExceededError`durante i tentativi di scrittura in`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Impostazioni sulla privacy</strong>: Alcuni browser o estensioni per la privacy possono bloccare l’accesso al`localStorage`.</p> </div> <div class="paragraph"> <p><strong>Limitazioni di dominio</strong> : Le `localStorage`non è accessibile sul protocollo`file://`in alcuni browser.</p> </div> <div class="paragraph"> <p><strong>Spazio di archiviazione saturato</strong>Sebbene raro, lo spazio di archiviazione può essere completamente pieno.</p> </div> <div class="paragraph"> <p>Per questo motivo il nostro codice utilizza un blocco`try…​catch`per gestire questi casi con eleganza, continuando a offrire la funzionalità di cambio di tema anche se la persistenza non è disponibile.</p> </div> </div> <div class="sect2"> <h3 id="_strategie_avanzate_di_persistenza">Strategie avanzate di persistenza</h3> <div class="paragraph"> <p>Per applicazioni più sofisticate, puoi considerare strategie aggiuntive:</p> </div> <div class="paragraph"> <p><strong>Sincronizzazione server (opzionale)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">async function setTheme(newTheme) { // Sauvegarde locale immédiate localStorage.setItem('preferred-theme', newTheme); document.documentElement.setAttribute('data-bs-theme', newTheme); // Synchronisation serveur en arrière-plan (si l'utilisateur est connecté) if (userIsAuthenticated()) { try { await fetch('/api/user/preferences', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ theme: newTheme }) }); } catch (error) { console.warn('Échec de la synchronisation serveur:', error); // L'échec n'est pas critique car la préférence est déjà sauvegardée localement } } }</code></pre> </div> </div> <div class="paragraph"> <p>Questo approccio permette di sincronizzare le preferenze tra dispositivi per gli utenti connessi, mantenendo al contempo la reattività locale immediata.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_2_lo_script_di_pre_caricamento_nel_head">Passo 2: Lo Script di Pre-caricamento nel `<head></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_cuore_della_soluzione">Il cuore della soluzione</h3> <div class="paragraph"> <p>Qui è dove la magia opera davvero. Posizioneremo un piccolo script<strong>in linea</strong>direttamente nel nostro`<head>`, prima di tutte le nostre etichette`<link>`di fogli di stile. Questo script è intenzionalmente minimalista, autonomo e progettato per essere eseguito il più rapidamente possibile.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Mon Site Incroyable</title> <!-- ========================================== NOTRE SCRIPT MAGIQUE DE PRÉ-CHARGEMENT Ce script DOIT être le premier élément dans le <head> après les meta tags ========================================== --> <script> // IIFE pour ne pas polluer le scope global (function() { 'use strict'; try { // Lecture de la préférence sauvegardée const savedTheme = localStorage.getItem('preferred-theme'); // Si une préférence existe, on l'applique immédiatement if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); } // Optionnel : Détecter la préférence système si aucune sauvegarde else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } // Sinon, le thème par défaut du CSS sera utilisé (généralement 'light') } catch (error) { // En cas d'erreur (localStorage bloqué, etc.), on log discrètement // et on laisse le thème par défaut s'appliquer console.warn('Impossible de charger la préférence de thème:', error); } })(); </script> <!-- FIN DU SCRIPT MAGIQUE --> <!-- Les feuilles de style sont chargées APRÈS le script --> <link rel="stylesheet" href="css/bootstrap.min.css"> <link rel="stylesheet" href="css/styles.css"> <!-- Autres ressources du head --> <link rel="icon" href="favicon.ico"> </head> <body> <!-- Contenu de la page --> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_anatomia_dello_script_ogni_linea_conta">Anatomia dello script: Ogni linea conta</h3> <div class="paragraph"> <p>Analizziamo questo script riga per riga per comprendere ogni decisione di design:</p> </div> <div class="paragraph"> <p><strong>L’IIFE (espressione di funzione richiamata immediatamente)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">(function() { // ... })();</code></pre> </div> </div> <div class="paragraph"> <p>Questa struttura crea una funzione che viene eseguita immediatamente. Perché? Per isolare le nostre variabili in uno scope locale e evitare di inquinare lo scope globale. Anche se ne utilizziamo solo`const`(che ha uno scope di blocco), l’IIFE è una buona pratica che rende le nostre intenzioni chiare e protegge contro eventuali conflitti di nomi</p> </div> <div class="paragraph"> <p><strong>La modalità rigorosa</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">'use strict';</code></pre> </div> </div> <div class="paragraph"> <p>Questa direttiva attiva la modalità strict di JavaScript, che : - Vietato l’uso di variabili non dichiarate - Genera errori per le operazioni pericolose Migliora le prestazioni in alcuni motori JavaScript</p> </div> <div class="paragraph"> <p>Per uno script critico come questo, vogliamo la massima sicurezza.</p> </div> <div class="paragraph"> <p><strong>Il blocco try…​catch</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">try { // Code principal } catch (error) { console.warn('Impossible de charger la préférence de thème:', error); }</code></pre> </div> </div> <div class="paragraph"> <p>Questo blocco è assolutamente cruciale. Garantisce che se qualcosa va storto (localStorage bloccato, errore di sintassi improbabile, ecc.), il nostro script non bloccherà il caricamento dell’intera pagina. L’utilizzo di`console.warn`piuttosto che`console.error`indica che è un problema non critico.</p> </div> <div class="paragraph"> <p><strong>La lettura di localStorage</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">const savedTheme = localStorage.getItem('preferred-theme');</code></pre> </div> </div> <div class="paragraph"> <p>Questa linea può sollevare un’eccezione in alcuni contesti (navigazione privata stretta di Safari). Per questo motivo si trova in un blocco try…​catch.</p> </div> <div class="paragraph"> <p><strong>L’Applicazione Condizionale</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); }</code></pre> </div> </div> <div class="paragraph"> <p>Applichiamo il tema solo se ne abbiamo trovato uno salvato. Altrimenti, lasciamo che il CSS utilizzi il suo tema predefinito. Questo approccio è più robusto di un valore predefinito hard‑coded nel JavaScript.</p> </div> </div> <div class="sect2"> <h3 id="_rilevamento_della_preferenza_di_sistema_bonus">Rilevamento della preferenza di sistema (Bonus)</h3> <div class="paragraph"> <p>Un miglioramento opzionale ma elegante consiste nel rilevare la preferenza di tema del sistema operativo dell’utente se non ha ancora fatto una scelta esplicita nella tua applicazione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); }</code></pre> </div> </div> <div class="paragraph"> <p>Questa funzionalità utilizza la Media Query`prefers-color-scheme`per interrogare il sistema. Su macOS, Windows 10+, iOS e Android moderno, questa query restituisce la preferenza di sistema dell’utente.</p> </div> <div class="paragraph"> <p><strong>Vantaggi :</strong> - Esperienza personalizzata dalla prima visita - Coerenza con l’ambiente di sistema dell’utente - Nessun spazio di archiviazione necessario per la prima visita</p> </div> <div class="paragraph"> <p><strong>Considerazioni :</strong> - Tutti i browser non supportano questa funzionalità (ma il supporto è eccellente dal 2020) - La verifica`window.matchMedia`garantisce la compatibilità L’utente può sempre sovrascrivere questa scelta</p> </div> </div> <div class="sect2"> <h3 id="_performance_perché_questo_script_è_veloce">Performance : Perché questo script è veloce</h3> <div class="paragraph"> <p>Il nostro script di precaricamento è progettato per essere estremamente veloce:</p> </div> <div class="paragraph"> <p><strong>dimensione minima</strong>: Circa 300 byte non minificati, 200 byte minificati. È trascurabile rispetto a qualsiasi immagine o libreria JavaScript.</p> </div> <div class="paragraph"> <p><strong>Inline</strong>: Nessuna richiesta HTTP aggiuntiva. Lo script è nell’HTML, quindi è immediatamente disponibile.</p> </div> <div class="paragraph"> <p><strong>Operazioni sincrone semplici</strong>: Lettura di una chiave nel localStorage (operazione ultra-rapida) e modifica di un attributo DOM (operazione nativa del browser).</p> </div> <div class="paragraph"> <p><strong>Nessuna dipendenza</strong>Nessun framework, nessuna libreria, solo JavaScript puro. Nessun tempo di avvio, nessun parsing delle dipendenze.</p> </div> <div class="paragraph"> <p><strong>Esecuzione unica</strong>Questo script si esegue una sola volta al caricamento. Nessun listener di eventi, nessun ciclo, nessun calcolo complesso.</p> </div> <div class="paragraph"> <p>In pratica, su hardware moderno, questo script si esegue in meno di 1 millisecondo, un tempo impercettibile che non ha alcun impatto sulle prestazioni di caricamento della pagina.</p> </div> </div> <div class="sect2"> <h3 id="_posizionamento_ottimale_nel_head">Posizionamento Ottimale nel `<head></h3> <div class="paragraph"> <p>L’ordine degli elementi nel`<head>`è importante. Ecco l’ordine consigliato:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><head> <!-- 1. Métadonnées critiques --> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <!-- 2. Notre script de pré-chargement (IMMÉDIATEMENT après les meta) --> <script> (function() { /* notre code */ })(); </script> <!-- 3. Titre de la page --> <title>Mon Site</title> <!-- 4. Feuilles de style --> <link rel="stylesheet" href="styles.css"> <!-- 5. Autres ressources (fonts, favicons, etc.) --> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="icon" href="favicon.ico"> <!-- 6. Autres scripts avec defer ou async --> <script src="app.js" defer></script> </head></code></pre> </div> </div> <div class="paragraph"> <p>Questo ordine garantisce che :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Il charset è definito prima di qualsiasi elaborazione di testo</p> </li> <li> <p>Il nostro script viene eseguito prima del caricamento dei CSS</p> </li> <li> <p>I CSS vengono caricati successivamente e applicano direttamente il tema corretto</p> </li> <li> <p>Le altre risorse non critiche sono caricate per ultime</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_3_la_potenza_dei_selettori_di_attributi_css">Passo 3: la potenza dei selettori di attributi CSS</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_sistema_di_tema_di_bootstrap_5">Il Sistema di Tema di Bootstrap 5</h3> <div class="paragraph"> <p>Bootstrap 5 ha introdotto un sistema elegante di gestione dei temi basato sulle custom properties CSS (variabili CSS) e sui selettori di attributo. Questo sistema utilizza l’attributo`data-bs-theme`sull’elemento`<html>`per determinare quale insieme di variabili di colore applicare.</p> </div> <div class="paragraph"> <p>La bellezza di questo sistema risiede nella sua semplicità: invece di caricare diversi fogli di stile o di attivare/disattivare le classi su migliaia di elementi, cambiamo semplicemente un attributo su un singolo elemento e il CSS si occupa del resto grazie alla cascata.</p> </div> </div> <div class="sect2"> <h3 id="_struttura_css_per_un_sistema_di_tema">Struttura CSS per un sistema di tema</h3> <div class="paragraph"> <p>Ecco una struttura CSS completa per implementare un sistema di tema robusto:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/** * SYSTÈME DE THÈME COMPLET * Utilise les Custom Properties CSS pour une maintenance facile */ /* ============================================ THÈME PAR DÉFAUT (LIGHT) Défini sur :root pour être le fallback ============================================ */ :root { /* Couleurs de base */ --color-primary: #0d6efd; --color-secondary: #6c757d; --color-success: #198754; --color-danger: #dc3545; --color-warning: #ffc107; --color-info: #0dcaf0; /* Couleurs de fond */ --bg-primary: #ffffff; --bg-secondary: #f8f9fa; --bg-tertiary: #e9ecef; /* Couleurs de texte */ --text-primary: #212529; --text-secondary: #6c757d; --text-tertiary: #adb5bd; /* Couleurs de bordure */ --border-color: #dee2e6; --border-color-subtle: #e9ecef; /* Couleurs d'ombre */ --shadow-sm: rgba(0, 0, 0, 0.075); --shadow-md: rgba(0, 0, 0, 0.15); --shadow-lg: rgba(0, 0, 0, 0.25</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html Fri, 7 Nov 2025 00:00:00 +0000 blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_il_problema_dipendenza_da_gradlerunner">Il Problema : Dipendenza da GradleRunner</a> <ul class="sectlevel2"> <li><a href="#_contesto_dello_sviluppo_del_plugin">Contesto dello sviluppo del plugin</a></li> <li><a href="#_il_dilemma_del_logging">Il dilemma del logging</a></li> <li><a href="#_le_false_buone_idee">Le false buone idee</a></li> </ul> </li> <li><a href="#_la_soluzione_logger_indipendente">La Soluzione : Logger Indipendente</a> <ul class="sectlevel2"> <li><a href="#_architettura_consigliata">Architettura Consigliata</a></li> <li><a href="#_flusso_di_esecuzione">Flusso di esecuzione</a></li> </ul> </li> <li><a href="#_implementazione_completa">Implementazione completa</a> <ul class="sectlevel2"> <li><a href="#_dipendenze_gradle">Dipendenze Gradle</a></li> <li><a href="#_configurazione_logback">Configurazione Logback</a></li> <li><a href="#_classe_di_test_completa">Classe di Test Completa</a></li> </ul> </li> <li><a href="#_schema_di_logging_multi_livello">Schema di logging multi-livello</a></li> <li><a href="#_buone_pratiche">Buone pratiche</a> <ul class="sectlevel2"> <li><a href="#_struttura_di_logging_consigliata">Struttura di logging consigliata</a></li> <li><a href="#_simboli_visivi_per_la_leggibilità">Simboli Visivi per la Leggibilità</a></li> <li><a href="#_estrazione_delle_informazioni_dalloutput">Estrazione delle informazioni dall’output</a></li> </ul> </li> <li><a href="#_confronto_primadopo">Confronto Prima/Dopo</a> <ul class="sectlevel2"> <li><a href="#_prima_approccio_problematico">Prima: Approccio problematico</a></li> <li><a href="#_dopo_approccio_robusto">Dopo : Approccio Robusto</a></li> </ul> </li> <li><a href="#_diagramma_riepilogativo">Diagramma Riepilogativo</a></li> <li><a href="#_trappole_da_evitare">Trappole da evitare</a> <ul class="sectlevel2"> <li><a href="#_trappola_n1_dimenticare_forwardoutput">�❌ Trappola n°1: Dimenticare `.forwardOutput()</a></li> <li><a href="#_trappola_n2_logger_non_inizializzato">❌ Trappola n°2 : Logger non inizializzato</a></li> <li><a href="#_trappola_n3_logging_eccessivo">�❌ Trappola n°3 : logging eccessivo</a></li> </ul> </li> <li><a href="#_risultati_e_metriche">Risultati e Metriche</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_risorse">Risorse</a></li> <li><a href="#_andare_più_lontano">Andare più lontano</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante lo sviluppo di un plugin Gradle, i test funzionali sono essenziali per validare il comportamento del plugin in un ambiente Gradle reale. Tuttavia, sorge rapidamente una questione cruciale:<strong>come impostare un sistema di logging efficace senza creare dipendenze problematiche con il <code>GradleRunner</code>?</strong></p> </div> <div class="paragraph"> <p>In questo articolo, esploreremo:</p> </div> <div class="ulist"> <ul> <li> <p>La problematica del logging nei test funzionali di Gradle</p> </li> <li> <p>L’architettura di una soluzione robusta con SLF4J e Logback</p> </li> <li> <p>L’implementazione completa con esempi concreti</p> </li> <li> <p>Le buone pratiche e i tranelli da evitare</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_dipendenza_da_gradlerunner">Il Problema : Dipendenza da GradleRunner</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contesto_dello_sviluppo_del_plugin">Contesto dello sviluppo del plugin</h3> <div class="paragraph"> <p>Quando si sviluppa un plugin Gradle, si usa generalmente il`GradleRunner`del <em>Gradle TestKit</em> per eseguire build di test:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `test my plugin`() { val result = GradleRunner.create() .withProjectDir(projectDir) .withArguments("myTask") .build() // Comment logger efficacement ici ? }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_il_dilemma_del_logging">Il dilemma del logging</h3> <div class="paragraph"> <p>Il problema principale è il seguente:<strong>il logging non deve dipendere da un oggetto del quale non si è sicuri dell’inizializzazione</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-deee1fbe3f382bde40453bc7c9efe8ac.png" alt="Diagram" width="447" height="262"> </div> </div> </div> <div class="sect2"> <h3 id="_le_false_buone_idee">Le false buone idee</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Non farlo :</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ MAUVAIS: Tentative d'obtenir un logger du runner val runner = GradleRunner.create() val logger = runner.logger // N'existe pas ! // ❌ MAUVAIS: Logger partagé initialisé tardivement lateinit var logger: Logger @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) }</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_logger_indipendente">La Soluzione : Logger Indipendente</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_architettura_consigliata">Architettura Consigliata</h3> <div class="paragraph"> <p>La soluzione consiste nell’utilizzare un logger<strong>completamente indipendente</strong> du <code>GradleRunner</code>, inizializzato a livello della classe di test.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ba3c98be68b906b5d1edfbd88cf67402.png" alt="Diagram" width="601" height="448"> </div> </div> </div> <div class="sect2"> <h3 id="_flusso_di_esecuzione">Flusso di esecuzione</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-30e3e98c853ad5eb1659c09795eb4e4e.png" alt="Diagram" width="787" height="686"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_implementazione_completa">Implementazione completa</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dipendenze_gradle">Dipendenze Gradle</h3> <div class="paragraph"> <p>Aggiungi le dipendenze necessarie nel tuo`build.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Pour les tests fonctionnels testImplementation(gradleTestKit()) testImplementation("org.junit.jupiter:junit-jupiter:5.10.2") // Pour le logging testImplementation("org.slf4j:slf4j-api:2.0.17") testRuntimeOnly("ch.qos.logback:logback-classic:1.4.14") // Pour les assertions testImplementation("org.assertj:assertj-core:3.27.6") } tasks.test { useJUnitPlatform() }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_configurazione_logback">Configurazione Logback</h3> <div class="paragraph"> <p>Crea il file`src/test/resources/logback-test.xml`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- Appender console avec format lisible --> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender> <!-- Appender fichier pour conservation --> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>build/test-results/functional-tests.log</file> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern> </encoder> </appender> <!-- Logger pour vos tests --> <logger name="com.cheroliv.bakery" level="DEBUG"/> <!-- Réduire le bruit de Gradle --> <logger name="org.gradle" level="WARN"/> <!-- Configuration racine --> <root level="INFO"> <appender-ref ref="STDOUT"/> <appender-ref ref="FILE"/> </root> </configuration></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_classe_di_test_completa">Classe di Test Completa</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package com.cheroliv.bakery import org.gradle.testkit.runner.GradleRunner import org.gradle.testkit.runner.TaskOutcome import org.junit.jupiter.api.* import org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS import org.junit.jupiter.api.io.TempDir import org.slf4j.Logger import org.slf4j.LoggerFactory import java.io.File import kotlin.test.assertEquals import kotlin.test.assertTrue @TestInstance(PER_CLASS) class BakeryPluginFunctionalTest { @field:TempDir lateinit var projectDir: File private val buildFile by lazy { projectDir.resolve("build.gradle.kts") } private val settingsFile by lazy { projectDir.resolve("settings.gradle.kts") } companion object { // ✓ Logger indépendant, initialisé au chargement de la classe private val logger: Logger = LoggerFactory.getLogger( BakeryPluginFunctionalTest::class.java ) @JvmStatic @BeforeAll fun globalSetup() { logger.info("═".repeat(60)) logger.info("DÉMARRAGE DE LA SUITE DE TESTS FONCTIONNELS") logger.info("═".repeat(60)) } @JvmStatic @AfterAll fun globalTeardown() { logger.info("═".repeat(60)) logger.info("FIN DE LA SUITE DE TESTS") logger.info("═".repeat(60)) } } @BeforeEach fun setup() { logger.info("─".repeat(60)) logger.info("Préparation de l'environnement de test") logger.debug("Répertoire de test: ${projectDir.absolutePath}") settingsFile.writeText(""" rootProject.name = "test-bakery-project" """.trimIndent()) logger.debug("✓ settings.gradle.kts créé") } @AfterEach fun teardown(testInfo: TestInfo) { logger.info("✓ Test terminé: ${testInfo.displayName}") logger.info("─".repeat(60)) } @Test fun `plugin can be applied successfully`() { logger.info("TEST: Application du plugin Bakery") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Fichier build.gradle.kts créé") logger.debug("Lancement du build Gradle...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() // ← Important : capture la sortie .withPluginClasspath() .withArguments("tasks", "--group=bakery", "--stacktrace") .withProjectDir(projectDir) .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // Analyse de la sortie logger.debug("Analyse de la sortie Gradle...") val outputLines = result.output.lines() logger.debug("Nombre de lignes capturées: ${outputLines.size}") // Validation val expectedTasks = listOf("bake", "printConfigPath", "printJBakeClasspath") logger.info("Vérification des tâches attendues:") expectedTasks.forEach { task -> val found = result.output.contains(task) logger.debug(" ${if (found) "✓" else "✗"} $task") assertTrue(found, "Task '$task' should be available") } logger.info("✓ Plugin appliqué avec succès - ${expectedTasks.size} tâches trouvées") } @Test fun `bake task executes and prints version`() { logger.info("TEST: Exécution de la tâche 'bake'") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Exécution de 'gradle bake'...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("bake", "--info") // --info pour plus de détails .withProjectDir(projectDir) .build() // Extraction d'informations depuis la sortie logger.debug("Recherche du message 'Baking site'...") val hasBakingMessage = result.output.contains("Baking site with Bakery Plugin!") logger.debug("Recherche de la version JBake...") val hasVersionMessage = result.output.contains("Using JBake version:") // Extraction de la version (si présente) val versionRegex = Regex("Using JBake version: (.+)") val versionMatch = versionRegex.find(result.output) if (versionMatch != null) { val version = versionMatch.groupValues[1] logger.info("Version JBake détectée: $version") } // Validation assertTrue(hasBakingMessage, "Message 'Baking site' attendu") assertTrue(hasVersionMessage, "Message de version attendu") assertEquals(TaskOutcome.SUCCESS, result.task(":bake")?.outcome) logger.info("✓ Tâche 'bake' exécutée avec succès") } @Test fun `analyze output with structured logging`() { logger.info("TEST: Analyse structurée de la sortie") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } task("diagnostics") { doLast { println("[DIAG] Project: ${'$'}{project.name}") println("[DIAG] Build dir: ${'$'}{project.buildDir}") println("[DIAG] Plugin applied: true") val config = configurations.findByName("jbakeRuntime") println("[DIAG] JBake config exists: ${'$'}{config != null}") if (config != null) { println("[DIAG] Dependencies count: ${'$'}{config.dependencies.size}") } } } """.trimIndent()) logger.debug("Exécution de la tâche diagnostics...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("diagnostics", "--quiet") .withProjectDir(projectDir) .build() // Analyse structurée logger.info("Extraction des informations de diagnostic:") val diagLines = result.output.lines() .filter { it.startsWith("[DIAG]") } logger.debug("Nombre de lignes de diagnostic: ${diagLines.size}") diagLines.forEach { line -> logger.info(" $line") // Analyse spécifique par type de ligne when { line.contains("Project:") -> { val projectName = line.substringAfter("Project:").trim() logger.debug(" → Nom du projet extrait: '$projectName'") } line.contains("Dependencies count:") -> { val count = line.substringAfter("count:").trim() logger.debug(" → Nombre de dépendances: $count") } } } assertTrue(diagLines.isNotEmpty(), "Des lignes de diagnostic devraient être présentes") logger.info("✓ Analyse structurée terminée - ${diagLines.size} lignes analysées") } @Test fun `test with error handling`() { logger.info("TEST: Gestion d'erreurs avec logging") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) try { logger.debug("Tentative d'exécution...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("printJBakeClasspath") .withProjectDir(projectDir) .build() val outcome = result.task(":printJBakeClasspath")?.outcome logger.info("Outcome: $outcome") if (outcome == TaskOutcome.SUCCESS) { logger.info("✓ Exécution réussie") } else { logger.warn("⚠ Outcome inattendu: $outcome") } assertEquals(TaskOutcome.SUCCESS, outcome) } catch (e: Exception) { logger.error("✗ Échec du test", e) logger.error("Type d'exception: ${e.javaClass.simpleName}") logger.error("Message: ${e.message}") // Log de la stack trace si nécessaire if (logger.isDebugEnabled) { logger.debug("Stack trace complète:", e) } throw e } } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_schema_di_logging_multi_livello">Schema di logging multi-livello</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-493c1e7d8f4df92b0edabbda4ec4d6a7.png" alt="Diagram" width="314" height="911"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche">Buone pratiche</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_struttura_di_logging_consigliata">Struttura di logging consigliata</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `mon test`() { // 1. LOG: Début du test logger.info("TEST: Description du test") // 2. LOG: Préparation logger.debug("Préparation des fichiers...") buildFile.writeText("...") logger.debug("✓ Fichiers préparés") // 3. LOG: Exécution logger.debug("Lancement du build...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() .withArguments("task") .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // 4. LOG: Analyse logger.debug("Analyse des résultats...") // ... validations ... // 5. LOG: Conclusion logger.info("✓ Test réussi") }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_simboli_visivi_per_la_leggibilità">Simboli Visivi per la Leggibilità</h3> <div class="paragraph"> <p>Utilizzare simboli Unicode per migliorare la leggibilità dei log :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">logger.info("✓ Succès") logger.info("✗ Échec") logger.info("⚠ Attention") logger.info("→ Étape suivante") logger.info("═".repeat(60)) // Séparateur principal logger.info("─".repeat(60)) // Séparateur secondaire</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_estrazione_delle_informazioni_dalloutput">Estrazione delle informazioni dall’output</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Recherche simple val hasMessage = result.output.contains("Expected message") // Extraction avec regex val versionRegex = Regex("Version: (.+)") val version = versionRegex.find(result.output)?.groupValues?.get(1) // Filtrage de lignes val errorLines = result.output.lines() .filter { it.contains("ERROR") } errorLines.forEach { logger.error("Gradle error: $it") }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_confronto_primadopo">Confronto Prima/Dopo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_prima_approccio_problematico">Prima: Approccio problematico</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { lateinit var logger: Logger // ❌ Initialisé tardivement @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) // ❌ Dépendance } @Test fun test() { val runner = GradleRunner.create() logger.info("Testing...") // ⚠ Peut échouer } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_dopo_approccio_robusto">Dopo : Approccio Robusto</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { companion object { private val logger = LoggerFactory.getLogger(...) // ✓ Indépendant } @Test fun test() { logger.info("TEST: Starting...") // ✓ Toujours disponible val result = GradleRunner.create() .forwardOutput() // ✓ Capture la sortie .build() logger.debug("Output: ${result.output}") // ✓ Analyse } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramma_riepilogativo">Diagramma Riepilogativo</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 9) ] @startuml ... ... ( skipping 129 lines ) ... } skinparam StereotypeI { BackgroundColor white BorderColor black } skinparam StereotypeN { BackgroundColor white BorderColor black } skinparam UseCaseStereoType { FontColor black FontName Verdana } skinparam backgroundColor #FEFEFE title Flusso Completo di Registrazione nei Test Funzionali actor "Sviluppatore" as dev participant "JUnit" as junit participant "TestClass" as test participant "Registratore ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml !theme plain skinparam backgroundColor #FEFEFE title Flusso Completo di Registrazione nei Test Funzionali actor "Sviluppatore" as dev participant "JUnit" as junit participant "TestClass" as test participant "Registratore (SLF4J)" as logger participant "Logback" as logback participant "GradleRunner" as runner participant "Console/File" as output dev -> junit : lance les tests activate junit junit -> test : charge la classe activate test test -> logger : initialize (companion) activate logger logger -> logback : configure activate logback logback --> logger : ready deactivate logback logger --> test : ✓ deactivate logger == Phase de Setup == junit -> test : @BeforeAll test -> logger : info("Inizializzazione") logger -> output : [INFO] Initialisation junit -> test : @BeforeEach test -> logger : debug("test di configurazione") logger -> output : [DEBUG] Setup test == Phase de Test == junit -> test : @Test test -> logger : info("Starting") logger -> output : [INFO] TEST: Starting test -> runner : create() activate runner test -> runner : .forwardOutput() test -> runner : .build() runner -> runner : execute Gradle runner --> test : BuildResult + output text deactivate runner test -> logger : debug("Analisi dell'output") logger -> output : [DEBUG] Analyzing output test -> test : assertions test -> logger : info("✓ Test superato") logger -> output : [INFO] ✓ Test passed == Phase de Cleanup == junit -> test : @AfterEach test -> logger : debug("pulizia") logger -> output : [DEBUG] Cleanup junit -> test : @AfterAll test -> logger : info("Fine dei test") logger -> output : [INFO] Fin des tests test --> junit : ✓ all tests passed deactivate test deactivate junit dev <-- junit : rapport de tests @enduml</pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_trappole_da_evitare">Trappole da evitare</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_trappola_n1_dimenticare_forwardoutput">�❌ Trappola n°1: Dimenticare `.forwardOutput()</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: La sortie Gradle n'est pas capturée val result = GradleRunner.create() .withArguments("task") .build() // result.output sera vide !</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: La sortie est capturée val result = GradleRunner.create() .forwardOutput() // ✓ .withArguments("task") .build()</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_trappola_n2_logger_non_inizializzato">❌ Trappola n°2 : Logger non inizializzato</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS class Test { lateinit var logger: Logger // Peut ne pas être initialisé }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON class Test { companion object { private val logger = LoggerFactory.getLogger(...) // Toujours initialisé } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_trappola_n3_logging_eccessivo">�❌ Trappola n°3 : logging eccessivo</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: Trop de logs DEBUG en production logger.debug("Variable a = $a") logger.debug("Variable b = $b") logger.debug("Variable c = $c") // ... 100 lignes de logs</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: Logging ciblé logger.info("Traitement de ${items.size} éléments") logger.debug("Détails: ${items.take(5)}...") // Échantillon seulement</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_risultati_e_metriche">Risultati e Metriche</h2> <div class="sectionbody"> <div class="paragraph"> <p>Con questo approccio, ottieni:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Metrica</th> <th class="tableblock halign-left valign-top">prima</th> <th class="tableblock halign-left valign-top">Dopo</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Linee di codice</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~50 lignes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~80 righe (+60%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Tempo di debug</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~30 min</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~5 min (-83%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Errori rilevati</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Base</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dettagliato</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Manutenzione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">difficile</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Semplice</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Indipendenza</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ accoppiata</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Indipendente</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’implementazione di un sistema di logging robusto nei test funzionali dei plugin Gradle si basa su un principio semplice :<strong>l’indipendenza</strong>.</p> </div> <div class="paragraph"> <p>Punti chiave da ricordare :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Logger indipendente</strong>Inizializzato in un`companion object`</p> </li> <li> <p><strong>SLF4J + Logback</strong>Stack collaudato e configurabile</p> </li> <li> <p><strong>.forwardOutput()</strong>Cattura dell’output Gradle</p> </li> <li> <p><strong>Logging strutturato</strong>: INFO per le fasi, DEBUG per i dettagli</p> </li> <li> <p><strong>Analisi di uscita</strong>Estrazione di informazioni da`result.output`</p> </li> </ol> </div> <div class="paragraph"> <p>Questo approccio garantisce test<strong>manutenibili</strong>, <strong>debuggabili</strong> et <strong>robusti</strong>, rispettando i principi di progettazione solidi.</p> </div> </div> </div> <div class="sect1"> <h2 id="_risorse">Risorse</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/test_kit.html">Documentazione del kit di test Gradle</a></p> </li> <li> <p><a href="https://www.slf4j.org/manual.html">Manuale SLF4J</a></p> </li> <li> <p><a href="https://logback.qos.ch/manual/configuration.html">Configurazione Logback</a></p> </li> <li> <p><a href="https://github.com/gradle/gradle/tree/master/subprojects/test-kit">Codice sorgente Gradle TestKit</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_andare_più_lontano">Andare più lontano</h2> <div class="sectionbody"> <div class="paragraph"> <p>In un prossimo articolo, esploreremo :</p> </div> <div class="ulist"> <ul> <li> <p>L’integrazione continua con logging strutturato</p> </li> <li> <p>I rapporti HTML di test con log integrati</p> </li> <li> <p>Debug avanzato con JVM attach</p> </li> <li> <p>Le prestazioni e le ottimizzazioni di logging</p> </li> </ul> </div> <div class="paragraph"> <p><em>Questo articolo fa parte della serie "Sviluppo di Plugin Gradle" sul mio blog tecnico.</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0096_afficher-couleurs-asciidoc_post.html Sat, 1 Nov 2025 00:00:00 +0000 blog/2025/0096_afficher-couleurs-asciidoc_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_la_problematica">La problematica</a> <ul class="sectlevel2"> <li><a href="#_contesto_di_utilizzo">Contesto di utilizzo</a></li> <li><a href="#_gli_approcci_possibili">Gli approcci possibili</a> <ul class="sectlevel3"> <li><a href="#_opzione_1_caratteri_unicode">Opzione 1 : Caratteri Unicode</a></li> <li><a href="#_opzione_2_immagini_esterne">Opzione 2: Immagini esterne</a></li> <li><a href="#_option_3_ruoli_css_personalizzati">Option 3 : Ruoli CSS personalizzati</a></li> <li><a href="#_opzione_4_iniezione_html_soluzione_adottata">Opzione 4 : Iniezione HTML (soluzione adottata)</a></li> </ul> </li> </ul> </li> <li><a href="#_la_soluzione_iniezione_html_con">La soluzione : Iniezione HTML con </a> <ul class="sectlevel2"> <li><a href="#_principio_di_funzionamento">Principio di funzionamento</a></li> <li><a href="#_implementazione">Implementazione</a> <ul class="sectlevel3"> <li><a href="#_spiegazione_delle_proprietà_css">Spiegazione delle proprietà CSS</a></li> </ul> </li> <li><a href="#_esempio_completo">Esempio completo</a></li> </ul> </li> <li><a href="#_ottimizzazioni_e_buone_pratiche">Ottimizzazioni e buone pratiche</a> <ul class="sectlevel2"> <li><a href="#_gestire_i_colori_chiari">Gestire i colori chiari</a></li> <li><a href="#_adatta_la_dimensione_dei_quadrati">Adatta la dimensione dei quadrati</a></li> <li><a href="#_creare_varianti">Creare varianti</a> <ul class="sectlevel3"> <li><a href="#_cerchio_colorato">Cerchio colorato</a></li> <li><a href="#_quadrato_con_bordo_colorato">Quadrato con bordo colorato</a></li> </ul> </li> </ul> </li> <li><a href="#_architettura_della_soluzione">Architettura della soluzione</a></li> <li><a href="#_vantaggi_e_limitazioni">Vantaggi e limitazioni</a> <ul class="sectlevel2"> <li><a href="#_vantaggi">Vantaggi</a></li> <li><a href="#_limitazioni">Limitazioni</a></li> <li><a href="#_miglioramento_dellaccessibilità">Miglioramento dell’accessibilità</a></li> </ul> </li> <li><a href="#_esempio_concreto_documentazione_dei_temi">Esempio concreto: Documentazione dei temi</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_risorse">Risorse</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante la redazione di documentazione tecnica, in particolare per guide di stile o specifiche di interfaccia utente, è frequente dover visualizzare palette di colori. AsciiDoc, nonostante sia molto potente per la documentazione, non propone una sintassi nativa per visualizzare esempi di colore. Questo articolo esplora la problematica e propone una soluzione elegante basata sull’iniezione HTML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_problematica">La problematica</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contesto_di_utilizzo">Contesto di utilizzo</h3> <div class="paragraph"> <p>Immaginiamo che voi documentiate le variabili CSS di un tema di un’applicazione web. Avete bisogno di :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Elencare i codici colori esadecimali</p> </li> <li> <p>Mostra un’anteprima visiva di ogni colore</p> </li> <li> <p>Maintenir la lisibilité du document source</p> </li> <li> <p>Assicurare la compatibilità con i generatori di siti statici come JBake</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="use-case-diagram.svg" alt="use case diagram" width="1050" height="203"> </div> </div> </div> <div class="sect2"> <h3 id="_gli_approcci_possibili">Gli approcci possibili</h3> <div class="paragraph"> <p>Diversi approcci possono essere considerati per visualizzare i colori in un documento AsciiDoc :</p> </div> <div class="imageblock"> <div class="content"> <img src="component-diagram.svg" alt="component diagram" width="863" height="190"> </div> </div> <div class="sect3"> <h4 id="_opzione_1_caratteri_unicode">Opzione 1 : Caratteri Unicode</h4> <div class="paragraph"> <p>L’utilizzo di caratteri Unicode come`■`(■) è semplice ma limitata :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* ■ --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitazioni</strong> : Nessun controllo sul colore, dipende dal carattere di sistema.</p> </div> </div> <div class="sect3"> <h4 id="_opzione_2_immagini_esterne">Opzione 2: Immagini esterne</h4> <div class="paragraph"> <p>Creare immagini PNG o SVG per ogni colore :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* image:colors/violet.svg[width=16] --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitazioni</strong> : Manutenzione pesante, moltiplicazione dei file, nessuna sincronizzazione automatica.</p> </div> </div> <div class="sect3"> <h4 id="_option_3_ruoli_css_personalizzati">Option 3 : Ruoli CSS personalizzati</h4> <div class="paragraph"> <p>Definire le classi CSS e applicarle tramite i ruoli AsciiDoc :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* [.color-violet]##■## --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitazioni</strong> : Richiede un foglio di stile esterno, definizione preliminare di tutti i colori possibili.</p> </div> </div> <div class="sect3"> <h4 id="_opzione_4_iniezione_html_soluzione_adottata">Opzione 4 : Iniezione HTML (soluzione adottata)</h4> <div class="paragraph"> <p>Utilizzare la macro``per iniettare HTML con stili inline :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em; background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_iniezione_html_con">La soluzione : Iniezione HTML con </h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principio_di_funzionamento">Principio di funzionamento</h3> <div class="paragraph"> <p>La macro``d’AsciiDoc permette di inserire contenuto grezzo che non verrà interpretato dal processore AsciiDoc. Questo ci permette di iniettare direttamente HTML con stili CSS inline.</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ] @startuml participant "documento ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "documento AsciiDoc" as doc participant "processore AsciiDoc" as processor participant "pass:[] macro" as pass participant "HTML finale" as html doc -> processor : Analyse document processor -> pass : Détecte pass:[] pass -> processor : Retourne HTML brut processor -> html : Insère sans transformation html -> html : Navigateur applique styles @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_implementazione">Implementazione</h3> <div class="paragraph"> <p>Ecco la struttura HTML da iniettare:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block; width:1em; height:1em; background:#7952b3; vertical-align:middle; margin-right:0.5em"> </span></code></pre> </div> </div> <div class="sect3"> <h4 id="_spiegazione_delle_proprietà_css">Spiegazione delle proprietà CSS</h4> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Proprietà</th> <th class="tableblock halign-left valign-top">Funzione</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>display:inline-block</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permette di impostare width/height rimanendo nel flusso inline</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>width:1em; height:1em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dimensione del quadrato relativa alla dimensione del carattere (responsive)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>background:#7952b3</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il colore da visualizzare (variabile secondo le tue esigenze)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>vertical-align:middle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Allinea il quadrato con il testo adiacente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>margin-right:0.5em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Spaziatura tra il quadrato e il testo</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_esempio_completo">Esempio completo</h3> <div class="paragraph"> <p>Ecco un esempio che documenta una paletta di tema:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">== Thème Clair * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)</code></pre> </div> </div> <div class="paragraph"> <p>Chi produce il rendering seguente :</p> </div> <div class="paragraph"> <p>Tema chiaro</p> </div> <div class="ulist"> <ul> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --bg-primary:`#f8f9fa`(bianco avorio)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span> --text-primary:`#212529`(nero molto scuro)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span> --accent-color:`#7952b3`(viola Bootstrap)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span> --accent-hover:`#61428f`(viola più scuro)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --card-bg:`#ffffff`(bianco)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ottimizzazioni_e_buone_pratiche">Ottimizzazioni e buone pratiche</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_gestire_i_colori_chiari">Gestire i colori chiari</h3> <div class="paragraph"> <p>Per i colori molto chiari (bianco, grigio molto chiaro), aggiungi un bordo per renderli visibili su sfondo bianco :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block;width:1em;height:1em; background:#ffffff;border:1px solid #ccc; vertical-align:middle;margin-right:0.5em"></span></code></pre> </div> </div> <div class="paragraph"> <p>Il bordo grigio (<code>border:1px solid #ccc</code>) permette di delimitare il quadrato bianco su uno sfondo bianco.</p> </div> </div> <div class="sect2"> <h3 id="_adatta_la_dimensione_dei_quadrati">Adatta la dimensione dei quadrati</h3> <div class="paragraph"> <p>Puoi regolare la dimensione dei quadrati in base alle tue esigenze :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré * pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré</code></pre> </div> </div> <div class="paragraph"> <p>L’utilizzo dell’unità`em`garantisce che i quadrati si adattino alla dimensione del carattere.</p> </div> </div> <div class="sect2"> <h3 id="_creare_varianti">Creare varianti</h3> <div class="paragraph"> <p>Per esigenze specifiche, puoi creare diverse forme :</p> </div> <div class="sect3"> <h4 id="_cerchio_colorato">Cerchio colorato</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_quadrato_con_bordo_colorato">Quadrato con bordo colorato</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_della_soluzione">Architettura della soluzione</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="architecture-diagram.svg" alt="architecture diagram" width="483" height="412"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_vantaggi_e_limitazioni">Vantaggi e limitazioni</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_vantaggi">Vantaggi</h3> <div class="ulist"> <ul> <li> <p>✓ <strong>Autonomie</strong> : Pas de dépendance à des fichiers externes</p> </li> <li> <p>✓ <strong>Portabilità</strong> : Funziona con tutti i processori AsciiDoc</p> </li> <li> <p>�✓ <strong>Sincronizzazione</strong> : Il codice colore è direttamente nell’HTML</p> </li> <li> <p>✓ <strong>Flessibilità</strong> : Personalizzazione completa dello stile</p> </li> <li> <p>�✓ <strong>Manutenzione</strong> : Modifica semplice del codice esadecimale</p> </li> <li> <p>�✓ <strong>Compatibilità JBake</strong> : Funziona perfettamente con i generatori di siti statici</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_limitazioni">Limitazioni</h3> <div class="ulist"> <ul> <li> <p><strong>Verbosità</strong> : Codice HTML ripetitivo nel sorgente AsciiDoc</p> </li> <li> <p>✗ <strong>Leggibilità fonte</strong> : Il documento sorgente è meno pulito</p> </li> <li> <p>�✗ <strong>Accessibilità</strong> : Nessun testo alternativo nativo (da aggiungere manualmente)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_miglioramento_dellaccessibilità">Miglioramento dell’accessibilità</h3> <div class="paragraph"> <p>Per rendere i quadrati accessibili ai lettori di schermo:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span role="img" aria-label="Couleur violet Bootstrap" style="display:inline-block;width:1em;height:1em;background:#7952b3; vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p>Gli attributi`role="img"` et `aria-label`consentono alle tecnologie assistive di comprendere e descrivere il contenuto visivo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_esempio_concreto_documentazione_dei_temi">Esempio concreto: Documentazione dei temi</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ecco un esempio completo documentante diversi temi:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Guide des couleurs de l'application == Thème Clair (`:root`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) == Thème Sombre (`[data-bs-theme="dark"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap) == Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’iniezione HTML tramite la macro``d’AsciiDoc offre una soluzione elegante e pratica per visualizzare dei campioni di colore nella documentazione tecnica. Sebbene leggermente verbosa, questo approccio garantisce una portabilità massima e una manutenzione semplificata.</p> </div> <div class="paragraph"> <p>Questa tecnica non richiede alcuna configurazione esterna, alcun foglio di stile aggiuntivo, e funziona immediatamente con JBake e tutti i processori AsciiDoc standard.</p> </div> <div class="paragraph"> <p>Una volta che hai creato il tuo primo quadrato colorato, basta copiare e incollare il codice HTML e modificare il codice esadecimale per creare rapidamente una palette completa.</p> </div> <div class="paragraph"> <p>Questa tecnica può essere estesa ad altri casi d’uso che richiedono un rendering visivo personalizzato: icone, badge, grafici semplici, o qualsiasi elemento visivo che richieda un controllo preciso dello stile.</p> </div> </div> </div> <div class="sect1"> <h2 id="_risorse">Risorse</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/" target="_blank" rel="noopener">Documentation AsciiDoc : pass macro</a></p> </li> <li> <p><a href="https://jbake.org/docs/2.6.7/" target="_blank" rel="noopener">JBake Documentation</a></p> </li> <li> <p><a href="https://developer.mozilla.org/fr/docs/Web/CSS/color_value" target="_blank" rel="noopener">MDN : Valori di colore CSS</a></p> </li> </ul> </div> <div class="paragraph"> <p>Articolo pubblicato il 2025-11-01</p> </div> </div> </div> https://cheroliv.com/blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html Mon, 20 Oct 2025 00:00:00 +0000 blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a> <ul class="sectlevel2"> <li><a href="#_diagramma_di_casi_duso_use_case">Diagramma di casi d’uso (Use Case)</a></li> </ul> </li> <li><a href="#_architettura_dellinternazionalizzazione">Architettura dell’internazionalizzazione</a> <ul class="sectlevel2"> <li><a href="#_diagramma_di_struttura_organizzazione_dei_file">Diagramma di struttura (Organizzazione dei file)</a></li> <li><a href="#_perché_questo_approccio">Perché questo approccio?</a></li> <li><a href="#_diagramma_dei_componenti">Diagramma dei componenti</a></li> </ul> </li> <li><a href="#_i18n_del_templating_con_thymeleaf">I18n del templating con Thymeleaf</a> <ul class="sectlevel2"> <li><a href="#_struttura_dei_file_di_messaggi">Struttura dei file di messaggi</a></li> <li><a href="#_contenuto_dei_file_dei_messaggi">Contenuto dei file dei messaggi</a></li> <li><a href="#_utilizzo_nei_template">Utilizzo nei template</a></li> <li><a href="#_diagramma_di_sequenza_risoluzione_i18n">Diagramma di sequenza - Risoluzione i18n</a></li> <li><a href="#_configurazione_della_locale_in_jbake">Configurazione della locale in JBake</a></li> </ul> </li> <li><a href="#_i18n_degli_articoli_organizzazione_per_cartelle">I18n degli articoli: organizzazione per cartelle</a> <ul class="sectlevel2"> <li><a href="#_diagramma_di_flusso_flow_generazione">Diagramma di flusso (Flow) - Generazione</a></li> <li><a href="#_struttura_delle_cartelle">Struttura delle cartelle</a></li> <li><a href="#_vantaggi_di_questo_approccio">Vantaggi di questo approccio</a></li> <li><a href="#_metadati_degli_articoli">Metadati degli articoli</a></li> <li><a href="#_configurazione_degli_url">Configurazione degli URL</a></li> </ul> </li> <li><a href="#_template_per_la_visualizzazione_multilingue">Template per la visualizzazione multilingue</a> <ul class="sectlevel2"> <li><a href="#_modello_di_articolo_con_selettore_di_lingua">Modello di articolo con selettore di lingua</a></li> <li><a href="#_indice_filtrato_per_lingua">Indice filtrato per lingua</a></li> </ul> </li> <li><a href="#_navigazione_tra_lingue">Navigazione tra lingue</a> <ul class="sectlevel2"> <li><a href="#_selezione_lingua_globale">Selezione lingua globale</a></li> <li><a href="#_diagramma_di_flusso_lettura_utente">Diagramma di flusso - Lettura utente</a></li> <li><a href="#_stile_css_per_il_selettore">Stile CSS per il selettore</a></li> </ul> </li> <li><a href="#_feed_rss_per_lingua">Feed RSS per lingua</a></li> <li><a href="#_buone_pratiche_e_consigli">Buone pratiche e consigli</a> <ul class="sectlevel2"> <li><a href="#_1_coerenza_degli_identificatori_dellarticolo">1. Coerenza degli identificatori dell’articolo</a></li> <li><a href="#_2_date_coerenti">2. Date coerenti</a></li> <li><a href="#_3_tag_multilingue">3. Tag multilingue</a></li> <li><a href="#_4_gestione_degli_articoli_non_tradotti">4. Gestione degli articoli non tradotti</a></li> <li><a href="#_5_sitemap_multilingue">5. Sitemap multilingue</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a> <ul class="sectlevel2"> <li><a href="#_diagramma_di_distribuzione">Diagramma di distribuzione</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’internationalizzazione (i18n) di un sito statico può sembrare complesso a prima vista, ma JBake combinato con Thymeleaf offre soluzioni eleganti per creare un sito multilingue. In questo articolo, vi mostrerò come ho implementato l’i18n sul mio blog, coprendo sia il templating che la gestione degli articoli in più lingue.</p> </div> <div class="sect2"> <h3 id="_diagramma_di_casi_duso_use_case">Diagramma di casi d’uso (Use Case)</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-57d78fce66f42ec7b59ecb2a28dac283.png" alt="Diagram" width="649" height="457"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_dellinternazionalizzazione">Architettura dell’internazionalizzazione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il nostro approccio si basa su due pilastri:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>L’internazionalizzazione del templating</strong>utilizzo dei file di messaggi Thymeleaf per gli elementi dell’interfaccia</p> </li> <li> <p><strong>L’i18n del contenuto</strong>organizzazione degli articoli per lingua in una struttura di cartelle dedicata</p> </li> </ol> </div> <div class="sect2"> <h3 id="_diagramma_di_struttura_organizzazione_dei_file">Diagramma di struttura (Organizzazione dei file)</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-2f100fc3ec2ec37f9556818cdc246602.png" alt="Diagram" width="188" height="513"> </div> </div> </div> <div class="sect2"> <h3 id="_perché_questo_approccio">Perché questo approccio?</h3> <div class="paragraph"> <p>Questa separazione permette di:</p> </div> <div class="ulist"> <ul> <li> <p>Mantenere la coerenza nell’interfaccia indipendentemente dalla lingua</p> </li> <li> <p>Gestire indipendentemente il contenuto e le traduzioni degli articoli</p> </li> <li> <p>Facilitare l’aggiunta di nuove lingue senza un refactoring importante</p> </li> <li> <p>Consentire articoli disponibili solo in alcune lingue</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_diagramma_dei_componenti">Diagramma dei componenti</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ae351b19032c5785e4193b7b09a801c0.png" alt="Diagram" width="1771" height="477"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i18n_del_templating_con_thymeleaf">I18n del templating con Thymeleaf</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_struttura_dei_file_di_messaggi">Struttura dei file di messaggi</h3> <div class="paragraph"> <p>Il primo passaggio consiste nel creare i file di proprietà per ogni lingua supportata :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">src/jbake/templates/ ├── messages.properties # Fallback par défaut ├── messages_fr.properties # Français ├── messages_en.properties # Anglais └── messages_de.properties # Allemand</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_contenuto_dei_file_dei_messaggi">Contenuto dei file dei messaggi</h3> <div class="paragraph"> <p>Ecco un esempio di file`messages_fr.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Accueil nav.blog=Blog nav.about=À propos nav.contact=Contact # Articles article.readmore=Lire la suite article.published=Publié le article.tags=Étiquettes article.also.available=Également disponible en # Interface site.title=Mon Blog Technique site.description=Partage de connaissances et expériences footer.copyright=© 2025 Tous droits réservés search.placeholder=Rechercher un article...</code></pre> </div> </div> <div class="paragraph"> <p>E il suo equivalente inglese`messages_en.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Home nav.blog=Blog nav.about=About nav.contact=Contact # Articles article.readmore=Read more article.published=Published on article.tags=Tags article.also.available=Also available in # Interface site.title=My Tech Blog site.description=Sharing knowledge and experiences footer.copyright=© 2025 All rights reserved search.placeholder=Search articles...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_utilizzo_nei_template">Utilizzo nei template</h3> <div class="paragraph"> <p>Nei vostri template Thymeleaf, utilizza la sintassi`#{}`per accedere ai messaggi :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> <meta name="description" th:content="#{site.description}" /> </head> <body> <nav> <a th:href="@{/}" th:text="#{nav.home}">Accueil</a> <a th:href="@{/blog/}" th:text="#{nav.blog}">Blog</a> <a th:href="@{/about.html}" th:text="#{nav.about}">À propos</a> </nav> <footer> <p th:text="#{footer.copyright}">Copyright</p> </footer> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_diagramma_di_sequenza_risoluzione_i18n">Diagramma di sequenza - Risoluzione i18n</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml actor Auteur participant JBake participant "AsciiDoc ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Auteur participant JBake participant "AsciiDoc Parser" as parser participant "Thymeleaf Engine" as thymeleaf participant "I18n\nResolver" as i18n database "messages_*.properties" as messages Auteur -> JBake: jbake -b activate JBake JBake -> parser: Lire article.fr.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=fr, article-id=xyz) deactivate parser JBake -> parser: Lire article.en.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=en, article-id=xyz) deactivate parser JBake -> thymeleaf: Générer page FR activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_fr.properties messages --> i18n: "Casa" i18n --> thymeleaf: "Casa" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=fr) JBake --> thymeleaf: article.en.html trouvé thymeleaf --> JBake: /fr/blog/article.html deactivate thymeleaf JBake -> thymeleaf: Générer page EN activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_en.properties messages --> i18n: "Casa" i18n --> thymeleaf: "Casa" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=en) JBake --> thymeleaf: article.fr.html trouvé thymeleaf --> JBake: /en/blog/article.html deactivate thymeleaf JBake --> Auteur: Site généré deactivate JBake @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_configurazione_della_locale_in_jbake">Configurazione della locale in JBake</h3> <div class="paragraph"> <p>Nel tuo file`jbake.properties`, imposta il locale predefinito :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Locale par défaut thymeleaf.locale=fr # Encodage template.encoding=UTF-8</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i18n_degli_articoli_organizzazione_per_cartelle">I18n degli articoli: organizzazione per cartelle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagramma_di_flusso_flow_generazione">Diagramma di flusso (Flow) - Generazione</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-286838d40f315fecc1c69883e795218f.png" alt="Diagram" width="285" height="1034"> </div> </div> </div> <div class="sect2"> <h3 id="_struttura_delle_cartelle">Struttura delle cartelle</h3> <div class="paragraph"> <p>Invece di utilizzare suffissi nei nomi dei file, ho optato per una organizzazione per cartelle che offre maggiore chiarezza e manutenibilità :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">content/blog/ ├── 2024/ │ ├── fr/ │ │ ├── introduction-jbake.adoc │ │ ├── guide-thymeleaf.adoc │ │ └── astuces-asciidoc.adoc │ └── en/ │ ├── introduction-jbake.adoc │ ├── thymeleaf-guide.adoc │ └── asciidoc-tips.adoc └── 2025/ ├── fr/ │ └── internationalisation-jbake.adoc └── en/ └── jbake-internationalization.adoc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_vantaggi_di_questo_approccio">Vantaggi di questo approccio</h3> <div class="paragraph"> <p>Questa struttura presenta diversi vantaggi:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Separazione chiara</strong>: ogni lingua ha il suo spazio</p> </li> <li> <p><strong>Denominazione flessibile</strong>I file possono avere nomi diversi a seconda della lingua</p> </li> <li> <p><strong>Scalabilità</strong>: facile da aggiungere una nuova lingua</p> </li> <li> <p><strong>organizzazione naturale</strong>: segue la logica temporale di JBake</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_metadati_degli_articoli">Metadati degli articoli</h3> <div class="paragraph"> <p>Ogni articolo deve contenere dei metadati per consentire il collegamento tra le traduzioni. Ecco un esempio :</p> </div> <div class="paragraph"> <p><strong>Versione francese</strong>(<code>2025/fr/internationalisation-jbake.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalisation d'un site statique JBake :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: fr :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide pour mettre en place l'i18n avec JBake</code></pre> </div> </div> <div class="paragraph"> <p><strong>Versione inglese</strong>(<code>2025/en/jbake-internationalization.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalizing a JBake Static Site :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: en :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide to implement i18n with JBake</code></pre> </div> </div> <div class="paragraph"> <p>NOTA: L’attributo`:jbake-article-id:`è cruciale : permette di collegare le diverse traduzioni di uno stesso articolo.</p> </div> </div> <div class="sect2"> <h3 id="_configurazione_degli_url">Configurazione degli URL</h3> <div class="paragraph"> <p>In`jbake.properties`, configura il pattern dell’URL per includere la lingua:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Pattern d'URL avec langue post.permalink.pattern=:lang/blog/:year/:name.html # Langue par défaut site.default.lang=fr</code></pre> </div> </div> <div class="paragraph"> <p>Ciò genererà URL del tipo :</p> </div> <div class="ulist"> <ul> <li> <p><code>/fr/blog/2025/internationalisation-jbake.html</code></p> </li> <li> <p><code>/en/blog/2025/jbake-internationalization.html</code></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_template_per_la_visualizzazione_multilingue">Template per la visualizzazione multilingue</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_modello_di_articolo_con_selettore_di_lingua">Modello di articolo con selettore di lingua</h3> <div class="paragraph"> <p>Create un template`post.html`che mostra le traduzioni disponibili:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="${content.title}">Article</title> </head> <body> <article> <header> <h1 th:text="${content.title}">Titre</h1> <div class="article-meta"> <time th:text="${#dates.format(content.date, 'dd MMMM yyyy')}" th:attr="datetime=${#dates.format(content.date, 'yyyy-MM-dd')}"> Date </time> <!-- Sélecteur de traductions --> <div class="translations" th:if="${content['article-id']}"> <span th:text="#{article.also.available}">Aussi disponible en :</span> <ul class="language-list"> <li th:each="post : ${published_posts}" th:if="${post['article-id'] == content['article-id'] and post.lang != content.lang}"> <a th:href="${post.uri}" th:text="${post.lang.toUpperCase()}"> LANG </a> </li> </ul> </div> </div> </header> <div class="content" th:utext="${content.body}"> Contenu de l'article </div> <footer class="article-footer"> <div class="tags" th:if="${content.tags}"> <span th:text="#{article.tags}">Étiquettes :</span> <span th:each="tag : ${content.tags}"> <a th:href="@{/tags/{tag}.html(tag=${tag})}" th:text="${tag}">tag</a> </span> </div> </footer> </article> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_indice_filtrato_per_lingua">Indice filtrato per lingua</h3> <div class="paragraph"> <p>Crea i template di indice per ogni lingua:</p> </div> <div class="paragraph"> <p><strong>index.html</strong>(indice italiano) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Titre</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Lire la suite </a> </article> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><strong>index_en.html</strong>(indice inglese) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">My Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'en'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Title</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Read more </a> </article> </div> </main> </body> </html></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_navigazione_tra_lingue">Navigazione tra lingue</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_selezione_lingua_globale">Selezione lingua globale</h3> </div> <div class="sect2"> <h3 id="_diagramma_di_flusso_lettura_utente">Diagramma di flusso - Lettura utente</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-35c457cfbd1b9be0156f6bbbfb2925d1.png" alt="Diagram" width="494" height="761"> </div> </div> <div class="paragraph"> <p>Aggiungi un selettore di lingua nel tuo template principale:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><nav class="language-switcher"> <a href="/index.html" th:classappend="${content.lang == 'fr'} ? 'active'" title="Français"> 🇫🇷 FR </a> <a href="/en/index.html" th:classappend="${content.lang == 'en'} ? 'active'" title="English"> 🇬🇧 EN </a> </nav></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_stile_css_per_il_selettore">Stile CSS per il selettore</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.language-switcher { display: flex; gap: 1rem; padding: 0.5rem; background: #f5f5f5; border-radius: 4px; } .language-switcher a { padding: 0.5rem 1rem; text-decoration: none; color: #333; border-radius: 4px; transition: background 0.2s; } .language-switcher a:hover { background: #e0e0e0; } .language-switcher a.active { background: #007bff; color: white; } .translations { margin: 1rem 0; padding: 1rem; background: #f8f9fa; border-left: 4px solid #007bff; } .language-list { display: inline-flex; gap: 0.5rem; list-style: none; padding: 0; margin: 0; } .language-list li::after { content: "•"; margin-left: 0.5rem; } .language-list li:last-child::after { content: ""; }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_feed_rss_per_lingua">Feed RSS per lingua</h2> <div class="sectionbody"> <div class="paragraph"> <p>Create dei template distinti:</p> </div> <div class="paragraph"> <p><strong>feed.xml</strong>(flusso francese) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:th="http://www.thymeleaf.org"> <channel> <title th:text="#{site.title}">Mon Blog</title> <link th:text="${config.site_host}">http://example.com</link> <description th:text="#{site.description}">Description</description> <language>fr</language> <item th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <title th:text="${post.title}">Titre</title> <link th:text="${config.site_host + post.uri}">Lien</link> <pubDate th:text="${#dates.format(post.date, 'EEE, dd MMM yyyy HH:mm:ss Z')}"> Date </pubDate> <description th:text="${post.description}">Description</description> </item> </channel> </rss></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche_e_consigli">Buone pratiche e consigli</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1_coerenza_degli_identificatori_dellarticolo">1. Coerenza degli identificatori dell’articolo</h3> <div class="paragraph"> <p>Assicurati che`:jbake-article-id:`è identico per tutte le traduzioni dello stesso articolo. Utilizza un formato coerente :</p> </div> <div class="ulist"> <ul> <li> <p>Preferisci gli identificatori in inglese per universalità</p> </li> <li> <p>Utilizzate dei trattini per separare le parole</p> </li> <li> <p>Evitate i caratteri speciali</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_2_date_coerenti">2. Date coerenti</h3> <div class="paragraph"> <p>Tutte le traduzioni di un articolo devono avere la stessa data di pubblicazione.<code>:jbake-date:</code>). Ciò facilita la classificazione e la visualizzazione cronologica.</p> </div> </div> <div class="sect2"> <h3 id="_3_tag_multilingue">3. Tag multilingue</h3> <div class="paragraph"> <p>Per i tag, hai due opzioni :</p> </div> <div class="paragraph"> <p><strong>Opzione 1: Tag universali in inglese</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> <div class="paragraph"> <p><strong>Option 2 : Tag tradotti con mapping</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc"># Version française :jbake-tags: java, spring-boot, microservices # Version anglaise :jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_gestione_degli_articoli_non_tradotti">4. Gestione degli articoli non tradotti</h3> <div class="paragraph"> <p>Non è obbligatorio tradurre tutti gli articoli. Se un articolo esiste solo in una lingua, semplicemente non apparirà negli elenchi dell’altra lingua.</p> </div> </div> <div class="sect2"> <h3 id="_5_sitemap_multilingue">5. Sitemap multilingue</h3> <div class="paragraph"> <p>Genera una sitemap che includa tutte le lingue :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org"> <url th:each="post : ${published_posts}"> <loc th:text="${config.site_host + post.uri}">URL</loc> <lastmod th:text="${#dates.format(post.date, 'yyyy-MM-dd')}">Date</lastmod> <!-- Liens alternatifs pour les traductions --> <xhtml:link th:each="translation : ${published_posts}" th:if="${translation['article-id'] == post['article-id'] and translation.lang != post.lang}" rel="alternate" th:attr="hreflang=${translation.lang},href=${config.site_host + translation.uri}" /> </url> </urlset></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’internazionalizzazione di un sito JBake con Thymeleaf è un approccio robusto e mantenibile. Separando l’i18n dal templating (tramite i file dei messaggi) e l’i18n dal contenuto (tramite l’organizzazione in cartelle), si ottiene un sistema flessibile che può evolvere facilmente.</p> </div> <div class="paragraph"> <p>I punti chiave da ricordare:</p> </div> <div class="ulist"> <ul> <li> <p><strong>File di messaggi Thymeleaf</strong>per l’interfaccia utente</p> </li> <li> <p><strong>Organizzazione per cartelle</strong>(anno/lingua) per gli articoli</p> </li> <li> <p><strong>identificatori articolo</strong>per collegare le traduzioni</p> </li> <li> <p><strong>Modelli dedicati</strong>per ogni lingua</p> </li> <li> <p><strong>URL esplicite</strong>incluse il codice della lingua</p> </li> </ul> </div> <div class="sect2"> <h3 id="_diagramma_di_distribuzione">Diagramma di distribuzione</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 14) ] @startuml node "Macchina di sviluppo" { artifact "Fonti" { folder "</think>" folder "templates/" folder "attivi/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "Server di build ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml node "Macchina di sviluppo" { artifact "Fonti" { folder "</think>" folder "templates/" folder "attivi/" } component "JBake CLI" as jbake Sources --> jbake : jbake -b } node "Server di build (CI/CD)" { component "GitHub Actions o GitLab CI" as ci jbake --> ci : push } cloud "CDN / Hosting" { node "Server Web statico" { artifact "Sito Generato" { folder "/it/blog/" folder "/en/blog/" folder "/assets/" } } } ci --> "Sito Generato" : déploiement actor "Lettori" as users users --> "Server Web statico" : HTTPS @enduml</pre> </div> </div> <div class="paragraph"> <p>Questa architettura ti permette di iniziare semplicemente con due lingue e di aggiungerne altre senza un refactoring importante. Il tutto rimane completamente statico e performante, fedele alla filosofia di JBake.</p> </div> <div class="paragraph"> <p>Buon sviluppo multilingue ! 🌍</p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0094_tor_browser_install_post.html Sun, 5 Oct 2025 00:00:00 +0000 blog/2025/0094_tor_browser_install_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_download_di_tor_e_della_sua_firma">Download di Tor e della sua firma</a></li> <li><a href="#_verifica_crittografica_della_firma">Verifica crittografica della firma</a> <ul class="sectlevel2"> <li><a href="#_importare_la_chiave_pubblica_del_tor_project">Importare la chiave pubblica del Tor Project</a></li> <li><a href="#_2_verificare_la_firma">2. Verificare la firma</a></li> <li><a href="#_esempio_pratico_firma_valida_ma_chiave_non_certificata">Esempio pratico: firma valida ma chiave non certificata</a></li> </ul> </li> <li><a href="#_perché_verificare_la_firma">Perché verificare la firma ?</a></li> <li><a href="#_estrazione_e_avvio_di_tor_browser">Estrazione e avvio di Tor Browser</a></li> <li><a href="#_integrazione_al_desktop_ubuntu">Integrazione al desktop Ubuntu</a></li> <li><a href="#_esplora_risorse_educative_con_tor">Esplora risorse educative con Tor</a></li> <li><a href="#_aggiornamento_di_tor_browser">Aggiornamento di Tor Browser</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_riferimenti">Riferimenti</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>In un mondo in cui la privacy digitale è sempre più minacciata, <strong>Tor Browser</strong> rimane uno strumento essenziale per preservare l’anonimato e la libertà di informazione. Tuttavia, è fondamentale non eseguire mai un software scaricato senza aver<strong>verificato la sua autenticità</strong>. Questo articolo presenta un metodo completo per:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Scaricare <strong>Tor Browser</strong> e la sua firma`.asc`</p> </li> <li> <p>Verificare la validità del file scaricato</p> </li> <li> <p>Installare e avviare <strong>Tor Browser</strong> su Ubuntu</p> </li> <li> <p>Aggiungerlo ai menu del desktop per un uso quotidiano</p> </li> <li> <p>Esplorare risorse educative e OSINT etiche via Tor</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_download_di_tor_e_della_sua_firma">Download di Tor e della sua firma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Crea una cartella dedicata per il browser Tor :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/workspace/tipiak/tor cd ~/workspace/tipiak/tor</code></pre> </div> </div> <div class="paragraph"> <p>Scarica poi l’archivio del browser Tor e la sua firma :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz.asc</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_verifica_crittografica_della_firma">Verifica crittografica della firma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa fase è<strong>indispensabile</strong>per assicurarsi che il file scaricato provenga effettivamente dal <strong>Tor Project</strong> e non sia stato modificato</p> </div> <div class="sect2"> <h3 id="_importare_la_chiave_pubblica_del_tor_project">Importare la chiave pubblica del Tor Project</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org</code></pre> </div> </div> <div class="paragraph"> <p>Verifichi che la chiave sia importata correttamente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --list-keys torbrowser@torproject.org</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_verificare_la_firma">2. Verificare la firma</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz</code></pre> </div> </div> <div class="paragraph"> <p>Se tutto è corretto, verrà visualizzato il messaggio seguente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg: Good signature from "Tor Browser Developers (signing key)"</code></pre> </div> </div> <div class="paragraph"> <p>In caso di avviso di chiave non certificata, ciò significa semplicemente che non hai ancora firmato la chiave di fiducia del Progetto Tor, ma la firma rimane valida.</p> </div> </div> <div class="sect2"> <h3 id="_esempio_pratico_firma_valida_ma_chiave_non_certificata">Esempio pratico: firma valida ma chiave non certificata</h3> <div class="paragraph"> <p>È frequente incontrare un messaggio come questo durante la verifica.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz gpg: Signature faite le mar. 16 sept. 2025 14:26:26 CEST gpg: avec la clef RSA CAAE408AEBE2288E96FC5D5E157432CF78A65729 gpg: Bonne signature de « Tor Browser Developers (signing key) <torbrowser@torproject.org> » [inconnu] gpg: Attention : cette clef n'est pas certifiée avec une signature de confiance. gpg: Rien n'indique que la signature appartient à son propriétaire. Empreinte de clef principale : EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290 Empreinte de la sous-clef : CAAE 408A EBE2 288E 96FC 5D5E 1574 32CF 78A6 5729</code></pre> </div> </div> <div class="paragraph"> <p>Questo messaggio indica che la firma è tecnicamente "buona" (il file non è stato alterato), ma il tuo sistema GPG non può <strong>certificare la fiducia</strong> nella chiave stessa. Per dissipare questo dubbio, è essenziale confrontare l’impronta della chiave principale (<code>EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290</code>) con quella pubblicata sul sito ufficiale del Tor Project.</p> </div> <div class="paragraph"> <p>Secondo il sito ufficiale, l’impronta attesa è :`EF6E286DDA85EA2A4BA7DE684E2C6E8793298290`.</p> </div> <div class="paragraph"> <p>Poiché l’impronta visualizzata da`gpg`corrisponde <strong>esattamente</strong> a quella del sito ufficiale, puoi essere certo che la chiave è legittima e che il file è sicuro. L’avviso di \"chiave non certificata\" è allora un’informazione sulla tua configurazione GPG locale, e non sulla validità della firma o sull’autenticità del file.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perché_verificare_la_firma">Perché verificare la firma ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La verifica delle firme GPG è un atto fondamentale di sicurezza digitale. Permette di:</p> </div> <div class="ulist"> <ul> <li> <p>Garantire<strong>l’autenticità</strong>del software scaricato</p> </li> <li> <p>Impedire l’installazione di un file compromesso da un attore malevolo</p> </li> <li> <p>Partecipare alla<strong>sovranità digitale</strong>individuale</p> </li> <li> <p>Favorire una cultura digitale responsabile ed etica</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="usecase-tor-verification.svg" alt="usecase tor verification" width="392" height="266"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_estrazione_e_avvio_di_tor_browser">Estrazione e avvio di Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Estrai l’archivio scaricato :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">tar -xvf tor-browser-linux-x86_64-14.5.7.tar.xz cd tor-browser</code></pre> </div> </div> <div class="paragraph"> <p>Avvia quindi il browser :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>Al primo avvio, si aprirà una finestra di configurazione per stabilire la connessione alla rete Tor.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integrazione_al_desktop_ubuntu">Integrazione al desktop Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per aggiungere <strong>Tor Browser</strong> nel menu delle applicazioni:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop --register-app</code></pre> </div> </div> <div class="paragraph"> <p>Puoi quindi :</p> </div> <div class="ulist"> <ul> <li> <p>Avvia <strong>Tor Browser</strong> dal menu delle applicazioni</p> </li> <li> <p>Aggiungerlo ai preferiti del dock</p> </li> <li> <p>Creare una scorciatoia da tastiera se desiderato</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="activity-tor-installation.svg" alt="activity tor installation" width="457" height="470"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_esplora_risorse_educative_con_tor">Esplora risorse educative con Tor</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor non è solo uno strumento di anonimato. Costituisce un portale di accesso a risorse educative e di ricerca, in particolare nei settori di:</p> </div> <div class="ulist"> <ul> <li> <p><strong>OSINT (Intelligence a sorgente aperta)</strong></p> </li> <li> <p><a href="https://inteltechniques.com">https://inteltechniques.com</a></p> </li> <li> <p><a href="https://osintframework.com">https://osintframework.com</a></p> </li> <li> <p><strong>Condivisione educativa e open source</strong></p> </li> <li> <p><a href="https://archive.org">https://archive.org</a>(accesso via Tor per maggiore riservatezza)</p> </li> <li> <p><a href="https://github.com/">https://github.com/</a>(consultabile via Tor)</p> </li> <li> <p><a href="https://librarygenesis.pro">https://librarygenesis.pro</a>(accesso alla letteratura scientifica libera)</p> </li> <li> <p><strong>Trasmissione di conoscenza e comprensione dell’uomo nella società digitale</strong></p> </li> <li> <p>Risorse sulla cultura digitale, la libertà di espressione e l’accesso alla conoscenza</p> </li> <li> <p>Documentazione libera sulla cybersicurezza e l’etica delle tecnologie</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_aggiornamento_di_tor_browser">Aggiornamento di Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per garantire una sicurezza ottimale, è fondamentale tenere <strong>Tor Browser</strong> aggiornato. Il browser incorpora un meccanismo di aggiornamento automatico che può essere attivato dalla riga di comando.</p> </div> <div class="paragraph"> <p>Dalla directory di installazione di Tor Browser, basta rilanciare lo script di avvio:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cd ~/workspace/tipiak/tor/tor-browser ./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>All’avvio, <strong>Tor Browser</strong> verificherà automaticamente se esiste una nuova versione. Se è così, lo scaricherà e lo installerà per te.</p> </div> <div class="paragraph"> <p>Questo semplice metodo garantisce che tu disponga sempre degli ultimi aggiornamenti di sicurezza e delle migliorie più recenti, il che è essenziale per una navigazione sicura.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Controllare i propri download è un riflesso essenziale per chiunque voglia evolvere in un ambiente digitale sicuro. Installare Tor in modo verificato, è<strong>proteggere la propria integrità digitale</strong>, <strong>preservare la fiducia nel software libero</strong>, et <strong>rafforzare la sua autonomia informativa</strong>.</p> </div> <div class="paragraph"> <p><strong>La sicurezza digitale è un atto di coscienza, non di paranoia.</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="summary-diagram.svg" alt="summary diagram" width="471" height="203"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_riferimenti">Riferimenti</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Sito ufficiale del Tor Project:https://www.torproject.org/download/[<a href="https://www.torproject.org/download/" class="bare">https://www.torproject.org/download/</a>]</p> </li> <li> <p>Documentazione di verifica delle firme :https://support.torproject.org/tbb/how-to-verify-signature/[<a href="https://support.torproject.org/tbb/how-to-verify-signature/" class="bare">https://support.torproject.org/tbb/how-to-verify-signature/</a>]</p> </li> <li> <p>Documentazione Ubuntu:https://ubuntu.com[<a href="https://ubuntu.com" class="bare">https://ubuntu.com</a>]</p> </li> <li> <p>Archivio educativo:https://archive.org/details/opensource[<a href="https://archive.org/details/opensource" class="bare">https://archive.org/details/opensource</a>]</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Questo articolo fa parte della serie <strong>Sicurezza e Coscienza Digitale</strong>, volti a promuovere pratiche responsabili e pedagogiche intorno agli strumenti liberi.</p> </div> </td> </tr> </table> </div> </div> </div> https://cheroliv.com/blog/2025/0093_gradle_plugin_toml_composite_build_post.html Sat, 27 Sep 2025 00:00:00 +0000 blog/2025/0093_gradle_plugin_toml_composite_build_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_1_il_catalogo_delle_versioni_libs_versions_toml_un_promemoria">1. Il Catalogo delle Versioni (<code>libs.versions.toml</code>) : Un promemoria</a></li> <li><a href="#_2_il_problema_una_build_composta_e_due_mondi_separati">2. Il problema: una build composta e due mondi separati</a></li> <li><a href="#_3_la_soluzione_condividere_la_risoluzione_delle_dipendenze">3. La Soluzione : Condividere la Risoluzione delle Dipendenze</a></li> <li><a href="#_4_conclusione_la_potenza_dei_builds_composti_ben_gestiti">4. Conclusione : La Potenza dei Builds Composti Ben Gestiti</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Pubblico di riferimento : sviluppatori Gradle che devono gestire le dipendenze nei progetti multi-build</div> <p>Nella nostra ricerca per creare il plugin`site-baker`, abbiamo cercato di mantenere una base di codice pulita e centralizzata. Una delle migliori pratiche nell’ecosistema Gradle moderno è l’utilizzo del<strong>catalogo di versioni</strong>(<code>libs.versions.toml</code>) per gestire le dipendenze. Ma cosa succede quando il tuo progetto diventa più complesso, come un<strong>costruire composito</strong>dove una build indipendente (il nostro plug‑in) deve essere inclusa in un’altra ?</p> </div> <div class="paragraph"> <p>È lì che la nostra avventura ha preso una svolta inaspettata. Volevamo che il nostro plugin`site-baker`, che è lui stesso un progetto Gradle, utilizza lo stesso catalogo di versioni del nostro progetto principale. Questo articolo, il quinto della nostra serie, racconta come abbiamo risolto questa sfida.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_il_catalogo_delle_versioni_libs_versions_toml_un_promemoria">1. Il Catalogo delle Versioni (<code>libs.versions.toml</code>) : Un promemoria</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il file`gradle/libs.versions.toml`è una funzionalità di Gradle che permette di centralizzare le versioni e le coordinate delle dipendenze del tuo progetto. È generalmente strutturato in quattro sezioni:</p> </div> <div class="ulist"> <ul> <li> <p><code>[versions]</code>: Definisce degli alias per i numeri di versione (es:`kotlin = "1.9.20"`).</p> </li> <li> <p><code>[libraries]`Definisce alias per le dipendenze complete, utilizzando le versioni definite sopra (ex:`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }</code>).</p> </li> <li> <p><code>[bundles]</code>: Raggruppa più librerie sotto un unico alias (es:`jackson = ["jackson-core", "jackson-databind"]`).</p> </li> <li> <p><code>[plugins]</code>: Definisce alias per i plugin Gradle.</p> </li> </ul> </div> <div class="paragraph"> <p>Una volta definito, Gradle genera automaticamente dei metodi di accesso tipizzati, il che rende il tuo`build.gradle.kts`molto più leggibile :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Au lieu de : implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20") implementation(libs.kotlin.stdlib) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="toml-flow.svg" alt="toml flow" width="466" height="252"> </div> <div class="title">Figure 1. Flusso di dati del catalogo delle versioni</div> </div> </div> </div> <div class="sect1"> <h2 id="_2_il_problema_una_build_composta_e_due_mondi_separati">2. Il problema: una build composta e due mondi separati</h2> <div class="sectionbody"> <div class="paragraph"> <p>La nostra struttura di progetto è un<strong>costruire composito</strong>. Il progetto principale (<code>thymeleaf.cheroliv.com</code>) include il progetto del progetto (<code>site-baker</code>) tramite il comando`includeBuild("site-baker")<code>nel file`settings.gradle.kts</code>.</p> </div> <div class="imageblock"> <div class="content"> <img src="composite-build.svg" alt="composite build" width="604" height="246"> </div> <div class="title">Figure 2. Struttura della build composita</div> </div> <div class="paragraph"> <p>Il problema è che, di default, un build incluso è un<strong>mondo separato</strong>. Ha la sua configurazione personale, il suo ciclo di vita personale, e non vede il file`libs.versions.toml`del build principale. Nostro`plugin/build.gradle.kts`stava tentando di usare`libs.plugins.kotlin.jvm`, ma l’oggetto`libs`non è stato generato dal file TOML corretto, provocando errori di build.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_la_soluzione_condividere_la_risoluzione_delle_dipendenze">3. La Soluzione : Condividere la Risoluzione delle Dipendenze</h2> <div class="sectionbody"> <div class="paragraph"> <p>Dopo diverse ricerche, la soluzione si è rivelata essere una funzionalità di Gradle progettata appositamente per questo caso :`dependencyResolutionManagement`.</p> </div> <div class="paragraph"> <p>Nel file`settings.gradle.kts` du <strong>costruire inclusivo</strong>(<code>site-baker/settings.gradle.kts</code>), possiamo dire a Gradle dove trovare il catalogo delle versioni da utilizzare.</p> </div> <div class="paragraph"> <p>Ecco la configurazione che abbiamo aggiunto a`site-baker/settings.gradle.kts`[Nothing to output]</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// site-baker/settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { gradlePluginPortal() mavenCentral() } versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } } } rootProject.name = "site-baker" include("plugin")</code></pre> </div> </div> <div class="paragraph"> <p>Analizziamo la parte cruciale :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">versionCatalogs { create("libs") { // Crée un catalogue nommé 'libs' from(files("../gradle/libs.versions.toml")) // En utilisant ce fichier } }</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>create("libs")</code>: Dichiaro un catalogo di versioni che sarà accessibile tramite l’alias`libs`.</p> </li> <li> <p><code>from(files("../gradle/libs.versions.toml"))`È la magia. Indichiamo a Gradle che l’origine di questo catalogo è il file TOML situato nella directory`gradle</code> du <strong>progetto padre</strong>(<code>../</code>).</p> </li> </ul> </div> <div class="paragraph"> <p>Con questa configurazione, il build`site-baker`sa adesso che deve utilizzare il catalogo delle versioni del progetto principale. L’oggetto`libs`viene generato correttamente, e le dipendenze sono risolte come previsto.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_conclusione_la_potenza_dei_builds_composti_ben_gestiti">4. Conclusione : La Potenza dei Builds Composti Ben Gestiti</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa esperienza è stata ricca di insegnamenti. Il catalogo di versioni è uno strumento fantastico per la manutenibilità, ma il suo comportamento in scenari di build composite non è sempre intuitivo.</p> </div> <div class="paragraph"> <p>La chiave è ricordare che una build inclusa rimane una build indipendente. Per condividere configurazioni come il catalogo di versioni, è necessario utilizzare i meccanismi espliciti forniti da Gradle, come il bloc`dependencyResolutionManagement`in`settings.gradle.kts`.</p> </div> <div class="paragraph"> <p>Risolvendo questo problema, non solo abbiamo reso il nostro build più pulito, ma abbiamo anche rafforzato la coerenza del nostro progetto assicurandoci che il plugin e il progetto principale condividano un’unica fonte di verità per le loro dipendenze.</p> </div> <div class="paragraph"> <p>Nel prossimo articolo, continueremo ad arricchire il nostro plugin aggiungendovi attività più complesse, ora che la nostra gestione delle dipendenze è solida e centralizzata.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0092_gradle_configuration_cache_post.html Fri, 26 Sep 2025 00:00:00 +0000 blog/2025/0092_gradle_configuration_cache_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_il_sintomo_build_fantasma">Il Sintomo : Build Fantasma</a></li> <li><a href="#_lindagine_cosè_il_cache_di_configurazione">L’indagine: cos’è il Cache di configurazione?</a></li> <li><a href="#_la_causa_del_problema_un_plugin_non_conforme">La causa del problema: un plugin non conforme</a></li> <li><a href="#_la_soluzione_temporanea_disattivare_la_cache">La soluzione temporanea : Disattivare la cache</a></li> <li><a href="#_la_vera_soluzione_rendere_il_plugin_compatibile">La Vera Soluzione: Rendere il Plugin Compatibile</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Pubblico di riferimento : Sviluppatori Gradle che hanno già riscontrato comportamenti di build "magici" o inattesi.</div> <p>Nella nostra avventura di creazione del plugin`site-baker`, abbiamo seguito un approccio TDD rigoroso. Ogni funzionalità era testata, validata, e avanzavamo con fiducia. E poi, un giorno, l’imprevisto è arrivato. Le build hanno iniziato a comportarsi in modo erratico. Le modifiche nella logica del plugin o nei file di configurazione sembravano essere ignorate, e i nostri test funzionali, un tempo affidabili, fallivano senza motivo apparente.</p> </div> <div class="paragraph"> <p>Questo tipo di problema può essere incredibilmente frustrante. Mette in dubbio l’affidabilità dello strumento e la validità del nostro codice. Dopo una sessione di debug intenso, il colpevole è stato identificato: il<strong>cache di configurazione di Gradle</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_sintomo_build_fantasma">Il Sintomo : Build Fantasma</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il problema si manifestava in diversi modi:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Stavo modificando una stringa di caratteri in un’attività`println`, ma la vecchia stringa continuava a essere visualizzata durante l’esecuzione.</p> </li> <li> <p>Stavo cambiando un valore nel mio file`managed-jbake-context.yml`, ma il plugin agiva come se il file non fosse stato modificato.</p> </li> <li> <p>I test funzionali, che creano progetti di test al volo, fallivano perché il plugin sembrava non rilevare i file di configurazione appena creati.</p> </li> </ol> </div> <div class="paragraph"> <p>Tutto procedeva come se Gradle stesse eseguendo una "versione fantasma" del nostro build, ignorando i nostri cambiamenti più recenti.</p> </div> </div> </div> <div class="sect1"> <h2 id="_lindagine_cosè_il_cache_di_configurazione">L’indagine: cos’è il Cache di configurazione?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La cache di configurazione è una funzionalità relativamente moderna ed estremamente potente di Gradle, attivata per impostazione predefinita nelle versioni più recenti. Il suo scopo è rendere le build più veloci.</p> </div> <div class="olist arabic"> <div class="title">Il principio è semplice :</div> <ol class="arabic"> <li> <p>Durante la prima esecuzione, Gradle esegue la fase di<strong>configurazione</strong>(lettura delle`build.gradle.kts`, creazione delle attività, risoluzione delle dipendenze) e costruisce un grafo di attività</p> </li> <li> <p>Alla fine di questa fase, Gradle<strong>Serializza questo grafo di attività</strong>e lo mette in cache.</p> </li> <li> <p>Durante le esecuzioni successive, se niente è cambiato (script di build,<code>gradle.properties</code>, etc.), Gradle<strong>salta completamente la fase di configurazione</strong>e riutilizza il grafo delle attività memorizzato nella cache.</p> </li> </ol> </div> <div class="paragraph"> <p>Il risparmio di tempo è spettacolare sui grandi progetti. Tuttavia, questa performance ha un prezzo: impone regole severe sul modo in cui i plugin devono essere scritti.</p> </div> <div class="paragraph"> <p>Il ciclo di vita della cache di configurazione</p> </div> <div class="imageblock"> <div class="content"> <img src="config-cache-lifecycle.svg" alt="config cache lifecycle" width="661" height="709"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_causa_del_problema_un_plugin_non_conforme">La causa del problema: un plugin non conforme</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il nostro plugin`site-baker`violava, senza saperlo, varie regole della cache di configurazione. Perché un grafo di attività sia serializzabile, le attività non devono contenere riferimenti a oggetti complessi come l’oggetto`Project`o leggere i file in modo arbitrario durante la fase di esecuzione.</p> </div> <div class="paragraph"> <p>Il nostro errore principale era leggere il contenuto del file YAML direttamente all’interno della logica di esecuzione dell’attività, utilizzando un riferimento al percorso memorizzato nella nostra estensione. Questo approccio è incompatibile con la cache perché Gradle non può sapere se il contenuto del file è cambiato se questa lettura non viene modellata come una<strong>voce di attività</strong>(Input del compito).</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_temporanea_disattivare_la_cache">La soluzione temporanea : Disattivare la cache</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per sbloccarci e ritrovare un comportamento di build prevedibile, la soluzione più rapida è stata disattivare il cache di configurazione. Basta aggiungere la seguente riga nel file`gradle.properties`del progetto che utilizza il plugin (o nel nostro caso, il progetto di test`site-baker`).</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># site-baker/gradle.properties org.gradle.configuration-cache=false</code></pre> </div> </div> <div class="paragraph"> <p>Istantaneamente, le build hanno ritrovato il loro comportamento normale. Ogni esecuzione riavviava la fase di configurazione e le nostre modifiche venivano prese in considerazione.</p> </div> <div class="paragraph"> <p>Tuttavia, è una soluzione di ripiego, non una soluzione durevole. Sacrifica le prestazioni e non risolve il problema di fondo del nostro plugin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_vera_soluzione_rendere_il_plugin_compatibile">La Vera Soluzione: Rendere il Plugin Compatibile</h2> <div class="sectionbody"> <div class="paragraph"> <p>Perché un plugin sia un buon cittadino dell’ecosistema Gradle moderno, deve essere compatibile con la cache di configurazione. Ciò implica di ripensare il modo in cui i dati fluiscono verso le nostre attività.</p> </div> <div class="paragraph"> <p>La chiave è di usare le<strong>Provider APIs</strong>di Gradle. Al posto di passare valori diretti (come un`String` ou un <code>File</code>) alle nostre attività, dobbiamo passare dei`Property<T>`o dei`Provider<T>`.</p> </div> <div class="olist arabic"> <div class="title">Ecco il piano di refactoring:</div> <ol class="arabic"> <li> <p><strong>Dichiarare le voci delle attività :</strong>L’operazione che analizza il file YAML deve dichiarare questo file come un input. Per questo si utilizza l’annotazione`@InputFile`. (note: there is a space after the period)</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] [Attesa del testo francese da tradurre] @get:InputFile abstract val configFile: RegularFileProperty ----</p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0091_jackson_yaml_tdd_post.html Thu, 25 Sep 2025 00:00:00 +0000 blog/2025/0091_jackson_yaml_tdd_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_1_il_contesto_il_nostro_plugin_site_baker">1. Il Contesto : Il nostro Plugin `site-baker</a></li> <li><a href="#_2_modellazione_della_configurazione_in_kotlin">2. Modellazione della configurazione in Kotlin</a></li> <li><a href="#_3_integrazione_di_jackson_nel_build_gradle_kts">3. Integrazione di Jackson nel `build.gradle.kts</a></li> <li><a href="#_4_lapproccio_tdd_testare_il_parsing_yaml">4. L’approccio TDD: Testare il parsing YAML</a> <ul class="sectlevel2"> <li><a href="#_4_1_test_unitario_mappare_il_yaml_in_oggetto_kotlin">4.1. Test Unitario : Mappare il YAML in Oggetto Kotlin</a></li> <li><a href="#_4_2_test_funzionale_verificare_la_lettura_del_file_di_configurazione">4.2. Test funzionale: Verificare la lettura del file di configurazione</a></li> </ul> </li> <li><a href="#_5_visualizzazione_del_flusso_di_parsing">5. Visualizzazione del Flusso di Parsing</a></li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Pubblico di riferimento : Sviluppatori Gradle intermedi che desiderano gestire configurazioni complesse.</div> <p>Nello sviluppo di plugin Gradle, la gestione di configurazioni complesse è un compito comune. Piuttosto che sovraccaricare il DSL con centinaia di proprietà, spesso è più pulito e manutenibile definire la configurazione in un file esterno, come YAML. Questo articolo ti guida attraverso l’integrazione della potente biblioteca Jackson per analizzare file YAML in oggetti Kotlin, adottando un approccio TDD rigoroso per garantire la robustezza del nostro plugin.<code>site-baker</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_il_contesto_il_nostro_plugin_site_baker">1. Il Contesto : Il nostro Plugin `site-baker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il nostro plugin`site-baker`è progettato per automatizzare la generazione e il deployment di un sito statico. Ha bisogno di leggere un file di configurazione YAML (<code>managed-jbake-context.yml</code>) per ottenere informazioni quali i percorsi delle sorgenti, le destinazioni di distribuzione e gli identificatori Git</p> </div> <div class="paragraph"> <p>La configurazione YAML che vogliamo analizzare è simile a questa:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" cname: "cheroliv.com" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/pages-content.github.io.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com" # ... autres configurations (pushMaquette, supabase, etc.)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_modellazione_della_configurazione_in_kotlin">2. Modellazione della configurazione in Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <p>Prima di eseguire il parsing, dobbiamo definire la struttura dei nostri dati in Kotlin. Jackson utilizzerà queste classi per mappare automaticamente il contenuto YAML.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/main/kotlin/com/cheroliv/site/baker/data/SiteConfiguration.kt package com.cheroliv.site.baker.data import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.dataformat.yaml.YAMLFactory import com.fasterxml.jackson.module.kotlin.readValue import com.fasterxml.jackson.module.kotlin.registerKotlinModule fun parseSiteConfiguration(yaml: String): SiteConfiguration { val mapper = ObjectMapper(YAMLFactory()).registerKotlinModule() return mapper.readValue(yaml) } data class GitPushConfiguration( val from: String = "", val to: String = "", val repo: RepositoryConfiguration = RepositoryConfiguration(), val branch: String = "", val message: String = "", ) data class RepositoryConfiguration( val name: String = "", val repository: String = "", val credentials: RepositoryCredentials = RepositoryCredentials(), ) { companion object { const val ORIGIN = "origin" const val CNAME = "CNAME" const val REMOTE = "remote" } } data class RepositoryCredentials(val username: String = "", val password: String = "") data class SiteConfiguration( val bake: BakeConfiguration = BakeConfiguration(), val pushPage: GitPushConfiguration = GitPushConfiguration(), val pushMaquette: GitPushConfiguration = GitPushConfiguration(), val pushSource: GitPushConfiguration? = null, val pushTemplate: GitPushConfiguration? = null, val supabase: SupabaseContactFormConfig? = null ) data class BakeConfiguration( val srcPath: String = "", val destDirPath: String = "", val cname: String? = null, ) // ... (autres data classes pour Supabase, si nécessaire)</code></pre> </div> </div> <div class="paragraph"> <p>La funzione`parseSiteConfiguration`è il nostro punto di ingresso per la deserializzazione. Utilizza`ObjectMapper`di Jackson, configurato con`YAMLFactory`per il formato YAML e`registerKotlinModule()`per il supporto delle specificità di Kotlin (come i valori predefiniti delle proprietà).</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_integrazione_di_jackson_nel_build_gradle_kts">3. Integrazione di Jackson nel `build.gradle.kts</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per utilizzare Jackson, dobbiamo aggiungere le dipendenze necessarie nel`build.gradle.kts`del nostro modulo`plugin`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/build.gradle.kts dependencies { // Jackson for YAML parsing implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3") implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3") // ... autres dépendances }</code></pre> </div> </div> <div class="paragraph"> <p>Noi utilizziamo`jackson-module-kotlin`per il supporto di Kotlin e`jackson-dataformat-yaml`per la gestione del formato YAML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_lapproccio_tdd_testare_il_parsing_yaml">4. L’approccio TDD: Testare il parsing YAML</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ora, applichiamo il TDD per validare la nostra logica di parsing.</p> </div> <div class="sect2"> <h3 id="_4_1_test_unitario_mappare_il_yaml_in_oggetto_kotlin">4.1. Test Unitario : Mappare il YAML in Oggetto Kotlin</h3> <div class="paragraph"> <p>Iniziamo con un test unitario in`SiteBakerPluginTest.kt`per verificare che la funzione`parseSiteConfiguration`può correttamente trasformare una stringa YAML in un oggetto`SiteConfiguration`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/test/kotlin/com/cheroliv/site/baker/SiteBakerPluginTest.kt @Test fun `can map configuration text to SiteConfiguration object`() { val yamlString = "../../managed-jbake-context.yml" .run(::File) .readText() .trimIndent() val config: SiteConfiguration = parseSiteConfiguration(yamlString) assertEquals("cheroliv.com", config.bake.cname) assertEquals("main", config.pushPage.branch) assertEquals("https://github.com/pages-content/pages-content.github.io.git", config.pushPage.repo.repository) }</code></pre> </div> </div> <div class="paragraph"> <p>Questo test legge il contenuto del file`managed-jbake-context.yml`(che deve esistere affinché il test sia valido) e effettua asserzioni sull’oggetto`SiteConfiguration`risultante. Verifica che i valori chiave del YAML siano correttamente mappati.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_test_funzionale_verificare_la_lettura_del_file_di_configurazione">4.2. Test funzionale: Verificare la lettura del file di configurazione</h3> <div class="paragraph"> <p>Per assicurarsi che il plugin possa leggere il file di configurazione tramite il suo DSL e che il parsing funzioni in un ambiente Gradle reale, aggiungiamo un test funzionale in`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="paragraph"> <p>Questo test è cruciale perché simula l’esecuzione del plugin in un progetto reale. Deve essere<strong>ermetico</strong>, cioè che deve creare lui stesso il file`managed-jbake-context.yml`con un contenuto controllato, per garantire la riproducibilità e l’isolamento del test.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt @Test fun `config file contains good data`(){ val configContent = configFile.readText(UTF_8) // Vérifications comme dans vos commentaires assertTrue(configContent.contains("bake")) assertTrue(configContent.contains("pushPage")) assertTrue(configContent.contains("repository")) }</code></pre> </div> </div> <div class="paragraph"> <p>Questo test funzionale verifica che il file di configurazione copiato nella directory temporanea del test contenga i dati attesi. Sebbene questo test non analizzi direttamente il YAML in un oggetto Kotlin, convalida la presenza del file e del suo contenuto, che è una fase preliminare essenziale per l’analisi da parte del plugin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_visualizzazione_del_flusso_di_parsing">5. Visualizzazione del Flusso di Parsing</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il diagramma seguente illustra il flusso di dati e le interazioni durante il parsing della configurazione YAML :</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e28323745a3140b4f6e06f19c9d4cf6e.png" alt="Diagram" width="1513" height="472"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Seguendo un approccio TDD, abbiamo integrato con successo la libreria Jackson per parseare i file di configurazione YAML in oggetti Kotlin all’interno del nostro plugin Gradle. Questo metodo ci ha permesso di:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Modellare chiaramente</strong>la nostra configurazione con le data class Kotlin.</p> </li> <li> <p><strong>Convalidare la logica di parsing</strong>con test unitari mirati.</p> </li> <li> <p><strong>Garantire l’integrazione</strong>in un ambiente Gradle reale grazie a test funzionali ermetici.</p> </li> </ul> </div> <div class="paragraph"> <p>Questa solida base ci offre una grande fiducia per estendere il nostro plugin con funzionalità che si basano su questa configurazione, garantendo allo stesso tempo la manutenibilità e la robustezza del codice. Il parsing YAML è ora una funzionalità affidabile e testata del nostro plugin`site-baker`.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0090_TDD_gradle_plugin_post.html Wed, 24 Sep 2025 00:00:00 +0000 blog/2025/0090_TDD_gradle_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_linizializzazione_del_progetto">L’inizializzazione del progetto</a></li> <li><a href="#_2_il_nostro_primo_ciclo_tdd_registrare_un_compito">2. Il nostro primo ciclo TDD: Registrare un compito</a> <ul class="sectlevel2"> <li><a href="#_2_1_il_test_prima_il_test_che_fallisce">2.1. Il Test Prima (Il Test che Fallisce)</a></li> <li><a href="#_2_2_il_codice_poi_far_passare_il_test">2.2. Il Codice Poi (Far Passare il Test)</a></li> </ul> </li> <li><a href="#_3_secondo_ciclo_tdd_aggiungere_unestensione_dsl">3. Secondo Ciclo TDD: Aggiungere un’estensione DSL</a> <ul class="sectlevel2"> <li><a href="#_3_1_il_test_iniziale">3.1. Il test iniziale</a></li> <li><a href="#_3_2_il_codice_successivo">3.2. Il codice successivo</a></li> </ul> </li> <li><a href="#_4_il_test_funzionale_validare_lintegrazione">4. Il Test Funzionale : Validare l’integrazione</a> <ul class="sectlevel2"> <li><a href="#_4_1_il_test_di_integrazione_creare_un_ambiente_controllato">4.1. Il Test di Integrazione: Creare un Ambiente Controllato</a></li> <li><a href="#_4_2_finalizzare_la_logica">4.2. Finalizzare la Logica</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>In questo articolo, esploreremo come impostare una base di sviluppo solida per un plugin Gradle utilizzando un approccio di sviluppo guidato dai test (TDD - Test-Driven Development). Questo metodo garantisce che il nostro codice sia robusto, mantenibile e risponda precisamente ai requisiti fin dall’inizio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_linizializzazione_del_progetto">L’inizializzazione del progetto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle facilita notevolmente la creazione di un nuovo plugin grazie al comando`gradle init`. Scegliendo di creare un "Gradle Plugin" con Kotlin, otteniamo una struttura di progetto pronta all’uso, includendo due tipi di test essenziali :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Test Unitari :</strong>Situati in`src/test`, consentono di validare componenti isolati del nostro plugin, come la logica interna di un’attività o la configurazione di un’estensione. Sono rapidi e non richiedono l’esecuzione completa di Gradle.</p> </li> <li> <p><strong>Test funzionali:</strong>Situati in`src/functionalTest`, usano`GradleRunner`per eseguire una build Gradle completa in un progetto di test temporaneo. Questo ci permette di verificare il comportamento reale del plugin in un ambiente controllato.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_2_il_nostro_primo_ciclo_tdd_registrare_un_compito">2. Il nostro primo ciclo TDD: Registrare un compito</h2> <div class="sectionbody"> <div class="paragraph"> <p>La nostra prima richiesta è semplice: il plugin deve registrare un’attività chiamata`printSiteConfig`.</p> </div> <div class="sect2"> <h3 id="_2_1_il_test_prima_il_test_che_fallisce">2.1. Il Test Prima (Il Test che Fallisce)</h3> <div class="paragraph"> <p>Conformemente al TDD, scriviamo innanzitutto un test che verifica l’esistenza di questa attività. Dentro`SiteBakerPluginTest.kt`(il nostro file di test unitario), aggiungiamo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers task`() { // Créer un projet de test en mémoire val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Vérifier que la tâche a bien été enregistrée assertNotNull(project.tasks.findByName("printSiteConfig")) }</code></pre> </div> </div> <div class="paragraph"> <p>Questo test fallisce perché non abbiamo ancora scritto alcun codice nel nostro plugin.</p> </div> </div> <div class="sect2"> <h3 id="_2_2_il_codice_poi_far_passare_il_test">2.2. Il Codice Poi (Far Passare il Test)</h3> <div class="paragraph"> <p>Ora scriviamo il minimo di codice necessario nel`SiteBakerPlugin.kt`affinché il test passi :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer une tâche simple project.tasks.register("printSiteConfig") { task -> // ... la logique de la tâche viendra plus tard } } }</code></pre> </div> </div> <div class="paragraph"> <p>Rilanciamo i test, e passano. La nostra prima funzionalità è validata.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3_secondo_ciclo_tdd_aggiungere_unestensione_dsl">3. Secondo Ciclo TDD: Aggiungere un’estensione DSL</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il requisito successivo è quello di permettere agli utenti di configurare il nostro plugin tramite un blocco DSL nel loro`build.gradle.kts`. Vogliamo un blocco`site { …​ }`dove si può specificare un percorso di configurazione.</p> </div> <div class="sect2"> <h3 id="_3_1_il_test_iniziale">3.1. Il test iniziale</h3> <div class="paragraph"> <p>Aggiungiamo un test per verificare che l’estensione`site`è ben registrata e si può assegnarle un valore</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers extension`() { val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Récupérer l'extension et lui affecter une valeur project.extensions .findByType(SiteExtension::class.java)!! .configPath .set("config.yml") // Vérifier que la valeur a bien été prise en compte assertEquals( "config.yml", project.extensions.findByType(SiteExtension::class.java)?.configPath?.get() ) }</code></pre> </div> </div> <div class="paragraph"> <p>Questo test fallisce perché né la classe`SiteExtension`né la registrazione dell’estensione esiste</p> </div> </div> <div class="sect2"> <h3 id="_3_2_il_codice_successivo">3.2. Il codice successivo</h3> <div class="paragraph"> <p>Stiamo creando la classe`SiteBakerExtension.kt`e aggiorniamo`SiteBakerPlugin.kt` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// SiteBakerExtension.kt open class SiteExtension @Inject constructor(objects: ObjectFactory) { val configPath: Property<String> = objects.property(String::class.java) } // SiteBakerPlugin.kt class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer l'extension val extension = project.extensions.create("site", SiteExtension::class.java) project.tasks.register("printSiteConfig") { task -> task.doLast { // On utilisera l'extension plus tard } } } }</code></pre> </div> </div> <div class="paragraph"> <p>I test passano di nuovo.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_il_test_funzionale_validare_lintegrazione">4. Il Test Funzionale : Validare l’integrazione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ora che le unità sono testate, dobbiamo assicurarci che tutto funzioni insieme in una vera build. Questo è il ruolo del test funzionale in`SiteBakerPluginFunctionalTest.kt`.</p> </div> <div class="sect2"> <h3 id="_4_1_il_test_di_integrazione_creare_un_ambiente_controllato">4.1. Il Test di Integrazione: Creare un Ambiente Controllato</h3> <div class="paragraph"> <p>Questo test simulerà un vero progetto che utilizza il nostro plugin. Per essere affidabile, deve essere<strong>ermetico</strong>, ovvero non deve dipendere da file esistenti sul sistema. Deve creare da sé tutte le condizioni necessarie alla sua esecuzione.</p> </div> <div class="paragraph"> <p>Il test quindi :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Creare un`build.gradle.kts`di test che utilizza il nostro plugin e il suo DSL.</p> </li> <li> <p><strong>Creare il file di configurazione</strong>(<code>managed-jbake-context.yml</code>) che il plugin dovrebbe leggere. È un passaggio cruciale per la robustezza del test.</p> </li> <li> <p>Eseguire il compito`printSiteConfig`via`GradleRunner`.</p> </li> <li> <p>Verificare che l’output della build sia corretto.</p> </li> </ol> </div> <div class="paragraph"> <p>Copiando o creando questo file di configurazione ad ogni esecuzione, ci assicuriamo che il test sia<strong>riproducibile</strong>e non dipende da uno stato esterno. Questo rende i nostri test sicuri contro le regressioni che potrebbero essere legate alla lettura del file.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `can run task with DSL`() { // 1. Créer un build.gradle.kts de test buildFile.writeText(""" plugins { id("com.cheroliv.site-baker") } site { configPath = "managed-jbake-context.yml" } """.trimIndent()) // 2. Créer le fichier de configuration pour un test contrôlé val configFile = File(projectDir, "managed-jbake-context.yml") configFile.writeText("site: { title: 'Mon Site de Test' }") // Contenu YAML simple // 3. Exécuter la build val runner = GradleRunner.create() runner.withPluginClasspath() runner.withArguments("printSiteConfig") runner.withProjectDir(projectDir) // Spécifier le répertoire du projet de test val result = runner.build() // 4. Vérifier la sortie assertTrue(result.output.contains("Site config path: managed-jbake-context.yml")) }</code></pre> </div> </div> <div class="paragraph"> <p>Questo test fallirà finché il compito`printSiteConfig`non utilizzerà realmente il valore dell’estensione.</p> </div> </div> <div class="sect2"> <h3 id="_4_2_finalizzare_la_logica">4.2. Finalizzare la Logica</h3> <div class="paragraph"> <p>Stiamo aggiornando l’attività in`SiteBakerPlugin.kt`affinché mostri il valore configurato:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.tasks.register("printSiteConfig") { task -> task.doLast { println("Site config path: ${extension.configPath.get()}") } }</code></pre> </div> </div> <div class="paragraph"> <p>Tutti i test, unitari e funzionali, passano ora.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Seguendo un approccio TDD, abbiamo costruito un plugin in modo incrementale e sicuro. Ogni piccola funzionalità viene immediatamente validata da un test, dai test unitari rapidi ai test funzionali che convalidano l’integrazione completa.</p> </div> <div class="paragraph"> <p>Avendo cura di rendere i nostri test funzionanti<strong>ermetici</strong>— ovvero, creando in modo programmato i file di configurazione necessari — costruiamo una rete di sicurezza estremamente robusta. Questa rigorosità ci protegge efficacemente dalle regressioni e ci dà molta fiducia per aggiungere funzionalità più complesse in seguito, come il parsing del file di configurazione YAML.</p> </div> <div class="paragraph"> <p>Questa base di test solidi è il punto di forza più prezioso per la manutenzione e l’evoluzione futura del plugin.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0089_creation_projet_plugin_gradle_post.html Tue, 23 Sep 2025 00:00:00 +0000 blog/2025/0089_creation_projet_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_passo_1_avviare_lassistente_di_progetto">Passo 1 : Avviare l’assistente di progetto</a></li> <li><a href="#_passo_2_comprendere_la_struttura_generata">Passo 2: Comprendere la struttura generata</a> <ul class="sectlevel2"> <li><a href="#_file_e_cartelle_chiave">File e cartelle chiave</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Pubblico di riferimento : Sviluppatore principiante-intermedio con Gradle.</div> <p>Avviare un nuovo progetto di plugin Gradle può sembrare intimidatorio. Per fortuna, Gradle fornisce un potente assistente interattivo, il task`init`, che genera una struttura di progetto completa, pulita e pronta all’uso. Questa guida ti mostrerà come utilizzare questo strumento per creare una base di plugin sana, e spiegirà la struttura e ti mostrerà come avviare le prime attività di build.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_1_avviare_lassistente_di_progetto">Passo 1 : Avviare l’assistente di progetto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il comando`gradle init`è il punto di partenza. Avvia una procedura guidata da riga di comando che ti pone una serie di domande per configurare il progetto.</p> </div> <div class="paragraph"> <p>Apri il tuo terminale in una cartella vuota e avvia:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle init</code></pre> </div> </div> <div class="paragraph"> <p>L’assistente ti guiderà. Ecco le scelte da fare per un plugin Gradle scritto in Kotlin:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Seleziona il tipo di progetto da generare:</strong>Scegliete`Gradle plugin`.</p> </li> <li> <p><strong>Seleziona il linguaggio di implementazione :</strong>Scegli`Kotlin`.</p> </li> <li> <p><strong>Seleziona il DSL dello script di build:</strong>scegliete`Kotlin`.</p> </li> <li> <p><strong>Nome del progetto:</strong>Inserisci un nome per il tuo progetto (es:`site-baker`).</p> </li> <li> <p><strong>ID del plugin:</strong>Dai un identificatore unico al tuo plugin (es:`com.cheroliv.site-baker`)</p> </li> <li> <p><strong>Classe plugin:</strong>Specifica il nome della classe di implementazione (es:`com.cheroliv.SiteBakerPlugin`).</p> </li> </ol> </div> <div class="paragraph"> <p>Una volta terminato, Gradle genera un albero di file completo.</p> </div> <div class="imageblock"> <div class="content"> <img src="init-gradle.svg" alt="init gradle" width="193" height="406"> </div> <div class="title">Figure 1. Diagramma del processo di inizializzazione</div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_2_comprendere_la_struttura_generata">Passo 2: Comprendere la struttura generata</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’assistente crea una struttura di progetto multi-modulo, separando il progetto radice dal codice sorgente del plugin stesso.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat ├── plugin/ │ ├── build.gradle.kts │ └── src/ │ ├── main/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPlugin.kt │ ├── test/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPluginTest.kt │ └── functionalTest/ │ └── kotlin/ │ └── com/cheroliv/SiteBakerPluginFunctionalTest.kt └── settings.gradle.kts</code></pre> </div> </div> <div class="sect2"> <h3 id="_file_e_cartelle_chiave">File e cartelle chiave</h3> <div class="ulist"> <ul> <li> <p><code>settings.gradle.kts</code>: Questo file nella radice definisce i moduli inclusi nella compilazione. Qui, include il sottoprogetto`plugin`.</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] ---- rootProject.name = "site-baker include("plugin") </think></p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0088_environnement_plugin_gradle_post.html Mon, 22 Sep 2025 00:00:00 +0000 blog/2025/0088_environnement_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_1_il_jdk_il_motore_di_gradle">1. Il JDK : Il motore di Gradle</a> <ul class="sectlevel2"> <li><a href="#_quale_versione_scegliere">Quale versione scegliere?</a></li> <li><a href="#_installation_via_sdkman_consigliato">Installation via SDKMAN! (Consigliato)</a> <ul class="sectlevel3"> <li><a href="#_installa_sdkman">Installa SDKMAN!</a></li> <li><a href="#_installare_una_versione_del_jdk">Installare una versione del JDK</a></li> <li><a href="#_verificare_linstallazione">Verificare l’installazione</a></li> </ul> </li> </ul> </li> <li><a href="#_2_lide_intellij_idea">2. L’IDE : IntelliJ IDEA</a></li> <li><a href="#_3_gradle_lo_strumento_di_build">3. Gradle : Lo strumento di build</a> <ul class="sectlevel2"> <li><a href="#_installazione_via_sdkman">Installazione via SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_installa_gradle">Installa Gradle</a></li> <li><a href="#_verificare_linstallazione_2">Verificare l’installazione</a></li> </ul> </li> </ul> </li> <li><a href="#_4_jbake_il_generatore_di_sito_statico">4. JBake: Il generatore di sito statico</a> <ul class="sectlevel2"> <li><a href="#_installazione_via_sdkman_2">Installazione via SDKMAN!</a> <ul class="sectlevel3"> <li><a href="#_installare_jbake">Installare JBake</a></li> <li><a href="#_verificare_linstallazione_3">Verificare l’installazione</a></li> </ul> </li> </ul> </li> <li><a href="#_5_il_gradle_wrapper_la_buona_pratica_assoluta">5. Il Gradle Wrapper: La buona pratica assoluta</a></li> <li><a href="#_6_docker_e_portainer_per_dei_builds_riproducibili_opzionale">6. Docker e Portainer: per dei Builds riproducibili (opzionale)</a> <ul class="sectlevel2"> <li><a href="#_installazione_di_docker_engine">Installazione di Docker Engine</a> <ul class="sectlevel3"> <li><a href="#_installare_docker_tramite_lo_script_ufficiale"><strong>Installare Docker tramite lo script ufficiale :</strong></a></li> <li><a href="#_gestisci_docker_senza_sudo_consigliato">Gestisci Docker senza <code>sudo</code> (consigliato) :</a></li> </ul> </li> <li><a href="#_gestisci_docker_con_portainer_gui">Gestisci Docker con Portainer (GUI)</a> <ul class="sectlevel3"> <li><a href="#_creare_un_volume_per_i_dati_di_portainer">Creare un volume per i dati di Portainer:</a></li> <li><a href="#_avviare_il_contenitore_portainer"><strong>Avviare il contenitore Portainer :</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">_Tempo di lettura _ : _ 9 minutes.</div> <p>Pubblico di destinazione : Sviluppatori che desiderano lanciarsi nella creazione di plugin Gradle</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per sviluppare efficacemente i plugin Gradle, è indispensabile un ambiente di sviluppo ben configurato. Un buon setup ti farà risparmiare tempo, ridurrà le frustrazioni e garantirà la coerenza delle tue build.</p> </div> <div class="olist arabic"> <div class="title">Questa guida si concentra su quattro pilastri essenziali :</div> <ol class="arabic"> <li> <p>Le <strong>JDK</strong>(Java Development Kit), poiché Gradle e JBake vengono eseguiti sulla JVM.</p> </li> <li> <p>Un <strong>IDE</strong>moderna (IntelliJ IDEA) con un buon supporto per Kotlin e Gradle.</p> </li> <li> <p><strong>Gradle</strong>egli stesso, per avviare i progetti.</p> </li> <li> <p><strong>JBake</strong>, il motore del nostro sito statico.</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/gradle-env.svg" alt="gradle env" width="509" height="213"> </div> <div class="title">Figure 1. Componenti dell’ambiente di sviluppo</div> </div> </div> </div> <div class="sect1"> <h2 id="_1_il_jdk_il_motore_di_gradle">1. Il JDK : Il motore di Gradle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle è un’applicazione che si esegue sulla Java Virtual Machine (JVM). Pertanto, l’installazione di un JDK è un prerequisito assoluto.</p> </div> <div class="sect2"> <h3 id="_quale_versione_scegliere">Quale versione scegliere?</h3> <div class="paragraph"> <p>È consigliato utilizzare una versione LTS (Long-Term Support) di Java. Al momento,<strong>JDK 17</strong> ou <strong>JDK 21</strong>sono eccellenti scelte.</p> </div> </div> <div class="sect2"> <h3 id="_installation_via_sdkman_consigliato">Installation via SDKMAN! (Consigliato)</h3> <div class="paragraph"> <p>SDKMAN! è uno strumento fantastico per gestire le versioni di molti SDK, inclusi Java e Gradle.</p> </div> <div class="sect3"> <h4 id="_installa_sdkman">Installa SDKMAN!</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_installare_una_versione_del_jdk">Installare una versione del JDK</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Pour lister les versions de Java disponibles sdk list java # Pour installer Java 17 (par exemple, la distribution Temurin) sdk install java 17.0.8-tem</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_verificare_linstallazione">Verificare l’installazione</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">java -version</code></pre> </div> </div> <div class="paragraph"> <p>Dovresti vedere la versione che hai appena installato apparire.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_lide_intellij_idea">2. L’IDE : IntelliJ IDEA</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per lo sviluppo di plugins Gradle con il DSL Kotlin,<strong>IntelliJ IDEA</strong>è lo strumento di scelta. La sua integrazione con Gradle e Kotlin è incomparabile.</p> </div> <div class="ulist"> <ul> <li> <p><strong>Edizione Community :</strong>Gratuita e ampiamente sufficiente per iniziare.</p> </li> <li> <p><strong>Edizione definitiva :</strong>A pagamento, offre funzionalità avanzate per lo sviluppo web e il database.</p> </li> </ul> </div> <div class="paragraph"> <p>Scarica la versione che preferisci dal sito di JetBrains: <a href="https://www.jetbrains.com/idea/download/" class="bare">https://www.jetbrains.com/idea/download/</a></p> </div> <div class="paragraph"> <p>L’IDE rileverà automaticamente i vostri file`build.gradle.kts` et <code>settings.gradle.kts</code>, offrendoti un autocompletamento potente, la navigazione nel codice e strumenti di debug integrati.</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_gradle_lo_strumento_di_build">3. Gradle : Lo strumento di build</h2> <div class="sectionbody"> <div class="paragraph"> <p>Anche se ogni progetto utilizzerà la propria versione di Gradle tramite il Gradle Wrapper, è utile avere un’installazione globale di Gradle per attività come l’inizializzazione di nuovi progetti (<code>gradle init</code>)</p> </div> <div class="sect2"> <h3 id="_installazione_via_sdkman">Installazione via SDKMAN!</h3> <div class="paragraph"> <p>Proprio come per il JDK, SDKMAN! semplifica l’installazione di Gradle.</p> </div> <div class="sect3"> <h4 id="_installa_gradle">Installa Gradle</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install gradle</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_verificare_linstallazione_2">Verificare l’installazione</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle -v</code></pre> </div> </div> <div class="paragraph"> <p>Questo comando mostrerà le versioni di Gradle, Kotlin, Groovy e del JDK utilizzate.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_jbake_il_generatore_di_sito_statico">4. JBake: Il generatore di sito statico</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake è lo strumento che utilizzeremo per trasformare i nostri file sorgenti (come questo) in un sito web statico. Avere un’installazione locale è utile per visualizzare in anteprima le modifiche.</p> </div> <div class="sect2"> <h3 id="_installazione_via_sdkman_2">Installazione via SDKMAN!</h3> <div class="paragraph"> <p>Come per gli altri strumenti, SDKMAN! è il metodo più semplice.</p> </div> <div class="sect3"> <h4 id="_installare_jbake">Installare JBake</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install jbake</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_verificare_linstallazione_3">Verificare l’installazione</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jbake -v</code></pre> </div> </div> <div class="paragraph"> <p>Questo comando visualizzerà la versione di JBake e le informazioni dell’ambiente Java che utilizza.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_il_gradle_wrapper_la_buona_pratica_assoluta">5. Il Gradle Wrapper: La buona pratica assoluta</h2> <div class="sectionbody"> <div class="paragraph"> <p>Una volta creato il tuo progetto (che vedremo nell’articolo seguente), non dovresti più utilizzare il comando globale`gradle`. Al posto, lo utilizzerai<strong>Wrapper di Gradle</strong>(<code>./gradlew</code>), uno script incluso nel tuo progetto.</p> </div> <div class="paragraph"> <p>Perché?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Riproducibilità :</strong>Il Wrapper garantisce che ogni persona che lavora sul progetto (compreso il tuo server CI/CD) utilizzi esattamente la<strong>stessa versione di Gradle</strong>, eliminando così gli errori di build dovuti a ambienti diversi.</p> </li> <li> <p><strong>Semplicità :</strong>Non è necessario installare Gradle manualmente per contribuire a un progetto.</p> </li> </ul> </div> <div class="paragraph"> <p>Basta clonare il repository e avviare`./gradlew`.</p> </div> <div class="paragraph"> <p>Un tipico comando avrà un aspetto simile a questo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Ne pas faire : gradle build # À faire : ./gradlew build</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_6_docker_e_portainer_per_dei_builds_riproducibili_opzionale">6. Docker e Portainer: per dei Builds riproducibili (opzionale)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Anche se non strettamente necessari per scrivere un plugin, Docker e Portainer sono strumenti DevOps moderni che facilitano notevolmente la creazione di build riproducibili e la gestione del tuo ambiente.</p> </div> <div class="sect2"> <h3 id="_installazione_di_docker_engine">Installazione di Docker Engine</h3> <div class="paragraph"> <p>Docker ti permette di impacchettare la tua applicazione e le sue dipendenze in un contenitore.</p> </div> <div class="sect3"> <h4 id="_installare_docker_tramite_lo_script_ufficiale"><strong>Installare Docker tramite lo script ufficiale :</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_gestisci_docker_senza_sudo_consigliato">Gestisci Docker senza <code>sudo</code> (consigliato) :</h4> <div class="paragraph"> <p>Aggiungi il tuo utente al gruppo`docker`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo usod -aG docker $USER</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run hello-world</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_gestisci_docker_con_portainer_gui">Gestisci Docker con Portainer (GUI)</h3> <div class="paragraph"> <p>Portainer è un’interfaccia web leggera per gestire i tuoi container Docker.</p> </div> <div class="sect3"> <h4 id="_creare_un_volume_per_i_dati_di_portainer">Creare un volume per i dati di Portainer:</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker volume create portainer_data</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_avviare_il_contenitore_portainer"><strong>Avviare il contenitore Portainer :</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest</code></pre> </div> </div> <div class="paragraph"> <p>Puoi ora accedere all’interfaccia di Portainer su`https://localhost:9443`.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il tuo ambiente è ora pronto! Disponi di un JDK, dell’IDE più adatto, di Gradle e di JBake. Con l’aggiunta di Docker, Lei è anche pronto per creare build containerizzati e riproducibili. Questa base solida ti permetterà di concentrarti sull’essenziale: lo sviluppo di plugin potenti e utili.</p> </div> <div class="paragraph"> <p>Nel prossimo articolo, utilizzeremo il comando`gradle init`per generare la struttura del nostro primo progetto di plugin.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0087_pypi_cicd_part_3_post.html Sat, 19 Jul 2025 00:00:00 +0000 blog/2025/0087_pypi_cicd_part_3_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_integrazione_con_poetry">Integrazione con Poetry</a> <ul class="sectlevel2"> <li><a href="#_installazione_di_poetry">Installazione di Poetry</a></li> <li><a href="#_inizializzazione_del_progetto">Inizializzazione del progetto</a></li> <li><a href="#_aggiunta_e_installazione_di_dipendenze">Aggiunta e installazione di dipendenze</a></li> <li><a href="#_pubblicazione_con_poetry">Pubblicazione con Poetry</a></li> </ul> </li> <li><a href="#_builds_riproducibili_con_docker">Builds riproducibili con Docker</a> <ul class="sectlevel2"> <li><a href="#_esempio_di_dockerfile">Esempio di Dockerfile</a></li> <li><a href="#_integrazione_in_github_actions">Integrazione in GitHub Actions</a></li> </ul> </li> <li><a href="#_pubblicazione_condizionata">Pubblicazione condizionata</a></li> <li><a href="#_automazione_delle_dipendenze_con_renovate_e_dependabot">Automazione delle dipendenze con Renovate e Dependabot</a> <ul class="sectlevel2"> <li><a href="#_dependabot">Dependabot</a></li> <li><a href="#_renovare">Renovare</a></li> </ul> </li> <li><a href="#_diagrammi_plantuml">Diagrammi PlantUML</a> <ul class="sectlevel2"> <li><a href="#_caso_duso_cicd_avanzato">Caso d’uso – CI/CD avanzato</a></li> <li><a href="#_sequenza_pubblicazione_condizionata">Sequenza – Pubblicazione condizionata</a></li> <li><a href="#_stati_pipeline_cicd">Stati – Pipeline CI/CD</a></li> <li><a href="#_distribuzione_architettura_cicd">Distribuzione – Architettura CI/CD</a></li> </ul> </li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Nelle prime due parti di questa serie, abbiamo : - Stabilito un pipeline CI/CD funzionante per un’applicazione Python con GitHub Actions e PyPI. - Industrializzato questo pipeline con test multi-version, una pubblicazione progressiva tramite Test PyPI e strumenti di qualità e sicurezza.</p> </div> <div class="paragraph"> <p>In questa terza parte, andremo.<strong>oltre la semplice pubblicazione su PyPI</strong>per costruire una pipeline CI/CD completa, robusta e professionale con: - <strong>Poesia</strong>per un packaging moderno e una gestione ottimizzata delle dipendenze. - <strong>Docker</strong>per creare build riproducibili e multi-piattaforma - <strong>Pubblicazione condizionata</strong>per gestire scenari come i release candidates. - <strong>Strumenti di automazione</strong>(Renovate, Dependabot) per mantenere il pipeline aggiornato senza sforzo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_integrazione_con_poetry">Integrazione con Poetry</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poetry sostituisce i vecchi strumenti di packaging (setup.py, requirements.txt) centralizzando la gestione delle dipendenze e del build in`pyproject.toml`.</p> </div> <div class="sect2"> <h3 id="_installazione_di_poetry">Installazione di Poetry</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Installer Poetry curl -sSL https://install.python-poetry.org | python3 - # Vérifier la version poetry --version</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_inizializzazione_del_progetto">Inizializzazione del progetto</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Initialiser un nouveau projet avec Poetry poetry init # Suivre l'assistant pour renseigner : nom, version, description, licence, dépendances.</code></pre> </div> </div> <div class="paragraph"> <p>Questo genera un file`pyproject.toml` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="toml">[tool.poetry] name = "playlist-downloader" version = "0.1.0" description = "CLI tool for managing YouTube playlists" authors = ["Christophe Hérolivier <cheroliv@example.com>"] [tool.poetry.dependencies] python = ">=3.8" typer = "^0.9.0" yt-dlp = "^2023.7.6" google-api-python-client = "^2.0.0" google-auth-oauthlib = "^1.0.0" [tool.poetry.group.dev.dependencies] pytest = "^7.0" mypy = "^1.0" bandit = "^1.7" safety = "^2.3" black = "^23.0" ruff = "^0.1"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_aggiunta_e_installazione_di_dipendenze">Aggiunta e installazione di dipendenze</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell">poetry add typer yt-dlp google-api-python-client google-auth-oauthlib poetry add --group dev pytest mypy black bandit safety ruff</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_pubblicazione_con_poetry">Pubblicazione con Poetry</h3> <div class="paragraph"> <p>Poetry gestisce nativamente la pubblicazione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Publication sur Test PyPI poetry publish --build --repository test-pypi # Publication sur PyPI poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>Questo comando utilizza automaticamente le informazioni presenti in`pyproject.toml`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_builds_riproducibili_con_docker">Builds riproducibili con Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per garantire esecuzioni identiche in sviluppo, CI/CD e produzione, Docker si integra perfettamente con Poetry.</p> </div> <div class="sect2"> <h3 id="_esempio_di_dockerfile">Esempio di Dockerfile</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="dockerfile">FROM python:3.11-slim WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN pip install poetry RUN poetry install --no-root --only main COPY . . CMD ["poetry", "run", "python", "cli.py"]</code></pre> </div> </div> <div class="paragraph"> <p>Ciò garantisce: - Un ambiente Python bloccato. - Dipendenze bloccate tramite`poetry.lock`. - Un’immagine eseguibile su qualsiasi sistema che supporta Docker.</p> </div> </div> <div class="sect2"> <h3 id="_integrazione_in_github_actions">Integrazione in GitHub Actions</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: Docker Build on: push: branches: [main] jobs: build-docker: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build Docker image run: docker build -t ghcr.io/${{ github.repository }}:latest . - name: Push Docker image run: docker push ghcr.io/${{ github.repository }}:latest</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pubblicazione_condizionata">Pubblicazione condizionata</h2> <div class="sectionbody"> <div class="paragraph"> <p>In un pipeline professionale, è necessario poter pubblicare solo in alcuni casi: - Candidati di rilascio verso Test PyPI. - Versioni stabili verso PyPI. - Build di Docker attivati solo per`main`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">- name: Publish to Test PyPI if: contains(github.ref, '-rc') run: poetry publish --build --repository test-pypi - name: Publish to PyPI if: startsWith(github.ref, 'refs/tags/v') run: poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>Questo approccio evita le pubblicazioni accidentali</p> </div> </div> </div> <div class="sect1"> <h2 id="_automazione_delle_dipendenze_con_renovate_e_dependabot">Automazione delle dipendenze con Renovate e Dependabot</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per evitare che le tue dipendenze diventino obsolete, integra gli strumenti di aggiornamento automatico.</p> </div> <div class="sect2"> <h3 id="_dependabot">Dependabot</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">version: 2 updates: - package-ecosystem: "pip" directory: "/" schedule: interval: "weekly" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"</code></pre> </div> </div> <div class="paragraph"> <p>Dependabot apre PR ogni settimana per aggiornare le dipendenze Python e GitHub Actions.</p> </div> </div> <div class="sect2"> <h3 id="_renovare">Renovare</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="json">{ "extends": ["config:base"], "packageRules": [ { "matchManagers": ["pip"], "groupName": "python-dependencies", "schedule": ["before 6am on monday"] } ] }</code></pre> </div> </div> <div class="paragraph"> <p>Renovate consente un controllo più fine: raggruppamento di dipendenze, pianificazione e regole avanzate.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrammi_plantuml">Diagrammi PlantUML</h2> <div class="sectionbody"> <div class="sect2"> &lt;h3 id="_caso_duso_cicd_avanzato">Caso d’uso – CI/CD avanzato</h3> <div class="imageblock"> <div class="content"> <img src="images/usecase-cicd.svg" alt="usecase cicd" width="819" height="317"> </div> </div> </div> <div class="sect2"> <h3 id="_sequenza_pubblicazione_condizionata">Sequenza – Pubblicazione condizionata</h3> <div class="imageblock"> <div class="content"> <img src="images/sequence-cicd.svg" alt="sequence cicd" width="275" height="571"> </div> </div> </div> <div class="sect2"> <h3 id="_stati_pipeline_cicd">Stati – Pipeline CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/states-cicd.svg" alt="states cicd" width="284" height="608"> </div> </div> </div> <div class="sect2"> <h3 id="_distribuzione_architettura_cicd">Distribuzione – Architettura CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/deployment-cicd.svg" alt="deployment cicd" width="579" height="288"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>In questa terza parte, abbiamo visto come: - Modernizzare il packaging di Python con Poetry. - Assicurare build riproducibili tramite Docker. Impostare una pubblicazione condizionale. - Automatizzare l’aggiornamento delle dipendenze.</p> </div> <div class="paragraph"> <p>Ora disponi di un pipeline CI/CD<strong>completo, industrializzato e sicuro</strong>, pronto a evolvere con i suoi progetti</p> </div> </div> </div> https://cheroliv.com/blog/2025/0086_pypi_cicd_part_2_post.html Fri, 18 Jul 2025 00:00:00 +0000 blog/2025/0086_pypi_cicd_part_2_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_architettura_del_pipeline_cicd">Architettura del pipeline CI/CD</a></li> <li><a href="#_struttura_del_progetto">Struttura del Progetto</a></li> <li><a href="#_configurazione_del_package_con_pyproject_toml">Configurazione del Package con pyproject.toml</a></li> <li><a href="#_workflow_di_cicd_test_e_qualità">Workflow di CI/CD - Test e Qualità</a></li> <li><a href="#_flusso_di_lavoro_di_rilascio_e_distribuzione">Flusso di lavoro di rilascio e distribuzione</a></li> <li><a href="#_diagrammi_di_architettura">Diagrammi di architettura</a> <ul class="sectlevel2"> <li><a href="#_diagramma_di_sequenza_processo_di_rilascio">Diagramma di sequenza - processo di rilascio</a></li> <li><a href="#_diagramma_degli_stati_ciclo_di_vita_del_pacchetto">Diagramma degli Stati - Ciclo di Vita del Pacchetto</a></li> <li><a href="#_diagramma_di_distribuzione_infrastruttura_cicd">Diagramma di Distribuzione - Infrastruttura CI/CD</a></li> </ul> </li> <li><a href="#_oggetti_e_modelli_della_pipeline">Oggetti e modelli della pipeline</a> <ul class="sectlevel2"> <li><a href="#_diagramma_delle_classi_modelli_cicd">Diagramma delle classi - Modelli CI/CD</a></li> </ul> </li> <li><a href="#_configurazione_dei_segreti">Configurazione dei Segreti</a> <ul class="sectlevel2"> <li><a href="#_segreti_github_actions">Segreti GitHub Actions</a></li> <li><a href="#_generazione_dei_token_pypi">Generazione dei token PyPI</a></li> </ul> </li> <li><a href="#_scripts_di_sviluppo_locale">Scripts di sviluppo locale</a> <ul class="sectlevel2"> <li><a href="#_makefile">Makefile</a></li> <li><a href="#_script_di_versione">Script di versione</a></li> </ul> </li> <li><a href="#_buone_pratiche_e_raccomandazioni">Buone Pratiche e Raccomandazioni</a> <ul class="sectlevel2"> <li><a href="#_versionamento_semantico">Versionamento semantico</a></li> <li><a href="#_strategia_di_ramificazione">Strategia di ramificazione</a></li> <li><a href="#_test_e_copertura">Test e Copertura</a></li> <li><a href="#_sicurezza">Sicurezza</a></li> </ul> </li> <li><a href="#_monitoraggio_e_osservabilità">Monitoraggio e Osservabilità</a> <ul class="sectlevel2"> <li><a href="#_metriche_di_pipeline">Metriche di Pipeline</a></li> <li><a href="#_notifiche">Notifiche</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_risorse_complementari">risorse complementari</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Obiettivo: Trasformare un pipeline semplice in un pipeline industriale robusto, rispettando gli standard moderni del packaging e dell’ingegneria del software.</div> <p>Nella prima parte di questa serie, abbiamo costruito un pipeline CI/CD semplice ma efficace per automatizzare i test e la pubblicazione di un pacchetto Python su PyPI.</p> </div> <div class="paragraph"> <p>Ora è il momento di professionalizzare questo pipeline. In questa seconda parte, faremo :</p> </div> <div class="ulist"> <ul> <li> <p>Migrare verso lo standard moderno pyproject.toml,</p> </li> <li> <p>Aggiungere strumenti di qualità e sicurezza (Black, Mypy, Bandit, Safety)</p> </li> <li> <p>Impostare test multi-versione,</p> </li> <li> <p>Integrare una distribuzione progressiva tramite Test PyPI,</p> </li> <li> <p>Automatizzare il versioning e migliorare il monitoraggio del pipeline.</p> </li> </ul> </div> <div class="paragraph"> <p>Preparati a passare da una pipeline funzionante a un’infrastruttura CI/CD professionale.</p> </div> <div class="paragraph"> <p>Distribuire un’applicazione Python su PyPI richiede un pipeline CI/CD robusto che automatizza i test, la costruzione e la pubblicazione dei pacchetti. Questo articolo descrive la configurazione di un pipeline completo utilizzando GitHub Actions per un’applicazione CLI Python, basandosi sulle migliori pratiche dell’ecosistema Python moderno.</p> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_del_pipeline_cicd">Architettura del pipeline CI/CD</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il pipeline che costruiremo segue un approccio in più fasi:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-df38b638048cb4b42e93fd9aea0c4b85.png" alt="Diagram" width="956" height="604"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_struttura_del_progetto">Struttura del Progetto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un’applicazione CLI Python pronta per la distribuzione deve rispettare una struttura standardizzata:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="text">playlist-downloader/ ├── .github/ │ └── workflows/ │ ├── ci.yml │ ├── release.yml │ └── security.yml ├── src/ │ └── playlist_downloader/ │ ├── __init__.py │ ├── cli.py │ ├── core/ │ └── adapters/ ├── tests/ │ ├── unit/ │ ├── integration/ │ └── conftest.py ├── docs/ ├── pyproject.toml ├── requirements.txt ├── requirements-dev.txt ├── MANIFEST.in ├── README.md ├── LICENSE └── CHANGELOG.md</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configurazione_del_package_con_pyproject_toml">Configurazione del Package con pyproject.toml</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il file`pyproject.toml`è lo standard moderno per configurare i pacchetti Python :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="toml">[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"] build-backend = "setuptools.build_meta" [project] name = "playlist-downloader" authors = [ {name = "Christophe Hérolivier", email = "cheroliv@example.com"}, ] description = "CLI tool for YouTube playlist management" readme = "README.md" requires-python = ">=3.8" keywords = ["youtube", "playlist", "cli", "downloader"] license = {text = "MIT"} classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Topic :: Multimedia :: Sound/Audio", "Topic :: Utilities", ] dependencies = [ "typer>=0.9.0", "yt-dlp>=2023.7.6", "google-api-python-client>=2.0.0", "google-auth-oauthlib>=1.0.0", "pyyaml>=6.0", "rich>=13.0.0", ] dynamic = ["version"] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", "black>=23.0.0", "flake8>=6.0.0", "mypy>=1.0.0", "pre-commit>=3.0.0", "tox>=4.0.0", ] test = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", ] [project.urls] Homepage = "https://github.com/cheroliv/playlist-downloader" Documentation = "https://github.com/cheroliv/playlist-downloader#readme" Repository = "https://github.com/cheroliv/playlist-downloader.git" "Bug Tracker" = "https://github.com/cheroliv/playlist-downloader/issues" [project.scripts] playlist-downloader = "playlist_downloader.cli:main" [tool.setuptools_scm] write_to = "src/playlist_downloader/_version.py" [tool.setuptools.packages.find] where = ["src"] [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] addopts = [ "--cov=src/playlist_downloader", "--cov-report=html", "--cov-report=term-missing", "--cov-fail-under=85", ] [tool.black] line-length = 88 target-version = ['py38'] include = '\.pyi?$' extend-exclude = ''' /( \.eggs | \.git | \.hg | \.mypy_cache | \.tox | \.venv | _build | buck-out | build | dist )/ ''' [tool.mypy] python_version = "3.8" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true disallow_incomplete_defs = true check_untyped_defs = true disallow_untyped_decorators = true no_implicit_optional = true warn_redundant_casts = true warn_unused_ignores = true warn_no_return = true warn_unreachable = true strict_equality = true [[tool.mypy.overrides]] module = [ "yt_dlp.*", "googleapiclient.*", "google_auth_oauthlib.*", ] ignore_missing_imports = true</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_workflow_di_cicd_test_e_qualità">Workflow di CI/CD - Test e Qualità</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il flusso di lavoro principale (<code>ci.yml</code>) esegue i test su più versioni di Python:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.8", "3.9", "3.10", "3.11"] steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - name: Cache dependencies uses: actions/cache@v3 with: path: | ~/.cache/pip ~/.cache/pre-commit key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }} restore-keys: | ${{ runner.os }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e ".[dev]" - name: Lint with flake8 run: | flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics flake8 src tests --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics - name: Check code formatting with Black run: black --check src tests - name: Type checking with mypy run: mypy src - name: Run tests with pytest run: | pytest tests/ -v --cov=src/playlist_downloader \ --cov-report=xml --cov-report=term-missing - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 if: matrix.python-version == '3.11' with: file: ./coverage.xml flags: unittests name: codecov-umbrella security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install dependencies run: | python -m pip install --upgrade pip pip install bandit[toml] safety - name: Run security checks with bandit run: bandit -r src/ -f json -o bandit-report.json - name: Check dependencies with safety run: safety check --json --output safety-report.json - name: Upload security reports uses: actions/upload-artifact@v3 if: always() with: name: security-reports path: | bandit-report.json safety-report.json build: needs: [test, security] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install build dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package with twine run: twine check dist/* - name: Upload build artifacts uses: actions/upload-artifact@v3 with: name: dist path: dist/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_flusso_di_lavoro_di_rilascio_e_distribuzione">Flusso di lavoro di rilascio e distribuzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il workflow di rilascio (<code>release.yml</code>) gestisce la pubblicazione automatica su PyPI :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: Release on: push: tags: - 'v*.*.*' workflow_dispatch: inputs: environment: description: 'Deployment environment' required: true default: 'test' type: choice options: - test - production env: PYTHON_VERSION: "3.11" jobs: release: runs-on: ubuntu-latest environment: name: ${{ github.event.inputs.environment || (startsWith(github.ref, 'refs/tags/') && 'production' || 'test') }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package run: twine check dist/* - name: Publish to Test PyPI if: github.event.inputs.environment == 'test' || (startsWith(github.ref, 'refs/tags/') && contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }} run: | twine upload --repository testpypi dist/* - name: Publish to PyPI if: github.event.inputs.environment == 'production' || (startsWith(github.ref, 'refs/tags/') && !contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | twine upload dist/* - name: Create GitHub Release if: startsWith(github.ref, 'refs/tags/') uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: ${{ github.ref }} release_name: Release ${{ github.ref }} draft: false prerelease: ${{ contains(github.ref, 'rc') }} post-release: needs: release runs-on: ubuntu-latest if: startsWith(github.ref, 'refs/tags/') steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Test installation from PyPI run: | sleep 60 # Attendre la propagation sur PyPI pip install playlist-downloader playlist-downloader --version - name: Update documentation run: | # Script pour mettre à jour la documentation echo "Documentation updated for version ${GITHUB_REF#refs/tags/}"</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagrammi_di_architettura">Diagrammi di architettura</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagramma_di_sequenza_processo_di_rilascio">Diagramma di sequenza - processo di rilascio</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-4f74e2977774507a8aeec4e807bd358e.png" alt="Diagram" width="944" height="832"> </div> </div> </div> <div class="sect2"> <h3 id="_diagramma_degli_stati_ciclo_di_vita_del_pacchetto">Diagramma degli Stati - Ciclo di Vita del Pacchetto</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-5965441467a9c31f4e004420bba24fac.png" alt="Diagram" width="525" height="740"> </div> </div> </div> <div class="sect2"> <h3 id="_diagramma_di_distribuzione_infrastruttura_cicd">Diagramma di Distribuzione - Infrastruttura CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-372e14838d33646e11a8bbb9f2642b9b.png" alt="Diagram" width="665" height="604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_oggetti_e_modelli_della_pipeline">Oggetti e modelli della pipeline</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagramma_delle_classi_modelli_cicd">Diagramma delle classi - Modelli CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-17c128b8b33835d9e11d7dece1edd995.png" alt="Diagram" width="814" height="635"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configurazione_dei_segreti">Configurazione dei Segreti</h2> <div class="sectionbody"> <div class="paragraph"> <p>Perché il pipeline funzioni, dovete configurare i seguenti segreti in GitHub :</p> </div> <div class="sect2"> <h3 id="_segreti_github_actions">Segreti GitHub Actions</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="bash"># Dans Settings > Secrets and variables > Actions # Token PyPI pour la production PYPI_API_TOKEN=pypi-... # Token Test PyPI pour les pré-releases TEST_PYPI_API_TOKEN=pypi-... # Token GitHub pour créer les releases GITHUB_TOKEN=(automatiquement fourni) # Token Codecov (optionnel) CODECOV_TOKEN=...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_generazione_dei_token_pypi">Generazione dei token PyPI</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="bash"># 1. Créer un compte sur PyPI et Test PyPI # 2. Aller dans Account Settings > API tokens # 3. Créer un token avec scope "Entire account" ou spécifique au projet # 4. Format du token : pypi-AgEIcHlwaS5vcmc...</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scripts_di_sviluppo_locale">Scripts di sviluppo locale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per facilitare lo sviluppo, crea script utilitari :</p> </div> <div class="sect2"> <h3 id="_makefile">Makefile</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="makefile">.PHONY: install test lint format security build clean release-test release-prod install: pip install -e ".[dev]" test: pytest tests/ -v --cov=src/playlist_downloader lint: flake8 src tests mypy src format: black src tests security: bandit -r src/ safety check build: python -m build twine check dist/* clean: rm -rf build/ dist/ *.egg-info/ find . -type d -name __pycache__ -delete find . -name "*.pyc" -delete release-test: clean build twine upload --repository testpypi dist/* release-prod: clean build twine upload dist/* pre-commit: format lint test security @echo "✅ Prêt pour commit"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_script_di_versione">Script di versione</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="python">#!/usr/bin/env python3 """Script pour gérer les versions du projet.""" import sys import subprocess from pathlib import Path def get_current_version(): """Récupère la version actuelle depuis git.""" try: result = subprocess.run( ["git", "describe", "--tags", "--abbrev=0"], capture_output=True, text=True, check=True ) return result.stdout.strip() except subprocess.CalledProcessError: return "0.0.0" def create_version_tag(version, message=None): """Crée un tag de version.""" if not version.startswith('v'): version = f'v{version}' tag_message = message or f"Release {version}" subprocess.run(["git", "tag", "-a", version, "-m", tag_message], check=True) print(f"✅ Tag {version} créé") # Push le tag subprocess.run(["git", "push", "origin", version], check=True) print(f"✅ Tag {version} poussé vers origin") if __name__ == "__main__": if len(sys.argv) < 2: current = get_current_version() print(f"Version actuelle: {current}") print("Usage: python version.py <new_version> [message]") sys.exit(1) new_version = sys.argv[1] message = sys.argv[2] if len(sys.argv) > 2 else None create_version_tag(new_version, message)</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche_e_raccomandazioni">Buone Pratiche e Raccomandazioni</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_versionamento_semantico">Versionamento semantico</h3> <div class="paragraph"> <p>Utilizzare il versionamento semantico (SemVer) :</p> </div> <div class="ulist"> <ul> <li> <p><code>MAJOR.MINOR.PATCH</code> (ex: 1.2.3)</p> </li> <li> <p><code>MAJOR</code>: modifiche incompatibili</p> </li> <li> <p><code>MINOR</code>: nuove funzionalità compatibili</p> </li> <li> <p>`PATCH`correzioni di bug compatibili</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_strategia_di_ramificazione">Strategia di ramificazione</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="text">main ──●──●──●──●──●────●── (releases stables) / / / develop ──●──●──●──●──●──●──●──●── (développement) / / / feature/xxx ●──●──●──●──●──/ (fonctionnalités)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_test_e_copertura">Test e Copertura</h3> <div class="ulist"> <ul> <li> <p>Copertura minima del codice: 85%</p> </li> <li> <p>test unitari per la logica di business</p> </li> <li> <p>Test di integrazione per gli adattatori</p> </li> <li> <p>Test end-to-end per le CLI</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_sicurezza">Sicurezza</h3> <div class="ulist"> <ul> <li> <p>Scansione automatica delle dipendenze (Safety)</p> </li> <li> <p>Analisi statica del codice (Bandit)</p> </li> <li> <p>Segreti mai nel codice</p> </li> <li> <p>Utilizzo di token PyPI specifici</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_monitoraggio_e_osservabilità">Monitoraggio e Osservabilità</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_metriche_di_pipeline">Metriche di Pipeline</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml"># .github/workflows/metrics.yml name: Pipeline Metrics on: workflow_run: workflows: ["CI", "Release"] types: [completed] jobs: metrics: runs-on: ubuntu-latest steps: - name: Collect metrics run: | echo "Pipeline: ${{ github.event.workflow_run.name }}" echo "Status: ${{ github.event.workflow_run.conclusion }}" echo "Duration: ${{ github.event.workflow_run.updated_at - github.event.workflow_run.created_at }}" # Envoyer vers système de monitoring</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_notifiche">Notifiche</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml"># Ajout dans les workflows pour notifications - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: failure text: "❌ Pipeline failed for ${{ github.repository }}" env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa pipeline CI/CD completa per Python offre:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Automazione completa</strong>: dalla validazione del codice alla pubblicazione</p> </li> <li> <p><strong>Sicurezza</strong>scansioni automatiche e gestione sicura dei segreti</p> </li> <li> <p><strong>Qualità</strong>: test multi-version, linting e copertura del codice</p> </li> <li> <p><strong>Affidabilità</strong>: distribuzione graduale tramite Test PyPI</p> </li> <li> <p><strong>Tracciabilità</strong>artefatti, rapporti e releases GitHub</p> </li> </ul> </div> <div class="paragraph"> <p>L’adozione di queste pratiche garantisce un processo di consegna robusto e professionale per le tue applicazioni CLI Python, facilitando la manutenzione e l’evoluzione dei tuoi progetti nel lungo termine.</p> </div> </div> </div> <div class="sect1"> <h2 id="_risorse_complementari">risorse complementari</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://packaging.python.org/">Guida utente al packaging di Python</a></p> </li> <li> <p><a href="https://docs.github.com/en/actions">Documentazione di GitHub Actions</a></p> </li> <li> <p><a href="https://pypi.org/help/">Documentazione Aiuto PyPI</a></p> </li> <li> <p><a href="https://semver.org/">Specifica Semantic Versioning</a></p> </li> <li> <p><a href="https://keepachangelog.com/">Tieni un changelog</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2025/0085_pypi_cicd_part_1_post.html Thu, 17 Jul 2025 00:00:00 +0000 blog/2025/0085_pypi_cicd_part_1_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_architettura_della_pipeline">Architettura della pipeline</a></li> <li><a href="#_configurazione_della_pipeline_di_integrazione_continua_ci">Configurazione della Pipeline di Integrazione Continua (CI)</a> <ul class="sectlevel2"> <li><a href="#_struttura_del_workflow_ci">Struttura del workflow CI</a></li> <li><a href="#_analisi_delle_fasi_ci">Analisi delle fasi CI</a> <ul class="sectlevel3"> <li><a href="#_1_trigger_on">1. Trigger (<code>on</code>)</a></li> </ul> </li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Obiettivo : Accompagnare il lettore nella configurazione di un pipeline CI/CD minimale ma funzionante per un’applicazione Python, con un deployment automatico su PyPI.</div> <p>L’automazione dei processi di sviluppo è diventata indispensabile nei progetti moderni. Un pipeline CI/CD ben progettato non solo permette di individuare le regressioni presto nel ciclo di sviluppo, ma anche di automatizzare completamente il processo di distribuzione.</p> </div> <div class="paragraph"> <p>In questo articolo, esploreremo come configurare una pipeline completa con GitHub Actions per un’applicazione Python, dall’integrazione continua (CI) al deployment continuo (CD) su PyPI.</p> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_della_pipeline">Architettura della pipeline</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il nostro pipeline è composto da due workflows distinti:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Pipeline CI</strong>: Eseguito su ogni push e pull request</p> </li> <li> <p><strong>pipeline CD</strong>: Attivato solo durante le release di GitHub</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/ci-cd-overview.svg" alt="ci cd overview" width="394" height="648"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configurazione_della_pipeline_di_integrazione_continua_ci">Configurazione della Pipeline di Integrazione Continua (CI)</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_struttura_del_workflow_ci">Struttura del workflow CI</h3> <div class="paragraph"> <p>Il workflow CI è progettato per validare ogni contributo al codice. Ecco la sua configurazione completa:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: CI/CD Pipeline on: push: branches: - main pull_request: branches: - main jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock - name: Run Linting (Ruff) run: ruff check . - name: Run Tests (Pytest) run: pytest</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_analisi_delle_fasi_ci">Analisi delle fasi CI</h3> <div class="sect3"> <h4 id="_1_trigger_on">1. Trigger (<code>on</code>)</h4> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">---- ---- on: push: branches: - main pull_request: branches: - main ---- Il pipeline si attiva su : - Ogni push sul ramo`main` - Ogni pull request verso`main` Questo approccio garantisce che il codice principale rimanga stabile e che ogni contributo venga convalidato prima dell'integrazione. ==== 2. Ambiente di esecuzione ---- runs-on: ubuntu-latest Ubuntu Latest offre un buon compromesso tra prestazioni, costo e compatibilità per la maggior parte dei progetti Python. ==== 3. Checkout del Codice ```yaml ---- ---- - name: Checkout code uses: actions/checkout@v4 ---- L'azione`checkout@v4`recupera il codice sorgente del repository. La versione v4 apporta miglioramenti delle prestazioni e della sicurezza. ==== 4. Configurazione Python ---- - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' L'utilizzo di`'3.x'`consente di utilizzare automaticamente l'ultima versione stabile di Python 3, semplificando la manutenzione. ==== 5. Installazione delle Dipendenze ```yaml ---- ---- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock ---- Questa fase: - Aggiorna pip all'ultima versione - Installa le dipendenze del progetto - Aggiungi gli strumenti di sviluppo (linting e test) ==== 6. Linting con Ruff ---- - name: Run Linting (Ruff) run: ruff check . **Ruff**è un linter Python ultra-veloce scritto in Rust. Combina le funzionalità di diversi strumenti (Flake8, Black, isort) in un unico strumento performante. ==== 7. Esecuzione dei test ```yaml ---- ---- - name: Run Tests (Pytest) run: pytest ---- Pytest esegue l'intera suite di test, garantendo che le modifiche non introducano regressioni. == Configurazione del pipeline di distribuzione (CD) === Struttura del flusso di lavoro CD Il workflow CD si attiva solo durante le release di GitHub e automatizza la pubblicazione su PyPI: [source,yaml] ---- name: Publish to PyPI on: release: types: - published jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install setuptools wheel twine - name: Build and publish env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | python setup.py sdist bdist_wheel twine upload dist/* ---- === Analisi delle fasi CD ==== 1. Scatto Rilascio ---- on: release: types: - published Il pipeline CD si attiva solo alla pubblicazione di una release GitHub. Questo approccio assicura un controllo preciso dei deployment. ==== 2. Installazione degli Strumenti di Build ```yaml ---- ---- pip install setuptools wheel twine ---- - **setuptools**: Strumenti di packaging Python - **wheel**: Formato di distribuzione Python moderno - **spago**: Strumento sicuro per caricare su PyPI ==== 3. Configurazione dell'autenticazione ---- env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} L'autenticazione utilizza un token API PyPI memorizzato come segreto GitHub, più sicuro delle credenziali tradizionali. ==== 4. Build e Pubblicazione ```yaml ---- ---- run: | python setup.py sdist bdist_wheel twine upload dist/* ---- - `sdist`: Crea una distribuzione sorgente - `bdist_wheel`: Crea una wheel (distribuzione binaria) - `twine upload`Pubblica le distribuzioni su PyPI == Configurazione del pacchetto Python === Struttura di setup.py Per far funzionare il pipeline, il tuo progetto deve includere un file`setup.py`</think> : [source,python] ---- from setuptools import setup, find_packages with open("README.adoc", "r", encoding="utf-8") as fh: long_description = fh.read() setup( name="playlist-downloader", version="1.0.0", author="Votre Nom", author_email="votre.email@example.com", description="CLI tool for managing YouTube playlists", long_description=long_description, long_description_content_type="text/plain", url="https://github.com/cheroliv/playlist-downloader", packages=find_packages(), classifiers=[ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", ], python_requires=">=3.8", install_requires=[ "typer>=0.9.0", "yt-dlp>=2023.1.6", "google-api-python-client>=2.70.0", "google-auth-oauthlib>=0.7.1", "pymonad>=2.4.0", "pyyaml>=6.0", ], entry_points={ "console_scripts": [ "playlist-downloader=cli:app", ], }, ) ---- === Punti chiave del setup.py 1. **Metadati**Nome, versione, autore, descrizione 2. **Dipendenze**Elenco dei pacchetti richiesti 3. **Punti di ingresso**: Comandi CLI esposti 4. **classificatori**: Metadati per PyPI == Sicurezza con i GitHub Secrets === Configurazione del Token PyPI 1. **Creare un token API su PyPI** : - Accedi a PyPI - Vai in Account Settings > API tokens - Crea un nuovo token con le autorizzazioni appropriate 1. **Aggiungere il segreto in GitHub** : - Impostazioni del repository > Segreti e variabili > Azioni - Crea un nuovo segreto chiamato`PYPI_API_TOKEN` - Incolla il tuo token PyPI [plantuml, secrets-flow, svg] ---- @startuml !theme plain actor Developer as dev participant "Repository GitHub" as repo participant "GitHub Actions" as actions participant PyPI dev -> repo : Configure PYPI_API_TOKEN secret repo -> actions : Trigger CD pipeline on release actions -> actions : Access secret securely actions -> PyPI : Authenticate with token PyPI -> PyPI : Validate and publish package note over actions, PyPI Token never exposed in logs Automatic rotation possible end note @enduml ---- == Workflow di Distribuzione Completa === Sequenza di distribuzione [plantuml, deployment-sequence, svg] ---- @startuml !theme plain actor Developer as dev participant "Git locale" as git participant "GitHub" as github participant "GitHub Actions" as actions participant PyPI participant "Utenti finali" as users dev -> git : git tag v1.0.0 dev -> git : git push origin v1.0.0 git -> github : Push tag dev -> github : Create release from tag github -> actions : Trigger CD pipeline actions -> actions : Checkout code actions -> actions : Setup Python environment actions -> actions : Install build tools actions -> actions : Build distributions (sdist + wheel) actions -> PyPI : Upload to PyPI with token PyPI -> PyPI : Validate and publish users -> PyPI : pip install playlist-downloader note over dev, github Release creation can be automated or done manually through GitHub UI end note @enduml ---- === Stati del pipeline [plantuml, pipeline-states, svg] ---- @startuml !theme plain [*] --> Idle Idle --> CI_Running : Push/PR created CI_Running --> CI_Success : All checks pass CI_Running --> CI_Failed : Linting/Tests fail CI_Success --> Idle : Merge completed CI_Failed --> Idle : Fix and retry Idle --> CD_Running : Release published CD_Running --> CD_Success : Package published CD_Running --> CD_Failed : Build/Upload error CD_Success --> Idle : Package available on PyPI CD_Failed --> Idle : Fix and retry release note on link #red : Blocks merge note on link #green : Allows deployment @enduml ---- == Buone Pratiche e Ottimizzazioni === 1. Gestione delle Versioni Utilizza tag Git semantici : ---- git tag -a v1.2.3 -m "Release version 1.2.3" git push origin v1.2.3 === 2. Test di matrice Per testare su più versioni di Python: ```yaml ---- ---- strategy: matrix: python-version: [3.8, 3.9, "3.10", "3.11"] ---- === 3. Cache delle Dipendenze Accelerate i build con la cache : ---- - name: Cache pip dependencies uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} === 4. Ambienti di distribuzione Utilizza gli ambienti GitHub per le distribuzioni controllate: ```yaml ---- ---- jobs: deploy: environment: production runs-on: ubuntu-latest ---- == Caso d'uso e architettura === Diagramma dei casi d'uso [plantuml, use-cases, svg] ---- @startuml !theme plain left to right direction actor "Sviluppatore" as dev actor "GitHub Actions" as ga actor "utente finale" as user package "Sistema CI/CD" { usecase "Esegui il linting" as lint usecase "Esegui i test" as test usecase "Costruisci pacchetto" as build usecase "Pubblica su PyPI" as publish usecase "Crea Release" as release } dev --> lint : Pushes code dev --> test : Pushes code dev --> release : Creates release ga --> build : On release trigger ga --> publish : After successful build user --> publish : Downloads package lint .> test : triggers test .> build : on success build .> publish : on success @enduml ---- === Architettura del deployment [plantuml, deployment-architecture, svg] ---- @startuml !theme plain cloud "GitHub" { [Source Repository] [GitHub Actions] [Secrets Store] } cloud "PyPI" { [Package Registry] [Distribution Files] } node "CI/CD Pipeline" { [Linting] [Testing] [Building] [Publishing] } [Source Repository] --> [GitHub Actions] : Triggers [GitHub Actions] --> [Linting] [Linting] --> [Testing] [Testing] --> [Building] [Building] --> [Publishing] [Publishing] --> [Package Registry] : Uploads [Secrets Store] --> [Publishing] : Provides token note as N1 Secure token-based authentication end note [Secrets Store] .. N1 @enduml ---- == Monitoraggio e debugging === Log e Monitoraggio GitHub Actions fornisce log dettagliati per ogni passaggio. Per il debug: 1. **Esamini i log**di ogni step 2. **Attiva il debug**con`ACTIONS_STEP_DEBUG` 3. **Utilizza gli artefatti**per salvare i file di build ---- - name: Upload build artifacts uses: actions/upload-artifact@v3 if: failure() with: name: build-logs path: build/ === Notifiche Aggiungi notifiche Slack o email : ```yaml ---- ---- - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} webhook_url: ${{ secrets.SLACK_WEBHOOK }} ---- == Conclusione L'implementazione di un pipeline CI/CD robusto con GitHub Actions trasforma radicalmente l'esperienza di sviluppo. Automatizzando il linting, i test e il deployment, tu: - **Riduci gli errori**in produzione - **Accelerate i cicli**di sviluppo - **Migliorate la fiducia**nei vostri rilasci - **Facilita la collaborazione**in squadra Questo pipeline può essere adattato a diversi tipi di progetti Python regolando gli strumenti di linting, i framework di test o le destinazioni di distribuzione. L'investimento iniziale nella configurazione di questi flussi di lavoro è rapidamente ripagato dal guadagno di tempo e dalla riduzione degli errori manuali durante i rilasci. == Risorse Complementari - https://docs.github.com/en/actions[Documentazione GitHub Actions] - https://packaging.python.org/[Python Packaging Guide] - https://docs.pytest.org/[Documentazione Pytest] - https://docs.astral.sh/ruff/[Documentazione Ruff] - https://twine.readthedocs.io/[Documentazione Twine] ✅ Pipeline funzionale raggiunto ! Ora hai un semplice pipeline CI/CD che ti permette di automatizzare i test e di pubblicare il tuo pacchetto Python su PyPI direttamente da GitHub Actions. Tuttavia, questo pipeline rimane volontariamente minimalista. Non copre ancora alcuni aspetti indispensabili in un contesto professionale: Test di più versioni di Python Analisi di sicurezza automatica, Distribuzione progressiva tramite Test PyPI, Monitoraggio e metriche della pipeline, Automazione del versioning e integrazione delle buone pratiche moderne (pyproject.toml). Nella prossima parte, passeremo al livello successivo. Imparerai a trasformare questo pipeline di base in una vera catena di distribuzione industriale, robusta e sicura, pronta per progetti Python di produzione. ----</code></pre> </div> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0084_disco_bot_discord_python_post.html Wed, 16 Jul 2025 00:00:00 +0000 blog/2025/0084_disco_bot_discord_python_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_contesto_e_sfide_attuali">Contesto e Sfide Attuali</a> <ul class="sectlevel2"> <li><a href="#_evoluzione_delle_api_musicali">Evoluzione delle API musicali</a></li> <li><a href="#_approccio_sviluppo_guidato_dai_log">Approccio Sviluppo guidato dai log</a></li> </ul> </li> <li><a href="#_architettura_concettuale">Architettura concettuale</a></li> <li><a href="#_stack_tecnico_e_paradigma_funzionale">Stack Tecnico e Paradigma Funzionale</a> <ul class="sectlevel2"> <li><a href="#_scelte_tecnologiche">Scelte tecnologiche</a></li> <li><a href="#_principi_funzionali_applicati">Principi Funzionali Applicati</a></li> </ul> </li> <li><a href="#_metodologia_agile_e_backlog">Metodologia Agile e Backlog</a> <ul class="sectlevel2"> <li><a href="#_epic_principali">Epic Principali</a> <ul class="sectlevel3"> <li><a href="#_epica_1_bot_discord_per_linfrastruttura">Epica 1 : Bot Discord per l’infrastruttura</a></li> <li><a href="#_epic_2_integrazione_spotify">Epic 2 : integrazione Spotify</a></li> <li><a href="#_epic_3_integrazione_youtube">Epic 3 : Integrazione YouTube</a></li> <li><a href="#_epic_4_funzionalità_musicali">Epic 4 : Funzionalità Musicali</a></li> </ul> </li> <li><a href="#_storie_utente_dettagliate">Storie Utente Dettagliate</a> <ul class="sectlevel3"> <li><a href="#_us1_1_inizializzazione_del_bot">US1.1 : Inizializzazione del Bot</a></li> <li><a href="#_us2_1_ricerca_spotify_intelligente">US2.1 : Ricerca Spotify intelligente</a></li> <li><a href="#_us3_1_estrazione_youtube_resiliente">US3.1 : Estrazione YouTube resiliente</a></li> </ul> </li> </ul> </li> <li><a href="#_approccio_sviluppo_guidato_dai_log_2">Approccio sviluppo guidato dai log</a> <ul class="sectlevel2"> <li><a href="#_strategia_di_logging">Strategia di logging</a></li> <li><a href="#_struttura_dei_log">Struttura dei log</a></li> <li><a href="#_esempio_di_log_design">Esempio di Log Design</a></li> </ul> </li> <li><a href="#_architettura_di_validazione_con_pydantic">Architettura di Validazione con Pydantic</a> <ul class="sectlevel2"> <li><a href="#_modelli_di_dati">Modelli di dati</a></li> </ul> </li> <li><a href="#_gestione_funzionale_degli_errori">Gestione funzionale degli errori</a> <ul class="sectlevel2"> <li><a href="#_monadi_e_gestione_degli_errori">Monadi e Gestione degli errori</a></li> </ul> </li> <li><a href="#_strategia_di_aggiramento_delle_restrizioni">Strategia di aggiramento delle restrizioni</a> <ul class="sectlevel2"> <li><a href="#_approccio_multifonte">Approccio multifonte</a></li> </ul> </li> <li><a href="#_piano_di_sviluppo_iterativo">piano di sviluppo iterativo</a> <ul class="sectlevel2"> <li><a href="#_pianificazione_dello_sprint">pianificazione dello sprint</a></li> <li><a href="#_metriche_di_qualità">Metriche di Qualità</a></li> </ul> </li> <li><a href="#_distribuzione_e_monitoring">Distribuzione e Monitoring</a> <ul class="sectlevel2"> <li><a href="#_architettura_di_produzione">Architettura di Produzione</a></li> <li><a href="#_monitoraggio_proattivo">Monitoraggio Proattivo</a></li> </ul> </li> <li><a href="#_conclusion_e_prospettive">Conclusion e Prospettive</a> <ul class="sectlevel2"> <li><a href="#_passi_successivi">Passi Successivi</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_introduzione"><a class="anchor" href="#_introduzione"></a>Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lo sviluppo di un bot Discord che integra le API di Spotify e YouTube rappresenta una sfida tecnica moderna, soprattutto alla luce delle recenti restrizioni ed evoluzioni delle piattaforme. Questo articolo presenta un approccio metodologico basato sul<strong>Sviluppo guidato dal log</strong>(LDD), un’estensione del Test Driven Development, applicata in un paradigma funzionale con Python.</p> </div> <div class="paragraph"> <p>Il nostro obiettivo: creare un bot robusto, mantenibile e scalabile, capace di navigare le attuali limitazioni delle API musicali offrendo al contempo un’esperienza utente fluida su Discord.</p> </div> </div> </div> <div class="sect1"> <h2 id="_contesto_e_sfide_attuali"><a class="anchor" href="#_contesto_e_sfide_attuali"></a>Contesto e Sfide Attuali</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_evoluzione_delle_api_musicali"><a class="anchor" href="#_evoluzione_delle_api_musicali"></a>Evoluzione delle API musicali</h3> <div class="paragraph"> <p>Le piattaforme musicali hanno notevolmente inasprito le loro politiche di accesso:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Spotify</strong>: Restrizioni sull’accesso ai metadati, limitazione delle quote</p> </li> <li> <p><strong>YouTube</strong>: Politica anti-bot rafforzata, complicazione dell’autenticazione</p> </li> <li> <p><strong>Discord</strong>Nuovi requisiti di sicurezza e prestazioni</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_approccio_sviluppo_guidato_dai_log"><a class="anchor" href="#_approccio_sviluppo_guidato_dai_log"></a>Approccio Sviluppo guidato dai log</h3> <div class="paragraph"> <p>LDD estende TDD ponendo i log al centro dello sviluppo :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Definizione dei log</strong>prima dell’implementazione</p> </li> <li> <p><strong>Validazione mediante osservazione</strong>comportamenti attesi</p> </li> <li> <p><strong>Tracciabilità completa</strong>flussi di dati</p> </li> <li> <p><strong>Debugging proattivo</strong>in anticipo degli errori</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_concettuale"><a class="anchor" href="#_architettura_concettuale"></a>Architettura concettuale</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-b7c365fbdbe4c8afb4f10ca8ae8ccc4d.png" alt="Diagram" width="777" height="618"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_stack_tecnico_e_paradigma_funzionale"><a class="anchor" href="#_stack_tecnico_e_paradigma_funzionale"></a>Stack Tecnico e Paradigma Funzionale</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_scelte_tecnologiche"><a class="anchor" href="#_scelte_tecnologiche"></a>Scelte tecnologiche</h3> <div class="paragraph"> <p>Il nostro stack si articola attorno alla programmazione funzionale :</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>PyMonade</strong></dt> <dd> <p>Gestione degli effetti di bordo e composizione di funzioni</p> </dd> <dt class="hdlist1"><strong>Pydantic</strong></dt> <dd> <p>Validazione dei dati type-safe e serializzazione</p> </dd> <dt class="hdlist1"><strong>Asyncio</strong></dt> <dd> <p>Programmazione asincrona per le API</p> </dd> <dt class="hdlist1"><strong>Structlog</strong></dt> <dd> <p>Logging strutturato per il LDD</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_principi_funzionali_applicati"><a class="anchor" href="#_principi_funzionali_applicati"></a>Principi Funzionali Applicati</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-29860a3df2d618c6e7a0cf221c3a45e8.png" alt="Diagram" width="698" height="554"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_metodologia_agile_e_backlog"><a class="anchor" href="#_metodologia_agile_e_backlog"></a>Metodologia Agile e Backlog</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_epic_principali"><a class="anchor" href="#_epic_principali"></a>Epic Principali</h3> <div class="paragraph"> <p>Il nostro sviluppo si organizza attorno a 4 epici principali:</p> </div> <div class="sect3"> <h4 id="_epica_1_bot_discord_per_linfrastruttura"><a class="anchor" href="#_epica_1_bot_discord_per_linfrastruttura"></a>Epica 1 : Bot Discord per l’infrastruttura</h4> <div class="paragraph"> <p><strong>Valore di business</strong> : Base solida e estensibile</p> </div> <div class="paragraph"> <p><strong>Criteri di accettazione</strong> : - Connessione Discord stabile con gestione di riconnessione - sistema di comandi modulare Logging strutturato integrato - Gestione degli errori centralizzata</p> </div> </div> <div class="sect3"> <h4 id="_epic_2_integrazione_spotify"><a class="anchor" href="#_epic_2_integrazione_spotify"></a>Epic 2 : integrazione Spotify</h4> <div class="paragraph"> <p><strong>Valore aziendale</strong> : Accesso ai metadati musicali</p> </div> <div class="paragraph"> <p><strong>Criteri di accettazione</strong> : - Autenticazione OAuth2 sicura - Ricerca di tracce con cache intelligente - Gestione delle quote API - Fallback sugli errori di rete</p> </div> </div> <div class="sect3"> <h4 id="_epic_3_integrazione_youtube"><a class="anchor" href="#_epic_3_integrazione_youtube"></a>Epic 3 : Integrazione YouTube</h4> <div class="paragraph"> <p><strong>Valore di business</strong> : Accesso al contenuto audio</p> </div> <div class="paragraph"> <p><strong>Criteri di accettazione</strong> : Aggiramento legale delle restrizioni - Estrazione audio ottimizzata - Gestione dei video privati/cancellati - Rispetto dei Termini di Servizio di YouTube</p> </div> </div> <div class="sect3"> <h4 id="_epic_4_funzionalità_musicali"><a class="anchor" href="#_epic_4_funzionalità_musicali"></a>Epic 4 : Funzionalità Musicali</h4> <div class="paragraph"> <p><strong>Valore aziendale</strong> : Esperienza utente completa</p> </div> <div class="paragraph"> <p>Criteri di accettazione - Riproduzione audio di alta qualità - Coda di lettura intelligente - Comandi vocali Discord - Sincronizzazione multipiattaforma</p> </div> </div> </div> <div class="sect2"> <h3 id="_storie_utente_dettagliate"><a class="anchor" href="#_storie_utente_dettagliate"></a>Storie Utente Dettagliate</h3> <div class="sect3"> <h4 id="_us1_1_inizializzazione_del_bot"><a class="anchor" href="#_us1_1_inizializzazione_del_bot"></a>US1.1 : Inizializzazione del Bot</h4> <div class="paragraph"> <p><strong>In qualità di</strong> sviluppatore Voglio un bot Discord che si connette in modo affidabile <strong>Per</strong> garantire la disponibilità del servizio</p> </div> <div class="paragraph"> <p><strong>DoD (Definizione di Fatto)</strong> : - [ ] Bot si connette automaticamente all’avvio - [ ] I log strutturati documentano ogni passaggio - [ ] Riconnessione automatica in caso di disconnessione - [ ] I test di integrazione passano</p> </div> </div> <div class="sect3"> <h4 id="_us2_1_ricerca_spotify_intelligente"><a class="anchor" href="#_us2_1_ricerca_spotify_intelligente"></a>US2.1 : Ricerca Spotify intelligente</h4> <div class="paragraph"> <p><strong>In quanto</strong> utente Discord <strong>Voglio</strong> cercare brani tramite Spotify <strong>Al fine di</strong> scoprire e condividere la musica</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] Ordine`/search`funzionale - [ ] Risultati pertinenti con metadati - [ ] Cache locale per ottimizzare le richieste - [ ] Gestione elegante degli errori API</p> </div> </div> <div class="sect3"> <h4 id="_us3_1_estrazione_youtube_resiliente"><a class="anchor" href="#_us3_1_estrazione_youtube_resiliente"></a>US3.1 : Estrazione YouTube resiliente</h4> <div class="paragraph"> <p><strong>In qualità di</strong> sistema <strong>Voglio</strong> estrarre l’audio YouTube in modo affidabile <strong>Al fine di</strong> mantenere la continuità del servizio</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] Estrazione senza violazione dei ToS qualità audio ottimale - [ ] Gestione delle restrizioni geografiche - [ ] Registri dettagliati delle operazioni</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_approccio_sviluppo_guidato_dai_log_2"><a class="anchor" href="#_approccio_sviluppo_guidato_dai_log_2"></a>Approccio sviluppo guidato dai log</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_strategia_di_logging"><a class="anchor" href="#_strategia_di_logging"></a>Strategia di logging</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-b721fb724ea5bee52ffd7a7f573da7a9.png" alt="Diagram" width="687" height="633"> </div> </div> </div> <div class="sect2"> <h3 id="_struttura_dei_log"><a class="anchor" href="#_struttura_dei_log"></a>Struttura dei log</h3> <div class="paragraph"> <p>Il nostro approccio LDD utilizza log strutturati con livelli semantici:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>traccia</strong></dt> <dd> <p>Flusso di dati dettagliato</p> </dd> <dt class="hdlist1"><strong>DEBUG</strong></dt> <dd> <p>Stati interni delle funzioni</p> </dd> <dt class="hdlist1"><strong>informazioni</strong></dt> <dd> <p>Operazioni di business riuscite</p> </dd> <dt class="hdlist1"><strong>AVVISO</strong></dt> <dd> <p>Situazioni degradate ma gestite</p> </dd> <dt class="hdlist1"><strong>ERRORE</strong></dt> <dd> <p>Errori che richiedono intervento</p> </dd> <dt class="hdlist1"><strong></think></strong></dt> <dd> <p>Guasti del sistema</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_esempio_di_log_design"><a class="anchor" href="#_esempio_di_log_design"></a>Esempio di Log Design</h3> <div class="paragraph"> <p>Prima di implementare la funzione di ricerca Spotify, definiamo i suoi log:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">INFO: spotify.search.start query="bohemian rhapsody" user_id=123456 DEBUG: spotify.search.validation query_length=16 safe_chars=true DEBUG: spotify.search.api_call endpoint="/search" params={...} INFO: spotify.search.success results_count=15 duration_ms=340</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_di_validazione_con_pydantic"><a class="anchor" href="#_architettura_di_validazione_con_pydantic"></a>Architettura di Validazione con Pydantic</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_modelli_di_dati"><a class="anchor" href="#_modelli_di_dati"></a>Modelli di dati</h3> <div class="paragraph"> <p>Il nostro approccio funzionale privilegia la validazione a monte:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ebd4e1dfbd7b19d5a6054ecf213e9e2d.png" alt="Diagram" width="696" height="339"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_gestione_funzionale_degli_errori"><a class="anchor" href="#_gestione_funzionale_degli_errori"></a>Gestione funzionale degli errori</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_monadi_e_gestione_degli_errori"><a class="anchor" href="#_monadi_e_gestione_degli_errori"></a>Monadi e Gestione degli errori</h3> <div class="paragraph"> <p>L’utilizzo di PyMonade permette una gestione elegante degli errori :</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c811579199c4500198fbda9d1972ca1f.png" alt="Diagram" width="511" height="494"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_strategia_di_aggiramento_delle_restrizioni"><a class="anchor" href="#_strategia_di_aggiramento_delle_restrizioni"></a>Strategia di aggiramento delle restrizioni</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_approccio_multifonte"><a class="anchor" href="#_approccio_multifonte"></a>Approccio multifonte</h3> <div class="paragraph"> <p>Di fronte alle restrizioni delle API, adottiamo una strategia di diversificazione:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ebc78307d017bc4d8ac2223716532d09.png" alt="Diagram" width="665" height="744"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_piano_di_sviluppo_iterativo"><a class="anchor" href="#_piano_di_sviluppo_iterativo"></a>piano di sviluppo iterativo</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pianificazione_dello_sprint"><a class="anchor" href="#_pianificazione_dello_sprint"></a>pianificazione dello sprint</h3> <div class="paragraph"> <p>Il nostro sviluppo segue un ciclo di sprint di 2 settimane:</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>Sprint 1-2</strong></dt> <dd> <p>Infrastruttura e Discord Bot Core</p> </dd> <dt class="hdlist1"><strong>Sprint 3-4</strong></dt> <dd> <p>Integrazione Spotify con LDD</p> </dd> <dt class="hdlist1"><strong>Sprint 5-6</strong></dt> <dd> <p>Integrazione YouTube e soluzioni alternative</p> </dd> <dt class="hdlist1"><strong>Sprint 7-8</strong></dt> <dd> <p>Features musicali avanzate</p> </dd> <dt class="hdlist1"><strong>Sprint 9-10</strong></dt> <dd> <p>Ottimizzazione e produzione</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_metriche_di_qualità"><a class="anchor" href="#_metriche_di_qualità"></a>Metriche di Qualità</h3> <div class="paragraph"> <p>Ogni sprint è valutato su :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Copertura dei log</strong>>90% dei percorsi critici</p> </li> <li> <p><strong>Affidabilità API</strong>: <1% di errori non gestiti</p> </li> <li> <p><strong>prestazione</strong>: <500ms tempo di risposta medio</p> </li> <li> <p><strong>Manutenibilità</strong>Complessità ciclomatica <10</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_distribuzione_e_monitoring"><a class="anchor" href="#_distribuzione_e_monitoring"></a>Distribuzione e Monitoring</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_architettura_di_produzione"><a class="anchor" href="#_architettura_di_produzione"></a>Architettura di Produzione</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-aed739bf739bae57abdfc5b45ac3e583.png" alt="Diagram" width="938" height="381"> </div> </div> </div> <div class="sect2"> <h3 id="_monitoraggio_proattivo"><a class="anchor" href="#_monitoraggio_proattivo"></a>Monitoraggio Proattivo</h3> <div class="paragraph"> <p>Il LDD facilita un monitoraggio intelligente:</p> </div> <div class="ulist"> <ul> <li> <p><strong>Avvisi basati sui pattern di log</strong></p> </li> <li> <p><strong>Rilevamento di anomalie comportamentali</strong></p> </li> <li> <p><strong>Metriche aziendali in tempo reale</strong></p> </li> <li> <p><strong>Debugging assistito da correlazione dei log</strong></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_e_prospettive"><a class="anchor" href="#_conclusion_e_prospettive"></a>Conclusion e Prospettive</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa approccio metodologico combina i benefici del paradigma funzionale con la robustezza del Log Driven Development. Ci permette di :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Prevedere i problemi</strong>Grazie ai logs progettati a monte</p> </li> <li> <p><strong>Mantenere la qualità</strong>tramite la validazione continua</p> </li> <li> <p><strong>Adattare rapidamente</strong>alle modifiche delle API</p> </li> <li> <p><strong>Garantire la tracciabilità</strong>completa delle operazioni</p> </li> </ol> </div> <div class="paragraph"> <p>Lo sviluppo iterativo e l’architettura modulare garantiscono la scalabilità di fronte ai requisiti mutevoli delle piattaforme musicali.</p> </div> <div class="sect2"> <h3 id="_passi_successivi"><a class="anchor" href="#_passi_successivi"></a>Passi Successivi</h3> <div class="ulist"> <ul> <li> <p><strong>Fase 1</strong>Implementazione del core con PyMonade</p> </li> <li> <p><strong>Fase 2</strong>: Integrazione Spotify con cache intelligente</p> </li> <li> <p><strong>Fase 3</strong>Soluzione YouTube resiliente</p> </li> <li> <p><strong>Fase 4</strong>Features avanzate e ottimizzazione</p> </li> </ul> </div> <div class="paragraph"> <p>Questa solida fondazione concettuale ci permetterà di affrontare le sfide tecniche garantendo al contempo un’esperienza utente eccezionale.</p> </div> <hr> <div class="paragraph"> <p><strong>Questo articolo sarà seguito da una serie tecnica che dettaglia l’implementazione di ogni componente con esempi di codice e pattern funzionali.</strong></p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0083_cold_computer_post.html Tue, 15 Jul 2025 00:00:00 +0000 blog/2025/0083_cold_computer_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_obiettivo_di_questa_guida">Obiettivo di questa guida</a></li> <li><a href="#_prerequisito">Prerequisito</a></li> <li><a href="#_installare_e_configurare_gli_strumenti">Installare e configurare gli strumenti</a> <ul class="sectlevel2"> <li><a href="#_lm_sensors_per_rilevare_i_sensori">lm-sensors` per rilevare i sensori</a></li> <li><a href="#_tlp_gestore_intelligente_dellenergia">tlp` : gestore intelligente dell’energia</a></li> <li><a href="#_cpufrequtils_limitare_le_frequenze_della_cpu">cpufrequtils` : limitare le frequenze della CPU</a></li> <li><a href="#_auto_cpufreq_gestione_dinamica_semplificata">auto-cpufreq` : gestione dinamica semplificata</a></li> <li><a href="#_thermald_protezione_termica_automatica">thermald` : protezione termica automatica</a></li> </ul> </li> <li><a href="#_monitoraggio_in_tempo_reale">Monitoraggio in tempo reale</a> <ul class="sectlevel2"> <li><a href="#_sensors_da_riga_di_comando">sensors` da riga di comando</a></li> <li><a href="#_opzione_gui_psensor">Opzione GUI: `psensor</a></li> </ul> </li> <li><a href="#_consigli_aggiuntivi">Consigli aggiuntivi</a></li> <li><a href="#_pulire_il_sistema_per_limitare_i_sovraccarichi">Pulire il sistema per limitare i sovraccarichi</a></li> <li><a href="#_per_andare_oltre">Per andare oltre</a></li> <li><a href="#_conclusion">📚 Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Senti che il tuo portatile si surriscalda in modo anomalo sotto Ubuntu? Questo articolo ti propone un approccio<strong>software</strong>completa per<strong>raffreddare</strong>, <strong>sorvegliare</strong> et <strong>controllare la temperatura</strong>della tua macchina.</p> </div> </div> </div> <div class="sect1"> <h2 id="_obiettivo_di_questa_guida">Obiettivo di questa guida</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Ridurre la temperatura globale del computer</p> </li> <li> <p>Ottimizzare la gestione dell’energia</p> </li> <li> <p>Monitorare i componenti critici (CPU, GPU, etc.)</p> </li> <li> <p>Evitare i rallentamenti dovuti al<strong>limitazione termica</strong></p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="gestion_thermique.svg" alt="gestion thermique" width="392" height="298"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_prerequisito">Prerequisito</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Una macchina Ubuntu (20.04 o superiore raccomandata)</p> </li> <li> <p>Connessione Internet</p> </li> <li> <p>Competenza da riga di comando (livello principiante a intermedio)</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_installare_e_configurare_gli_strumenti">Installare e configurare gli strumenti</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lm_sensors_per_rilevare_i_sensori">lm-sensors` per rilevare i sensori</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install lm-sensors sudo sensors-detect sensors</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Rispondi`YES`a tutte le domande di`sensors-detect`per rilevare i moduli.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_tlp_gestore_intelligente_dellenergia">tlp` : gestore intelligente dell’energia</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install tlp tlp-rdw sudo systemctl enable tlp sudo systemctl start tlp</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="tlp_etat.svg" alt="tlp etat" width="370" height="432"> </div> </div> </div> <div class="sect2"> <h3 id="_cpufrequtils_limitare_le_frequenze_della_cpu">cpufrequtils` : limitare le frequenze della CPU</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install cpufrequtils cpufreq-info sudo cpufreq-set -g powersave</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>powersave</code>: limita i picchi di frequenza</p> </li> <li> <p><code>performance</code>: favorisce la potenza a scapito della temperatura</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_auto_cpufreq_gestione_dinamica_semplificata">auto-cpufreq` : gestione dinamica semplificata</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git clone https://github.com/AdnanHodzic/auto-cpufreq.git cd auto-cpufreq sudo ./auto-cpufreq-installer sudo auto-cpufreq --install</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="auto_cpufreq_cycle.svg" alt="auto cpufreq cycle" width="189" height="298"> </div> </div> </div> <div class="sect2"> <h3 id="_thermald_protezione_termica_automatica">thermald` : protezione termica automatica</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install thermald sudo systemctl enable thermald sudo systemctl start thermald</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_monitoraggio_in_tempo_reale">Monitoraggio in tempo reale</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sensors_da_riga_di_comando">sensors` da riga di comando</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">watch -n 2 sensors</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_opzione_gui_psensor">Opzione GUI: `psensor</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install psensor</code></pre> </div> </div> <div class="paragraph"> <p>Interfaccia grafica semplice per CPU, GPU, ventole.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_consigli_aggiuntivi">Consigli aggiuntivi</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Chiudere le schede e le applicazioni pesanti (es: browser)</p> </li> <li> <p>Evitare gli utilizzi intensivi sulla batteria</p> </li> <li> <p>Monitorare i processi via`htop`:</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install htop htop</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pulire_il_sistema_per_limitare_i_sovraccarichi">Pulire il sistema per limitare i sovraccarichi</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt autoremove sudo apt autoclean sudo journalctl --vacuum-time=3d</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_per_andare_oltre">Per andare oltre</h2> <div class="sectionbody"> <div class="paragraph"> <p>Puoi creare un servizio`systemd`personalizzato per applicare automaticamente alcune impostazioni all’avvio. Vorresti un esempio in un prossimo articolo? Fammelo sapere!</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">📚 Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Combinando questi semplici strumenti, otterrai:</p> </div> <div class="ulist"> <ul> <li> <p>Una temperatura CPU controllata</p> </li> <li> <p>Meno rumore di ventilazione</p> </li> <li> <p>Una migliore autonomia</p> </li> </ul> </div> <div class="paragraph"> <p>Non dimenticare di monitorare le tue temperature regolarmente per prevenire qualsiasi surriscaldamento.</p> </div> <div class="paragraph"> <p>(empty) Meglio prevenire che fondere la propria CPU <em>__</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0082_ui_struggle_post.html Mon, 14 Jul 2025 00:00:00 +0000 blog/2025/0082_ui_struggle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_il_campo_di_battaglia_un_mockup_tre_browser_rendering_multipli">Il campo di battaglia: un mockup, tre browser, rendering multipli</a></li> <li><a href="#_problema_1_la_carta_volante_della_sezione_hero">Problema 1 : La carta volante della sezione "Hero</a></li> <li><a href="#_problema_2_la_barra_di_navigazione_cannibale">Problema 2 : La barra di navigazione cannibale</a></li> <li><a href="#_problema_3_la_tipografia_anarchica">Problema 3: La tipografia anarchica</a></li> <li><a href="#_problema_4_la_barra_di_navigazione_che_deborda">Problema 4: La barra di navigazione che deborda</a></li> <li><a href="#_problema_5_il_menu_hamburger_invisibile">Problema 5 : Il menu hamburger invisibile</a></li> <li><a href="#_conclusion_le_lezioni_di_un_debug_ostinato">Conclusion: le lezioni di un debug ostinato</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Tempo di lettura :</strong> circa 7 minuti <strong>Livello :</strong> Intermedio</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>In questo caso pratico dettagliato, analizzeremo i problemi di compatibilità con i browser più comuni e talvolta più frustranti incontrati durante la creazione di una maquetta UI con Bootstrap 5.2. Dalla gestione Flexbox alla sottigliezza del rendering dei caratteri, scopri il nostro percorso di debug per trasformare un design traballante su Firefox in un’esperienza pixel-perfect su tutti i browser.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_il_campo_di_battaglia_un_mockup_tre_browser_rendering_multipli">Il campo di battaglia: un mockup, tre browser, rendering multipli</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ogni sviluppatore front-end conosce questa sensazione. Dopo ore di lavoro, la bozza è finalmente perfetta. Gli allineamenti sono netti, la tipografia è elegante, le animazioni sono fluide. Si tira un sospiro di soddisfazione, si ammira il proprio lavoro su Chrome (o Brave, o Edge), poi, per acquisito di coscienza, si apre il progetto su Firefox. Ed è qui che nasce il dramma. Elementi che fuoriescono, allineamenti rotti, caratteri con dimensioni caotiche…​ la bella armonia se ne è andata.</p> </div> <div class="paragraph"> <p>È precisamente lo scenario che abbiamo affrontato sviluppando una nuova interfaccia di portfolio. Le specifiche erano semplici: una homepage moderna, responsive, con un selettore di temi (chiaro, scuro e ad alto contrasto), utilizzando <strong>vanilla JavaScript</strong> e l’ultima versione di <strong>Bootstrap 5.2</strong>.</p> </div> <div class="paragraph"> <p>Questo articolo non è una lista di soluzioni miracolose. È il registro di bordo della nostra sessione di debug, un’approfondimento sul "perché" delle differenze di rendering tra i motori Blink (Chromium, Brave) e Gecko (Firefox), e la dimostrazione che soluzioni robuste e moderne valgono sempre meglio di toppe affrettate.</p> </div> <div class="paragraph"> <p>Diagramma dei casi d’uso: il processo di debug</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/usecase-debugging-firefox.svg" alt="usecase debugging firefox" width="1025" height="402"> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/components-solution-architecture.svg" alt="components solution architecture" width="1278" height="188"> </div> <div class="title">Figure 1. Diagramma dei Componenti : Architettura della soluzione front-end</div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_1_la_carta_volante_della_sezione_hero">Problema 1 : La carta volante della sezione "Hero</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il primo bug era anche il più visibile. La sezione di benvenuto ("hero") è composta da due colonne: a sinistra, il titolo principale; a destra, una carta di presentazione.</p> </div> <div class="ulist"> <ul> <li> <p><strong>Il sintomo :</strong>Su Chrome e Brave, le due colonne erano perfettamente centrate verticalmente. Su Firefox, la carta di destra cadeva inspiegabilmente sotto il testo di sinistra.</p> </li> <li> <p><strong>L’investigazione :</strong>Il codice HTML sembrava però semplice e corretto, utilizzando le classi standard di Bootstrap.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container"> <!-- Cette ligne est la clé du problème --> <div class="row align-items-center min-vh-100"> <div class="col-lg-6"> <!-- Contenu de gauche --> </div> <div class="col-lg-6"> <!-- Carte de droite --> </div> </div> </div> </section></code></pre> </div> </div> <div class="paragraph"> <p>Nostro CSS personalizzato per`.hero-section`definiva`display: flex` et <code>align-items: center</code>, e la classe`min-vh-100`dava effettivamente un’altezza minima alla riga (<code>div.row</code>). Allora, perché Firefox rifiutava di centrare le colonne?</p> </div> <div class="ulist"> <ul> <li> <p><strong>La causa profonda :</strong>È un caso d’esempio sul modo in cui i motori di rendering interpretano le altezze implicite. La`<section>`aveva una`min-height`, ma nessun`height`esplicito. Per applicare`align-items-center`all’interno di`div.row`, Firefox ha bisogno di conoscere l’altezza di riferimento di questo contenitore. Come i suoi genitori (<code>div.container</code> et la `<section>`ella stessa) non avevano altezza<strong>stricta</strong>, Firefox era perso. Il motore Blink, più permissivo, riesce a "indovinare" l’intenzione e a centrare gli elementi. Gecko, più fedele alla specifica, non lo fa.</p> </li> <li> <p><strong>La soluzione:</strong>Rendere l’altezza esplicita. Abbiamo forzato il`.container` et le `.row`occupare il 100% dell’altezza del loro rispettivo genitore utilizzando la classe di utilità`h-100`di Bootstrap.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container h-100"> <div class="row align-items-center min-vh-100 h-100"> <!-- ... --> </div> </div> </section></code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>Quando un`align-items`Flexbox non funziona come previsto sull’asse verticale, verifica sempre che il contenitore abbia un’altezza (<code>height</code> ou <code>min-height</code>) definita e, se il problema persiste (soprattutto su Firefox), assicurati che i contenitori genitori intermedi trasmettano correttamente questa altezza.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_problema_2_la_barra_di_navigazione_cannibale">Problema 2 : La barra di navigazione cannibale</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">Una volta allineata la sezione "Hero", è comparso un altro problema: la barra di navigazione, con la sua classe`fixed-top`, si sovrapponeva al titolo. Un`padding-top: 80px`era stato applicato alla sezione 'Hero' come soluzione.</div> <ul> <li> <p><strong>Il sintomo :</strong> Le `padding`era sufficiente su Chrome, ma non su Firefox, dove il titolo era sempre parzialmente mascherato.</p> </li> <li> <p><strong>La causa profonda :</strong>L’utilizzo di un "numero magico" (")<code>80px</code>) è una pratica molto pessima. L’altezza di un elemento come una barra di navigazione può variare di pochi pixel da un browser all’altro a causa di differenze sottili nel rendering dei caratteri, degli spaziature, o persino delle impostazioni dell’utente. Fare affidamento su un valore fisso è la ricetta per un design fragile.</p> </li> <li> <p><strong>La soluzione :</strong>Una soluzione dinamica e infallibile in JavaScript. Abbiamo scritto un piccolo script per :</p> </li> <li> <p>Misurare l’altezza <strong>reale</strong> della barra di navigazione dopo il rendering della pagina.</p> </li> <li> <p>Applicare questa altezza misurata come`padding-top`alla sezione "Hero".</p> </li> <li> <p>Re-eseguire questa funzione ad ogni ridimensionamento della finestra per adattarsi alle modifiche (come il passaggio al menu hamburger).</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function() { function adjustHeroPadding() { const navbar = document.querySelector('.navbar.fixed-top'); const heroSection = document.querySelector('.hero-section'); if (navbar && heroSection) { const navbarHeight = navbar.offsetHeight; heroSection.style.paddingTop = navbarHeight + 'px'; } } // Ajuster au chargement et au redimensionnement adjustHeroPadding(); window.addEventListener('resize', adjustHeroPadding); });</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/sequence-dynamic-padding.svg" alt="sequence dynamic padding" width="887" height="703"> </div> <div class="title">Figure 2. Diagramma di sequenza : Regolazione dinamica del padding</div> </div> <div class="paragraph"> <p>In parallelo, naturalmente abbiamo eliminato la regola`padding-top: 80px;`del nostro file`styles.css`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_3_la_tipografia_anarchica">Problema 3: La tipografia anarchica</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">Il problema successivo era il più dannoso per l’immagine di marca: la dimensione del titolo principale.</div> <ul> <li> <p><strong>Il sintomo :</strong>Su Firefox, il carattere del titolo "Développeur Formateur…​" era enorme, quasi sconvolgente, mentre era armonioso sugli altri browser.</p> </li> <li> <p><strong>La causa profonda :</strong>Il titolo utilizzava una classe`display-4`di Bootstrap. Queste classi utilizzano dimensioni di carattere responsive, spesso basate sull’unità`rem`e delle media query. Ancora una volta, l’algoritmo di rendering di Firefox, combinato con il carattere "Inter", dava origine a un calcolo di dimensioni molto più grande sulla nostra risoluzione di 1920x1080.</p> </li> <li> <p><strong>La soluzione :</strong>Riprendere il controllo con la funzione CSS`clamp()<code>. Questa funzione è una rivoluzione per la tipografia fluida. Consente di definire una dimensione del carattere con tre valori: una dimensione minima, una dimensione "preferita" (che si adatta alla larghezza della vista,`vw</code>), e una dimensione massima.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.hero-content h1 { color: var(--text-primary); line-height: 1.2; /* Min: 2rem Préférée: s'adapte à la vue Max: 2.5rem (40px) */ font-size: clamp(2rem, 1.2rem + 1.5vw, 2.5rem); }</code></pre> </div> </div> <div class="paragraph"> <p>Con`clamp()<code>, noi abbiamo potuto dire al navigatore: "Fai ingrandire il carattere insieme allo schermo, ma non superare<strong>mai</strong>il limite di`2.5rem</code>. Questo ha istantaneamente armonizzato il rendering su tutti i browser, dandoci un controllo assoluto sull’aspetto finale.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_4_la_barra_di_navigazione_che_deborda">Problema 4: La barra di navigazione che deborda</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">È stato il problema che ci ha dato più filo da torcere e che ha infine rivelato la natura profonda delle micro-differenze di rendering.</div> <ul> <li> <p><strong>Il sintomo :</strong>Su uno schermo 1920x1080, gli ultimi collegamenti del menu (« Blog », « Contact ») venivano spinti fuori dallo schermo verso destra, ma solo su Firefox.</p> </li> <li> <p><strong>La causa profonda:</strong>Dopo diversi tentativi infruttuosi (cambiare i punti di interruzione di Bootstrap di`lg` à <code>xl`poi`xxl</code>), abbiamo capito. La causa non era la logica di Bootstrap, ma un semplice calcolo di larghezza. Su Firefox, la somma delle larghezze di tutti i link, incluse le loro`padding` et `margin`A livello di subpixel, era <strong>leggermente</strong> superiore a 1920 pixel. Su Chrome, questa stessa somma era <strong>leggermente</strong> inferiore. Ci mancavano alcuni pixel.</p> </li> <li> <p><strong>La soluzione:</strong>Una riduzione chirurgica degli spaziature. Dato che era fuori questione prendere di mira specificamente Firefox con gli obsoleti "hack" CSS, l’unica soluzione pulita era trovare uno stile comune che funzionasse ovunque. Abbiamo quindi leggermente ridotto i margini e il padding orizzontali di ogni link di navigazione.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* La version finale, légèrement plus compacte */ .navbar-nav .nav-link { font-size: 0.9rem; /* 90% de la taille de base */ color: var(--text-primary) !important; font-weight: 500; margin: 0 0.2rem; padding: 0.5rem 0.5rem !important; border-radius: 0.375rem; transition: all 0.3s ease; }</code></pre> </div> </div> <div class="paragraph"> <p>Questa riduzione, quasi invisibile a occhio nudo su un solo elemento, ci ha fatto guadagnare collettivamente lo spazio necessario affinché tutti i link entrino nel riquadro su Firefox, mantenendo al contempo un aspetto quasi identico sugli altri browser.</p> </div> </div> </div> <div class="sect1"> <h2 id="_problema_5_il_menu_hamburger_invisibile">Problema 5 : Il menu hamburger invisibile</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">L’ultimo problema, e non di poco conto, riguardava l’accessibilità su mobile.</div> <ul> <li> <p><strong>Il sintomo:</strong>In modalità responsive (menu "hamburger"), l’icona del menu era invisibile sui temi "dark" e "high-contrast".</p> </li> <li> <p><strong>La causa profonda:</strong>L’icona del menu di Bootstrap 5 è un`background-image`(un SVG codificato in URL). Per impostazione predefinita, il colore del suo tratto è scuro, ottimizzato per uno sfondo chiaro. Non si adatta automaticamente al cambio di tema.</p> </li> <li> <p><strong>La soluzione :</strong>Utilizzare le variabili CSS di Bootstrap per sovrascrivere l’icona. Abbiamo definito una nuova icona SVG, ma questa volta con un tratto bianco (<code>#ffffff</code>), e l’abbiamo applicata specificamente quando i temi`dark` ou `high-contrast`sono attivi.</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* ====================== Fix pour l'icône du menu Burger (Blanc) ====================== */ [data-bs-theme="dark"] .navbar-toggler-icon, [data-bs-theme="high-contrast"] .navbar-toggler-icon { --bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23ffffff' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e"); }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>La personalizzazione dei componenti di Bootstrap come questo viene effettuata sempre più spesso tramite la sovrascrittura delle variabili CSS (<code>--bs-component-property</code>), che è il metodo più pulito e più durevole.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_lezioni_di_un_debug_ostinato">Conclusion: le lezioni di un debug ostinato</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questo percorso, sebbene a volte frustrante, è ricco di insegnamenti. Ogni problema risolto rafforza una verità fondamentale dello sviluppo web:<strong>Nulla sostituisce un test multi-browser rigoroso</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/mindmap-debugging-summary.svg" alt="mindmap debugging summary" width="999" height="866"> </div> <div class="title">Figure 3. Mindmap : Sintesi del debug e delle lezioni apprese</div> </div> <div class="olist arabic"> <div class="title">Ecco le lezioni che conserviamo:</div> <ol class="arabic"> <li> <p><strong>Firefox è un alleato:</strong>La sua massima fedeltà agli standard CSS ci costringe a scrivere un codice più robusto e meno ambiguo.</p> </li> <li> <p><strong>Fuggite i "numeri magici":</strong>I valori fissi (come`padding-top: 80px`) sono bombe a orologeria. Preferite sempre soluzioni dinamiche (JavaScript) o relative (Flexbox, Grid).</p> </li> <li> <p><strong>Padroneggia la tua tipografia :</strong>Utilizzate`clamp()`per un controllo totale sulla dimensione dei caratteri responsive.</p> </li> <li> <p><strong>Pensa in "componenti":</strong>Per personalizzare Bootstrap, sovrascrivi le sue variabili CSS anziché moltiplicare le regole che sovrascrivono il framework.</p> </li> <li> <p><strong>Non puntare a un browser:</strong>La soluzione quasi mai consiste nel fare un "hack" per un browser specifico, ma nel trovare uno stile comune che funzioni ovunque.</p> </li> </ol> </div> <div class="paragraph"> <p>Alla fine, la maquetta è ormai stabile, prevedibile e pronta per essere incorporata in un sistema di templating. Ogni bug corretto non era un insuccesso, ma un passo verso un codice di migliore qualità.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0081_TDD_Gradle_Properties_Fix_post.html Sun, 13 Jul 2025 00:00:00 +0000 blog/2025/0081_TDD_Gradle_Properties_Fix_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_il_problema_isolare_i_test_unitari_di_un_plugin_gradle">Il problema: Isolare i test unitari di un plugin Gradle</a> <ul class="sectlevel2"> <li><a href="#_architettura_del_problema">Architettura del Problema</a></li> <li><a href="#_la_tentazione_di_una_falsa_buona_idea">La tentazione di una falsa buona idea</a></li> </ul> </li> <li><a href="#_la_soluzione_simulare_la_proprietà_con_extrapropertiesextension">La Soluzione : Simulare la Proprietà con `ExtraPropertiesExtension</a> <ul class="sectlevel2"> <li><a href="#_passo_1_comprendere_extrapropertiesextension">Passo 1: Comprendere ExtraPropertiesExtension</a></li> <li><a href="#_passo_2_impostazione_del_test_preparazione">Passo 2: Impostazione del Test - Preparazione</a></li> <li><a href="#_passo_3_iniezione_della_proprietà">Passo 3 : Iniezione della Proprietà</a></li> <li><a href="#_passo_4_diagramma_di_flusso_della_soluzione">Passo 4 : Diagramma di Flusso della Soluzione</a></li> <li><a href="#_passo_5_confronto_primadopo">Passo 5 : Confronto Prima/Dopo</a></li> <li><a href="#_passo_6_gestione_dei_casi_di_test_multipli">Passo 6 : Gestione dei casi di test multipli</a></li> <li><a href="#_architettura_finale_della_soluzione">Architettura finale della soluzione</a></li> </ul> </li> <li><a href="#_i_vantaggi_di_questo_approccio">I vantaggi di questo approccio</a></li> <li><a href="#_buone_pratiche_e_consigli">Buone pratiche e consigli</a> <ul class="sectlevel2"> <li><a href="#_creare_un_metodo_utilitario">Creare un metodo utilitario</a></li> <li><a href="#_validazione_delle_proprietà">Validazione delle Proprietà</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div class="sect1"> <h2 id="_il_problema_isolare_i_test_unitari_di_un_plugin_gradle">Il problema: Isolare i test unitari di un plugin Gradle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante la scrittura di test unitari per un plugin Gradle, una sfida comune è gestire le dipendenze dalla configurazione del progetto, come le proprietà definite nel file`gradle.properties`. Nel nostro caso, il plugin`jbake.ghpages`devait leggere una proprietà`site_config_path`per funzionare correttamente. Il test unitario per il compito`initialize`doveva verificare il comportamento del plugin in presenza di questa proprietà.</p> </div> <div class="paragraph"> <p>Il problema fondamentale è che i test unitari, per progettazione, devono essere <strong>isolati</strong>. L’utilizzo di`ProjectBuilder`di Gradle crea un’istanza di`Project`in memoria, completamente scollegata da un vero progetto sul sistema di file. Di conseguenza, questa istanza di test non legge automaticamente il file`gradle.properties`e quindi non ha conoscenza della proprietà`site_config_path`.</p> </div> <div class="sect2"> <h3 id="_architettura_del_problema">Architettura del Problema</h3> <div class="paragraph"> <p>Il diagramma seguente illustra la disconnessione tra l’ambiente di test e il sistema di file:</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/test-isolation-problem.svg" alt="test isolation problem" width="833" height="295"> </div> </div> </div> <div class="sect2"> <h3 id="_la_tentazione_di_una_falsa_buona_idea">La tentazione di una falsa buona idea</h3> <div class="paragraph"> <p>Un primo approccio potrebbe essere di creare un file`gradle.properties`fittizio nelle risorse del test.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">// src/test/resources/gradle.properties site_config_path=src/jbake/settings/site.yml</code></pre> </div> </div> <div class="paragraph"> <p>Tuttavia, questo metodo è destinato al fallimento perché`ProjectBuilder`non è progettato per eseguire la scansione del file system alla ricerca di file di configurazione. Il test rimarrebbe isolato e ignorerebbe questo file.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_simulare_la_proprietà_con_extrapropertiesextension">La Soluzione : Simulare la Proprietà con `ExtraPropertiesExtension</h2> <div class="sectionbody"> <div class="paragraph"> <p>La soluzione elegante a questo problema non è <strong>leggere</strong> il file, ma <strong>simulare</strong> la presenza della proprietà direttamente nell’oggetto`Project`di test. Gradle fornisce un meccanismo potente per questo : le <strong>proprietà aggiuntive</strong> (Extra Properties).</p> </div> <div class="sect2"> <h3 id="_passo_1_comprendere_extrapropertiesextension">Passo 1: Comprendere ExtraPropertiesExtension</h3> <div class="paragraph"> <p>`ExtraPropertiesExtension`è un contenitore chiave-valore collegato a ogni oggetto del modello Gradle. Consente di aggiungere proprietà dinamicamente a un progetto, una task o qualsiasi altra estensione Gradle.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/extra-properties-architecture.svg" alt="extra properties architecture" width="533" height="436"> </div> </div> </div> <div class="sect2"> <h3 id="_passo_2_impostazione_del_test_preparazione">Passo 2: Impostazione del Test - Preparazione</h3> <div class="paragraph"> <p>Cominciamo creando la struttura di base del nostro test unitario :</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Structure de base</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File @Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Suite des étapes... } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_passo_3_iniezione_della_proprietà">Passo 3 : Iniezione della Proprietà</h3> <div class="paragraph"> <p>Ecco il processo dettagliato per iniettare la proprietà nel progetto di test :</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Injection complète</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé en mémoire val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Étape 2 : Récupérer le gestionnaire de propriétés supplémentaires val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) // Étape 3 : Définir la propriété requise pour ce test extra.set("site_config_path", "src/jbake/settings/site.yml") // Étape 4 : Vérifier que la propriété est bien injectée assertTrue(project.hasProperty("site_config_path")) // Étape 5 : Appliquer le plugin qui pourra maintenant accéder à la propriété project.plugins.apply("jbake.ghpages") // Étape 6 : Exécuter la tâche et vérifier son comportement val task: Task = project.tasks.findByName("initialize") .apply(::assertNotNull)!! // Étape 7 : Exécuter les actions de la tâche task.actions.forEach { it.execute(task) } // Étape 8 : Assertions finales assertEquals( "src/jbake/settings/site.yml", project.properties["site_config_path"], "La propriété devrait être accessible dans le projet" ) }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_passo_4_diagramma_di_flusso_della_soluzione">Passo 4 : Diagramma di Flusso della Soluzione</h3> <div class="imageblock"> <div class="content"> <img src="./images/solution-flow.svg" alt="solution flow" width="242" height="807"> </div> </div> </div> <div class="sect2"> <h3 id="_passo_5_confronto_primadopo">Passo 5 : Confronto Prima/Dopo</h3> <div class="imageblock"> <div class="content"> <img src="./images/before-after-comparison.svg" alt="before after comparison" width="1484" height="399"> </div> </div> </div> <div class="sect2"> <h3 id="_passo_6_gestione_dei_casi_di_test_multipli">Passo 6 : Gestione dei casi di test multipli</h3> <div class="paragraph"> <p>Per testare diversi scenari, creiamo più test con configurazioni varie:</p> </div> <div class="listingblock"> <div class="title">Tests multiples avec configurations différentes</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File private fun createProjectWithProperty(propertyValue: String?): Project { val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Injection conditionnelle de la propriété propertyValue?.let { value -> val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) extra.set("site_config_path", value) } return project } @Test fun `should work with valid property`() { val project = createProjectWithProperty("src/jbake/settings/site.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! task.actions.forEach { it.execute(task) } // Assertions pour le cas normal assertEquals("src/jbake/settings/site.yml", project.properties["site_config_path"]) } @Test fun `should handle missing property gracefully`() { val project = createProjectWithProperty(null) // Pas de propriété project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Le plugin devrait gérer l'absence de propriété assertDoesNotThrow { task.actions.forEach { it.execute(task) } } } @Test fun `should handle invalid property path`() { val project = createProjectWithProperty("invalid/path/to/config.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Test du comportement avec un chemin invalide assertThrows<FileNotFoundException> { task.actions.forEach { it.execute(task) } } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_architettura_finale_della_soluzione">Architettura finale della soluzione</h3> <div class="imageblock"> <div class="content"> <img src="./images/final-architecture.svg" alt="final architecture" width="754" height="631"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_i_vantaggi_di_questo_approccio">I vantaggi di questo approccio</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Isolamento completo</strong>Il test non dipende da alcun file esterno. È autonomo e può essere eseguito in modo affidabile in qualsiasi ambiente (locale, CI/CD, ecc.).</p> </li> <li> <p><strong>Chiarezza e Intenzione</strong>: Il test dichiara esplicitamente le condizioni preliminari per la sua esecuzione. Chiunque legge il test vede immediatamente che il plugin richiede la proprietà`site_config_path`per funzionare.</p> </li> <li> <p><strong>Manutenibilità</strong>: Se il nome della proprietà cambia, basta aggiornarlo in un unico punto nel test, senza dover manipolare i file di configurazione di test.</p> </li> <li> <p><strong>Flessibilità</strong>: Diventa banale testare diversi scenari semplicemente cambiando il valore della proprietà iniettata in ogni test (valore valido, non valido, assente, ecc.).</p> </li> <li> <p><strong>Performance</strong>: Nessuna lettura di file, tutto avviene in memoria, il che rende i test più veloci.</p> </li> <li> <p><strong>Riproducibilità</strong>: I test sono deterministici perché non dipendono dallo stato del sistema di file.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche_e_consigli">Buone pratiche e consigli</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_creare_un_metodo_utilitario">Creare un metodo utilitario</h3> <div class="listingblock"> <div class="title">Méthode utilitaire pour la réutilisation</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GradleTestUtils { companion object { fun createProjectWithProperties( projectDir: File, properties: Map<String, String> ): Project { val project = ProjectBuilder.builder() .withProjectDir(projectDir) .build() val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) properties.forEach { (key, value) -> extra.set(key, value) } return project } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_validazione_delle_proprietà">Validazione delle Proprietà</h3> <div class="listingblock"> <div class="title">Validation robuste</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `should validate property injection`() { val project = createProjectWithProperty("test-value") // Vérifications multiples assertTrue(project.hasProperty("site_config_path")) assertEquals("test-value", project.property("site_config_path")) assertNotNull(project.properties["site_config_path"]) // Vérification que la propriété est accessible par le plugin project.plugins.apply("jbake.ghpages") // ... reste du test }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Invece di lottare per far leggere i file di configurazione a un ambiente di test unitario, la pratica migliore consiste nel simulare lo stato richiesto. L’uso di`ExtraPropertiesExtension`Definire a livello di programmazione le proprietà Gradle è il metodo più pulito e robusto per realizzare test unitari di plugin efficaci e affidabili.</p> </div> <div class="paragraph"> <p>Questa tecnica trasforma un problema di dipendenza esterna in una semplice iniezione di dipendenza, al cuore stesso della filosofia del Test-Driven Development (TDD). Offre un controllo totale sull’ambiente di test mantenendo l’isolamento necessario per test unitari di qualità.</p> </div> <div class="paragraph"> <p>I diagrammi e gli esempi presentati in questo articolo mostrano come questo approccio possa essere implementato in modo progressivo e metodico, consentendo di creare una suite di test robusta e mantenibile per i tuoi plugin Gradle.</p> </div> </div> </div> https://cheroliv.com/blog/2025/0079_gradle_tasks_tests_report_post.html Fri, 11 Jul 2025 00:00:00 +0000 blog/2025/0079_gradle_tasks_tests_report_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_centralizzare_le_configurazioni_con_allprojects_e_subprojects">Centralizzare le Configurazioni con <code>allprojects</code> e `subprojects</a></li> <li><a href="#_sourceplantuml">[source,plantuml]</a></li> <li><a href="#_enduml">@enduml</a></li> <li><a href="#_sourcekotlin">[source,kotlin]</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>L’automazione delle attività di build è cruciale per qualsiasi progetto software, e Gradle, con il suo DSL Kotlin, offre una flessibilità eccezionale. Durante la nostra conversazione, abbiamo esplorato come centralizzare e riutilizzare la logica di build, in particolare per i report dei test, sfruttando<strong>tutti i progetti</strong>, <strong>buildSrc</strong>, e attività personalizzate in Kotlin.</p> </div> </div> </div> <div class="sect1"> <h2 id="_centralizzare_le_configurazioni_con_allprojects_e_subprojects">Centralizzare le Configurazioni con <code>allprojects</code> e `subprojects</h2> <div class="sectionbody"> <div class="paragraph"> <p>i blocchi`allprojects` et `subprojects`nel vostro`build.gradle.kts`La radice è fondamentale per applicare configurazioni comuni in tutto il tuo progetto multi-modulo.</p> </div> <div class="paragraph"> <p>*<code>allprojects { …​ }</code>: Applica la configurazione a<strong>progetto radice e a tutti i suoi sottoprogetti</strong>. Ideale per definire un`group`, una`version`, o alcuni`repositories`comuni. *<code>subprojects { …​ }</code>: Applica la configurazione<strong>solo ai sottoprogetti</strong>, escluso il progetto radice. Perfetto per applicare plugin specifici ai moduli (come`java` ou <code>kotlin-jvm</code>) o dipendenze comuni alle tue librerie.</p> </div> <div class="paragraph"> <p>Ecco un esempio illustrativo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// build.gradle.kts (projet racine) plugins { base // Appliqué au projet racine } allprojects { group = "com.example" version = "1.0.0" repositories { mavenCentral() } tasks.withType<org.gradle.api.tasks.testing.Test> { useJUnitPlatform() // Configuration commune des tests pour tous les projets } } subprojects { apply(plugin = "java") apply(plugin = "org.jetbrains.kotlin.jvm") dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") } }</code></pre> </div> </div> <div class="paragraph"> <p>\== <code>buildSrc</code>: Il coltellino svizzero della logica di build</p> </div> <div class="paragraph"> <p>Quando la logica delle vostre attività diventa complessa o deve essere riutilizzata,<strong>buildSrc</strong>è la soluzione privilegiata. È un modulo Gradle speciale che viene compilato prima degli script di build principali, rendendo le sue classi disponibili sul classpath dell’intero build.</p> </div> <div class="paragraph"> <p>Perché utilizzare`buildSrc`per le attività ?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Riutilizzabilità</strong>: Un compito definito in`buildSrc`può essere applicata a qualsiasi progetto del build.</p> </li> <li> <p><strong>Organizzazione</strong>Centralizza il codice di build, rendendolo più pulito e mantenibile.</p> </li> <li> <p><strong>Sicurezza dei tipi e autocompletamento</strong>: Il codice Kotlin in`buildSrc`è compilato, offrendo la verifica degli errori e l’autocompletamento del tuo IDE, migliorando l’esperienza di sviluppo.</p> </li> </ul> </div> <div class="paragraph"> <p>\=== Diagramma di flusso`buildSrc`(Codice PlantUML)</p> </div> <div class="paragraph"> <p>Per generare questo diagramma, copia il codice qui sotto e incollalo in uno strumento che supporta PlantUML.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourceplantuml">[source,plantuml]</h2> <div class="sectionbody"> <div class="paragraph"> <p>@startuml skinparam manoscritto true skinparam monochrome true</p> </div> <div class="paragraph"> <p>rettangolo "Gradle Build Process" { componente "buildSrc" come BS { file "MyCustomTask.kt" come T file "MyConventionPlugin.kt" as P } componente "Root Project" come RP componente "Subproject A" come SA componente "Subproject B" come SB }</p> </div> <div class="paragraph"> <p>T --\> P : "è definito in viene applicato a P --\> SA : "è applicato a P --\> SB : "viene applicato a</p> </div> <div class="paragraph"> <p>RP --|\> SA : "contiene RP --|\> SB : "contiene</p> </div> <div class="paragraph"> <p>RP -up-\> BS : "dipende da (per la logica di build) SA -up-\> BS : "dipende da (per la logica di build) SB -up→ BS : "dipende da (per la logica di compilazione)</p> </div> <div class="paragraph"> <p>nota a destra di T Classi di task personalizzate (es: OpenTestReportTask) nota finale</p> </div> <div class="paragraph"> <p>note right of P Plugin di convenzione che registrano le attività end note</p> </div> </div> </div> <div class="sect1"> <h2 id="_enduml">@enduml</h2> <div class="sectionbody"> <div class="paragraph"> <p>Creazione di compiti di report astratti</p> </div> <div class="paragraph"> <p>Per gestire i rapporti di test, abbiamo progettato un approccio modulare utilizzando una classe di compito astratto nella`buildSrc`. Secondo le vostre esigenze, questa classe può ereditare`DefaultTask` ou de <code>Exec</code>.</p> </div> <div class="paragraph"> <p>\=== Compito Astratto`OpenTestReportTask`(ereditando da`DefaultTask`)</p> </div> <div class="paragraph"> <p>Questo approccio è consigliato se è necessario avere una logica Kotlin personalizzata che interagisce con il file system o altre API Gradle, quindi esegue un comando esterno.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>pacchetto com.yourpackage</p> </div> <div class="paragraph"> <p>import org.gradle.api.DefaultTask import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction importa java.io.File</p> </div> <div class="paragraph"> <p>abstract class OpenTestReportTask : DefaultTask() {}</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- init { group = "verification" description = "Opens a test report in Firefox." dependsOn("check") // Assure que les rapports sont générés } @get:Input abstract var reportPath: String @TaskAction fun openReport() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportPath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } project.exec { commandLine("firefox", "--new-tab", reportFile.absolutePath) } logger.lifecycle("Opened test report: ${reportFile.absolutePath}") } ---- ## } \\=== Implementazioni concrete Queste classi ereditano dal compito astratto e definiscono il percorso specifico del rapporto. ## [source,kotlin] pacchetto com.yourpackage abstract class ReportUnitTestsTask : OpenTestReportTask() inizializzazione { description = "Apre il rapporto dei test unitari in Firefox. reportPath = "build/reports/tests/test/index.html } } package com.yourpackage ## abstract class ReportFunctionalTestsTask : OpenTestReportTask() { init { description = "Apre il rapporto dei test funzionali in Firefox." reportPath = "build/reports/tests/functionalTest/index.html" } } Registrazione delle attività Nel`build.gradle.kts`del tuo progetto radice: ## [source,kotlin] tasks.register<com.yourpackage.ReportUnitTestsTask>("reportTests") {} tasks.register<com.yourpackage.ReportFunctionalTestsTask>("reportFunctionalTests") {} \=== Diagramma UML delle Attività del Rapporto (Code PlantUML) Copia il codice seguente e incollalo in uno strumento che supporta PlantUML. ## [source,plantuml] @startuml skinparam manoscritto vero skinparam monochrome true classe astratta DefaultTask { } classe astratta Exec { \+ commandLine(args: String...) \+ exec() } abstract class OpenTestReportTask extends DefaultTask { \+ group: String = "verifica \+ descrizione: String \+ dependsOn("check") + abstract reportPath: String \+ openReport() : void } classe astratta AbstractJbakeExecTask estende Exec { \+ gruppo: stringa = "verifica \+ descrizione: String \+ dependsOn("check") \+ abstract reportRelativePath: String \+ exec() : void } class ReportUnitTestsTask extends OpenTestReportTask { \ + reportPath: String = "build/reports/tests/test/index.html } class ReportFunctionalTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/functionalTest/index.html } class ReportJbakeTestsTask extends AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/test/index.html } class ReportJbakeFunctionalTestsTask extends AbstractJbakeExecTask { \+ percorsoRelativoRapporto: Stringa = "build/reports/tests/functionalTest/index.html } OpenTestReportTask \<-- ReportUnitTestsTask OpenTestReportTask \<-- ReportFunctionalTestsTask AbstractJbakeExecTask \<-- ReportJbakeTestsTask AbstractJbakeExecTask \<-- ReportJbakeFunctionalTestsTask DefaultTask \<|-- OpenTestReportTask Exec \<|-- AbstractJbakeExecTask DefaultTask \<|-- Exec ## @enduml \== Compito astratto`AbstractJbakeExecTask`(ereditando da`Exec`) Se il tuo compito consiste principalmente nell'eseguire un comando esterno con argomenti variabili, ereditare direttamente da**Esegui**è più diretto. ## [source,kotlin] package com.yourpackage import org.gradle.api.tasks.Exec import org.gradle.api.tasks.Input import java.io.File classe astratta AbstractJbakeExecTask : Exec() { ---- init { group = "verification" description = "Opens a Jbake project report in Firefox." dependsOn("check") } @get:Input abstract var reportRelativePath: String override fun exec() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportRelativePath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } commandLine("firefox", "--new-tab", reportFile.absolutePath) logger.lifecycle("Attempting to open report: ${reportFile.absolutePath}") super.exec() // Appelle la méthode exec() de la super-classe Exec } ## } \=== Implementazioni concrete per`Exec` ## [source,kotlin] pacchetto com.yourpackage classe astratta ReportJbakeTestsTask : AbstractJbakeExecTask() init { description = "Apre il rapporto di test unitario Jbake in Firefox. reportRelativePath = "build/reports/tests/test/index.html } } package com.yourpackage abstract class ReportJbakeFunctionalTestsTask : AbstractJbakeExecTask() { init { description = "Apre il rapporto di test funzionale in Firefox." reportRelativePath = "build/reports/tests/functionalTest/index.html" } } \== Visibilità delle Attività`buildSrc` Le attività e le classi che definisci in**buildSrc**sono : ***Visibili e utilizzabili**per tutti i progetti del tuo build principale (radice e sottoprogetti). Perciò puoi utilizzare`com.yourpackage.ReportUnitTestsTask`in`allprojects { ... }`. ***Non eseguibili**direttamente come attività di buildSrc (ad esempio,`gradle :buildSrc:reportTests`non funzionerebbe se il compito non fosse registrato specificamente in`buildSrc/build.gradle.kts`).`buildSrc`è un modulo di compilazione, non un modulo applicativo eseguibile per queste attività del build principale. Eseguire un rapporto per i test di`buildSrc`lui stesso Si `buildSrc`ha i suoi test e genera dei rapporti, è possibile registrare un'attività di rapporto direttamente in`buildSrc/build.gradle.kts`</think> ## [source,kotlin] plugins { `kotlin-jvm` } repositori { mavenCentral() } tasks.withType\<Test\> { useJUnitPlatform() reports.html.outputLocation.set(layout.buildDirectory.dir("reports/tests")) } import com.yourpackage.ReportJbakeTestsTask // Importa la tua classe di attività ## tasks.register<ReportJbakeTestsTask>("reportBuildSrcTests") { // Il percorso è già definito nella classe, punterà verso i rapporti di buildSrc } Potrai quindi eseguire :`./gradlew :buildSrc:test`seguito da`./gradlew :buildSrc:reportBuildSrcTests`. Adottando queste pratiche, costruirete sistemi di build Gradle in Kotlin DSL che non sono solo potenti, ma anche incredibilmente modulari, mantenibili e facili da comprendere.</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html Wed, 9 Jul 2025 00:00:00 +0000 blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_obiettivo">Obiettivo</a></li> <li><a href="#_configuration_déclarative">Configuration déclarative</a></li> <li><a href="#_architettura_del_plugin">Architettura del plugin</a></li> <li><a href="#_definizione_dellestensione_dsl">Definizione dell’estensione DSL</a></li> <li><a href="#_definizione_del_compito_personalizzato">Definizione del compito personalizzato</a></li> <li><a href="#_interfaccia_gitadapter">Interfaccia GitAdapter</a></li> <li><a href="#_implementazione_concreta_con_jgit">Implementazione concreta con JGit</a></li> <li><a href="#_configurazione_dsl_kotlin">Configurazione DSL Kotlin</a></li> <li><a href="#_test_unitari_con_mockito">Test unitari con Mockito</a> <ul class="sectlevel2"> <li><a href="#_dipendenze">Dipendenze</a></li> <li><a href="#_test_del_comportamento_git">Test del comportamento Git</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_prossimi_passi">Prossimi passi</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Questo articolo presenta l’intero approccio di progettazione e di test (TDD) di un plugin Gradle scritto in Kotlin DSL. Questo plugin automatizza la generazione di siti statici con <strong>JBake</strong> e il <strong>deployment Git</strong> tramite <strong>JGit</strong>, il tutto a partire da un file YAML di configurazione.</p> </div> </div> </div> <div class="sect1"> <h2 id="_obiettivo">Obiettivo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Creare un plugin Gradle :</p> </div> <div class="ulist"> <ul> <li> <p>configurabile in Kotlin DSL ;</p> </li> <li> <p>capace di:</p> </li> <li> <p>generare un sito statico da JBake ;</p> </li> <li> <p>deployare su un repository Git remoto via JGit;</p> </li> <li> <p>integrabile in un workflow CI/CD;</p> </li> <li> <p>testato secondo un approccio TDD.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_configuration_déclarative">Configuration déclarative</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ecco un esempio di configurazione YAML da modellare nel nostro DSL :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/trainings.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com"</code></pre> </div> </div> <div class="paragraph"> <p>Questa configurazione è rappresentata da un’estensione Gradle dichiarabile in Kotlin DSL.</p> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_del_plugin">Architettura del plugin</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/jbake-asciidoctor-class-diagram.png" alt="jbake asciidoctor class diagram" width="568" height="261"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definizione_dellestensione_dsl">Definizione dell’estensione DSL</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">open class WorkspaceEngineExtension { var outputDir: String = "build/site" var template: String = "freemarker" var repoUrl: String = "" var branch: String = "main" var message: String = "Generated by engine" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definizione_del_compito_personalizzato">Definizione del compito personalizzato</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class GenerateSiteTask : DefaultTask() { lateinit var gitAdapter: GitAdapter @get:Input abstract val repoUrl: Property<String> @get:InputDirectory abstract val outputDir: DirectoryProperty @get:Input abstract val branch: Property<String> @get:Input abstract val message: Property<String> @TaskAction fun run() { val repo = gitAdapter.cloneRepository(repoUrl.get(), outputDir.get().asFile) gitAdapter.commitAndPush(repo, branch.get(), message.get()) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_interfaccia_gitadapter">Interfaccia GitAdapter</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">interface GitAdapter { fun cloneRepository(uri: String, directory: File): Repository fun commitAndPush(repo: Repository, branch: String, message: String) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_implementazione_concreta_con_jgit">Implementazione concreta con JGit</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JGitAdapter : GitAdapter { override fun cloneRepository(uri: String, directory: File): Repository { return Git.cloneRepository() .setURI(uri) .setDirectory(directory) .call() .repository } override fun commitAndPush(repo: Repository, branch: String, message: String) { Git(repo).use { it.add().addFilepattern(".").call() it.commit().setMessage(message).call() it.push().call() } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configurazione_dsl_kotlin">Configurazione DSL Kotlin</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">workspaceEngine { outputDir = "build/out" template = "freemarker" repoUrl = "https://github.com/cheroliv/trainings.git" branch = "main" message = "deploy from plugin" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_test_unitari_con_mockito">Test unitari con Mockito</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_dipendenze">Dipendenze</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">testImplementation("org.mockito:mockito-core:5.12.0") testImplementation("org.mockito.kotlin:mockito-kotlin:5.2.1") testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_test_del_comportamento_git">Test del comportamento Git</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GenerateSiteTaskMockitoTest { @TempDir lateinit var tempDir: File @Test fun `task should call clone and commitAndPush`() { val project = ProjectBuilder.builder().build() val task = project.tasks.create("generateSite", GenerateSiteTask::class.java) val mockGitAdapter = mock<GitAdapter>() val mockRepo = mock<Repository>() whenever(mockGitAdapter.cloneRepository(any(), any())).thenReturn(mockRepo) task.gitAdapter = mockGitAdapter task.repoUrl.set("https://github.com/cheroliv/test.git") task.outputDir.set(project.layout.projectDirectory.dir(tempDir.name)) task.branch.set("main") task.message.set("test commit") task.run() verify(mockGitAdapter).cloneRepository(eq("https://github.com/cheroliv/test.git"), any()) verify(mockGitAdapter).commitAndPush(eq(mockRepo), eq("main"), eq("test commit")) } }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/jbake-asciidoctor-sequence-diagram.png" alt="jbake asciidoctor sequence diagram" width="808" height="326"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>La separazione delle responsabilità via`GitAdapter`consente di applicare pienamente il TDD nello sviluppo di plugin Gradle :</p> </div> <div class="ulist"> <ul> <li> <p>le chiamate Git sono astratte e testabili ;</p> </li> <li> <p>la configurazione DSL è pulita e chiara;</p> </li> <li> <p>Il plugin rimane agnostico dell’implementazione reale.</p> </li> </ul> </div> <div class="paragraph"> <p>Questo approccio garantisce una elevata testabilità ed estensibilità (verso GitHub API, GitLab, etc.).</p> </div> </div> </div> <div class="sect1"> <h2 id="_prossimi_passi">Prossimi passi</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Integrare la generazione JBake come un`BakeAdapter`</p> </li> <li> <p>Aggiungere test di integrazione con`GradleRunner`</p> </li> <li> <p>Supportare il caricamento automatico dei file`site.yml`via SnakeYAML</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2025/0077_asciidoc_syntaxe_post.html Fri, 20 Jun 2025 00:00:00 +0000 blog/2025/0077_asciidoc_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_cosè_asciidoc">Cos’è AsciiDoc?</a> <ul class="sectlevel2"> <li><a href="#_perché_scegliere_asciidoc">Perché scegliere AsciiDoc?</a></li> </ul> </li> <li><a href="#_diagramma_di_caso_duso_use_case">Diagramma di caso d’uso (Use Case)</a></li> <li><a href="#_diagramma_mind_map">Diagramma Mind Map</a></li> <li><a href="#_diagramma_di_flusso">Diagramma di flusso</a></li> <li><a href="#_struttura_di_base_di_un_file_asciidoc">Struttura di base di un file AsciiDoc</a></li> <li><a href="#_sintassi_fondamentale">Sintassi fondamentale</a> <ul class="sectlevel2"> <li><a href="#_titoli_e_sezioni">Titoli e sezioni</a></li> <li><a href="#_testo_in_grassetto_corsivo_e_monospazio">Testo in grassetto, corsivo e monospazio</a></li> <li><a href="#_elenchi_puntati_e_numerati">Elenchi puntati e numerati</a></li> <li><a href="#_link_e_immagini">Link e immagini</a></li> <li><a href="#_blocchi_di_codice">Blocchi di codice</a></li> <li><a href="#_dipinti">dipinti</a></li> <li><a href="#_note_e_avvertenze">Note e avvertenze</a></li> </ul> </li> <li><a href="#_utilizzo_di_attributi_e_variabili">Utilizzo di attributi e variabili</a></li> <li><a href="#_casi_dutilizzo_comuni">Casi d’utilizzo comuni</a></li> <li><a href="#_buone_pratiche">Buone pratiche</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_per_andare_oltre">Per andare oltre</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Pubblico di riferimento :</em> Sviluppatori, redattori tecnici e chiunque desideri scrivere documentazione tecnica o articoli ricchi.</div> <p>AsciiDoc è un linguaggio di markup leggero, progettato per scrivere documenti tecnici strutturati, articoli, libri o ancora presentazioni. Si distingue per la sua leggibilità, la sua ricchezza sintattica e la sua capacità di generare vari formati (HTML, PDF, DocBook, ecc.). In questo articolo, esploreremo la sintassi essenziale di AsciiDoc e proporremo suggerimenti per un avvio rapido.</p> </div> </div> </div> <div class="sect1"> <h2 id="_cosè_asciidoc">Cos’è AsciiDoc?</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc è un linguaggio di descrizione di documenti, simile a Markdown ma più potente. Consente di strutturare efficacemente testi, titoli, elenchi, tabelle, blocchi di codice e molto altro ancora. La sua versatilità lo rende una scelta popolare per la documentazione di progetti open source, la redazione di libri e la pubblicazione web.</p> </div> <div class="sect2"> <h3 id="_perché_scegliere_asciidoc">Perché scegliere AsciiDoc?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Sintassi leggibile e intuitiva.</p> </li> <li> <p>Supporto nativo di strutture complesse (tabelle, note, avvisi, ecc.).</p> </li> <li> <p>Generazione multi-formato (HTML, PDF, ePub, DocBook…)</p> </li> <li> <p>Integrazione semplice con i generatori di siti statici come JBake o Antora.</p> </li> <li> <p>Personalizzazione avanzata con gli attributi e le estensioni.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramma_di_caso_duso_use_case">Diagramma di caso d’uso (Use Case)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un diagramma dei casi d’uso consente di presentare le interazioni principali tra gli utenti e il sistema. Ecco un esempio semplice per un sistema di documentazione :</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-381f40e6e0660c0c53433ff054330b76.png" alt="Diagram" width="423" height="258"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramma_mind_map">Diagramma Mind Map</h2> <div class="sectionbody"> <div class="paragraph"> <p>La mind map (carta mentale) è ideale per esplorare i concetti legati a AsciiDoc e le loro relazioni:</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e1560e9cc014158b6fbeed1e5ad8e138.png" alt="Diagram" width="394" height="527"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramma_di_flusso">Diagramma di flusso</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un diagramma di flusso permette di descrivere il processo di generazione di un documento AsciiDoc</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-51318d77b9e18062d3a9b751587670ae.png" alt="Diagram" width="299" height="361"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_struttura_di_base_di_un_file_asciidoc">Struttura di base di un file AsciiDoc</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un file AsciiDoc generalmente inizia con un titolo, attributi opzionali e poi il contenuto strutturato. Ecco un esempio minimale :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre Principal Auteur 2024-09-03 :toc: :icons: font Votre contenu commence ici...</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_sintassi_fondamentale">Sintassi fondamentale</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_titoli_e_sezioni">Titoli e sezioni</h3> <div class="paragraph"> <p>AsciiDoc supporta diversi livelli di titoli:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre de niveau 1 == Titre de niveau 2 === Titre de niveau 3 ==== Titre de niveau 4</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_testo_in_grassetto_corsivo_e_monospazio">Testo in grassetto, corsivo e monospazio</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">*gras* _italique_ `monospace`</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_elenchi_puntati_e_numerati">Elenchi puntati e numerati</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* Élément 1 * Élément 2 . Premier . Deuxième . Troisième</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_link_e_immagini">Link e immagini</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">Lien standard : https://asciidoc.org[AsciiDoc] Image : image::images/logo.png[AsciiDoc Logo]</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_blocchi_di_codice">Blocchi di codice</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">[source,python]</code></pre> </div> </div> <div class="paragraph"> <p>def hello(): Buongiorno AsciiDoc!</p> </div> </div> <div class="sect2"> <h3 id="_dipinti">dipinti</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">|=== | Colonne 1 | Colonne 2 | Valeur A | Valeur B | Valeur C | Valeur D |===</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_note_e_avvertenze">Note e avvertenze</h3> <div class="paragraph"> <p>AsciiDoc propone dei blocchi di informazione visiva:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">NOTE: Ceci est une note importante. TIP: Conseil utile pour l’utilisateur. WARNING: Attention à ce point.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_utilizzo_di_attributi_e_variabili">Utilizzo di attributi e variabili</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gli attributi personalizzati consentono di riutilizzare valori o di configurare i comportamenti:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:project-name: AsciiDoc Explorer Le projet s’appelle {project-name}.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casi_dutilizzo_comuni">Casi d’utilizzo comuni</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentation progetto open source (README, guide tecniche) - Redazione di libri e ebook - Generazione automatica di siti web statici (JBake, Antora) - Presentazioni tecniche</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche">Buone pratiche</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Utilizza titoli coerenti e un indice automatico (:toc:). - Privilegiate le ammonizioni per attirare l’attenzione sui punti chiave. - Struttura i tuoi file per facilitare la manutenzione. - Approfitta dei blocchi di codice annotati per illustrare esempi.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc è uno strumento potente e accessibile per scrivere qualsiasi documentazione tecnica o articolo strutturato. La sua sintassi ricca, combinata alla generazione multi-formato, ne fa un alleato di scelta per sviluppatori e redattori esigenti. Prova AsciiDoc nel tuo prossimo progetto e scopri la differenza!</p> </div> </div> </div> <div class="sect1"> <h2 id="_per_andare_oltre">Per andare oltre</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentazione ufficiale: <a href="https://asciidoc.org" class="bare">https://asciidoc.org</a> - Asciidoctor : <a href="https://asciidoctor.org" class="bare">https://asciidoctor.org</a> - JBake e AsciiDoc: <a href="https://jbake.org/docs/2.6.4/#asciidoc_support" class="bare">https://jbake.org/docs/2.6.4/#asciidoc_support</a></p> </li> </ul> </div> <div class="paragraph"> <p>Condividi le tue esperienze e consigli nei commenti!</p> </div> </div> </div> https://cheroliv.com/blog/2025/0076_port_forwarding_post.html Wed, 28 May 2025 00:00:00 +0000 blog/2025/0076_port_forwarding_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_il_problema_nat_e_indirizzi_privati">Il problema: NAT e indirizzi privati</a></li> <li><a href="#_passo_1_identifica_il_tuo_indirizzo_ip_pubblico">Passo 1: Identifica il tuo indirizzo IP pubblico</a></li> <li><a href="#_passo_2_conoscere_lindirizzo_ip_locale_della_tua_macchina_ubuntu">Passo 2: Conoscere l’indirizzo IP locale della tua macchina Ubuntu</a></li> <li><a href="#_passaggio_3_configurare_il_port_forwarding_sulla_tua_box">Passaggio 3: configurare il port forwarding sulla tua box</a> <ul class="sectlevel2"> <li><a href="#_accesso_allinterfaccia_di_amministrazione">Accesso all’interfaccia di amministrazione</a></li> <li><a href="#_configurazione_del_reindirizzamento">Configurazione del reindirizzamento</a></li> </ul> </li> <li><a href="#_passo_4_configurazione_del_servizio_su_ubuntu">Passo 4 : Configurazione del servizio su Ubuntu</a></li> <li><a href="#_passo_5_configurazione_del_firewall_ubuntu">Passo 5: configurazione del firewall Ubuntu</a></li> <li><a href="#_passo_6_test_e_validazione">Passo 6 : Test e validazione</a> <ul class="sectlevel2"> <li><a href="#_test_dalla_rete_locale">Test dalla rete locale</a></li> <li><a href="#_test_dallesterno">Test dall’esterno</a></li> </ul> </li> <li><a href="#_buone_pratiche_e_sicurezza">Buone pratiche e sicurezza</a> <ul class="sectlevel2"> <li><a href="#_sicurezza_di_base">Sicurezza di base</a></li> <li><a href="#_monitoraggio_delle_connessioni">Monitoraggio delle connessioni</a></li> <li><a href="#_uso_di_un_reverse_proxy">Uso di un reverse proxy</a></li> </ul> </li> <li><a href="#_alternative_al_port_forwarding">Alternative al port forwarding</a> <ul class="sectlevel2"> <li><a href="#_soluzioni_cloud">Soluzioni cloud</a></li> <li><a href="#_vps_e_proxy_inverso">VPS e proxy inverso</a></li> </ul> </li> <li><a href="#_risoluzione_dei_problemi">risoluzione dei problemi</a> <ul class="sectlevel2"> <li><a href="#_problemi_comuni">Problemi comuni</a></li> <li><a href="#_debug_rete">Debug rete</a></li> </ul> </li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="ulist"> <div class="title">Pubblico di riferimento : Intermedio</div> <ul> <li> <p><strong>Prerequisiti assunti</strong>: conoscenze di base di Ubuntu, del terminale, concetti di rete di base</p> </li> <li> <p><strong>Concetti tecnici</strong> : NAT, inoltro di porta, firewall, proxy inverso</p> </li> <li> <p><strong>Comandi di sistema</strong>: utilizzo del terminale, configurazione di rete</p> </li> <li> <p><strong>Sezioni avanzate</strong> : monitoraggio, sicurezza, alternative cloud</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_il_problema_nat_e_indirizzi_privati">Il problema: NAT e indirizzi privati</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Problematica : Stai sviluppando un’applicazione web sulla tua macchina Ubuntu e vuoi renderla accessibile dall’esterno della tua rete domestica? Sei nel posto giusto! In questo articolo vedremo come esporre un servizio locale (ad esempio sulla porta 8080) verso Internet configurando il port forwarding sulla tua box internet.</div> <p>Per impostazione predefinita, la tua box internet utilizza il NAT (Network Address Translation) per condividere un singolo indirizzo IP pubblico tra tutti i dispositivi della tua rete domestica. I tuoi dispositivi locali utilizzano indirizzi IP privati (192.168.x.x, 10.x.x.x, ecc.) che non sono instradabili su Internet.</p> </div> <div class="paragraph"> <p>Quando avvii un servizio sulla tua macchina Ubuntu (ad esempio un server web sulla porta 8080), quello è accessibile solo dalla tua rete locale. Per renderlo accessibile da Internet, dobbiamo configurare un reindirizzamento di porta.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_1_identifica_il_tuo_indirizzo_ip_pubblico">Passo 1: Identifica il tuo indirizzo IP pubblico</h2> <div class="sectionbody"> <div class="paragraph"> <p>Prima di tutto, recuperiamo l’indirizzo IP pubblico della tua connessione Internet :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Plusieurs méthodes au choix curl ifconfig.me curl ipecho.net/plain wget -qO- http://ipecho.net/plain # Ou encore curl -s checkip.amazonaws.com</code></pre> </div> </div> <div class="paragraph"> <p>Questo indirizzo IP è quello che gli utenti utilizzeranno per accedere al tuo servizio.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_2_conoscere_lindirizzo_ip_locale_della_tua_macchina_ubuntu">Passo 2: Conoscere l’indirizzo IP locale della tua macchina Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>La tua macchina Ubuntu ha un indirizzo IP privato sulla tua rete locale. Per conoscerlo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Afficher toutes les interfaces réseau ip addr show # Ou plus spécifiquement pour l'interface principale ip route get 1.1.1.1 | awk '{print $7; exit}' # Alternative avec hostname hostname -I | awk '{print $1}'</code></pre> </div> </div> <div class="paragraph"> <p>Nota questo indirizzo (ad esempio`192.168.1.100`), ne avremo bisogno per la configurazione.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passaggio_3_configurare_il_port_forwarding_sulla_tua_box">Passaggio 3: configurare il port forwarding sulla tua box</h2> <div class="sectionbody"> <div class="paragraph"> <p>La configurazione varia in base al modello della tua box, ma il principio rimane lo stesso:</p> </div> <div class="sect2"> <h3 id="_accesso_allinterfaccia_di_amministrazione">Accesso all’interfaccia di amministrazione</h3> <div class="paragraph"> <p>Aprire il browser e accedere all’interfaccia web della box :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Freebox</strong> : <code>192.168.1.1</code> ou <code>mafreebox.freebox.fr</code></p> </li> <li> <p><strong>Livebox Orange</strong> : <code>192.168.1.1</code></p> </li> <li> <p><strong>SFR Box</strong>:`192.168.1.1`</p> </li> <li> <p><strong>Bbox Bouygues</strong>:`192.168.1.254`</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_configurazione_del_reindirizzamento">Configurazione del reindirizzamento</h3> <div class="paragraph"> <p>Cerca la sezione dedicata al port forwarding (i nomi variano):</p> </div> <div class="ulist"> <ul> <li> <p>Inoltro porte</p> </li> <li> <p>NAT/PAT</p> </li> <li> <p>inoltro di porta</p> </li> <li> <p>Server di giochi</p> </li> </ul> </div> <div class="paragraph"> <p>Crea una nuova regola con questi parametri:</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">campo</th> <th class="tableblock halign-left valign-top">Valore</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nome/Descrizione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Servizio Web Ubuntu" (o altro nome esplicito)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Porta esterna (o porta pubblica)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Indirizzo IP interno</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’IP della tua macchina Ubuntu (es: 192.168.1.100)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Porta interna (o porta privata)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Protocollo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">TCP</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Stato</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Attivato</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_passo_4_configurazione_del_servizio_su_ubuntu">Passo 4 : Configurazione del servizio su Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Assicurati che il tuo servizio ascolti su tutte le interfacce, non solo sul localhost :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># ✅ Correct : écoute sur toutes les interfaces python3 -m http.server 8080 --bind 0.0.0.0 # ❌ Incorrect : écoute seulement en local python3 -m http.server 8080 --bind 127.0.0.1</code></pre> </div> </div> <div class="paragraph"> <p>Per verificare che il tuo servizio ascolti correttamente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Vérifier les ports en écoute sudo netstat -tlnp | grep :8080 # ou avec ss (plus moderne) sudo ss -tlnp | grep :8080</code></pre> </div> </div> <div class="paragraph"> <p>Dovresti vedere qualcosa come`0.0.0.0:8080`e non`127.0.0.1:8080`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_passo_5_configurazione_del_firewall_ubuntu">Passo 5: configurazione del firewall Ubuntu</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu utilizza UFW (Firewall Semplificato) per impostazione predefinita. Verifica il suo stato e consenti la porta se necessario :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Vérifier le statut du pare-feu sudo ufw status # Si le pare-feu est actif, autoriser le port 8080 sudo ufw allow 8080/tcp # Ou plus spécifiquement pour un service web sudo ufw allow 'Apache' # si vous utilisez Apache sudo ufw allow 'Nginx Full' # si vous utilisez Nginx</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_passo_6_test_e_validazione">Passo 6 : Test e validazione</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_test_dalla_rete_locale">Test dalla rete locale</h3> <div class="paragraph"> <p>Prima, testa l’accesso da un’altra macchina della tua rete locale :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Remplacez par l'IP locale de votre machine Ubuntu curl http://192.168.1.100:8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_test_dallesterno">Test dall’esterno</h3> <div class="paragraph"> <p>Ora, prova da Internet utilizzando il tuo indirizzo IP pubblico :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Remplacez par votre IP publique curl http://VOTRE_IP_PUBLIQUE:8080</code></pre> </div> </div> <div class="paragraph"> <p>Puoi anche utilizzare strumenti online come :</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://www.yougetsignal.com/tools/open-ports/" class="bare">https://www.yougetsignal.com/tools/open-ports/</a></p> </li> <li> <p><a href="https://canyouseeme.org/" class="bare">https://canyouseeme.org/</a></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_buone_pratiche_e_sicurezza">Buone pratiche e sicurezza</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sicurezza_di_base">Sicurezza di base</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Configurer fail2ban pour protéger contre les attaques par force brute sudo apt update && sudo apt install fail2ban # Limiter l'accès avec UFW (exemple : autoriser seulement certaines IP) sudo ufw allow from 203.0.113.0/24 to any port 8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_monitoraggio_delle_connessioni">Monitoraggio delle connessioni</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Surveiller les connexions en temps réel sudo netstat -an | grep :8080 # Logs des connexions (selon votre application) sudo tail -f /var/log/nginx/access.log # pour Nginx sudo journalctl -f -u your-service # pour un service systemd</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_uso_di_un_reverse_proxy">Uso di un reverse proxy</h3> <div class="paragraph"> <p>Per una maggiore sicurezza e flessibilità, considera l’utilizzo di un reverse proxy come Nginx :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-nginx" data-lang="nginx">server { listen 80; server_name votre-domaine.com; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_alternative_al_port_forwarding">Alternative al port forwarding</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_soluzioni_cloud">Soluzioni cloud</h3> <div class="ulist"> <ul> <li> <p><strong>ngrok</strong>tunnel sicuro temporaneo</p> </li> <li> <p><strong>Cloudflare Tunnel</strong>soluzione gratuita e sicura</p> </li> <li> <p><strong>serveo.net</strong>: tunnel SSH semplice</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Exemple avec ngrok ngrok http 8080 # Exemple avec serveo ssh -R 80:localhost:8080 serveo.net</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_vps_e_proxy_inverso">VPS e proxy inverso</h3> <div class="paragraph"> <p>Per un uso professionale, considera l’utilizzo di un VPS con un reverse proxy che punta verso la tua infrastruttura locale tramite VPN.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_risoluzione_dei_problemi">risoluzione dei problemi</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_problemi_comuni">Problemi comuni</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Problema</th> <th class="tableblock halign-left valign-top">soluzione</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Servizio inaccessibile dall’esterno</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Controlla la configurazione del forwarding delle porte e che il servizio ascolti su 0.0.0.0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Connessione rifiutata</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il servizio non è avviato o ascolta solo su 127.0.0.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Timeout di connessione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problema di firewall (box o Ubuntu) o port forwarding mal configurato</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">L’IP pubblico cambia regolarmente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configura un DNS dinamico (DynDNS, No-IP, etc.)</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_debug_rete">Debug rete</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Tester la connectivité locale telnet localhost 8080 # Tester depuis une autre machine du réseau telnet 192.168.1.100 8080 # Vérifier les routes réseau ip route show # Analyser le trafic réseau sudo tcpdump -i any port 8080</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Esponere un servizio locale su Internet richiede una configurazione accurata del port forwarding, della sicurezza e del monitoraggio. Sebbene questo approccio sia perfetto per lo sviluppo o i progetti personali, considera alternative più robuste (VPS, CDN, servizi cloud) per l’uso in produzione.</p> </div> <div class="paragraph"> <p>L’importante è tenere sempre presente la sicurezza: usa password forti, aggiorna regolarmente il tuo sistema e monitora gli accessi ai tuoi servizi esposti.</p> </div> <div class="paragraph"> <p>Non esitate a condividere le vostre esperienze e domande nei commenti!</p> </div> </div> </div> https://cheroliv.com/blog/2025/0099_debugging-mockito-gradle-plugin_post.html Sun, 17 Nov 2024 00:00:00 +0000 blog/2025/0099_debugging-mockito-gradle-plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_il_contesto_plugin_gradle_bakery">Il contesto: Plugin Gradle Bakery</a></li> <li><a href="#_problema_1_verificare_il_mock_errato">Problema #1: Verificare il mock errato</a> <ul class="sectlevel2"> <li><a href="#_la_diagnosi">La diagnosi</a></li> <li><a href="#_la_soluzione">La soluzione</a></li> </ul> </li> <li><a href="#_problema_2_unfinishedstubbingexception_a_cascata">Problema #2 : UnfinishedStubbingException a cascata</a> <ul class="sectlevel2"> <li><a href="#_la_diagnosi_2">La diagnosi</a></li> <li><a href="#_la_soluzione_2">La soluzione</a></li> </ul> </li> <li><a href="#_problema_3_il_file_di_configurazione_non_esiste">Problema #3: Il file di configurazione non esiste</a> <ul class="sectlevel2"> <li><a href="#_la_diagnosi_3">La diagnosi</a></li> <li><a href="#_la_soluzione_3">La soluzione</a></li> </ul> </li> <li><a href="#_problema_4_afterevaluate_e_nullpointerexception">Problema #4 : afterEvaluate e NullPointerException</a> <ul class="sectlevel2"> <li><a href="#_la_diagnosi_4">La diagnosi</a></li> <li><a href="#_la_soluzione_4">La soluzione</a></li> </ul> </li> <li><a href="#_la_soluzione_completa">La soluzione completa</a></li> <li><a href="#_lezioni_apprese">lezioni apprese</a> <ul class="sectlevel2"> <li><a href="#_1_verificare_il_mock_corretto">1. Verificare il mock corretto</a></li> <li><a href="#_2_evitare_i_mock_annidati">2. Evitare i mock annidati</a></li> <li><a href="#_3_mockare_i_callback_di_valutazione">3. Mockare i callback di valutazione</a></li> <li><a href="#_4_testare_la_risoluzione_dei_percorsi">4. Testare la risoluzione dei percorsi</a></li> </ul> </li> <li><a href="#_architettura_di_test_finale">Architettura di test finale</a></li> <li><a href="#_conclusione">Conclusione</a></li> <li><a href="#_risorse">Risorse</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Durante lo sviluppo del plugin Gradle<strong>Panetteria</strong>per il mio blog JBake, ho riscontrato un problema apparentemente semplice: un test unitario che falliva con l’errore`Wanted but not invoked`. Ciò che sembrava essere un banale errore si è rivelato un caso perfetto da manuale per comprendere le sfumature del mocking con Mockito e Kotlin.</p> </div> <div class="paragraph"> <p>In questo articolo, vi porto in un viaggio di debugging metodico, dove ogni soluzione rivela un nuovo problema, fino alla risoluzione finale.</p> </div> </div> </div> <div class="sect1"> <h2 id="_il_contesto_plugin_gradle_bakery">Il contesto: Plugin Gradle Bakery</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il plugin Bakery è un wrapper attorno a JBake che facilita la pubblicazione di siti statici. Ecco la sua struttura semplificata:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class BakeryPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "bakery", BakeryExtension::class.java ) project.afterEvaluate { if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") } else { // C'EST ICI QUE ÇA SE PASSE project.plugins.apply(JBakePlugin::class.java) val site = FileSystemManager.from(project, extension.configPath.get()) // Configuration de JBake... } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Il test che falliva era semplice :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val project = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(project.plugins).apply(JBakePlugin::class.java) }</code></pre> </div> </div> <div class="paragraph"> <p>L’errore :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Wanted but not invoked: pluginContainer.apply(class org.jbake.gradle.JBakePlugin); Actually, there were zero interactions with this mock.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_1_verificare_il_mock_errato">Problema #1: Verificare il mock errato</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_diagnosi">La diagnosi</h3> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-1.svg" alt="mockito problem 1" width="687" height="521"> </div> </div> <div class="paragraph"> <p>Il problema: Mockito non può tracciare le interazioni su`project.plugins`perché non è altro che un getter che restituisce il mock vero`mockPluginContainer`. La verifica deve essere fatta direttamente sull’istanza del mock.</p> </div> </div> <div class="sect2"> <h3 id="_la_soluzione">La soluzione</h3> <div class="paragraph"> <p>Modifica`createMockProject()`per restituire i due oggetti :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { val mockPluginContainer = mock<PluginContainer>() val mockProject = mock<Project> { on { plugins } doReturn mockPluginContainer } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>E adattare il test :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) // ✅ Vérification directe sur le bon mock verify(mockPluginContainer).apply(JBakePlugin::class.java) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_2_unfinishedstubbingexception_a_cascata">Problema #2 : UnfinishedStubbingException a cascata</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_diagnosi_2">La diagnosi</h3> <div class="paragraph"> <p>Una volta applicata la prima correzione, è comparsa un nuovo errore :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">UnfinishedStubbingException: Unfinished stubbing detected here Hints: 3. you are stubbing the behaviour of another mock inside before 'thenReturn' instruction is completed</code></pre> </div> </div> <div class="paragraph"> <p>Il codice problematico utilizzava la sintassi DSL di Mockito‑Kotlin:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val mockProject = mock<Project> { on { extensions } doReturn mockExtensionContainer on { plugins } doReturn mockPluginContainer on { logger } doReturn mock() // ❌ PROBLÈME ICI ! }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-2.svg" alt="mockito problem 2" width="690" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_la_soluzione_2">La soluzione</h3> <div class="paragraph"> <p>creare<strong>tutti</strong>i mock fuori da ogni blocco di stubbing, quindi configurarli con`whenever()`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ Créer TOUS les mocks d'abord val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() // 2️⃣ Configurer les mocks séparément avec whenever() whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.logger).thenReturn(mockLogger) return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>regola d’oro</strong>: Non chiamare mai`mock()`All’interno di un blocco di configurazione dei mock. Sempre creare i mock per primi, poi configurarli.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_3_il_file_di_configurazione_non_esiste">Problema #3: Il file di configurazione non esiste</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_diagnosi_3">La diagnosi</h3> <div class="paragraph"> <p>Anche con i mock corretti, il test falliva sempre perché il plugin non trovava il file di configurazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Dans BakeryPlugin.kt if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") return@afterEvaluate // ❌ Sort avant d'appliquer JBake ! }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-3.svg" alt="mockito problem 3" width="568" height="373"> </div> </div> </div> <div class="sect2"> <h3 id="_la_soluzione_3">La soluzione</h3> <div class="paragraph"> <p>Configurare i mock affinché la risoluzione del percorso funzioni:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile // Configuration cohérente des chemins whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // Maintenant : projectDir.resolve("site.yml") existe ! ✅ }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/path-resolution.svg" alt="path resolution" width="1761" height="5580"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_problema_4_afterevaluate_e_nullpointerexception">Problema #4 : afterEvaluate e NullPointerException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_la_diagnosi_4">La diagnosi</h3> <div class="paragraph"> <p>Il plugin applica JBake in un bloc`afterEvaluate`, e accede a`buildDirectory.dir()`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.afterEvaluate { // ... project.tasks.withType(JBakeTask::class.java) .getByName("bake").apply { output = project.layout.buildDirectory .dir(site.bake.destDirPath) // ❌ NPE ici ! .get() .asFile } }</code></pre> </div> </div> <div class="paragraph"> <p>Il mock di`buildDirectory.dir()<code>ritornava`null</code>.</p> </div> </div> <div class="sect2"> <h3 id="_la_soluzione_4">La soluzione</h3> <div class="paragraph"> <p>deridere`afterEvaluate`affinché venga eseguito immediatamente e configurare completamente`buildDirectory`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val mockBuildDirectory = mock<DirectoryProperty>() val buildDir = File(projectDir, "build") // Mocker dir() pour retourner un Provider valide whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // Mocker afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) // ✅ Exécution synchrone null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/after-evaluate-flow.svg" alt="after evaluate flow" width="802" height="357"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_soluzione_completa">La soluzione completa</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ecco la funzione`createMockProject()`finale, che risolve tutti i problemi :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ CRÉER tous les mocks (pas de nested mocks !) val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockTaskContainer = mock<TaskContainer>() val mockConfigPathProperty = mock<Property<String>>() val mockBakeryExtension = mock<BakeryExtension>() val mockProjectDirectory = mock<Directory>() val mockBuildDirectory = mock<DirectoryProperty>() val mockProjectLayout = mock<ProjectLayout>() val mockProject = mock<Project>() // 2️⃣ CONFIGURER la résolution des chemins val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile val buildDir = File(projectDir, "build") whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockConfigPathProperty.isPresent).thenReturn(true) whenever(mockBakeryExtension.configPath).thenReturn(mockConfigPathProperty) whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // 3️⃣ CONFIGURER buildDirectory avec dir() whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // 4️⃣ ASSEMBLER le projet whenever(mockProjectLayout.projectDirectory).thenReturn(mockProjectDirectory) whenever(mockProjectLayout.buildDirectory).thenReturn(mockBuildDirectory) whenever(mockExtensionContainer.create("bakery", BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockExtensionContainer.getByType(BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.tasks).thenReturn(mockTaskContainer) whenever(mockProject.layout).thenReturn(mockProjectLayout) whenever(mockProject.logger).thenReturn(mockLogger) whenever(mockProject.projectDir).thenReturn(projectDir) // 5️⃣ CONFIGURER afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>E il test finale che passa :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(mockPluginContainer).apply(JBakePlugin::class.java) // ✅ SUCCÈS ! }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lezioni_apprese">lezioni apprese</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/lessons-learned.svg" alt="lessons learned" width="748" height="472"> </div> </div> <div class="sect2"> <h3 id="_1_verificare_il_mock_corretto">1. Verificare il mock corretto</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX verify(project.plugins).apply(JBakePlugin::class.java) // ✅ CORRECT val (project, mockPluginContainer) = createMockProject() verify(mockPluginContainer).apply(JBakePlugin::class.java)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_evitare_i_mock_annidati">2. Evitare i mock annidati</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX - UnfinishedStubbingException val mockProject = mock<Project> { on { logger } doReturn mock() // Nested mock creation ! } // ✅ CORRECT - Créer séparément val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() whenever(mockProject.logger).thenReturn(mockLogger)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_3_mockare_i_callback_di_valutazione">3. Mockare i callback di valutazione</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ✅ afterEvaluate doit s'exécuter pour les tests whenever(mockProject.afterEvaluate(any())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_testare_la_risoluzione_dei_percorsi">4. Testare la risoluzione dei percorsi</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Toujours vérifier que les chemins se résolvent correctement val extension = project.extensions.getByType(BakeryExtension::class.java) val configPath = extension.configPath.get() val projectDir = project.layout.projectDirectory.asFile val resolvedConfig = projectDir.resolve(configPath) println("Resolved config: ${resolvedConfig.absolutePath}") println("Exists: ${resolvedConfig.exists()}")</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_architettura_di_test_finale">Architettura di test finale</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/test-architecture.svg" alt="test architecture" width="707" height="598"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ciò che sembrava essere un semplice problema di prova si è rivelato essere un eccellente caso di studio :</p> </div> <div class="ulist"> <ul> <li> <p>Le sfumature di Mockito con Kotlin</p> </li> <li> <p>L’importanza di mockare gli oggetti corretti</p> </li> <li> <p>La gestione delle callback asincrone nei test</p> </li> <li> <p>La risoluzione dei percorsi nei plugin Gradle</p> </li> </ul> </div> <div class="paragraph"> <p>Il debug metodico, comprendendo ogni livello del problema, ha permesso di arrivare a una soluzione robusta e mantenibile.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Consiglio per i tuoi test</strong>: Se incontri "Wanted but not invoked" con Mockito, chiediti sempre : 1. Sto verificando il mock corretto ? 2. Tutti i miei mock sono creati fuori dai blocchi di configurazione? 3. I miei callback si eseguono davvero? 4. I miei percorsi si risolvono correttamente?</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_risorse">Risorse</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/mockito/mockito-kotlin">Documentazione Mockito-Kotlin</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_plugins.html">Guida allo sviluppo di plugin Gradle</a></p> </li> <li> <p><a href="https://jbake.org/">JBake Generatore di Siti Statici</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Hai riscontrato problemi simili nei tuoi test? Condividi la tua esperienza nei commenti!</em></p> </div> </div> </div> https://cheroliv.com/blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html Tue, 24 Sep 2024 00:00:00 +0000 blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_che_cosa_è_la_monade_either">Che cosa è la monade Either ?</a> <ul class="sectlevel2"> <li><a href="#_perché_utilizzare_either">Perché utilizzare Either ?</a></li> </ul> </li> <li><a href="#_contesto">Contesto</a></li> <li><a href="#_le_diverse_approcci">Le diverse approcci</a> <ul class="sectlevel2"> <li><a href="#_lapproccio_classico_con_when">L’approccio classico con `when</a></li> <li><a href="#_utilizzo_di_fold_per_un_approccio_più_conciso">Utilizzo di <code>fold</code> per un approccio più conciso</a></li> <li><a href="#_trasformazione_con_map_e_mapleft">Trasformazione con <code>map</code> e `mapLeft</a></li> <li><a href="#_gestione_degli_errori_con_getorelse">Gestione degli errori con `getOrElse</a></li> <li><a href="#_azioni_laterali_con_onleft_e_onright">Azioni laterali con <code>onLeft</code> e `onRight</a></li> <li><a href="#_concatenamento_di_operazioni_con_flatmap">Concatenamento di operazioni con `flatMap</a></li> <li><a href="#_trasformazione_bidirezionale_con_bimap">Trasformazione bidirezionale con `bimap</a></li> <li><a href="#_inversione_dei_lati_con_swap">Inversione dei lati con `swap</a></li> <li><a href="#_utilizzo_di_tap_e_tapleft">Utilizzo di <code>tap</code> e <code>tapLeft</code> :</a></li> <li><a href="#_utilizzo_di_recover">Utilizzo di <code>recover</code>:</a></li> </ul> </li> <li><a href="#_casi_duso_pratici">Casi d’uso pratici</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_per_andare_oltre">Per andare oltre</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Pubblico destinatario :</em> Sviluppatori Kotlin di livello intermedio-avanzato.</div> <p>Nel mondo della programmazione funzionale in Kotlin, la libreria Arrow offre strumenti potenti per gestire gli errori e i casi alternativi. Tra questi strumenti, la monade`Either`si distingue per la sua capacità di rappresentare due stati possibili: successo (Right) o fallimento (Left). Ma come navigare efficacemente tra questi due stati? Questo è ciò che esploreremo in questo articolo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_che_cosa_è_la_monade_either">Che cosa è la monade Either ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La monade`Either`è una struttura di dati che rappresenta due possibilità mutualmente esclusive. In Kotlin con Arrow, è spesso utilizzata per gestire i casi di successo e di fallimento di un’operazione, offrendo un’alternativa elegante alle eccezioni tradizionali.</p> </div> <div class="sect2"> <h3 id="_perché_utilizzare_either">Perché utilizzare Either ?</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Gestione esplicita degli errori: obbliga lo sviluppatore a considerare i casi di fallimento.</p> </li> <li> <p>Composizione funzionale : Facilita il concatenamento di operazioni che possono fallire.</p> </li> <li> <p>Type-safety: gli errori sono tipizzati, il che aiuta a gestirli in modo più preciso.</p> </li> <li> <p>Nessuna eccezione: evita gli effetti collaterali e le interruzioni inaspettate del flusso di esecuzione.</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_contesto">Contesto</h2> <div class="sectionbody"> <div class="paragraph"> <p>Immaginiamo che tu stia sviluppando un’API REST conhttps://spring.io/projects/spring-boot/[Spring Boot,windows=read-later] et <a href="https://kotlinlang.org/">Kotlin</a>, utilizzando la libreriahttps://arrow-kt.io/[Arrow,windows=read-later]. Hai una funzione`findOneUserByEmail`che restituisce un`Either<Throwable, User>`. Come puoi trattare questo risultato in modo elegante e funzionale ?</p> </div> <div class="paragraph"> <p>Abbiamo una classe User :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@file:Suppress( "RemoveRedundantQualifierName", "MemberVisibilityCanBePrivate", "SqlNoDataSourceInspection" ) package webapp.users import arrow.core.Either import arrow.core.left import arrow.core.right import com.fasterxml.jackson.annotation.JsonIgnore import com.fasterxml.jackson.databind.ObjectMapper import jakarta.validation.constraints.NotNull import jakarta.validation.constraints.Pattern import jakarta.validation.constraints.Size import org.springframework.beans.factory.getBean import org.springframework.context.ApplicationContext import org.springframework.data.r2dbc.core.R2dbcEntityTemplate import org.springframework.r2dbc.core.DatabaseClient import org.springframework.r2dbc.core.awaitOne import org.springframework.r2dbc.core.awaitRowsUpdated import webapp.core.property.ANONYMOUS_USER import webapp.core.property.EMPTY_STRING import webapp.core.utils.AppUtils.cleanField import webapp.users.EntityModel.Companion.ID_MEMBER import webapp.users.User.UserDao.Attributes.EMAIL_ATTR import webapp.users.User.UserDao.Attributes.ID_ATTR import webapp.users.User.UserDao.Attributes.LANG_KEY_ATTR import webapp.users.User.UserDao.Attributes.LOGIN_ATTR import webapp.users.User.UserDao.Attributes.PASSWORD_ATTR import webapp.users.User.UserDao.Attributes.VERSION_ATTR import webapp.users.User.UserDao.Constraints.LOGIN_REGEX import webapp.users.User.UserDao.Fields.EMAIL_FIELD import webapp.users.User.UserDao.Fields.ID_FIELD import webapp.users.User.UserDao.Fields.LANG_KEY_FIELD import webapp.users.User.UserDao.Fields.LOGIN_FIELD import webapp.users.User.UserDao.Fields.PASSWORD_FIELD import webapp.users.User.UserDao.Fields.VERSION_FIELD import webapp.users.User.UserDao.Relations.INSERT import webapp.users.security.Role import webapp.users.security.Role.RoleDao import webapp.users.security.UserRole.UserRoleDao import java.util.* import jakarta.validation.constraints.Email as EmailConstraint data class User( override val id: UUID? = null, @field:NotNull @field:Pattern(regexp = LOGIN_REGEX) @field:Size(min = 1, max = 50) val login: String, @JsonIgnore @field:NotNull @field:Size(min = 60, max = 60) val password: String = EMPTY_STRING, @field:EmailConstraint @field:Size(min = 5, max = 254) val email: String = EMPTY_STRING, @JsonIgnore val roles: MutableSet<Role> = mutableSetOf(Role(ANONYMOUS_USER)), @field:Size(min = 2, max = 10) val langKey: String = EMPTY_STRING, @JsonIgnore val version: Long = -1, ) : EntityModel<UUID>() { companion object { @JvmStatic fun main(args: Array<String>) = println(UserDao.Relations.sqlScript) } object UserDao { object Constraints { // Regex for acceptable logins const val LOGIN_REGEX = "^(?>[a-zA-Z0-9!$&*+=?^_`{|}~.-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*)|(?>[_.@A-Za-z0-9-]+)$" const val PASSWORD_MIN: Int = 4 const val PASSWORD_MAX: Int = 16 const val IMAGE_URL_DEFAULT = "https://placehold.it/50x50" const val PHONE_REGEX = "^(\\+|00)?[1-9]\\d{0,49}\$" } object Members { const val PASSWORD_MEMBER = "password" const val ROLES_MEMBER = "roles" } object Fields { const val ID_FIELD = "`id`" const val LOGIN_FIELD = "`login`" const val PASSWORD_FIELD = "`password`" const val EMAIL_FIELD = "`email`" const val LANG_KEY_FIELD = "`lang_key`" const val VERSION_FIELD = "`version`" } object Attributes { val ID_ATTR = ID_FIELD.cleanField() val LOGIN_ATTR = LOGIN_FIELD.cleanField() val PASSWORD_ATTR = PASSWORD_FIELD.cleanField() val EMAIL_ATTR = EMAIL_FIELD.cleanField() const val LANG_KEY_ATTR = "langKey" val VERSION_ATTR = VERSION_FIELD.cleanField() } object Relations { const val TABLE_NAME = "`user`" const val SQL_SCRIPT = """ CREATE TABLE IF NOT EXISTS $TABLE_NAME ( $ID_FIELD UUID default random_uuid() PRIMARY KEY, $LOGIN_FIELD VARCHAR, $PASSWORD_FIELD VARCHAR, $EMAIL_FIELD VARCHAR, $LANG_KEY_FIELD VARCHAR, $VERSION_FIELD bigint ); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_login` ON $TABLE_NAME ($LOGIN_FIELD); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_email` ON $TABLE_NAME ($EMAIL_FIELD); """ @Suppress("SqlDialectInspection") const val INSERT = """ insert into $TABLE_NAME ( $LOGIN_FIELD, $EMAIL_FIELD, $PASSWORD_FIELD, $LANG_KEY_FIELD, $VERSION_FIELD ) values ( :login, :email, :password, :langKey, :version)""" @JvmStatic val sqlScript: String get() = setOf( UserDao.Relations.SQL_SCRIPT, RoleDao.Relations.SQL_SCRIPT, UserRoleDao.Relations.SQL_SCRIPT ).joinToString("") .trimMargin() } object Dao { val Pair<User, ApplicationContext>.toJson: String get() = second.getBean<ObjectMapper>().writeValueAsString(first) suspend fun Pair<User, ApplicationContext>.save(): Either<Throwable, Long> = try { second.getBean<R2dbcEntityTemplate>() .databaseClient .sql(INSERT) .bind(LOGIN_ATTR, first.login) .bind(EMAIL_ATTR, first.email) .bind(PASSWORD_ATTR, first.password) .bind(LANG_KEY_ATTR, first.langKey) .bind(VERSION_ATTR, first.version) .fetch() .awaitRowsUpdated() .right() } catch (e: Throwable) { e.left() } suspend fun ApplicationContext.findOneUserByEmail( email: String ): Either<Throwable, User> = try { getBean<DatabaseClient>() .sql("SELECT * FROM `user` WHERE LOWER(email) = LOWER(:email)") .bind("email", email) .fetch() .awaitOne() .let { row -> User( id = row[ID_ATTR] as UUID?, login = row[LOGIN_ATTR] as String, password = row[PASSWORD_ATTR] as String, email = row[EMAIL_ATTR] as String, langKey = row[LANG_KEY_ATTR] as String, version = row[VERSION_ATTR] as Long ) }.right() } catch (e: Throwable) { e.left() } } } /** Account REST API URIs */ object UserRestApis { const val API_AUTHORITY = "/api/authorities" const val API_USERS = "/api/users" const val API_SIGNUP = "/signup" const val API_SIGNUP_PATH = "$API_USERS$API_SIGNUP" const val API_ACTIVATE = "/activate" const val API_ACTIVATE_PATH = "$API_USERS$API_ACTIVATE?key=" const val API_ACTIVATE_PARAM = "{activationKey}" const val API_ACTIVATE_KEY = "key" const val API_RESET_INIT = "/reset-password/init" const val API_RESET_FINISH = "/reset-password/finish" const val API_CHANGE = "/change-password" const val API_CHANGE_PATH = "$API_USERS$API_CHANGE" } } // Abstract entity model with Generic ID, which can be of any type abstract class EntityModel<T>( open val id: T? = null ) { companion object { const val ID_MEMBER = "id" } } // Generic extension function that allows the ID to be applied to any EntityModel type inline fun <reified T : EntityModel<ID>, ID> T.withId(id: ID): T { // Use reflection to create a copy with the passed ID return this::class.constructors.first { it.parameters.any { param -> param.name == ID_MEMBER } } .call(id, *this::class.constructors.first().parameters.drop(1).map { param -> this::class.members.first { member -> member.name == param.name }.call(this) }.toTypedArray()) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_diverse_approcci">Le diverse approcci</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lapproccio_classico_con_when">L’approccio classico con `when</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val user: User by lazy { userFactory(USER) } val result: Either<Throwable, User> = context.findOneUserByEmail(user.email) when (result) { is Either.Left -> { val error = result.value println("Erreur : ${error.message}") } is Either.Right -> { val user = result.value println("Utilisateur trouvé : ${user.login}") } }</code></pre> </div> </div> <div class="paragraph"> <p>Questa metodo, sebbene semplice e leggibile, non sfrutta appieno le capacità funzionali di Arrow.</p> </div> </div> <div class="sect2"> <h3 id="_utilizzo_di_fold_per_un_approccio_più_conciso">Utilizzo di <code>fold</code> per un approccio più conciso</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.fold( { error -> println("Erreur : ${error.message}") }, { user -> println("Utilisateur trouvé : ${user.login}") } )</code></pre> </div> </div> <div class="paragraph"> <p>`fold`permette di definire delle azioni per i due casi (Left e Right) in modo conciso ed elegante.</p> </div> </div> <div class="sect2"> <h3 id="_trasformazione_con_map_e_mapleft">Trasformazione con <code>map</code> e `mapLeft</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val processedResult = result .map { user -> "Utilisateur trouvé : ${user.login}" } .mapLeft { error -> "Erreur : ${error.message}" } println(processedResult.merge())</code></pre> </div> </div> <div class="paragraph"> <p>Questo approccio permette di trasformare i valori contenuti in Either preservandone la struttura, ideale per catene di elaborazione più complesse.</p> </div> </div> <div class="sect2"> <h3 id="_gestione_degli_errori_con_getorelse">Gestione degli errori con `getOrElse</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val user = result.getOrElse { error -> println("Erreur : ${error.message}") User(login = "default", email = "default@example.com") // utilisateur par défaut } println("Login : ${user.login}")</code></pre> </div> </div> <div class="paragraph"> <p>`getOrElse`offre una gestione elegante degli errori consentendo di fornire un valore predefinito.</p> </div> </div> <div class="sect2"> <h3 id="_azioni_laterali_con_onleft_e_onright">Azioni laterali con <code>onLeft</code> e `onRight</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.onLeft { error -> println("Erreur : ${error.message}") } .onRight { user -> println("Utilisateur trouvé : ${user.login}") }</code></pre> </div> </div> <div class="paragraph"> <p>Questi metodi permettono di eseguire azioni su ogni lato senza modificare l’Either, perfetto per il logging o gli effetti collaterali leggeri.</p> </div> </div> <div class="sect2"> <h3 id="_concatenamento_di_operazioni_con_flatmap">Concatenamento di operazioni con `flatMap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun findUser(email: String): Either<Throwable, User> = // ... implémentation fun getUserPermissions(user: User): Either<Throwable, List<String>> = // ... implémentation val userPermissions = findUser("user@example.com") .flatMap { user -> getUserPermissions(user) }</code></pre> </div> </div> <div class="paragraph"> <p><code>flatMap`è utile per concatenare operazioni che restituiscono a loro volta degli`Either</code>, evitando così gli`Either`annidati.</p> </div> </div> <div class="sect2"> <h3 id="_trasformazione_bidirezionale_con_bimap">Trasformazione bidirezionale con `bimap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val processedResult = result.bimap( { error -> "Erreur: ${error.message}" }, { user -> "Utilisateur: ${user.login}" } )</code></pre> </div> </div> <div class="paragraph"> <p>`bimap`permette di trasformare sia il lato sinistro che il lato destro in una singola operazione.</p> </div> </div> <div class="sect2"> <h3 id="_inversione_dei_lati_con_swap">Inversione dei lati con `swap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val swapped = result.swap()</code></pre> </div> </div> <div class="paragraph"> <p><code>swap`è utile quando vuoi invertire i lati di un`Either</code>, ad esempio per adattare l’interfaccia di una funzione a un’altra.</p> </div> </div> <div class="sect2"> <h3 id="_utilizzo_di_tap_e_tapleft">Utilizzo di <code>tap</code> e <code>tapLeft</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.tap { user -> println("Utilisateur trouvé : ${user.login}") } .tapLeft { error -> println("Erreur : ${error.message}") }</code></pre> </div> </div> <div class="paragraph"> <p>Simile a`onLeft` et <code>onRight</code>, ma questi metodi restituiscono l’Either originale, il che è utile per il concatenamento di operazioni.</p> </div> </div> <div class="sect2"> <h3 id="_utilizzo_di_recover">Utilizzo di <code>recover</code>:</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val recoveredUser = result.recover { error -> println("Erreur récupérée : ${error.message}") User(login = "recovered", email = "recovered@example.com") } println("Login : ${recoveredUser.login}")</code></pre> </div> </div> <div class="paragraph"> <p>Questo metodo permette di trasformare un Either.Left in Either.Right fornendo un valore di sostituzione.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_casi_duso_pratici">Casi d’uso pratici</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Utilizzi`fold`per operazioni semplici che richiedono un trattamento per ogni caso. - Preferisci`map` et <code>mapLeft`per trasformazioni di dati senza cambiare la struttura dell`Either</code>. Scegli`flatMap`durante il concatenamento di operazioni che possono fallire - Utilizzate`recover`per fornire un valore predefinito in caso di errore. - Scegli`onLeft` et <code>onRight</code> (ou <code>tap</code> et <code>tapLeft</code>) per effetti collaterali come il logging - Utilizzate`bimap`per trasformare entrambi i lati in un’unica operazione. - Applicate`swap`quando devi adattare l’interfaccia di una funzione a un’altra.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ognuno di questi approcci ha i suoi vantaggi a seconda del contesto d’uso. I metodi come`fold`, <code>map</code>(empty)<code>mapLeft</code>, et `recover`sono particolarmente utili quando volete concatenare più operazioni o trasformare i dati in modo funzionale.</p> </div> <div class="paragraph"> <p>La monade`Either`d’Arrow offre una flessibilità notevole per gestire i casi di successo e di errore nelle tue applicazioni Kotlin. Padroneggiando questi diversi approcci, potrai scrivere un codice più robusto, più leggibile e più funzionale.</p> </div> <div class="paragraph"> <p>Nel tuo prossimo progetto, non esitare a esplorare queste tecniche per sfruttare al meglio la programmazione funzionale con Kotlin e Arrow!</p> </div> </div> </div> <div class="sect1"> <h2 id="_per_andare_oltre">Per andare oltre</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Documentazione ufficiale di Arrow :https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/-either/[Arrow Either] - Kotlin Coroutines con Arrow :https://arrow-kt.io/docs/fx/[Arrow Fx Coroutines]</p> </li> </ul> </div> <div class="paragraph"> <p>Non dimenticare di condividere le tue esperienze e le tue tecniche preferite per lavorare con`Either`nei commenti qui sotto!</p> </div> </div> </div> https://cheroliv.com/blog/2024/0074_seach_file_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2024/0074_seach_file_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_introduzione">Introduzione</a></li> <li><a href="#_utilizzo_del_comando_find">Utilizzo del comando `find</a> <ul class="sectlevel2"> <li><a href="#_opzioni_aggiuntive_per_find">Opzioni aggiuntive per `find</a></li> </ul> </li> <li><a href="#_utilizzo_del_comando_locate">Utilizzo del comando `locate</a></li> <li><a href="#_utilizzo_del_comando_grep_per_cercare_testo_nei_file">Utilizzo del comando <code>grep</code> per cercare testo nei file</a></li> <li><a href="#_conclusione">Conclusione</a></li> </ul> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Il problema : Cercare file in un sistema operativo Linux tramite il terminale.</div> <p>In questo articolo, esploreremo come cercare un file su Ubuntu utilizzando un terminale Zsh. Zsh (Z shell) è un interprete di comandi potente e ampliamente utilizzato per la sua flessibilità e le sue funzionalità avanzate.</p> </div> <div class="paragraph"> <p>Ubuntu, una distribuzione Linux popolare, offre diversi strumenti da riga di comando per cercare file. Vedremo come utilizzare comandi come`find`, <code>locate</code> et `grep`per individuare rapidamente e efficientemente i file nel terminale.</p> </div> </div> </div> <div class="sect1"> <h2 id="_utilizzo_del_comando_find">Utilizzo del comando `find</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’ordine`find`permette di cercare file in una directory specifica e nelle sue sottodirectory. La sua sintassi di base è la seguente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find [chemin] -name [nom_du_fichier]</code></pre> </div> </div> <div class="paragraph"> <p>Ecco un esempio pratico in cui cerchiamo un file denominato`example.txt`nella directory`/home`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find /home -name "example.txt"</code></pre> </div> </div> <div class="paragraph"> <p>Questo comando passa attraverso tutti i sottodirectory di`/home`e mostrare il percorso completo del file se viene trovato.</p> </div> <div class="paragraph"> <p><strong>Manuale online del comando`find`:https://man.archlinux.org/man/find.1.fr/[man trovare,finestre=da-leggere-più-tardi]</strong></p> </div> <div class="sect2"> <h3 id="_opzioni_aggiuntive_per_find">Opzioni aggiuntive per `find</h3> <div class="paragraph"> <p>Il comando`find`è molto potente e dispone di molte opzioni. Ecco alcuni esempi utili :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Cerca per tipo di file</strong>: Per cercare solo i file, utilizzate`-type f`, e per cercare le directory, utilizzi`-type d`. - <strong>Cerca per dimensione</strong>Puoi anche filtrare i file in base alla loro dimensione utilizzando l’opzione`-size`. Par exemple, pour rechercher des fichiers de plus de 100 Mo, utilisez :</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find /home -size +100M</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_utilizzo_del_comando_locate">Utilizzo del comando `locate</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il comando`locate`è più veloce di`find`Perché utilizza un database pre-indicizzato dei file presenti nel sistema. Devi prima aggiornare questo database con il seguente comando:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo updatedb</code></pre> </div> </div> <div class="paragraph"> <p>Poi puoi cercare un file così:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">locate example.txt</code></pre> </div> </div> <div class="paragraph"> <p>Usohttps://fr.wikipedia.org/wiki/Z_Shell[zsh]conhttps://github.com/ohmyzsh/ohmyzsh/wiki[oh-my-zsh], si scopre che l’ordine`locate`non è accessibile da`zsh`ma ben possibile da`bash`, per ovviare a ciò, l’argomento`-c`del comando`bash`permette di lanciare un comando`bash`da un altro tipo di terminale.</p> </div> <div class="paragraph"> <p>qui cerco i file che terminano con il motivo`001.pdf`nella directory utente</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">bash -c "locate ~/*001.pdf"</code></pre> </div> </div> <div class="paragraph"> <p><strong>Manuale online del comando`locate`:https://man.archlinux.org/man/locate.1.fr/[man locate,windows=read-later]</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_utilizzo_del_comando_grep_per_cercare_testo_nei_file">Utilizzo del comando <code>grep</code> per cercare testo nei file</h2> <div class="sectionbody"> <div class="paragraph"> <p>Se vuoi cercare un testo specifico all’interno di un file, puoi utilizzare`grep`. Per esempio, per cercare l’occorrenza della parola "Ubuntu" in tutti i file`.txt`dalla directory corrente, utilizza:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">grep "Ubuntu" *.txt</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>La ricerca di file in Ubuntu tramite un terminale Zsh può essere eseguita utilizzando diversi strumenti potenti.`find`è flessibile e offre una moltitudine di opzioni, mentre`locate`permette una ricerca rapida utilizzando un database pre-costruito. Infine,`grep`Consente di trovare le occorrenze di testo all’interno dei file.</p> </div> <div class="paragraph"> <p>Questi comandi ti offrono una gamma completa di strumenti per rendere le tue ricerche di file più efficienti e adattate alle tue esigenze e ciascuno di questi comandi ha un manuale visibile con il comando`man`</p> </div> </div> </div> https://cheroliv.com/blog/2021/0030_memo_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2021/0030_memo_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_la_tastiera">La tastiera:</a> <ul class="sectlevel2"> <li><a href="#_il_tasto_ctrl"><em>il tasto <Ctrl></em></a></li> </ul> </li> <li><a href="#_permessoauthorization">Permesso(authorization)</a></li> <li><a href="#_ricerca_di_file">Ricerca di file</a></li> </ul> </div> <div class="sect1"> <h2 id="_la_tastiera">La tastiera:</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_il_tasto_ctrl"><em>il tasto <Ctrl></em></h3> <table class="tableblock frame-all grid-all stretch"> </table> <div class="paragraph"> <p><a href="https://korben.info/les-raccourcis-clavier-pour-bash-terminal-linux-et-macos.html">link</a><br> <a href="https://blogmotion.fr/systeme/astuces-bash-linux-16175">altro link</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_permessoauthorization">Permesso(authorization)</h2> <div class="sectionbody"> <div class="paragraph"> <p>CHMOD viene utilizzato per cambiare i permessi di un file.</p> </div> <div class="paragraph"> <p>permesso comando</p> </div> <div class="paragraph"> <p>U G W rwx rwx rwx chmod 777 nomefile rwx rwx r-x chmod 775 filename rwx r-x r-x chmod 755 nomefile rw- rw- r-- chmod 664 nomefile rw- r-- r-- chmod 644 filename</p> </div> <div class="paragraph"> <p>U = Utente G = Gruppo W = Mondo</p> </div> <div class="paragraph"> <p>r = Leggibile w = scrivibile x = eseguibile - = nessun permesso</p> </div> <div class="paragraph"> <p>Un altro modo di vedere i permessi:</p> </div> <div class="paragraph"> <p>400 letto dal proprietario 040 letto dal gruppo 004 letto da chiunque (altro) 200 scritto dal proprietario 020 scrivi per gruppo scritto da chiunque 100 esegu dal proprietario 010 execute by group eseguito da chiunque</p> </div> <div class="paragraph"> <p>Per ottenere una combinazione, basta sommarli.<br> Ad esempio, per essere letto, scritto, eseguito dal proprietario,<br> letto, eseguito, per gruppo e eseguito da chiunque,<br> voi aggiungereste 400+200+100+040+010+001 per dare 751.<br></p> </div> </div> </div> <div class="sect1"> <h2 id="_ricerca_di_file"><a href="/blog/2024/0074_seach_file_linux_post.html">Ricerca di file</a></h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html Thu, 1 Feb 2024 00:00:00 +0000 blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html https://cheroliv.com/blog/2024/0070_installer_pandoc_post.html Tue, 30 Jan 2024 00:00:00 +0000 blog/2024/0070_installer_pandoc_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Tempo di lettura: 3 min</em> Pandoc un convertitore universale di documento</div> <p>Pandoc è un software di elaborazione testi open source che può essere utilizzato per convertire documenti tra diversi formati. Esistono diversi modi per installare Pandoc.</p> </div> </div> </div> <div class="sect1"> <h2 id="_installazione_dalla_pagina_di_download"><strong>Installazione dalla pagina di download</strong></h2> <div class="sectionbody"> <div class="paragraph"> <p>Per installare Pandoc dalla pagina di download, procedi come segue:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Accedi alla pagina di download di Pandoc :https://pandoc.org/installing.html/[<a href="https://pandoc.org/installing.html" class="bare">https://pandoc.org/installing.html</a>]</p> </li> <li> <p>Scarica il programma di installazione del pacchetto per il tuo sistema operativo.</p> </li> <li> <p>Esegui il programma di installazione per installare Pandoc.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Installazione da un file zip</strong></p> </div> <div class="paragraph"> <p>Per installare Pandoc da un file zip, procedi come segue :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Scarica il file zip contenente i binari di Pandoc e la documentazione.</p> </li> <li> <p>Decomprimi il file zip.</p> </li> <li> <p>Sposta i binari in una directory a tua scelta.</p> </li> </ol> </div> <div class="paragraph"> <p><strong>Installazione con Chocolatey</strong></p> </div> <div class="paragraph"> <p>Per installare Pandoc utilizzando Chocolatey, procedi come segue:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Aprire un prompt dei comandi.</p> </li> <li> <p>Esegui il comando seguente :</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-powershell" data-lang="powershell">choco install pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>Installazione con winget</strong></p> </div> <div class="paragraph"> <p>Per installare Pandoc utilizzando winget, procedi come segue:</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Aprire un prompt dei comandi.</p> </li> <li> <p>Esegui il seguente comando:</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-powershell" data-lang="powershell">winget install --source winget --exact --id JohnMacFarlane.Pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>Raccomandazioni</strong></p> </div> <div class="paragraph"> <p>Per impostazione predefinita, Pandoc crea PDF utilizzando LaTeX. È consigliato installare LaTeX tramite MiKTeX. Con l’opzione`--pdf-engine`, è però possibile specificare altri programmi per questa attività.</p> </div> <div class="paragraph"> <p><strong>Avvertenza</strong></p> </div> <div class="paragraph"> <p>L’utilizzo di più metodi di installazione può provocare due installazioni distinte di Pandoc. Si consiglia di disinstallare correttamente Pandoc prima di passare a un metodo di installazione alternativo.</p> </div> <div class="paragraph"> <p><strong>Installazione su Linux tramite WSL</strong></p> </div> <div class="paragraph"> <p>Verifica se la versione di pandoc nel tuo gestore di pacchetti non è obsoleta. Pandoc si trova nei repository di Debian, Ubuntu, Slackware, Arch, Fedora, NixOS, openSUSE, Gentoo e Void.</p> </div> <div class="paragraph"> <p>Per ottenere l’ultima versione, offriamo un pacchetto binario per l’architettura amd64 nella pagina di download.</p> </div> <div class="paragraph"> <p>L’eseguibile è collegato staticamente e non ha dipendenze dinamiche né dipendenze da file di dati esterni. Nota: a causa del collegamento statico, il binario pandoc di questo pacchetto non può utilizzare i filtri lua che richiedono moduli lua esterni scritti in C.</p> </div> <div class="paragraph"> <p>Sono forniti un tarball e un installatore deb. Per installare il deb :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo dpkg -i $DEB</code></pre> </div> </div> <div class="paragraph"> <p>Esempio al momento della scrittura :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">wget https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo dpkg -i pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="paragraph"> <p>où `$DEB`è il percorso verso il deb scaricato. Ciò installerà l’eseguibile`pandoc`e la pagina del manuale.</p> </div> <div class="paragraph"> <p>Se utilizzi una distribuzione basata su RPM, potresti essere in grado di installare il deb dalla nostra pagina di download utilizzando alien.</p> </div> <div class="paragraph"> <p>Su qualsiasi distribuzione, potete installare a partire dal tarball in`$DEST`(ad esempio,<code>/usr/local/</code> ou <code>$HOME/.local</code>) facendo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">tar xvzf $TGZ --strip-components 1 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>où `$TGZ`è il percorso verso il tarball zippato scaricato. Per le versioni di Pandoc precedenti alla 2.0, che non forniscono un tarball, prova invece :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>Puoi anche installare dalla sorgente, utilizzando le istruzioni qui sotto sotto`Compilation à partir de la source`. Nota che la maggior parte delle distribuzioni ha la piattaforma Haskell nei loro repository di pacchetti. Ad esempio, su Debian/Ubuntu, puoi installarlo con</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">apt-get install haskell-platform</code></pre> </div> </div> <div class="paragraph"> <p>Per impostazione predefinita, Pandoc crea PDF utilizzando LaTeX. Ti consigliamo di installare TeX Live tramite il tuo gestore di pacchetti. (Su Debian/Ubuntu,<code>apt-get install texlive</code>). Con l’opzione`--pdf-engine`, è tuttavia possibile specificare altri programmi per questa attività.</p> </div> </div> </div> https://cheroliv.com/blog/2023/0069_triple_python_js_ts_post.html Mon, 25 Dec 2023 00:00:00 +0000 blog/2023/0069_triple_python_js_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>Tempo di lettura: 2 min</em> Creare una implementazione completa della classe kotlin.Triple in JavaScript, TypeScript e Python utilizzando la programmazione funzionale.</div> <p><strong>Nota :</strong>I tipi`Maybe`, <code>Either</code>, `Result`non fanno parte del linguaggio di base in JavaScript o TypeScript, quindi è necessario implementarli noi stessi.</p> </div> </div> </div> <div class="sect1"> <h2 id="_javascript">JavaScript</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//javascript // Maybe type const Maybe = (value) => ({ map: (fn) => (value !== null && value !== undefined ? Maybe(fn(value)) : Maybe(null)), flatMap: (fn) => (value !== null && value !== undefined ? fn(value) : Maybe(null)), getOrElse: (defaultValue) => (value !== null && value !== undefined ? value : defaultValue), }); // Either type const Either = { Left: (value) => ({ map: (fn) => Either.Left(value), flatMap: (fn) => Either.Left(value), getOrElse: (defaultValue) => defaultValue, isLeft: true, isRight: false, }), Right: (value) => ({ map: (fn) => Either.Right(fn(value)), flatMap: (fn) => fn(value), getOrElse: (defaultValue) => value, isLeft: false, isRight: true, }), }; // Triple class class Triple { constructor(a, b, c) { this.a = a; this.b = b; this.c = c; } map(fn) { return new Triple(fn(this.a), fn(this.b), fn(this.c)); } static of(a, b, c) { return new Triple(a, b, c); } // Example method using Maybe and Either divideBy(other) { return Maybe(this.b) .flatMap((numerator) => Maybe(other) .flatMap((denominator) => denominator !== 0 ? Either.Right(numerator / denominator) : Either.Left('Division by zero') ) ) .getOrElse(Either.Left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_typescript">TypeScript</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">//Typescript // Maybe type // noinspection JSAnnotator type Maybe<T> = { map<U>(fn: (value: T) => U): Maybe<U>; flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>; getOrElse(defaultValue: T): T; }; const just = <T>(value: T): Maybe<T> => ({ map: <U>(fn: (value: T) => U) => just(fn(value)), flatMap: <U>(fn: (value: T) => Maybe<U>) => fn(value), getOrElse: (_: T) => value, }); const nothing = <T>(): Maybe<T> => ({ map: <U>(_: (value: T) => U) => nothing<U>(), flatMap: <U>(_: (value: T) => Maybe<U>) => nothing<U>(), getOrElse: (defaultValue: T) => defaultValue, }); // Either type type Either<L, R> = { map<U>(fn: (value: R) => U): Either<L, U>; flatMap<U>(fn: (value: R) => Either<L, U>): Either<L, U>; getOrElse(defaultValue: R): R; isLeft: boolean; isRight: boolean; }; const left = <L, R>(value: L): Either<L, R> => ({ map: <U>(_: (value: R) => U) => left<L, U>(value), flatMap: <U>(_: (value: R) => Either<L, U>) => left<L, U>(value), getOrElse: (defaultValue: R) => defaultValue, isLeft: true, isRight: false, }); const right = <L, R>(value: R): Either<L, R> => ({ map: <U>(fn: (value: R) => U) => right<L, U>(fn(value)), flatMap: <U>(fn: (value: R) => Either<L, U>) => fn(value), getOrElse: (_: R) => value, isLeft: false, isRight: true, }); // Triple class class Triple<T> { constructor(public a: T, public b: T, public c: T) {} map<U>(fn: (value: T) => U): Triple<U> { return new Triple<U>(fn(this.a), fn(this.b), fn(this.c)); } static of<T>(a: T, b: T, c: T): Triple<T> { return new Triple<T>(a, b, c); } // Example method using Maybe and Either divideBy(other: T): Either<string, number> { return just(this.b) .flatMap((numerator) => just(other) .flatMap((denominator) => denominator !== 0 ? right(numerator / denominator) : left('Division by zero') ) ) .getOrElse(left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_python_pydantic_pymonad">Python, pydantic, pymonad</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per creare un’implementazione in Python utilizzando`pydantic`per la validazione dei tipi e`pymonad`per le monadi :</p> </div> <div class="listingblock"> <div class="title">Installare le dipendenze :</div> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">pip install pydantic pymonad</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-python" data-lang="python">from pymonad.either import Either, Left, Right from pydantic import BaseModel, ValidationError, validator # Définition de la classe Triple avec Pydantic class Triple(BaseModel): a: int b: int c: int @validator('b') def validate_b(cls, b, values): if b == 0: raise ValueError('Division by zero is not allowed') return b # Méthode utilisant Either pour la gestion des erreurs def divide_by(self, other): def division(numerator, denominator): return Right(numerator / denominator) def handle_error(error): return Left(str(error)) return Either(lambda: division(self.b, other)).or_else(handle_error) # Exemple d'utilisation try: triple = Triple(a=1, b=2, c=3) result = triple.divide_by(2) if result.is_right: print(f'Division result: {result.value}') else: print(f'Error: {result.value}') except ValidationError as e: print(f'Validation Error: {e}') except Exception as e: print(f'An unexpected error occurred: {e}')</code></pre> </div> </div> <div class="ulist"> <div class="title">In questo esempio :</div> <ul> <li> <p><code>pydantic`per definire la classe`Triple`con campi tipizzati. - Il metodo`divide_by`usa la monade`Either</code> de `pymonad`per gestire gli errori potenziali derivanti dalla divisione per zero - Validazione personalizzata per assicurarsi che il valore di`b`non è uguale a zero. Se è uguale a zero, viene sollevata un’eccezione, e`pymonad`cattura questa eccezione per restituire un risultato`Left`indicando l’errore.</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2023/0068_introduction_google_apps_script_post.html Fri, 22 Dec 2023 00:00:00 +0000 blog/2023/0068_introduction_google_apps_script_post.html <div class="sect1"> <h2 id="_indice">Indice</h2> <div class="sectionbody"> <div class="paragraph"> <p><em>tempo di lettura: 30 min</em></p> </div> <div class="ulist"> <ul> <li> <p><a href="#_introduzione">Introduzione</a></p> </li> <li> <p><a href="#_struttura_di_base_in_google_apps_script">Struttura di base in Google Apps Script</a></p> </li> <li> <p><a href="#_tipi_e_variabili_in_google_apps_script">Tipi e Variabili in Google Apps Script</a></p> </li> <li> <p><a href="#Costanti">Variabili e Lettere in Google Apps Script</a></p> </li> <li> <p><a href="#_operazioni_e_operatori_in_google_apps_script">Operazioni e Operatori in Google Apps Script</a></p> </li> <li> <p><a href="#Variabili 'let' e 'const' in Google Apps Script">[Variabili 'let' e 'const' in Google Apps Script]</a></p> </li> <li> <p><a href="#_strutture_di_controllo_in_google_apps_script">Strutture di Controllo in Google Apps Script</a></p> </li> <li> <p><a href="#_cicli_in_google_apps_script">Cicli in Google Apps Script</a></p> </li> <li> <p>Oggetti in Google Apps Script</p> </li> <li> <p><a href="#_funzioni_in_google_apps_script">Funzioni in Google Apps Script</a></p> </li> <li> <p><a href="#_parametri_e_scopes_in_google_apps_script">Parametri e Scopes in Google Apps Script</a></p> </li> <li> <p><a href="#Operatori di Riposo e di Propagazione in Google Apps Script">[Operatori di Riposo e di Propagazione in Google Apps Script]</a></p> </li> <li> <p><a href="#_assegnazione_per_decomposizione_in_google_apps_script">Assegnazione per decomposizione in Google Apps Script</a></p> </li> <li> <p><a href="#Raccolte e Programmazione Dichiarativa in Google Apps Script">[Raccolte e Programmazione Dichiarativa in Google Apps Script]</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_introduzione">Introduzione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script (GAS) è una piattaforma di sviluppo di script associata a diversi servizi Google quali Google Sheets, Google Docs e Google Forms. Consente di automatizzare le attività, aggiungere funzionalità personalizzate e integrare i servizi Google.</p> </div> <div class="paragraph"> <p>In questo promemoria, esploreremo i principali concetti di Google Apps Script basandoci su esempi concreti. Tratteremo nozioni come le variabili, i cicli, le funzioni e molto altro, adattandole al contesto specifico di GAS.</p> </div> </div> </div> <div class="sect1"> <h2 id="_struttura_di_base_in_google_apps_script">Struttura di base in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per cominciare, esaminiamo la struttura di base di uno script Google Apps.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Structure de base en Google Apps Script */ function exempleStructureGAS() { // Votre code ici Logger.log("Hello, Google Apps Script!"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tipi_e_variabili_in_google_apps_script">Tipi e Variabili in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script utilizza JavaScript come linguaggio di programmazione. I tipi di dati e le variabili funzionano in modo simile a JavaScript standard.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Types et Variables en Google Apps Script */ function exempleTypesVariablesGAS() { // Votre code ici var nombre = 42; var texte = "Bonjour, Google Apps Script!"; Logger.log(nombre); Logger.log(texte); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_operazioni_e_operatori_in_google_apps_script">Operazioni e Operatori in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le operazioni e gli operatori in Google Apps Script sono gli stessi di JavaScript.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérations et Opérateurs en Google Apps Script */ function exempleOperationsGAS() { // Votre code ici var x = 10; var y = 5; var resultat = x + y; Logger.log(resultat); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_var_let_e_const_in_google_apps_script">Var, Let e Const in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>In GAS, i concetti di`var`, <code>let</code>, et `const`sono utilizzati per dichiarare variabili. Tuttavia, è essenziale comprendere le loro differenze e le loro implicazioni.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Var, Let et Const en Google Apps Script */ function exempleVarLetConstGAS() { // Votre code ici // Utilisation de var var x = 10; if (true) { var x = 20; // La variable x est modifiée globalement } Logger.log(x); // Utilisation de let let y = 30; if (true) { let y = 40; // La variable y est limitée au bloc if } Logger.log(y); // Utilisation de const const z = 50; // z = 60; // Impossible de réassigner une constante Logger.log(z); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_strutture_di_controllo_in_google_apps_script">Strutture di Controllo in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le strutture di controllo come`if`, <code>else</code>, <code>while</code> et `for`sono utilizzate per gestire il flusso di esecuzione in Google Apps Script.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Structures de Contrôle en Google Apps Script */ function exempleStructuresControleGAS() { // Votre code ici var condition = true; if (condition) { Logger.log("La condition est vraie."); } else { Logger.log("La condition est fausse."); } var compteur = 0; while (compteur < 5) { Logger.log(compteur); compteur++; } for (var i = 0; i < 3; i++) { Logger.log(i); } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_parametri_e_scopes_in_google_apps_script">Parametri e Scopes in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>I parametri e gli ambiti svolgono un ruolo cruciale nello sviluppo di script in GAS. Capisci come funzionano per evitare comportamenti imprevisti.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Paramètres et Scopes en Google Apps Script */ function exempleParametresScopesGAS(parametre) { // Votre code ici var variableGlobale = "Je suis global"; function afficherParametre() { Logger.log(parametre); } afficherParametre(); Logger.log(variableGlobale); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_constantes_variables_et_lettres_en_google_apps_script">Constantes, Variables, et Lettres en Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comprendere la differenza tra`const`, <code>var</code>, et `let`è essenziale per un utilizzo efficace delle variabili in Google Apps Script.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_cicli_in_google_apps_script">Cicli in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>I cicli, come`for` et <code>while</code>, sono essenziali per iterare sugli elementi e eseguire operazioni ripetitive.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Boucles en Google Apps Script */ function exempleBouclesGAS() { // Votre code ici for (var i = 0; i < 3; i++) { Logger.log(i); } var condition = true; var compteur = 0; while (condition) { Logger.log("Tour de boucle"); compteur++; if (compteur === 3) { condition = false; } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_oggetti_in_google_apps_script">Oggetti in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gli oggetti vengono utilizzati per strutturare i dati. In GAS, molti oggetti integrati facilitano l’interazione con i servizi Google.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Objets en Google Apps Script */ function exempleObjetsGAS() { // Votre code ici var feuille = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); var cellule = feuille.getRange("A1"); cellule.setValue("Nouvelle valeur"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_costanti_variabili_e_lettere_in_google_apps_script">Costanti, Variabili e Lettere in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Capire la differenza tra`const`, <code>var</code>, et `let`è essenziale per un utilizzo efficace delle variabili in Google Apps Script.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_funzioni_in_google_apps_script">Funzioni in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le funzioni sono elementi fondamentali nella programmazione. In GAS, possono essere dichiarate e richiamate in diversi modi.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Fonctions en Google Apps Script */ function exempleFonctionsGAS() { // Votre code ici function additionner(a, b) { return a + b; } var resultat = additionner(2, 3); Logger.log(resultat); // Fonction anonyme var multiplier = function (x, y) { return x * y; }; Logger.log(multiplier(4, 5)); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_operatori_di_rest_e_spread_in_google_apps_script">Operatori di Rest e Spread in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gli operatori di riposo (<code>…​</code>) e di propagazione (<code>…​</code>) sono utili per manipolare gli array e gli oggetti in modo conciso.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérateurs de Repos et de Propagation en Google Apps Script */ function exempleOperateursReposPropagationGAS() { // Votre code ici // Opérateur de repos (...) pour les tableaux var nombres = [1, 2, 3, 4, 5]; var [...copieNombres] = nombres; Logger.log(copieNombres); // Opérateur de propagation (...) pour les objets var objOriginal = { x: 1, y: 2 }; var objClone = { ...objOriginal, z: 3 }; Logger.log(objClone); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_assegnazione_per_decomposizione_in_google_apps_script">Assegnazione per decomposizione in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’assegnazione per decomposizione è una funzionalità potente che permette di estrarre valori da oggetti e array in modo conciso.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Affectation par Décomposition en Google Apps Script */ function exempleAffectationDecompositionGAS() { // Votre code ici var coordonnees = [3, 4]; var [x, y] = coordonnees; Logger.log(x); Logger.log(y); var utilisateur = { nom: "John", age: 30 }; var { nom, age } = utilisateur; Logger.log(nom); Logger.log(age); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_collezioni_e_programmazione_dichiarativa_in_google_apps_script">Collezioni e Programmazione Dichiarativa in Google Apps Script</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script supporta le strutture di dati come gli array, e i concetti di programmazione funzionale e di iterazione dichiarativa (><imperativa), come`map`, <code>reduce</code> et <code>forEach</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Collections et Programmation Déclarative en Google Apps Script */ function exempleCollectionsFonctionnelleGAS() { // Votre code ici // Exemple de tableau (collection) var nombres = [1, 2, 3, 4, 5]; // Utilisation de forEach nombres.forEach(function (nombre) { Logger.log(nombre); }); // Utilisation de map var carresNombres = nombres.map(function (nombre) { return nombre * nombre; }); Logger.log(carresNombres); // Utilisation de reduce var somme = nombres.reduce(function (acc, nombre) { return acc + nombre; }, 0); Logger.log(somme); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusione">Conclusione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questo promemoria ha coperto i concetti fondamentali di Google Apps Script illustrandoli con esempi di codice concreti. Utilizza queste conoscenze per automatizzare le tue attività quotidiane, personalizzare i tuoi documenti e sfruttare appieno le funzionalità di Google Apps Script.</p> </div> </div> </div> https://cheroliv.com/blog/2023/0067_formation_express_sur_google_forms_script_post.html Wed, 20 Dec 2023 00:00:00 +0000 blog/2023/0067_formation_express_sur_google_forms_script_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>Durata : 30 minuti</p> </div> </div> </div> <div class="sect1"> <h2 id="_obiettivi">Obiettivi</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comprendere le basi di Google Apps Script in Forms - Imparare ad accedere all’editor di script e eseguire un’istruzione al trigger</p> </div> </div> </div> <div class="sect1"> <h2 id="_temporizzazione">temporizzazione</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Introduzione allo script di Google Form</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Anteprima rapida di Google Form Script - Presentazione delle funzionalità principali</p> </li> </ul> </div> </li> <li> <p><strong>Creazione di un Modulo Google e di uno Script associato</strong>(5 min)</p> <div class="ulist"> <ul> <li> <p>Creazione di un modulo semplice con Google Forms Introduzione all’editor di script associato</p> </li> </ul> </div> </li> <li> <p><strong>Eseguire un’istruzione</strong>(10 min)</p> <div class="ulist"> <ul> <li> <p>Configurazione del trigger "on start - Configurazione del trigger "on submit - Scrittura di uno script per eseguire un’istruzione - Test rapidi per verificare il corretto funzionamento nel giornale</p> </li> </ul> </div> </li> <li> <p><strong>Analisi dei risultati e buone pratiche</strong>(10 minuti)</p> <div class="ulist"> <ul> <li> <p>Verifica dei risultati dell’esecuzione di un’istruzione - Discussione su un esempio di script e su come l’automazione può far risparmiare tempo</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_prerequisiti">Prerequisiti</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Avere un account Google e accesso a Google Forms e Google Sheets</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_materiale">Materiale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Computer con un navigatore web e una connessione internet</p> </div> </div> </div> <div class="sect1"> <h2 id="_nota">Nota</h2> <div class="sectionbody"> <div class="paragraph"> <p>Questa formazione express offre una rapida introduzione all’automazione con Google Form Script. Per una comprensione più approfondita, sono raccomandate formazioni più lunghe.</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_introduction_à_google_form_script">1 - Introduction à Google Form Script</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_slide_1_panoramica_rapida_di_google_form_script">Slide 1: Panoramica rapida di Google Form Script</h3> <div class="ulist"> <ul> <li> <p>Google Form Script è una piattaforma di scripting integrata a Google Forms. Consente di aggiungere funzionalità personalizzate e di automatizzare le attività.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_2_presentazione_delle_funzionalità_principali">Slide 2: Presentazione delle funzionalità principali</h3> <div class="ulist"> <ul> <li> <p>Script Editor : L’editor di script integrato per scrivere script Google Apps Script. - Trigger: Eventi come "on submit" che attivano l’esecuzione degli script.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_3_vantaggi_dellutilizzo_di_google_form_script">Slide 3: Vantaggi dell’utilizzo di Google Form Script</h3> <div class="paragraph"> <p>Personalizzazione: Create moduli personalizzati con funzionalità uniche. - Automazione: Automatizza le azioni in risposta alle risposte dei moduli. - Integrazione: Integra gli script con altri servizi Google per un’esperienza più ricca.</p> </div> </div> <div class="sect2"> <h3 id="_nota_per_il_presentatore">Nota per il presentatore:</h3> <div class="paragraph"> <p>Queste funzionalità offrono un potenziale considerevole per personalizzare e automatizzare i moduli. Il seguito di questa formazione esplorerà più in dettaglio la creazione di script e di automazioni specifiche.</p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr" class="bare">https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms?hl=fr</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms/form-app?hl=it" class="bare">https://developers.google.com/apps-script/reference/forms/form-app?hl=it</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_creazione_di_un_modulo_google_e_di_uno_script_associato_5_min"><strong>Creazione di un Modulo Google e di uno Script associato</strong> (5 min)</h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/blog/2023/0066_memo_python_post.html Sun, 19 Nov 2023 00:00:00 +0000 blog/2023/0066_memo_python_post.html <div class="sect1"> <h2 id="_installa_python_su_windows">Installa python su Windows</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://ninite.com/pythonx3/">python su Windows</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/starting/install3/win.html" class="bare">https://python-docs.readthedocs.io/en/latest/starting/install3/win.html</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref" class="bare">https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_esecuzione_di_python">Esecuzione di python</h2> <div class="sectionbody"> <div class="listingblock"> <div class="title">Riferimento :</div> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">cd mon_projet python -m venv mon_venv source mon_venv/bin/activate # Sur windows mon_venv\Scripts\activate deactivate</code></pre> </div> </div> <div class="sect2"> <h3 id="_requisito_di_installazione">requisito di installazione</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">pip install -r requirements.txt</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_iniziazione">iniziazione</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://python.doctor/page-apprendre-programmation-orientee-objet-poo-classes-python-cours-debutants">python POO</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_i_pattern_di_progettazione_gof_in_python">I pattern di progettazione GoF in Python</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://github.com/whikwon/python-patterns/">implementazione 1</a></p> </div> <div class="paragraph"> <p><a href="https://github.com/Sean-Bradley/Design-Patterns-In-Python">implementazione 2</a></p> </div> <div class="paragraph"> <p><a href="https://sbcode.net/python/">libro completo</a></p> </div> <div class="paragraph"> <p>I design pattern di GoF sono un insieme di 23 design pattern che sono stati descritti nel libro "Design Patterns: Elements of Reusable Object-Oriented Software".</p> </div> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. Ecco un elenco dei design pattern di GoF</caption> <colgroup> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0849%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nome</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Metodo Factory</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crea oggetti senza specificare la classe esatta da istanziare.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Abstract Factory</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crea famiglie di oggetti correlati o dipendenti senza specificare la loro classe concreta.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>costruttore</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Separa la costruzione di un oggetto complesso dalla sua rappresentazione affinché lo stesso processo di costruzione possa creare diverse rappresentazioni.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Prototipo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Crea nuovi oggetti copiando un prototipo esistente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Singleton</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Limita l’istanziazione di una classe a un solo oggetto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Adattare</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Converte l’interfaccia di una classe in un’altra interfaccia che il cliente si aspetta.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Bridge</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Disaccoppia un’astrazione dalla sua implementazione in modo che entrambe possano variare indipendentemente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>composito</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Compone oggetti in strutture ad albero per rappresentare gerarchie parte-tutto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Decoratore</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aggiungi dinamicamente responsabilità aggiuntive a un oggetto.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Facciata</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fornisce un’interfaccia unificata a un insieme di interfacce in un sottosistema.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Peso mosca</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Riduce il costo di creazione e utilizzo di oggetti leggeri.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Proxy</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fornisce un sostituto o uno spazio riservato per un altro oggetto al fine di controllare l’accesso a esso.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Catena di responsabilità</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permette a più di un oggetto di trattare una richiesta.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>ordine</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Incapsula una richiesta in un oggetto, consentendo così di configurare i client con richieste diverse, code o registri, e di supportare operazioni annullabili.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Interprete</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dai una rappresentazione della grammatica di una lingua e usa questa rappresentazione per interpretare frasi in questa lingua.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Iteratore</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fornisce un modo per percorrere sequenzialmente gli elementi di un oggetto aggregato senza esporne la rappresentazione sottostante.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mediator</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Permette di ridurre le dipendenze complesse tra gli oggetti facendoli comunicare esclusivamente tramite un oggetto mediatore.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Memento</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fornisce la capacità di ripristinare un oggetto al suo stato precedente (senza violare l’incapsulamento).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Osserva</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Definisce una dipendenza uno-a-molti tra gli oggetti in modo che quando un oggetto cambia stato, tutti i suoi dipendenti vengono notificati e aggiornati automaticamente.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Stato</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Consente a un oggetto di cambiare comportamento quando cambia il suo stato interno.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Strategia</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Definisce una famiglia di algoritmi, incapsula ciascuno di essi e li rende intercambiabili.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Metodo Template</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Definisce lo scheletro di un algoritmo in un metodo, delegando alcuni passaggi alle sottoclassi.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>visitatore</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Consente di definire una nuova operazione da eseguire su una struttura di oggetti senza modificare le classi degli oggetti sui quali opera.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_programmazione_funzionale">Programmazione funzionale</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 27.7777%;"> <col style="width: 55.5557%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Biblioteca</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/jasondelaat/pymonad" class="bare">https://github.com/jasondelaat/pymonad</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad è un’implementazione di strutture di dati monadiche in Python basata su linguaggi di programmazione quali Haskell e F# con implementazioni per i tipi di monadi più comunemente utilizzati nella programmazione funzionale.https://www.miguelfarrajota.com/2021/06/monads-in-python-with-pymonad/[article]</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/EntilZha/PyFunctional/" class="bare">https://github.com/EntilZha/PyFunctional/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional è una libreria Python per la programmazione funzionale che fornisce strumenti per lavorare con funzioni pure e iterabili.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Strumenti</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://toolz.readthedocs.io/en/latest/" class="bare">https://toolz.readthedocs.io/en/latest/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz è una libreria Python per la programmazione funzionale che fornisce strumenti per lavorare con funzioni pure e iterabili.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/kachayev/fn.py" class="bare">https://github.com/kachayev/fn.py</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py è una libreria Python per la programmazione funzionale che fornisce strumenti per lavorare con funzioni pure e iterabili.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">cocco</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://coconut-lang.org/" class="bare">https://coconut-lang.org/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Coconut aggiunge diverse funzionalità a Python per la programmazione funzionale, incluse il pattern matchinghttps://stackoverflow.com/questions/11909681/are-there-pattern-matching-functions-in-python-like-this[conversazione sof]</p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_effetti_collaterali">effetti collaterali</h3> </div> <div class="sect2"> <h3 id="_loops">loops</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-python" data-lang="python"># impérative way result = [] for i in inputs: x = f(g(i)) result.append(x) # idiomatic way result = map(comp(f,g), inputs)</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2023/0065_training_web_dev_post.html Thu, 24 Aug 2023 00:00:00 +0000 blog/2023/0065_training_web_dev_post.html https://cheroliv.com/blog/2023/0064_training_trading_card_games_post.html Mon, 21 Aug 2023 00:00:00 +0000 blog/2023/0064_training_trading_card_games_post.html https://cheroliv.com/blog/2023/0063_memo_ts_post.html Sat, 19 Aug 2023 00:00:00 +0000 blog/2023/0063_memo_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>repository GitHub:https://github.com/cheroliv/ts-codebase[ts-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_ts"><span class="underline">Intro typescript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#ts_types">I tipi in typescript</a></p> </li> <li> <p><a href="#funzioni">[funzioni]</a></p> </li> <li> <p><a href="#data_struct">Struttura dei dati</a></p> </li> <li> <p><a href="#enums_tuples">Enum e tuple</a></p> </li> <li> <p><a href="#void_never">Void e Never</a></p> </li> <li> <p><a href="#class_interface">Classi e interfacce</a></p> </li> <li> <p><a href="#tsconfig">Il file tsconfig.json</a></p> </li> <li> <p><a href="#moduli">[moduli]</a></p> </li> <li> <p><a href="#promesse">Promesse</a></p> </li> <li> <p><a href="#async-await">async/await</a></p> </li> <li> <p><a href="#generici">[generici]</a></p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> <title>Document</title> </head> <body> Intro typescript <script src="01_types.js"></script> <script src="02_data_structure.js"></script> <script src="03_enums_tuples.js"></script> </body> </html></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="ts_types">I tipi in typescript</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_tipi.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Les types en typescript */ //quand le type n'est pas defini des le debut, // alors il est réassignable // c'est le type Any qui est attribué par défaut let my_var; my_var = "username"; console.assert(my_var === "username"); my_var = 11; console.assert(my_var === 11); my_var = true; console.assert(my_var === true); let age = 1; console.assert(age === 1); age = 2; // age="trois" c'est impossible // car l'inference de type a attribué le type number console.assert(age === 2); // Déclaration explicite de type let pi: Number = 3.14; console.assert(typeof pi === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="fonctions">Funzioni</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le funzioni sono blocchi di codice riutilizzabili.</p> </div> <div class="paragraph"> <p>Esempio di quotazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const add = (a: number, b: number): number => a + b;</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="data_struct">Struttura dei dati</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_data_structure.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/*** * Structure de données: * Avec le type any on peut changer * le type de la variable à tout instruction * Lorsque l'on fixe le type * alors il n'est plus possible de le changer * lors d'une assignation */ // Arrays let buddies: any[] = [ "cheroliv", "imrandeh", "issoudeh", "soumi92" ] console.assert(buddies[0] === "cheroliv"); console.assert(buddies[1] === "imrandeh"); console.assert(buddies[2] === "issoudeh"); console.assert(buddies[3] === "soumi92"); // Déclaré en type any, l'inference de type // a bien réaligné en type string console.assert(typeof buddies[0] === "string"); console.assert(typeof buddies[1] === "string"); console.assert(typeof buddies[2] === "string"); console.assert(typeof buddies[3] === "string"); let writers: (String | String | String | Number)[][] = [ ["Chrétien", "de Troyes", "fr", 12], ["François", "Rabelais", "fr", 16], ["René", "Descartes", "fr", 17], ["Jean-Jacques", "Rousseau", "fr", 18], ["Georg", "Hegel", "de", 19], ["Karl", "Marx", "de", 19], ["Friedrich", "Engels", "de", 19], ["Victor", "Hugo", "fr", 19], ["Paul", "Verlaine", "fr", 19], ["Arthur", "Rimbaud", "fr", 19], ["Gérard", "de Nerval", "fr", 19], ["Georg", "Lukacs", "hu", 20], ["Franz", "Kafka", "hu", 20], ["Antonio", "Gramsci", "it", 20], ["Domenico","Losurdo","it",20], ]; // console.table(writers); // Objects let author: { first_name: String, last_name: String, lang: String, century: Number } = { // slice(-1) renvoie le dernier élèment first_name: writers.slice(-1)[0][0] as String, last_name: writers.slice(-1)[0][1] as String, lang: writers.slice(-1)[0][2] as String, century: writers.slice(-1)[0][3] as Number, } // assertion sur la valeur en accés par encapsulation(dot) console.assert(author.first_name === "Antonio") console.assert(author.last_name === "Gramsci") console.assert(author.lang === "it") console.assert(author.century === 20); // assertion sur le type en accès par index console.assert(typeof author["first_name"] === "string") console.assert(typeof author["last_name"] === "string") console.assert(typeof author["lang"] === "string") console.assert(typeof author["century"] === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="enums_tuples">Enum e tuple</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_enums_tuples.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Enums et Tuples * * Enum: il existe les enums numérique * et les enums chaine de caracteres. * * Tuple: similaire aux arrays mais ne peut * contenir qu'une valeur de type spécifié. * */ //Enum numérique // l'index par de debut défaut est 0 // ici on le place a 1 enum Week { Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7, }; console.assert(Week.Monday == 1); console.assert(Week.Tuesday == 2); console.assert(Week.Wednesday == 3); console.assert(Week.Thursday == 4); console.assert(Week.Friday == 5); console.assert(Week.Saturday == 6); console.assert(Week.Sunday == 7); console.assert(Week[1] === "Monday"); console.assert(Week[2] === "Tuesday"); console.assert(Week[3] === "Wednesday"); console.assert(Week[4] === "Thursday"); console.assert(Week[5] === "Friday"); console.assert(Week[6] === "Saturday"); console.assert(Week[7] === "Sunday"); let motd_arr_fr: String[] = [ "Associé à la Lune", "Du dieu Tiw, associé à Mars", "Du dieu germanique Odin", "Du dieu germanique du tonnerre Thor", "De la déesse germanique Frigga associée à Vénus", "Associé à Saturne", "Associé au Soleil", ]; let motd_arr_en: String[] = [ "associated with the Moon", "from the god Tiw, associated with Mars", "from Germanic god Odin", "from Germanic god of thunder Thor", "from Germanic goddess Frigga associated with Venus", "associated with Saturn", "associated with the Sun", ]; // Un tuple (triple) let monday_triple_fr: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_fr[0], ]; console.assert(monday_triple_fr[0] === 1); console.assert(monday_triple_fr[1] === "Monday"); console.assert(monday_triple_fr[2] === "Associé à la Lune"); let monday_triple_en: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_en[0], ]; console.assert(monday_triple_en[0] === 1); console.assert(monday_triple_en[1] === "Monday"); console.assert(monday_triple_en[2] === "associated with the Moon"); // On se fait un type pour ajouter le nom de la langue type Meaning_of_the_day = { lang: String, meaning: (Week | String)[][], }; //fonction d'affichage du type Meaning_of_the_day const display_motd = (motd: Meaning_of_the_day) => { motd.meaning.forEach(day => console.table(`${Week[day[0] as Week]}: ${day[1]}.(${motd.lang})`) ) }; //fonction d'assertion sur le type Meaning_of_the_day // afin de verifier la concordance du contenu avec // motd_arr_#lang# const test_motd = ( motd: Meaning_of_the_day, motd_arr: String[] ) => { console.assert(motd.lang.length === 2) for (const [i, value] of motd.meaning.entries()) { console.assert(value[1] === motd_arr[i]); } }; let motd_fr: Meaning_of_the_day = { lang: "fr", meaning: [ [Week.Monday, motd_arr_fr[0]], [Week.Tuesday, motd_arr_fr[1]], [Week.Wednesday, motd_arr_fr[2]], [Week.Thursday, motd_arr_fr[3]], [Week.Friday, motd_arr_fr[4]], [Week.Saturday, motd_arr_fr[5]], [Week.Sunday, motd_arr_fr[6]], ], } console.log("---------"); console.log("display_motd(motd_fr):"); display_motd(motd_fr); test_motd(motd_fr, motd_arr_fr) let motd_en: Meaning_of_the_day = { lang: "en", meaning: [ [Week.Monday, motd_arr_en[0]], [Week.Tuesday, motd_arr_en[1]], [Week.Wednesday, motd_arr_en[2]], [Week.Thursday, motd_arr_en[3]], [Week.Friday, motd_arr_en[4]], [Week.Saturday, motd_arr_en[5]], [Week.Sunday, motd_arr_en[6]], ], } console.log("---------"); console.log("display_motd(motd_en):"); display_motd(motd_en); console.log("---------"); test_motd(motd_en, motd_arr_en); // Un tuple (triple) utilisant le type // Meaning_of_the_day pour peupler le meaning let motd_triple: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_fr.meaning[0][1] as String ]; console.assert(motd_triple[0] === 1); console.assert(motd_triple[1] === "Monday"); console.assert(motd_triple[2] === "Associé à la Lune");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="void_never">Void e Never</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">// Le type void est l'opposé du type any // c'est l'absence de type. function verify_writers_length(): void { console.assert(writers.length > 0); } verify_writers_length(); const verify_writers_length_arrow = (): void => console.assert(writers.length > 0); verify_writers_length_arrow(); //Type of et never let value = 30; console.assert(typeof value === "number"); //never: qqchs qui n'arrive jamais function foo(x: String | Number): Boolean { if (typeof x === "string") { return true; } else if (typeof x === "number") { return false; } return fail("Error!") } function fail(message: String): never { throw new Error(message as string); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="class_interface">Classi e interfacce</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Les classes: * members, * visibility, * nommage, * accesseurs * scope identifier: static,private,protected * * convention de nommage : * Les membres private sont préfixés avec un _ * */ class Member { username: String = ""; email: String = ""; private _password: String = ""; readonly signup_date: Date = new Date(Date.now()); constructor(username: String, email: String) { this.username = username; this.email = email; } get password(): String { return this._password; } set password(new_password: String) { this._password = new_password; } /** * Une fonction static qui initilise un member, * à partir d'un author */ static fromAuthor(author: { first_name: String, last_name: String, lang: String, century: Number }): Member { return new Member( `${author.first_name}.${author.last_name}`, `${author.first_name}.${author.last_name}@acme.com`, ); } }; let domenico = Member.fromAuthor(author); domenico.password = "test"; console.assert(domenico.email === "Domenico.Losurdo@acme.com"); console.assert(domenico.password === "test"); // Héritage enum Forms { Undefined = 0, Polygones = 1, Circle = 2, Straight = 3, Segment = 4, }; class Form { type: Forms = Forms.Undefined; }; class Rectangle extends Form { h: Number = 0; w: Number = 0; }; class Square extends Rectangle { side: Number = 0; }; /** * Interface donne un contrat à un type. * Les interfaces permettent de définir la structure d'un objet. */ interface IPerson { username: String; email: String; readonly signup_date: Date; } const user1: IPerson = { username: Member.fromAuthor(author)["username"], email: Member.fromAuthor(author)["email"], signup_date: Member.fromAuthor(author)["signup_date"], }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="tsconfig">Il file tsconfig.json</h2> <div class="sectionbody"> <div class="paragraph"> <p>tsconfig.json</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-json" data-lang="json">{ /* Visit https://aka.ms/tsconfig to read more about this file */ "compileOnSave": true, "compilerOptions": { "target": "es2016", "module": "CommonJS", "noEmitOnError": true, "strict": true, "noImplicitAny": true, "esModuleInterop": true } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="modules">Moduli</h2> <div class="sectionbody"> <div class="paragraph"> <p>I moduli permettono di organizzare il codice in più file.</p> </div> <div class="paragraph"> <p>Esempio di quota:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">// Dans un fichier math.ts export const add = (a: number, b: number): number => a + b; // Dans un autre fichier import { add } from './math'; let result = add(2, 3);</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="promesse">Promesse</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le promesse vengono utilizzate per eseguire operazioni asincrone.</p> </div> <div class="paragraph"> <p>Esempio di quota :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const promise = new Promise<string>((resolve) => { // Code asynchrone ici resolve("Succès"); }); promise.then((result) => { console.log(result); });</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="async-await">async/await</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’async/await semplifica la gestione delle promesse.</p> </div> <div class="paragraph"> <p>Esempio di valutazione:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const fetchData = async (): Promise<void> => { const result = await someAsyncFunction(); console.log(result); };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="generiques">Generici</h2> <div class="sectionbody"> <div class="paragraph"> <p>I generici permettono di creare componenti riutilizzabili con tipi dinamici.</p> </div> <div class="paragraph"> <p>Esempio di valutazione :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const identity = <T>(arg: T): T => arg; const output = identity<string>("hello"); console.log(output);</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2023/0062_memo_css_post.html Mon, 14 Aug 2023 00:00:00 +0000 blog/2023/0062_memo_css_post.html <div class="sect1"> <h2 id="toc">Indice</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#good_links">Buoni link</a></p> </li> <li> <p><a href="#repo">Repository e esempio di codice</a></p> </li> <li> <p><a href="#toc_inizio">[toc_inizio]</a></p> </li> </ol> </div> <div class="sect2"> <h3 id="good_links">Buoni link</h3> <div class="paragraph"> <p><a href="#toc">Indice</a></p> </div> </div> <div class="sect2"> <h3 id="repo">Repository e esempio di codice</h3> <div class="paragraph"> <p>repository GitHub:https://github.com/cheroliv/css-codebase[css-codebase, finestra = "_blank]</p> </div> </div> <div class="sect2"> <h3 id="toc_début"><span class="underline">Inizio CSS</span></h3> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#inizio_intro">[inizio_intro]</a></p> </li> <li> <p><a href="#inizio_testi">[inizio_testi]</a></p> </li> <li> <p><a href="#inizio_background">[inizio_background]</a></p> </li> <li> <p><a href="#inizio_boxes">Le scatole (boxes)</a></p> </li> <li> <p><a href="#inizio_flexbox">[inizio_flexbox]</a></p> </li> <li> <p><a href="#inizio_grid">[inizio_grid]</a></p> </li> <li> <p>inizio_ass_pos</p> </li> <li> <p><a href="#inizio_responsive">[inizio_responsive]</a></p> </li> <li> <p><a href="#inizio_conclusione">[inizio_conclusione]</a></p> </li> </ol> </div> <div class="paragraph"> <p><a href="#toc">Indice</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="début_intro">Introduzione & Impostazione</h2> <div class="sectionbody"> <div class="paragraph"> <p>Intro basato su questo video:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/iSWjmVcfQGg?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> <div class="paragraph"> <p>repository GitHub:https://github.com/cheroliv/css-codebase/début_css/[inizio css, window = "_blank]</p> </div> <div class="paragraph"> <p>memo fonte:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message" ></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p>Collegare il file style.css alla pagina html:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"></head> <link rel="stylesheet" href="style.css" /> </head></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_début"><span class="underline">Inizio CSS</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_texts">I testi</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* import remote de font sur l'ensemble de la feuille*/ @import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); /* import local de font */ @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* body est le parent de toutes les balises, qu'il contient, donc je le déclare avant, pour la logique de précédence de parent */ body { /* si DMSerif n'est pas trouvé alors il se rabat sur Verdana*/ font-family: "DMSerif", Verdana; } /* va styliser toutes les balises h1, celles de body sont surchargés, par la déclaration présente */ h1 { text-transform: uppercase; /* espacement entre les lettres en pixel*/ letter-spacing: 3px; /* alignement du texte*/ text-align: center; /* Les tailles de polices doivent être en REM (rem = root em). Le REM se base pas sur l'élément parent pour obtenir sa taille mais sur l'élément racine. Ainsi 1rem prendra sa valeur de la font-size de votre document (body ou html).*/ font-size: 2.5rem; /* ombrage du texte */ text-shadow: 3px /* offset-x */ 3px /* offset-y */ 8px /* blur-radius */ #00000042/* color */; /* couleur du texte */ color: #ab0ef4; /*attibuer les polices(font): liste, ordonnée par priorité, de polices à utiliser pour mettre en forme le texte de l'élément ciblé.*/ font-family: "Oswald", sans-serif; /* surligner le text*/ text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_background">Sfondo</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; /* 100VH = 100% de la taille de l'écran (viewport height) min afin de ne pas bloquer la possibilité d'avoir un plus grand */ min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="inizio_boxes">Le scatole (boxes)</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* *: létoile donne du style a tous les éléments. Ensuite remettre un à un les parametres par defaut afin d'eviter les stylisation inattendu.*/ * { /* surcharge de base tous les elements à padding 0*/ margin: 0; /* surcharge de base tous les elements à padding 0*/ padding: 0; } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; /* quelque soit la taille de l'écran, la boite fait toujours 90% de la taille de la page, les 10% restant sont une marge à droite, pour avoir 5% de chaque coté on ajoute une margin, tel que [0, auto]*/ width: 90%; /* haut bas prend 0, et gauche droite prend auto(center cad meme de chaque cotés)*/ margin: 0 auto; /* on ajoute des bords a notre boite*/ border: 2px solid rgb(0, 140, 255); /* on arrondis les coins de la boite*/ border-radius: 20px 20px 0 0; /* ombrage sur la boite*/ box-shadow: 0px 0px 20px 4px #81cfc6; /* marge interrieure de la boite sur tous les cotés*/ padding: 15px; } h2 { /* afin de recuprer le comportement par defaut qui a ete surchargé par l'operateur étoile*/ margin: 0; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_flexbox">Flexbox</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } /* le point permet d'acceder à la classe d'un composant*/ .flexbox { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } /* FLEXBOX */ /* Sert à répartir équitablement des éléments sur la page */ .flexbox ul { padding: 0; /* aligne les éléments enfants de ul(les li)*/ display: flex; /* reparti convenablement(équitablement les li sur la page) */ justify-content: space-around; } /* ce style concerne les li de la classe, flexbox des balises qui y font referencent*/ .flexbox li { /* suprime les boules des éléments de la list li*/ list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; /* Centrer un unique élément verticalement et horizontalement */ display: flex; justify-content: center; align-items: center; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_grid">Griglia</h2> <div class="sectionbody"> <div class="paragraph"> <p>Per distribuire gli elementi in modo un po' più complesso rispetto alle flexbox, con un sistema di griglia, tra l’altro.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } /* GRID */ .grid-container { display: grid; /* séparatuion de la grille en deux(à ses deux enfants), avec à gauche 30% pour l'image et à droite 70% pour le formulaire*/ grid-template-columns: 30% 70%; } /* sizing de l'image css-logo contenu dans la classe grid qui est dans le parent grid-container*/ .grid img { /* l'image remplt 80% de part de grille*/ width: 80%; margin: 20px auto; display: block; } form { display: grid; /* deux colonnes de chacune 1 fraction*/ grid-template-columns: 1fr 1fr; /* trois rangés de chacune 1 fraction*/ grid-template-rows: 1fr 1fr 1fr; /* structuration sous forme de template de notre repartition des composants enfants de la forme*/ grid-template-areas: "i1 i2"/* i1: input1, i2:input2*/ "ta ta"/*ta: text area */ "vi bt"/*vi:, bt: bouton */; } /* on donne du style sur deux éléments en meme temps en les listant avant les parentheses*/ input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } /* donner du style uniquement la textearea*/ textarea { /* renseigner le nommage pour le grid template area*/ grid-area: ta; height: 40px; /* empeche le cassage du style de la page en empechant le resizing de la textarea du formulaire*/ resize: none; } /* pour pointer un id d'élément html on utilise la notation préfixe # */ #btn-submit { /* renseigner le nommage*/ grid-area: bt; /* change le le symbole de curseur souris quand il survole sur le bouton*/ cursor: pointer; background: cyan; transition: 0.2s; } /* au survole(hover) de la souris le bouton change de comportement*/ #btn-submit:hover { background: darkblue; /* couleur de text du bouton devient blanc*/ color: white; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_abs_pos">Position absolute</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } /* ABSOLUTE */ /* Sans élément en Relative, de base, l'élément en absolute l'est par rapport au Body */ /* Il faut mettre une position relative au parent pour contraindre l'élément en absolute dans ses frontières */ .absolute { /* position relative par rapport à son parent, donc contenu dans les frontieres de son parents*/ position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: /*traslate de 50% de la taille du cercle, pour etre centré par rapport au centre du cercle, plutot que sur son bord gauche par défaut.*/ translateX(-50%); top: 100px; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_responsive">Il responsive</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; /* pour etre plus responsive on peut passer la taille en vw(view port width) pour qu'elle s'adapte à la taille de l'ecran*/ font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; /* permet en media query de la centrer en petit écran*/ display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } .absolute { position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: translateX(-50%); top: 100px; } /* RESPONSIVE: a partir des tailles d'ecran permet de surcharger les reglages definis plus haut */ @media screen and (max-width: 900px) { .grid-container { display: block; } .grid-container img { width: 40%; } } @media screen and (max-width: 610px) { .flexbox ul { flex-direction: column; align-items: center; } form { grid-template-columns: 1fr; grid-template-rows: 1fr; grid-template-areas: "i1" "i2" "ta" "bt"; } input, textarea { font-size: 0.8rem; } }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_conclusion">Debug & Conclusione</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* all elements: supprime les comportements par défaut*/ * { /* les marges à zéro*/ margin: 0; /* les parge internes(padding) à zéro*/ padding: 0; /* tous les bords avec un cadre rouge de 2px. qui est ou et qui fait quoi...*/ border: 2px solid red; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_inizio">[toc_inizio]</a></p> </div> </div> </div> https://cheroliv.com/blog/2023/0061_memo_html_post.html Sun, 13 Aug 2023 00:00:00 +0000 blog/2023/0061_memo_html_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_buoni_link">Buoni link</a></li> <li><a href="#_repository_e_esempio_di_codice">Repository e esempio di codice</a></li> </ul> </div> <div class="sect1"> <h2 id="_buoni_link">Buoni link</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">html</div> <ul> <li> <p><a href="https://htmlcheatsheet.com" target=""_blank">htmlcheatsheet.com</a>: Foglio di riferimento HTML</p> </li> </ul> </div> <div class="ulist"> <div class="title">font</div> <ul> <li> <p><a href="https://fontawesome.com" target=""_blank">fontawesome.com</a>: biblioteca di icone</p> </li> <li> <p><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a>: Icone native in HTML</p> </li> </ul> </div> <div class="ulist"> <div class="title">caratteri speciali e escape</div> <ul> <li> <p><a href="https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/" class="bare">https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/3614344/13104550" class="bare">https://stackoverflow.com/a/3614344/13104550</a></p> </li> <li> <p><a href="https://html.spec.whatwg.org/multipage/named-characters.html" class="bare">https://html.spec.whatwg.org/multipage/named-characters.html</a></p> </li> </ul> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_repository_e_esempio_di_codice">Repository e esempio di codice</h2> <div class="sectionbody"> <div class="paragraph"> <p>repository GitHub:https://github.com/cheroliv/html-codebase[html-codebase, finestra = "_blank]</p> </div> <div class="paragraph"> <p>fonte memo:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- Le titre de la page --> <title>Cours HTML</title> <!-- Icone de l'onglet --> <link rel="shortcut icon" href="html-logo.png" /> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" /> </head> <body> <header> <h1>Texte - Titre H1</h1> <p> <em>em pour mettre en italique</em>, <strong>strong pour mettre en gras</strong> <span>L'élement en span ne revient pas à la ligne</span>. </p> <p> Lorem ipsum dolor sit amet consectetur adipisicing elit. Exercitationem cumque ratione veniam officiis nulla a debitis at facilis sed dignissimos. </p> </header> <section> <div> <h2>Photo - Titre H2</h2> <img src="./img-1.jpg" alt="image-arbre" height="200" /> </div> <div> <h3>Liste - Titre H3</h3> <ul> <li>UL = unordered list</li> <li>UL = unordered list</li> <li>UL = unordered list</li> </ul> <ol> <li>OL = ordered list</li> <li>OL = ordered list</li> <li>OL = ordered list</li> </ol> </div> <div> <h4>Tableaux - Titre H4</h4> <table border="4" cellpadding="10" cellspacing="4" style="text-align: center"> <thead> <tr> <th>Col 1</th> <th>Col 2</th> <th>Col 3</th> </tr> </thead> <tbody> <tr> <td rowspan="2">Row 1 Cell 1</td> <td>Row 1 Cell 2</td> <td>Row 1 Cell 3</td> </tr> <tr> <td>Row 2 Cell 2</td> <td>Row 2 Cell 3</td> </tr> <tr> <td colspan="3">Row 3 Cell 1</td> </tr> </tbody> </table> </div> <div> <h5><span>♖</span> Liens - Titre H5</h5> <a href="https://htmlcheatsheet.com/" target="_blank">HTML Cheatsheet</a> <br /> <a href="https://www.toptal.com/designers/htmlarrows/symbols/" target="_blank">Icones natifs en HTML</a> </div> <div> <h6><i class="fas fa-video"></i> Vidéo - Titre H6</h6> <video src="video.mp4" height="150" autoplay loop muted></video> </div> </section> <br /> <!-- Formulaires en HTML --> <section> <h2>Formulaire</h2> <form action="/action.php" method="post"> <label for="name">Nom</label> <input id="name" type="text" placeholder="Entrez votre nom" /><br /> <label for="number">Entrez votre age</label> <input type="number" id="number-age" value="15" oninput="document.getElementById('range-age').value=this.value"> <input type="range" id="range-age" min="0" max="100" oninput="document.getElementById('number-age').value=this.value"><br /> <!-- Input select --> <label for="gender">Genre</label> <select id="gender"> <option selected="selected" value="Homme">Homme</option> <option value="Femme">Femme</option> </select><br /> <!-- Input radio --> <div> <input type="radio" name="type" id="human" checked /> <label for="human">Humain</label> <input type="radio" name="type" id="dog" /> <label for="dog">Chien</label> <input type="radio" name="type" id="cat" /> <label for="cat">Chat</label> </div> <textarea cols="20" rows="5" placeholder="Votre message..."></textarea><br /> <!-- Input Checkbox --> <label><input type="checkbox" />Accepter les CGV</label> <br /> <input type="submit" value="Submit" /> </form> </section> <br /> <!-- Mail & envoi de fichiers --> <footer> <a href="mailto:fs@gmail.com">Ecrivez-moi !</a> <br /> <a href="notice.txt" download="nom-du-fichier">Télécharger la notice</a> <details> <summary>Plus d'infos</summary> <p> Lorem ipsum dolor, sit amet consectetur adipisicing elit. Harum, repellendus. </p> </details> </footer> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> https://cheroliv.com/blog/2023/0060_memo_js_post.html Fri, 4 Aug 2023 00:00:00 +0000 blog/2023/0060_memo_js_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>repository GitHubhttps://github.com/cheroliv/js-codebase[js-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_js"><span class="underline">Introduzione JavaScript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#start">Variabili, operatori aritmetici e stringhe di caratteri</a> is not actual text. So nothing to translate. Output nothing.</p> </li> </ol> </div> <div class="paragraph"> <p></think></p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#array">[array]</a></p> </li> <li> <p><a href="#functions">Le funzioni</a></p> </li> <li> <p><a href="#param_x_scope">Parametri e ambiti</a></p> </li> <li> <p>oggetti</p> </li> <li> <p><a href="#loops">I cicli</a></p> </li> <li> <p><a href="#const_var_let">Const, var e let</a></p> </li> <li> <p><a href="#rest_and_spread_operators">Rest e spread operators</a></p> </li> <li> <p><a href="#distrutturazione">[distrutturazione]</a></p> </li> <li> <p><a href="#import_export">Importazione ed esportazione di moduli</a></p> </li> <li> <p><a href="#classi">[classi]</a></p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <title>Document</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> </head> <body> index <script src="01_start.js"></script> <script src="02_arrays.js"></script> <script src="03_functions.js"></script> <script src="04_param_x_scope.js"></script> <script src="05_objects.js"></script> <script src="06_loops.js"></script> <script src="07_const_var_let.js"></script> <script src="08_rest_and_spread_operators.js"></script> <script src="09_destructuring.js"></script> <script src="10_module_import_export.js"></script> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="start">Variabili, operatori aritmetici e stringhe di caratteri</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_start.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Variables */ //une variable stupide var my_variable = "dummy variable"; console.log(my_variable); //assertion console.assert(my_variable === "dummy variable"); var username = "cheroliv"; console.log(username); console.assert(username === "cheroliv"); //concaténation de string console.assert(username === "cher" + "oliv"); /** * Opérateur arithmétique: + - * / % */ //integer var x = 10; var y = 5; var z = 20; console.log(x + y); console.assert(x + y === 15); console.log(x + y - z); console.assert(x + y - z === -5); console.log(x - y); console.assert(x - y === 5); console.log(x * y); console.assert(x * y === 50); console.log(x / y); console.assert(x / y === 2); console.log("---------"); x = 20; y = 10; console.log(x + y); console.assert(x + y === 30); console.log(x + y - z); console.assert(x + y - z === 10); console.log(x - y); console.assert(x - y === 10); console.log(x * y); console.assert(x * y === 200); console.log(x / z); console.assert(x / z === 1); //Littéraux de gabarits pour string avec backstick ` //Template literals (Template strings) console.assert(`typeof z: ${typeof z}` === "typeof z: number"); console.log(`x is type of : ${typeof x}`); console.log(`y is type of : ${typeof y}`); console.log(`z is type of : ${typeof z}`); //typeof: donne le type de la variable console.assert(typeof x === "number"); console.assert(typeof y === "number"); console.assert(typeof z === "number"); console.log("---------"); /** * Incrémenation/décrémentation */ //incrémantation/décrémentation préfixe console.log(++x) //incrémenté puis affiché: 21 console.log(x) //la valeur incrémenté: 21 //incrémantation/décrémentation suffixe console.log(y++) //affiche la valeur sans incrémenation puis incrémente: 10 console.log(y) //la valeur incrémenté: 11 //décrémentation x--; y--; console.assert(x === 20); console.assert(y === 10); /** * String: chaine de caractères */ console.log(`username: ${username}`); //taille de la string console.log(`username.length: ${username.length}`); console.assert(username.length === 8); console.assert(username.length === "cheroliv".length); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrays">Gli array</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_arrays.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les arrays */ // auteurs [["nom ", "prénom", "pays"]] var writers = [ ["Karl", "Marx", "de"], ["Jean-Jacques", "Rousseau", "fr"], ["Victor", "Hugo", "fr"], ["René", "Descartes", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["Georg", "Hegel", "de"], ["Friedrich", "Engels", "de"], ] console.table(writers); // accés aux élèments du tableau console.log(writers[0]); console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); //sauvegarder la valeur du prénom de Marx var karl = writers[0][0] //éditer un élement du tableau, le prénom de Marx writers[0][0] = "Karlito" console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karlito, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl" === karl); //remettre la valeur initale du prénom de Marx writers[0][0] = karl; console.assert(`${karl}, Marx (de)` === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.log("---------"); /** * Arrays: map/forEach/pop/push/slice/sort/shift/unshift */ var numbers = [1, 5, 4, 3, 2]; console.log("Iterate with forEach"); // parcourir avec array.forEach numbers.forEach((it) => console.log(it)); console.log("---------"); console.log("Iterate with map"); // parcourir avec array.map numbers.map((it) => console.log(it)); console.log("---------"); //afficher les éléments sur une ligne //génère la string avec le formatage des nombres const numbersString = (numberArray) => { var consoleOutput = new String(); numberArray.forEach(number => consoleOutput += `${number}, `); return consoleOutput = consoleOutput.substring(0, consoleOutput.length - 2); }; //affiche la chaine entre crochets dans la console const displayNumbers = (numbersStr) => { console.log(`[${numbersString(numbersStr)}]`); }; console.log("orginal number array") displayNumbers(numbers); console.log("---------"); //push: ajoute à la fin console.log("push"); numbers.push(6); displayNumbers(numbers); console.log("---------"); //pop: suprime le dernier console.log("pop"); numbers.pop(); displayNumbers(numbers); console.log("---------"); //unshift: ajouter le parametre au debut de l'array console.log("unshift"); numbers.unshift(0); displayNumbers(numbers); console.log("---------"); //shift: supprime le premier element de l'array console.log("shift"); numbers.shift(); displayNumbers(numbers); console.log("---------"); //slice: renvoi l'array entre les positions en argument console.log("slice"); var sliceNumbersResult = numbers.slice(2, 4); displayNumbers(sliceNumbersResult); console.log("---------"); //sort asc console.log("sort asc"); var ascSort = numbers.sort((a, b) => a - b); displayNumbers(ascSort); console.log("---------"); //sort desc console.log("sort desc"); var descSort = numbers.sort((a, b) => b - a); displayNumbers(descSort); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">Le funzioni</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les fonctions */ //function style legacy function sayHelloWorldLegacy() { console.log("Hello world legacy!"); } sayHelloWorldLegacy(); function sayHelloLegacy(firstName, lastName, style) { console.log(`Hello ${firstName}, ${lastName} (${style})`); } sayHelloLegacy("Cher", "Oliv", "legacy"); console.log("---------"); //function style arrow const sayHelloWorld = () => console.log("Hello world!"); sayHelloWorld(); const sayHello = (firstName, lastName) => console.log(`Hello ${firstName}, ${lastName}`); sayHello("Cher", "Oliv"); console.log("---------"); var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ] const displayAuthors = (authorsArray) => authorsArray.forEach(author => console.log(`${author[0]} ${author[1]}, (${author[2]})`) ); displayAuthors(authors); console.log("---------"); /** * valeur par défaut des parametres d'une fonctions */ const add = (a = 0, b = 0) => a + b; console.assert(add() === 0) console.assert(add(1) === 1) console.assert(add(1, 1) === 2) console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="param_x_scope">Parametri e ambiti</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_param_x_scope.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//global scope: visible partout, dans et hors functions var global; const foo = () => { //local scope: visible uniquement dans la fonction foo var bar = "bar" console.log(bar) } foo(); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="objects">Gli oggetti</h2> <div class="sectionbody"> <div class="paragraph"> <p>05_objects.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les objects */ var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; var hugo = { firstName: authors[7][0], lastName: authors[7][1], country: authors[7][2], }; var book = { author: hugo, title: "Les misérables" }; console.log(hugo); console.log(book); //accéder à un membre de l'objet par point console.log(hugo.country); //accéder à un membre de l'objet par crochet console.log(book["title"]); console.log(book.author.lastName); console.log(book["author"]["firstName"]); //ajouter une clé a un objet hugo.gender = "non binary"; console.assert(hugo.gender === "non binary"); //mettre à jour une clé hugo.gender = "male"; console.assert(hugo.gender !== "non binary"); console.assert(hugo["gender"] === "male"); //supprimer une clé delete hugo.gender; //verfier que l'objet ne contient pas la clé gender console.assert(!Object.keys(hugo).includes("gender")); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="loops">I cicli</h2> <div class="sectionbody"> <div class="paragraph"> <p>06_loops.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les boucles: Itérer sur arrays et objets. */ console.log("for loop over array"); var numbers = [12, 10, 8, 6, 4, 2, 0]; for (number of numbers) { console.log(number); } console.log("---------"); console.log("for loop over object key"); var obj = { a: 1, b: 2, c: 3, d: 4 }; for (key in obj) { console.log(key); } console.log("---------"); console.log("for loop over object value"); for (value in obj) { console.log(obj[value]); } console.log("---------"); console.log("another for loop over authors array") var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; for (const [i, value] of authors.entries()) { console.log(`${value[0]}, ${value[1]} (${value[2]})`); } console.log("---------"); console.log("while loop over array") var i = 0 while (i < authors.length) { console.log(`${authors[i][0]}, ${authors[i][1]} (${authors[i][2]})`); i++; } console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="const_var_let">Const, var e let</h2> <div class="sectionbody"> <div class="paragraph"> <p>07_const_var_let.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * const X var X let */ //var x du if n'est pas confiné au scope du if const varTest = () => { var x = 1; console.log(x); console.assert(x === 1); if (true) { var x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x !== 1); console.assert(x === 2); } varTest(); console.log("---------"); //var x est global à tous les fichier js //chargés dans la page html //var x issue du fichier 1_start.js //ligne 46 console.log(x); console.assert(x === 20); console.log("---------"); //premier let x est confiné au scope de la fonction //le let x du if est confiné au scope du if const letTest = () => { let x = 1; console.log(x); console.assert(x === 1); if (true) { let x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x === 1); console.assert(x !== 2); } letTest(); console.log("---------"); /** * const: déclare un emplacement mémoire non réattribuable * c'est modifiable pour un array, * mais non réinitialisable; * ex: * const arr = [25, 27, 29] * arr = [5, 7] //impossible * arr[0]=20 // possible * ex: * const n = 1; * n = 3; //impossible */ const arr = [25, 27, 29] console.table(arr); arr[0] = 20 // possible console.table(arr); arr.pop() console.table(arr); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="rest_and_spread_operators">Rest e spread operators</h2> <div class="sectionbody"> <div class="paragraph"> <p>08_riposo_e_diffusione_operatori.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérateur de rest: * const add = (...operandes) => a + b; * ou avec parametres avec valeur par défaut * const add = (a=0, b=0, ...operandes) => a + b; */ /** * spread opérateur: * récupère l'ensemble des elements d'une collection, * dans un array */ const user_ages = [25, 56, 12, 58, 41, 62, 26]; const max_user_age = Math.max(...user_ages); const min_user_age = Math.min(...user_ages); console.assert(max_user_age == 62); console.assert(min_user_age == 12); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="destructuring">Distrutturazione</h2> <div class="sectionbody"> <div class="paragraph"> <p>09_destructuring.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * L'affectation par décomposition (destructuring) */ const user = { first_name: "Oliv", last_name: "Cher", nick_name: "cheroliv", gender: "male", is_adult: true }; console.log(user); //première façon d'initaliser des variables sans destructuration let first_name_legacy = user.first_name; let last_name_legacy = user.last_name; let nick_name_legacy = user.nick_name; let gender_legacy = user.gender; let is_adult_legacy = user.is_adult; console.assert("Oliv" === first_name_legacy); console.assert("Cher" === last_name_legacy); console.assert("cheroliv" === nick_name_legacy); console.assert("male" === gender_legacy); console.assert(true === is_adult_legacy); console.log("---------"); /** * Initialisation par déstructuration */ const { first_name, last_name, nick_name, gender, is_adult } = user; console.assert(user.first_name === first_name); console.assert(user.last_name === last_name); console.assert(user.nick_name === nick_name); console.assert(user.gender === gender); console.assert(user.is_adult === is_adult); /** * Intialisation par déstructuration des arrays */ //cible explicite const [a1, a2] = [15, 25, 17, 81, 51, 46]; console.assert(a1 === 15); console.assert(a2 === 25); //cible avec position par rapport aux index par virgules //je veux b3 à 46 const [b1, b2, , , , b3] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(b3 === 46); //déstructuration avec operateur de rest // je contruit un autre avec avec les elements // à partir du premier élèment non destructuré const [c1, c2, ...sub_arr] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(sub_arr.length === 4); console.assert(sub_arr[0] === 17); console.assert(sub_arr[1] === 81); console.assert(sub_arr[2] === 51); console.assert(sub_arr[3] === 46); // Une boucle pour comparer le resultat attendu for (const [i, value] of[15, 25, 17, 81, 51, 46].entries()) { //on reconstruit le tableau à chaque iteration console.assert([c1, c2].concat(sub_arr)[i] === value); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="import_export">Importazione ed esportazione di moduli</h2> <div class="sectionbody"> <div class="paragraph"> <p>10_module_import_export.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Import et export de module * * Dans le fichier html * au niveau de la balise d'import de script * spécifier le type module * * 1er technique: import nommé des fonctions: * import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; * * 2eme technique: import global des fonction avec l'asterisque(*) * en préfixant l'import par un nommage du fichier importé: * import * as math from "./dummy_math_functions.js"; * * 3eme technique: import par alias avec le mot clé "as" * import { * sum as add, * minus as substract, * times as multiply, * div as divide, * rem as modulo * } from "./dummy_math_functions.js"; */ import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; console.assert(sum(1, 1) === 2); console.assert(minus(4, 2) === 2); console.assert(times(2, 2) === 4); console.assert(div(4, 2) === 2); console.assert(rem(4, 2) === 0);</code></pre> </div> </div> <div class="paragraph"> <p>dummy_math_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//sum const sum = (x, y) => x + y; // subtraction const minus = (x, y) => x - y; // multiplication const times = (x, y) => x * y; // division const div = (x, y) => x / y; // remainder: reste de la division euclidiene const rem = (x, y) => x % y; // log sum const sum_log = (x, y) => console.log(sum(x, y)); // log subtraction const minus_log = (x, y) => console.log(minus(x, y)); // log multiplication const times_log = (x, y) => console.log(times(x, y)); // log division const div_log = (x, y) => console.log(div(x, y)); // log remainder const rem_log = (x, y) => console.log(rem(x, y)); export { sum, minus, times, div, rem, sum_log, minus_log, times_log, div_log, rem_log };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="classes">Utilizzo delle classi</h2> <div class="sectionbody"> <div class="paragraph"> <p>11_classes.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Utilisation des classes */ //creation d'un objet class Account { constructor(username) { this.username = username; } }; const acc1 = new Account("cheroliv"); console.table(acc1); console.assert(acc1.username === "cheroliv"); console.log("---------"); //création d'un objet et ajout de getter et setter(accesseurs) class AccountInfo { constructor(username) { this._username = username; } get username() { return this._username; } /** * @param {(arg0: string) => void} new_username */ set new_username(new_username) { this._username = new_username; } }; const acc_info1 = new AccountInfo("cheroliv"); console.table(acc_info1); //accés au membre _username avec le getter username() console.assert(acc_info1.username === "cheroliv"); //update la valeur username de acc_info1 avec le setter acc_info1.new_username = "imrandeh"; console.assert(acc_info1.username === "imrandeh"); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">Introduzione JavaScript</span></a></p> </div> </div> </div> https://cheroliv.com/blog/2022/0054_memo_cadrage_post.html Sat, 31 Dec 2022 00:00:00 +0000 blog/2022/0054_memo_cadrage_post.html <div class="sect1"> <h2 id="_inquadratura">inquadratura</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_laboratorio_1_visione">Laboratorio 1: Visione</h3> <div class="sect3"> <h4 id="_1_il_pattern_qqoqcp_chi_cosa_dove_quando_come_perché">1. Il pattern “QQOQCP” – Chi, Cosa, Dove, Quando, Come, Perché</h4> </div> <div class="sect3"> <h4 id="_2_il_product_vision_board">2. Il Product Vision Board</h4> <div class="sect4"> <h5 id="_gruppo_target">Gruppo target</h5> <div class="paragraph"> <p>Chi sono gli utenti che utilizzano il prodotto o l’offerta? (diretto, indiretto)</p> </div> </div> <div class="sect4"> <h5 id="_bisogni">Bisogni</h5> <div class="paragraph"> <p>Quali sono i 5 bisogni principali degli utenti chiave dell’applicazione?</p> </div> </div> <div class="sect4"> <h5 id="_prodotto">prodotto</h5> <div class="paragraph"> <p>Qual è la mia proposta di valore? Quali sono le 5 funzionalità principali del prodotto che permettono di rispondere alle bisogni</p> </div> </div> <div class="sect4"> <h5 id="_obiettivo_commerciale">obiettivo commerciale</h5> <div class="paragraph"> <p>Quali sono i criteri di successo ?</p> </div> </div> <div class="sect4"> <h5 id="_visone">Visone</h5> <div class="paragraph"> <p>Quando le 4 colonne sono complete, dovrai compilare la sezione vision del Product Vision Board in una frase completa.</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_laboratorio_2_personaspercorsi_utenti">Laboratorio 2: Personas/percorsi utenti</h3> <div class="ulist"> <div class="title">Definire per ogni persona un percorso utente:</div> <ul> <li> <p>Chi utilizzerà il mio servizio? (Obiettivo)</p> </li> <li> <p>Cosa vuole fare ? (Ma)</p> </li> <li> <p>Come farà? (Percorso Utente)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_laboratorio_3_zoning_storyboard_sitemap">Laboratorio 3: Zoning, Storyboard, Sitemap</h3> <div class="sect3"> <h4 id="_zonizzazione">Zonizzazione</h4> </div> <div class="sect3"> <h4 id="_2_storyboard">2. Storyboard</h4> </div> <div class="sect3"> <h4 id="_3_sitemap">3. SiteMap</h4> </div> </div> <div class="sect2"> <h3 id="_laboratorio_4_wireframemoodboard">Laboratorio 4: Wireframe/Moodboard</h3> <div class="sect3"> <h4 id="_1_wireframes">1. Wireframes</h4> </div> <div class="sect3"> <h4 id="_2_moodboard">2. Moodboard</h4> </div> </div> <div class="sect2"> <h3 id="_laboratorio_5_story_mapping_user_stories">Laboratorio 5: Story Mapping/ User stories</h3> <div class="sect3"> <h4 id="_story_mapping_prioritizzazione_delle_us">Story mapping (prioritizzazione delle US)</h4> </div> <div class="sect3"> <h4 id="_in_quanto_type_dutilisateur_voglio_un_objectif_affinché_une_raison">In quanto <type d’utilisateur>, voglio <un objectif> affinché <une raison>.</h4> </div> </div> <div class="sect2"> <h3 id="_laboratorio_6_backlog">Laboratorio 6: Backlog</h3> <div class="paragraph"> <p><a href="https://www.atlassian.com/fr/agile/scrum/backlogs">arretrati</a></p> </div> </div> <div class="sect2"> <h3 id="_atelier_7_tecnica_e_architettura">Atelier 7: Tecnica e Architettura</h3> </div> </div> </div> https://cheroliv.com/blog/2022/0053_memo_kotlin_post.html Sun, 29 May 2022 00:00:00 +0000 blog/2022/0053_memo_kotlin_post.html <div class="sect1"> <h2 id="_buoni_link">buoni link</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://play.kotlinlang.org/">kotlinlang area giochi</a>+</p> </div> <div class="paragraph"> <p><a href="https://arrow-kt.io/">freccia.kt</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/MVIKotlin/">MVI:Model View Intent</a>+</p> </div> <div class="paragraph"> <p><a href="https://github.com/arkivanov/Essenty">Essenty</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/Decompose/">Decompose</a>+</p> </div> </div> </div> <div class="sect1"> <h2 id="_frammento_di_codice_vario">Frammento di codice vario</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_map_reduce">map reduce</h3> <div class="paragraph"> <p>Convertire una lista di bit in una lista di stringhe e riassumere la lista di stringhe<br> in una stringa contenente la concatenazione. Come loggare la richiesta inviata(requestBodyContent:byte[])</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">log.info( requestBodyContent!!.map { it.toInt().toChar().toString() } .reduce { request: String, s: String -> request + s } )</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_enum_e_classi_sealed">enum e classi sealed</h3> <div class="paragraph"> <p>post:<a href="0038_training_kotlin_enum_sealed_class_post" target=""_blank">formazione kotlin enum classe sigillata</a></p> </div> </div> <div class="sect2"> <h3 id="_functional_interface_e_method_reference">functional interface e method reference</h3> <div class="paragraph"> <p>È possibile trasformare un’entità in un modello di dominio DTO utilizzando un metodo di riferimento (stile funzionale - Java 8)</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun findAllByLoginNot( pageable:Pageable, login:String) :Page<UserDto> { return userDao.findAllByLoginNot( pageable, login).map(::fromEntity) }</code></pre> </div> </div> <div class="paragraph"> <p>unahttps://stackoverflow.com/a/22245383/837404[buona spiegazione]</p> </div> </div> <div class="sect2"> <h3 id="_catturare_loutput_standard">Catturare l’output standard</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOF { private val standardOut: PrintStream? = out private val outputStreamCaptor = ByteArrayOutputStream() @BeforeTest fun setUp() = setOut(PrintStream(outputStreamCaptor)) @AfterTest fun tearDown() = setOut(standardOut) @Test fun `three times dope`() { 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_qual_è_la_differenza_in_kotlin_tra_apply_run_let_also_use_e_with">Qual è la differenza in Kotlin tra apply, run, let, also, use e with ?</h3> <div class="paragraph"> <p><strong>Confronto delle funzioni Kotlin e utilizzo delle forme lambda Riferimento</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_applica">applica</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Introduzione Le funzioni Kotlin`apply`, <code>run</code>, <code>let</code>, <code>also</code>, <code>use</code>, et `with`offrono diversi modi di trattare gli oggetti. Ciascuna ha i propri casi d’uso e comportamenti. Inoltre, le forme lambda reference consentono di rendere il codice più leggibile e riutilizzabile facendo riferimento a funzioni lambda esistenti.</div> <p>La funzione`apply`viene utilizzato per configurare un oggetto durante la sua creazione. Restituisce l’oggetto su cui viene chiamata.</p> </div> <div class="paragraph"> <p>Esempio con lambda reference:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val someObject = SomeClass().apply(::configureObject)</code></pre> </div> </div> <div class="paragraph"> <p>Esempio con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val someObject = SomeClass().apply { // configuration des propriétés de someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_esegui">esegui</h2> <div class="sectionbody"> <div class="paragraph"> <p>La funzione`run`viene utilizzata per eseguire un blocco di codice su un oggetto e restituisce il risultato del blocco di codice.</p> </div> <div class="paragraph"> <p>Esempio con riferimento lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run(::someFunction)</code></pre> </div> </div> <div class="paragraph"> <p>Esempio con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lascia">lascia</h2> <div class="sectionbody"> <div class="paragraph"> <p>La funzione`let`viene utilizzata per eseguire un blocco di codice su un oggetto e restituisce il risultato del blocco di codice.</p> </div> <div class="paragraph"> <p>Esempio con riferimento lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let(::processObject)</code></pre> </div> </div> <div class="paragraph"> <p>Esempio con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_anche">anche</h2> <div class="sectionbody"> <div class="paragraph"> <p>La funzione`also`viene utilizzata per eseguire un’azione aggiuntiva su un oggetto e restituisce l’oggetto su cui viene chiamata</p> </div> <div class="paragraph"> <p>Esempio con riferimento lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someObject.also(::performAdditionalAction)</code></pre> </div> </div> <div class="paragraph"> <p>Esempio con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someObject.also { // action additionnelle sur someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_logora">logora</h2> <div class="sectionbody"> <div class="paragraph"> <p>La funzione`use`Viene utilizzata per lavorare con le risorse che devono essere chiuse dopo l’uso. Chiama automaticamente la funzione`close`alla fine del blocco</p> </div> <div class="paragraph"> <p>Esempio con riferimento lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someResource.use(::useResource)</code></pre> </div> </div> <div class="paragraph"> <p>Esempio con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someResource.use { // travailler avec la ressource }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_con">con</h2> <div class="sectionbody"> <div class="paragraph"> <p>La funzione`with`viene utilizzato per chiamare più metodi su un oggetto senza ripetere il suo nome e restituisce il risultato dell’ultima espressione.</p> </div> <div class="paragraph"> <p>Esempio con riferimento lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = with(someObject, ::processWithObject)</code></pre> </div> </div> <div class="paragraph"> <p>Esempio con lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = with(someObject) { // appeler des méthodes sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> <div class="paragraph"> <p>Utilizzando le forme lambda di riferimento o i blocchi`{}`, puoi incapsulare la logica in funzioni separate, migliorando così la leggibilità e la riutilizzabilità del codice.</p> </div> </div> </div> <div class="sect1"> <h2 id="_let_function_in_kotlin">let Function in Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Restituisce let l’oggetto con gli effetti collaterali applicati sopra o nello stato iniziale di ingresso in funzione(let) ?</div> <p>La funzione`let`In Kotlin è utilizzata per eseguire operazioni su un oggetto e restituire un risultato diverso. Tuttavia, è importante notare che la funzione`let`non modifica lo stato iniziale dell’oggetto su cui viene chiamata</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Firma</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>inline fun <T, R> T.let(block: (T) → R): R</code></p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Uso</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">La funzione`let`è comunemente utilizzata per applicare delle trasformazioni a un oggetto e ottenere un risultato basato su queste trasformazioni.</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Risultato</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Il valore restituito dalla funzione`let`è il risultato dell’espressione lambda passata come argomento, generalmente il risultato delle operazioni effettuate sull’oggetto.</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Effetti di bordo</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sebbene la funzione`let`può avere effetti collaterali sull’oggetto quando viene utilizzata nell’espressione lambda, ma non modifica lo stato iniziale dell’oggetto stesso.</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Così, la funzione`let`è un modo elegante per eseguire operazioni su un oggetto ottenendo contemporaneamente un risultato derivato, preservando al contempo l’integrità dell’oggetto originale.</p> </div> </div> </div> https://cheroliv.com/blog/2022/0052_memo_jvm_post.html Sat, 28 May 2022 00:00:00 +0000 blog/2022/0052_memo_jvm_post.html <div class="sect1"> <h2 id="toc">indice</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#char">stringhe di caratteri e caratteri</a></p> </li> <li> <p><a href="#math">numeri e matematica</a></p> </li> <li> <p><a href="#date">date e ore</a></p> </li> <li> <p><a href="#java8date">date e ore java8</a></p> </li> <li> <p><a href="#arrCol">array e collezioni</a></p> </li> <li> <p><a href="#sysProp">System.Properties</a></p> </li> <li> <p><a href="#threads">Thread</a></p> </li> <li> <p><a href="#regex">Espressioni regolari</a></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="char">stringhe di caratteri e caratteri</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.Collator import java.util.* import kotlin.test.* class StringsTest { @Test fun `chaines de caractères et caractères`() { //inférence de type val s = "C'est" assertEquals("C'est", s) //concaténation val t: String = s + " le moment." assertEquals("C'est le moment.", t) // StringBuilder val t1: String = s + buildString { append(" le moment.") } assertEquals("C'est le moment.", t1) //interpolation val t2 = "$s le moment." assertEquals("C'est le moment.", t2) //multiligne chaine de caractères val t3 = """$s le moment.""" assertEquals("C'est le moment.", t3) //conversion de type val t4 = t + " " + 23.4 assertEquals("C'est le moment. 23.4", t4) val t5 = 'C'.toString() assertEquals("C", t5) //taille de la chaine de caractères assertEquals(16, t.length) //sous-chaine d'une chaine de caractères //retourne une chaine de caractères contenant, //les caractères aux positions x à y-1 //sub = t.substring(x, y) //t = "C'est le moment." //retourne les caractères 6 et 7 var sub = t.substring(6, 8) assertEquals("le", sub) //retourne les caractères 0 à 4 sub = t.substring(0, 5) assertEquals("C'est", sub) //la longueur d'une sous-chaine est toujours égale (y-x) val numChars = sub.length assertEquals(5 - 0, numChars) //extraction des caractères d'une chaine assertEquals('e', t.elementAt(2)) assertEquals('e', t.get(2)) assertEquals('e', t[2]) //conversion d'une chaine en tableau de caractères val ca = t.toCharArray() assertEquals(t.length, ca.size) t.mapIndexed { index, char -> assertEquals(char, ca[index]) } //place les 4 premiers caractères de t1 //dans le tableau ca a la position 2 (t as java.lang.String).getChars( /* srcBegin = */ 0, /* srcEnd = */ 3, /* dst = */ ca, /* dstBegin = */ 1 ) assertEquals("CC'et le moment.", String(ca)) //colle tous les caractères dans un meme string assertEquals("CC'et le moment.", ca.concatToString()) //to lower case assertEquals("c'est le moment.", t.toLowerCase()) assertEquals("c'est le moment.", t.lowercase()) //to upper case assertEquals("C'EST LE MOMENT.", t.toUpperCase()) assertEquals("C'EST LE MOMENT.", t.uppercase()) //comparaison de chaines de caractères //t = "C'est le moment." assertFalse(t.equals("hello")) assertFalse(t == "hello") //ignore la casse assertTrue(t.equalsIgnoreCase("C'EST LE MOMENT.")) assertTrue(t.equals("C'EST LE MOMENT.", ignoreCase = true)) //démarre par assertTrue(t.startsWith("C'est")) //se finit par assertTrue(t.endsWith("le moment.")) //compareTo //retourne une valeur < 0, car s est //alphabétiquement avant "N'est" val r1: Int = s.compareTo("N'est") assertTrue(r1 < 0) //variante ignorant la casse val r1Prime: Int = (s as java.lang.String).compareToIgnoreCase("n'est") assertTrue(r1Prime < 0) //retourne 0 si les chaines sont equivalente val r2: Int = s.compareTo("C'est") assertEquals(0, r2) //retourne une valeur > 0 car s vient apres "B'est" val r3: Int = s.compareTo("B'est") assertTrue(r3 > 0) //Recherche de caractères et de sous-chaines de caractères //recherche de caractères //position du premier caractères 't' var pos = t.indexOf('t') assertEquals(4, pos) //position du suivant pos = t.indexOf('t', pos + 1) assertEquals(14, pos) //retour d'érreur -1 si absence de suivant pos = t.indexOf('t', pos + 1) assertEquals(-1, pos) //position du dernier 't' dans la chaine: 14 pos = t.lastIndexOf('t') assertEquals(14, pos) //recherche de 't' vers l'arrière a partir du caractères 13 pos = t.lastIndexOf('t', pos - 1) assertEquals(4, pos) //recherche de sous-chaines //retourne 2 pos = t.indexOf("est") assertEquals(2, pos) //"est" n'apparait qu'une seule fois: retourne -1 pos = t.indexOf("est", pos + 1) assertEquals(-1, pos) //recherche d'une sous-chaine depuis l'arrière //t = "C'est le moment." //retourne 6 pos = t.lastIndexOf("le ") assertEquals(6, pos) //extrait depuis la position 9, //renvoi toute la chaine après "le " val noun = t.substring(pos + 3) assertEquals(-1, noun.indexOf("le ")) //remplacement de toutes les instances d'un caractère //par un autre caractère //ne fonctionne que avec les caractères, pas les chaines val exclaim: String = t.replace('.', '!') assertEquals('!', exclaim.get(exclaim.length - 1)) assertEquals(exclaim.length - 1, exclaim.indexOf('!')) assertEquals(-1, exclaim.indexOf('.')) //suppression des espaces blancs //au début et à la fin d'une chaine val noextraspaces = t.trim() assertNotEquals(' ', noextraspaces.get(0)) assertNotEquals(' ', noextraspaces.get(noextraspaces.length - 1)) //extraction des instances uniques de chaines de caractères //avec intern() val s1 = s.intern() assertEquals(s, s1) val s2 = "C'est".intern() assertEquals("C'est", s2) assertEquals(s1, s2) //StringBuilder pour manipuler les caractères d'une chaine de caractères //crée un tampon StringBuilder à partir d'une chaine de caractères val b = StringBuilder("N'est") //extrait et définit des caractères individuel du tampon StringBuilder //le caractères à l'index 0 val c: Char = b.get(0) assertEquals('N', c) //modifier le premier caractère de la chaine b.setCharAt(0, 'C') assertEquals(s, b.toString()) //ajouter des données à un StringBuilder b.append(' ') b.append("le moment.") b.append(23) //insère des chaines de caractères ou autre dans le StringBuilder b.insert(6, "pas ") assertEquals("C'est pas le moment.23", b.toString()) //remplace un sous ensemble de caractères //avec une chaine de caractères donnée b.replace(2, 9, "est") assertEquals("C'est le moment.23", b.toString()) //supprime les caractères b.delete(15, 18) assertEquals("C'est le moment", b.toString()) b.deleteCharAt(2) assertEquals("C'st le moment", b.toString()) //insert à la postion 2 et décale reste à droite(sans perte de données) b.insert(2, 'e') //tronque la taille de la donnée b.setLength(5) assertEquals("C'est", b.toString()) //inverse les caractères de la chaine b.reverse() assertEquals("tse'C", b.toString()) //écrase le StringBuilder, pret à etre réutilisé b.setLength(0) assertEquals("", b.toString()) //java.util.StringTokenizer pour fragmenter une chaine //de caractères en un ensemble de mots var st = StringTokenizer(t) //nb d'items encore présentent dans la file assertEquals(3, st.countTokens()) //est ce que il y a encore des items dans la file assertTrue(st.hasMoreTokens()) //récupérer le token courrant assertEquals("C'est", st.nextToken()) assertEquals("le", st.nextToken()) assertEquals("moment.", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //extraire des occurences de mots délimités //par des caractères autres que des expaces. val str = "a:b:c:d" st = StringTokenizer(str, ":") assertEquals(4, st.countTokens()) assertTrue(st.hasMoreTokens()) assertEquals("a", st.nextToken()) assertEquals("b", st.nextToken()) assertEquals("c", st.nextToken()) assertEquals("d", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //text="C'est le moment." val text = t.toCharArray() var p = 0 //sauter les espaces de tete //pour ramener p à la position du premier caractère imprimable while ((p < text.size) && (Character.isWhitespace(text[p])) ) p++ assertEquals(0, p) assertEquals("C'est le moment.", text.concatToString()) //met le premier mot du texte en majuscule while (p < text.size && Character.isLetter(text[p])) { text[p] = Character.toUpperCase(text[p]) p++ } assertEquals(1, p) assertEquals('C', text[0]) assertTrue(Character.isUpperCase(text[0])) assertFalse(Character.isLetter(text[1])) //comparer des chaines de caractères // avec les contrainte la locale système val col = Collator.getInstance() //le résulat est négatif car chica //est avant chico dans l'ordre alphabétique assertTrue(col.compare("chica", "chico") < 0) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="math">numeri e matematica</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.math.BigInteger import java.security.SecureRandom import java.text.NumberFormat import java.util.* import kotlin.test.* class NumbersMathTest { @Test fun `Nombres et Math`() { //Constantes utiles Byte.MIN_VALUE Byte.MAX_VALUE Short.MIN_VALUE Short.MAX_VALUE Float.MIN_VALUE Float.MAX_VALUE Math.PI Math.E val s = "-42" //conversion de chaine de caractères //vers un nombre, si possible. var b: Byte = java.lang.Byte.parseByte(s) var sh: Short = java.lang.Short.parseShort(s) var i: Int = java.lang.Integer.parseInt(s) var l: Long = java.lang.Long.parseLong(s) var f: Float = java.lang.Float.parseFloat(s) var d: Double = java.lang.Double.parseDouble(s) //valeur exacte val f_exac = java.lang.Float.valueOf(s) val d_exac = java.lang.Double.valueOf(s) //les routines de conversions entière gérent //les nombres dans diverses bases. //1011 en binare est égal a 11 en base dix b = java.lang.Byte.parseByte("1011", 2) assertEquals(11, b) //ff en base 16(hexa) est égal à 255 en base dix. sh = java.lang.Short.parseShort("ff", 16) assertEquals(255, sh) //la méthode valueOf() peut gérer des bases arbitraires. i = java.lang.Integer.valueOf("egg", 17).toInt() assertEquals(4334, i) //la méthode decode() gére les representations octale, //décimal, hexadécimal, en fonction du préfixe numérique //de la chaine de caractères //un 0 de tete signifie base 8 //un 0x de tete signifie base 16 //les autres sont en base 10 val sho = java.lang.Short.decode("0377") //la classe Integer peut convertir les nombres //en diverses chaines de caractères. val decimal = java.lang.Integer.toString(42) assertEquals("42", decimal) val decimal_ = 42.toString() assertEquals("42", decimal_) val binary = java.lang.Integer.toBinaryString(42) assertEquals("101010", binary) val octal = java.lang.Integer.toOctalString(42) assertEquals("52", octal) val hex = java.lang.Integer.toHexString(42) assertEquals("2a", hex) val base36 = java.lang.Integer.toString(42, 36) assertEquals("16", base36) val base36_ = 42.toString(36) assertEquals("16", base36_) //java.text.NumberFormat effectue la conversion // d'une maniere spécifique aux parametres locaux //sans parametre prend la local systeme comme reference val nf = NumberFormat.getNumberInstance(Locale.FRANCE) val formatted_number = nf.format(9876543.21) assertNotEquals("9876543.21", formatted_number) //parse la chaine de caractères en fonction des parametres locaux(fr) val n = nf.parse("1234567,89") assertEquals(1234567.89, n) //les valeurs monétaires sont parfois formaté // d'une maniere differente des nombres val money_format = NumberFormat.getCurrencyInstance(Locale.FRANCE) assertEquals("123,40 €", money_format.format(1234.56)) //java.lang.Math d = Math.toRadians(27.0) d = Math.cos(d) d = Math.sqrt(d) d = Math.log(d) d = Math.exp(d) d = Math.pow(10.0, d) d = Math.atan(d) d = Math.toDegrees(d) //arrondi au dessus val up = Math.ceil(d) //arrondi au dessous val down = Math.floor(d) //arrondi au plus près val nearest = Math.round(d) //java.lang.Math.Random() val r = Math.random() assertTrue(r >= 0.0 && r < 1.0) //créé un nouvel objet Random, en l'initialisant //avec l'heure courante val generator = java.util.Random(System.currentTimeMillis()) //prochaine valeur aléatoire de taille double d = generator.nextDouble() assertTrue((d >= 0.0) && (d < 1.0)) //prochaine valeur aléatoire de taille float f = generator.nextFloat() assertTrue((f >= 0.0) && (f < 1.0)) //prochaine valeur aléatoire de taille long l = generator.nextLong() assertTrue( (Math.abs(l) <= Long.MAX_VALUE) && (Math.abs(l) >= 0) ) //prochaine valeur aléatoire de taille int i = generator.nextInt() assertTrue( (Math.abs(i) <= java.lang.Integer.MAX_VALUE) && (Math.abs(i) >= 0) ) val limit = 100 //prochaine valeur aléatoire de taille int //la limit max du ramdom est ramené à limit //et la limit min est 0 i = generator.nextInt(limit) assertTrue(i in 0 until limit) //prochaine valeur aléatoire de taille booléen val bool = generator.nextBoolean() assertNotNull(bool) //valeur moyenne 0.0, déviation standard 1.0 d = generator.nextGaussian() //randoms bytes //rempli un tableau avec des valeurs byte aléatoires val b_arr = ByteArray(128) generator.nextBytes(b_arr) b_arr.iterator().forEachRemaining { assertTrue( it <= Byte.MAX_VALUE && it >= Byte.MIN_VALUE ) } //java.security.SecureRandom pour les nombres aléatoires //utilisé en cryptographie val secure_generator = SecureRandom() //le générateur génère sa propre tete de liste sur 16 octets secure_generator.setSeed(secure_generator.generateSeed(16)) val sec_b_arr = ByteArray(128) secure_generator.nextBytes(sec_b_arr) sec_b_arr.iterator().forEachRemaining { assertTrue( it <= java.lang.Byte.MAX_VALUE && it >= java.lang.Byte.MIN_VALUE ) } //java.math.BigDecimal java.math.BigInteger //pour travailler sur des grandes valeurs. //calcule de la factorielle de 1000 var total = BigInteger.valueOf(1) (2..1000).forEach { total = total.multiply(BigInteger.valueOf(it.toLong())) } assertTrue(total.toString().length == 2568) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="date">date e ore</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.DateFormat import java.text.SimpleDateFormat import java.time.Instant import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertTrue class DatesHoursTest { @Test fun `Dates et heures`() { //l'heure courante en millisecondes val t0 = System.currentTimeMillis() //une autre représentation de la meme information val now = java.util.Date() //converti un objet java.util.Date en une valeur long. val t1 = now.getTime() assertTrue(t1 > Instant.EPOCH.toEpochMilli()) //kotlin property access syntaxe style val t1_prime = now.time //java.text.DateFormat //affiche la date d'aujourd'hui en utilisant le format //par défaut des parametres locaux val defaultDateFormat = DateFormat.getDateInstance() //personnalisation du formatage et de la locale val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE) val localeFormattedDate = df.format(Date()) //constantes pour les styles de pattern de formatage assertEquals(0, DateFormat.FULL) assertEquals(1, DateFormat.LONG) assertEquals(2, DateFormat.MEDIUM) assertEquals(3, DateFormat.SHORT) assertEquals(2, DateFormat.DEFAULT) //utilise pour l'heure un format abrégé avec //des parametres personnalisés val tf = DateFormat.getTimeInstance( DateFormat.SHORT, Locale.FRANCE ) //affiche l'heure en utilisant le format de tf val shortTime = tf.format(Date()) assertTrue(shortTime.contains(':')) //affiche la date et l'heure en utilisant //un format détaillé val longTimeStamp = DateFormat.getDateTimeInstance( DateFormat.FULL, DateFormat.FULL, ) assert(longTimeStamp.format(Date()).isNotEmpty()) //utilisez java.text.SimpleDateFormat //pour définir votre propre modele de formatage val customFormat = SimpleDateFormat("yyyy.MM.dd") assertEquals(10, customFormat.format(Date()).length) //DateFormat peut également parser les date contenu dans des chaines val kotlinAnnounceDate = customFormat.parse("2019.05.08") //la class Date et sa représentation en millisecondes //n'autorise qu'une forme trés simple d'arithmétique //on ajoute 3 600 000 millisecondes à l'heure courante val anHourFromNow = now.getTime() + (60 * 60 * 1000) assert(anHourFromNow > now.getTime()) //java.util.Calendar //pour manipuler les dates et heures de facon plus sophistiquée //instanciation selon les parametres locaux //et le fuseau horaire local val calendar = Calendar.getInstance() //initialisation du calendrier à la date de maintenant calendar.setTime(now) //détermine le jour de l'année auquel correspond la date courante val dayOfYear = calendar.get(Calendar.DAY_OF_YEAR) assert(dayOfYear < 366) //réinitialisation de la date courante calendar.set(2019, Calendar.MAY, 8) assertEquals(4, calendar.get(Calendar.DAY_OF_WEEK)) //à quel jour du mois correspond le deuxieme mercredi de mai 2019 //set(key,value) calendar.set(Calendar.YEAR, 2019) calendar.set(Calendar.MONTH, Calendar.MAY) calendar.set(Calendar.DAY_OF_WEEK, Calendar.WEDNESDAY) //defini à quel (n=2) semaine du mois est la date calendar.set(Calendar.DAY_OF_WEEK_IN_MONTH, 2) //extrait le jour du mois val dayOfMonth = calendar.get(Calendar.DAY_OF_MONTH) assertEquals(8, dayOfMonth) calendar.setTime(kotlinAnnounceDate) //ajoute 30j à la date calendar.add(Calendar.DATE, 30) val monthAfter = calendar.getTime() //date est elle avant ou apres? assertTrue(monthAfter.after(kotlinAnnounceDate)) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="java8date">date e ore java8</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 8 introduce il nuovo pacchetto <strong><em>java.time</em></strong>, che contiene le classi di base che<br> La maggior parte degli sviluppatori lavora con. Contiene anche quattro sottopacchetti:<br></p> </div> <div class="paragraph"> <p><strong><em>java.time.chrono</em></strong><br> Cronologie alternative che gli sviluppatori che utilizzano sistemi di calendario non<br> seguire la norma ISO interagirà con. Un esempio sarebbe un calendario giapponese<br> sistema durevole.<br> <strong><em>java.time.format</em></strong><br> Contiene il DateTimeFormatter utilizzato per convertire gli oggetti di data e ora<br> in una stringa e anche per analizzare le stringhe negli oggetti di dati e di tempo.<br> <strong><em>java.time.temporal</em></strong><br> Contiene le interfacce richieste dalle classi di data e ora di base e anche<br> astrazioni (ad esempio query e regolatori) per operazioni avanzate con le date.<br> <strong><em>java.time.zone</em></strong><br> Classi utilizzate per le regole di fuso orario sottostanti;<br> La maggior parte degli sviluppatori non avranno bisogno di questo pacchetto.<br></p> </div> <div class="imageblock"> <div class="content"> <img src="../../img/java8-date-time.png" alt="java8 date time"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.time.LocalDate import java.time.Month import java.time.Period import java.time.YearMonth import java.time.temporal.* import java.util.HashMap import java.util.stream.Collectors import kotlin.test.Test class DatesHoursJava8Test { class BirthdayDiary { private val birthdays: MutableMap<String, LocalDate> init { birthdays = HashMap() } fun addBirthday( name: String, day: Int, month: Int, year: Int ): LocalDate { val birthday: LocalDate = LocalDate.of(year, month, day) birthdays[name] = birthday return birthday } fun getBirthdayFor(name: String): LocalDate? { return birthdays[name] } fun getAgeInYear(name: String, year: Int): Int { val period: Period = Period.between( birthdays[name], birthdays[name]!!.withYear(year) ) return period.getYears() } fun getFriendsOfAgeIn(age: Int, year: Int): Set<String> { return birthdays.keys.stream() .filter { p: String -> getAgeInYear(p, year) == age } .collect(Collectors.toSet()) } fun getDaysUntilBirthday(name: String): Int { val period: Period = Period.between( LocalDate.now(), birthdays[name] ) return period.getDays() } fun getBirthdaysIn(month: Month): Set<String> { return birthdays.entries.stream() .filter { (_, value): Map.Entry<String, LocalDate> -> value.getMonth() === month } .map<String> { (key): Map.Entry<String, LocalDate> -> key } .collect(Collectors.toSet()) } val birthdaysInCurrentMonth: Set<String> get() = getBirthdaysIn(LocalDate.now().getMonth()) val totalAgeInYears: Int get() = birthdays.keys.stream() .mapToInt { p: String -> getAgeInYear( p, LocalDate.now().getYear() ) } .sum() } //Les ajusteurs modifient les objets de date et d'heure. Supposons, par exemple, que nous voulions //renvoie le premier jour d'un trimestre qui contient un horodatage particulier : class FirstDayOfQuarter : TemporalAdjuster { override fun adjustInto(temporal: Temporal): Temporal? { val currentQuarter: Int = YearMonth.from(temporal) .get(IsoFields.QUARTER_OF_YEAR) return when (currentQuarter) { 1 -> LocalDate.from(temporal) .with(TemporalAdjusters.firstDayOfYear()) 2 -> LocalDate.from(temporal) .withMonth(Month.APRIL.value) .with(TemporalAdjusters.firstDayOfMonth()) 3 -> LocalDate.from(temporal) .withMonth(Month.JULY.value) .with(TemporalAdjusters.firstDayOfMonth()) 4 -> LocalDate.from(temporal) .withMonth(Month.OCTOBER.value) .with(TemporalAdjusters.firstDayOfMonth()) else -> null } } } enum class Quarter { FIRST, SECOND, THIRD, FOURTH } //Dans quel trimestre de l'année cette date se situe-t-elle ? class QuarterOfYearQuery : TemporalQuery<Quarter> { override fun queryFrom(temporal: TemporalAccessor): Quarter { val now = LocalDate.from(temporal) return if (now.isBefore(now.with(Month.APRIL).withDayOfMonth(1))) Quarter.FIRST else if (now.isBefore( now.with(Month.JULY) .withDayOfMonth(1) ) ) Quarter.SECOND else if (now.isBefore( now.with(Month.NOVEMBER) .withDayOfMonth(1) ) ) Quarter.THIRD else Quarter.FOURTH } } @Test fun `Dates et heures après java 8`() { val today = LocalDate.now() val currentMonth = today.month val firstMonthOfQuarter = currentMonth.firstMonthOfQuarter() val q = QuarterOfYearQuery() // Direct var quarter: Quarter? = q.queryFrom(LocalDate.now()) println(quarter) // Indirect quarter = LocalDate.now().query(q) println(quarter) val now = LocalDate.now() val fdoq: Temporal = now.with(FirstDayOfQuarter()) println(fdoq) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrCol">array e collezioni</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/collections_classes_inheritance.png" alt="Classes de collections et héritage"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package playground.programming import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertTrue class ArrayCollectionTest { @Test fun `Tableaux, collections`() { //Tableau //java.util.Arrays définit d'utiles méthodes de manipulation de tableaux, //y compris de tri et de recherche au sein d'un tableau val intArray = arrayOf(10, 5, 7, -3) //tri le tableau Arrays.sort(intArray) var pos = Arrays.binarySearch(intArray, 7) //la valeur 7 est trouvé a l'index 2 assertEquals(2, pos) //12 pas trouvé retourne une valeur negative assert(Arrays.binarySearch(intArray, 12) < 0) //les tableaux peuvent également etre triés //et faire l'objet d'une recherche val stringArray = arrayOf("le", "moment", "c'est") assertEquals("c'est", stringArray[2]) assertEquals("le", stringArray[0]) assertEquals("moment", stringArray[1]) Arrays.sort(stringArray) assertEquals("c'est", stringArray[0]) assertEquals("le", stringArray[1]) assertEquals("moment", stringArray[2]) //Arrays.equals() compare tous les éléments de deux tableaux //Arrays.clone() copie tous les elements du tableau dans un autre stringArray.forEachIndexed { i, it -> assertEquals(it, stringArray.clone()[i]) } val data = ByteArray(100) //Arrays.fill() initialise tous les éléments des deux tableaux //initalise tous les éléments à -1 Arrays.fill(data, -1) data.forEach { assertEquals(-1, it) } //attribue aux éléments 5, 6, 7, 8 et 9 la valeur -2 Arrays.fill(data, 5, 10, -2) ((5 until (10 - 1))).forEach { assertEquals(-2, data[it]) } //récupère le type de data val type = data::class.java //est ce que data est un tableau? assertTrue(type.isArray()) //est ce que data est un tableau de byte assertEquals(Byte::class.java, type.getComponentType()) //Collection val s = java.util.HashSet<String>() s.add("test") assertTrue(s.contains("test")) assertFalse(s.contains("test2")) s.remove("test") assertFalse(s.contains("test")) val ss = TreeSet<String>() ss.add("b") ss.add("a") ss.iterator().forEach { assertTrue(it == "a" || it == "b") } //liste doublement chainée var dll: List<String> = LinkedList<String>() //plus efficace val l = java.util.ArrayList<String>() l.addAll(ss) l.addAll(1, ss) val obj = l.get(1) val obj_prime = l[1] assertEquals(obj, obj_prime) l.set(3, "nouvel élément") l.add("test") l.add(0, "test2") l.removeAt(1) l.remove("a") assertFalse(l.contains("a")) l.removeAll(ss) assertFalse(l.containsAll(ss)) assertFalse(l.isEmpty()) assertTrue(l.isNotEmpty()) val sublist = l.subList(1, 3) val elements = l.toArray() l.clear() val m = HashMap<String, Integer>() m.put("clé", Integer(42)) m["clé"] = Integer(42) val value: Integer = m.get("clé")!! assertEquals(Integer(42), value) m.remove("clé") assertTrue(m.isEmpty()) val keys = m.keys assertTrue(keys.isEmpty()) val set = HashSet<String>() set.add("key_1") set.add("key_2") set.add("key_3") val members = set.toArray() assertEquals(3, members.size) val list = ArrayList<String>() list.add("items1") list.add("items2") list.add("items3") val items = list.toArray() assertEquals(3, items.size) //trie et recherche d'éléments sur les collections list.add("clé") //en premier on trie Collections.sort(list) //en kotlin list.sort() //en deuxieme on cherche //retourne l'index du premier trouvé sinon -1 pos = Collections.binarySearch(list, "clé") assertEquals(0, pos) val list1 = mutableListOf(1, 2, 3, 4, 5) val list2 = mutableListOf<Int>(0, 0, 0, 0, 0) //d'autres méthodes intéressantes concernant Collections //copie list1 dans list2, 2e parametre dans 1er parametre Collections.copy(list2, list1) //comparaison de la copy avec filter assertTrue(list1.filterIndexed { i: Int, it: Int -> it != list2[i] }.isEmpty()) //comparaison de la copy avec map list1.mapIndexed { index: Int, it: Int -> assertEquals(it, list2[index]) } //rempli avec des 0 Collections.fill(list2, 0) assertTrue(list2.none { it != 0 }) //le maximum assertEquals(5, Collections.max(list1)) //le minimum assertEquals(1, Collections.min(list1)) //renverse Collections.reverse(list) listOf("items3", "items2", "items1", "clé").mapIndexed { i: Int, it: String -> assertEquals(it, list[i]) } //mélange la list Collections.shuffle(list) //retourne un ensemble immuable possédant un seul élément 0 Collections.singleton(0) //renvoi un emballage immuable autour d'une liste Collections.unmodifiableList(list) //renvoi un emballage synchronisé autour d'une map, ensemble clé valeur Collections.synchronizedMap(m) //java.util.Properties un est objet key value } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="sysProp">System.Properties</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html">documentazione ufficiale di System.Properties</a></p> </div> <div class="paragraph"> <p>ecco una tabella di alcune proprietà interessanti<br> Queste proprietà sono interessanti per avere informazioni<br> sul sistema host della JVM.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3343%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Chiave</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Significato</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">separatore di file</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carattere che separa i componenti di un percorso di file. Questo è "/" su UNIX e "\" su Windows.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Percorso utilizzato per trovare le directory e gli archivi JAR contenenti i file di classe. Gli elementi del class path sono separati da un carattere specifico della piattaforma specificato nella proprietà path.separator.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directory di installazione per Java Runtime Environment (JRE)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nome del fornitore JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor.url</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL del fornitore JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.versione</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">numero di versione JRE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">line.separator</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sequenza utilizzata dal sistema operativo per separare le righe nei file di testo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.arch</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Architettura del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.name</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nome del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">versione del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Versione del sistema operativo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">separatore.percorso</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carattere separatore di percorso utilizzato in java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.dir</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directory di lavoro dell’utente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">user.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Directory personale dell’utente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">nome utente</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nome dell’account utente</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="threads">Thread</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.DateFormat import java.util.* import kotlin.test.Test class ThreadsTest { @Test fun `threads test`() { //java.lang.Thread représente le thread fondamentale de l'API java //il existe deux manière de définir un thread //1) étendre la classe Thread ou une lambda en kotlin //2) implémenter l'interface Runnable, // puis passer une instance de cet objet Runnable au constructeur de Thread. val list1: List<Int> = List( size = 45, init = { (1..31).random() } ) println("list1$list1") //facon 1 val t = Thread { Collections.sort(list1) println("list1 sorted$list1") } t.start() val list2 = List( size = 45, init = { (1..31).random() } ) println("list2$list2") //facon 2 val sorter = BackgroundSorter(list2) sorter.start() //priorité des threads //tant qu'un thread de niveau de priorité supérieure n'est pas fini //alors celui de niveau inférieur ne peut s'exécuter //on définit un thread avec une priorité inférieur à la normale t.setPriority(Thread.NORM_PRIORITY - 1) //ici on définit un thread avec une priorité inférieur à la priorité //du thread courant t.setPriority(Thread.currentThread().getPriority() - 1) //Thread.yield() fait une pause pour laisser les autres threads de meme priorité s'exécuter } class BackgroundSorter(private val l: List<Int>) : Thread() { override fun run() { Collections.sort(l) println("list2 sorted$l") } } //pour l'arrêt du thread, plutôt qu'utiliser la fonction Thread.stop() // qui laisse la memoire dans un état non controlé. //utiliser la méthode tel que l'exemple pleaseStop() class DummyClock( private val df: DateFormat = DateFormat.getTimeInstance(DateFormat.MEDIUM), private var keepRunning: Boolean = true ) : Thread() { init { isDaemon = true start() } override fun run() { while (keepRunning) { println(df.format(Date())) try { sleep(1000) } catch (e: InterruptedException) { println(e.message) } } } fun pleaseStop() { keepRunning = false } } //java.util.Timer //java.util.TimerTask //ces classes permettent l'exécution de taches répétitives @Test fun `Timer et TimerTask test`() { DummyClock() } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">indice</a></p> </div> </div> </div> <div class="sect1"> <h2 id="regex">Espressioni regolari</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.util.* import java.util.regex.Matcher import java.util.regex.Pattern import java.util.stream.Collectors import kotlin.test.Test import kotlin.test.assertEquals class RegularExpressionsTest { @Test fun `expressions régulières`() { val p: Pattern = Pattern.compile("honou?r") val caesarUK = "For Brutus is an honourable man" val mUK: Matcher = p.matcher(caesarUK) assertEquals(true, mUK.find(), "Should matches UK spelling") val caesarUS = "For Brutus is an honorable man" val mUS: Matcher = p.matcher(caesarUS) assertEquals(true, mUS.find(), "Should matches US spelling") } @Test fun `expressions régulières plus complexes`() { //Notez que nous devons utiliser \\ car nous avons besoin d'un littéral \ //et Java utilise un seul \ comme caractère d'échappement var pStr = "\\d" // Un chiffre numérique var text = "Apollo 13" var p = Pattern.compile(pStr) var m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) pStr = "[a..zA..Z]" //N'importe quelle lettre p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) //N'importe quel nombre de lettres, qui doivent toutes être comprises entre 'a' et 'j' //mais peut-être en majuscule ou en minuscule. pStr = "([a..jA..J]*)" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) text = "abacab" //'a' suivi de quatre caractères quelconques, suivi de 'b' pStr = "a....b" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) } @Test fun `Quelles chaînes correspondent à la regex ?`() { val pStr = "\\d" // Un chiffre numérique val p = Pattern.compile(pStr) val ls: List<String> = Arrays.asList("Cat", "Dog", "Ice-9", "99 Luftballoons") val containDigits: List<String> = ls.stream() .filter(p.asPredicate()) .collect(Collectors.toList()) assert(containDigits.contains("Ice-9")) assert(containDigits.contains("99 Luftballoons")) assertEquals(2, containDigits.size) } }</code></pre> </div> </div> <div class="sect2"> <h3 id="_tabella_dei_metacaratteri_regex">Tabella dei metacaratteri regex</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7592%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Metacarattere</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">funzionalità</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Note</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carattere facoltativo—zero o un’istanza</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zero o più del carattere precedente</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Uno o più dei caratteri precedenti</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">{M,N}</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tra M e N istanze del carattere precedente</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\d</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un numero</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\D</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carattere non numerico</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\w</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carattere di parola</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cifre, lettere e _</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\W</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carattere senza parola</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un carattere di spazio</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\S</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">un carattere non vuoto</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carattere di nuova riga</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\t</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Carattere di tabulazione</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Qualsiasi carattere</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non include la nuova riga in Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ogni carattere contenuto tra parentesi quadre</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chiamato una classe di caratteri</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[^ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ogni carattere non contenuto tra parentesi quadre</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chiamato una classe di caratteri inversa</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Costruire un gruppo di elementi di motivo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chiamato un gruppo (o gruppo di cattura)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Definire possibilità alternative</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implementa l’OR logico</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Inizio della stringa $ Fine della stringa</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>completarehttps://www.codeurjava.com/2015/05/les-expressions-regulieres-avec-regex.html[con]</p> </div> </div> </div> </div> https://cheroliv.com/blog/2022/0047_memo_gradle_post.html Mon, 23 May 2022 00:00:00 +0000 blog/2022/0047_memo_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_mostra_laiuto">Mostra l’aiuto</a></li> <li><a href="#_impostare_la_proprietà_di_sistema_della_jvm_d_system_prop">Impostare la proprietà di sistema della JVM : `-D, --system-prop</a></li> <li><a href="#_definire_la_proprietà_del_progetto_per_lo_script_di_build_pmypropmyvalue">Definire la proprietà del progetto per lo script di build : `-Pmyprop=myvalue</a></li> <li><a href="#_specifica_la_directory_di_avvio_di_gradle_il_valore_predefinito_è_la_directory_corrente">Specifica la directory di avvio di Gradle. Il valore predefinito è la directory corrente.</a></li> <li><a href="#_sovrascrivere_la_proprietà_param_component_tramite_la_riga_di_comando">Sovrascrivere la proprietà 'param_component' tramite la riga di comando :</a></li> <li><a href="#_aggiungere_una_cartella_a_un_source_set_in_un_progetto_normale_con_il_kotlin_dsl">Aggiungere una cartella a un source-set in un progetto normale con il Kotlin DSL</a></li> <li><a href="#_aggiungere_una_cartella_a_un_source_set_in_un_progetto_android_con_il_groovy_dsl">Aggiungere una cartella a un source-set in un progetto android con il groovy dsl</a></li> <li><a href="#_evitare_di_costruire_e_testare_un_sottamodulo">Evitare di costruire e testare un sottamodulo</a></li> <li><a href="#_prendere_un_dossier">prendere un dossier</a></li> <li><a href="#_mostra_le_dipendenze_di_un_build">Mostra le dipendenze di un build</a></li> <li><a href="#_esempio_di_utilizzo_di_reduce_concatenazione_di_una_lista_in_una_stringa">Esempio di utilizzo di reduce : concatenazione di una lista in una stringa</a></li> <li><a href="#_recuperare_la_descrizione_di_unattività_particolare">Recuperare la descrizione di un’attività particolare</a></li> <li><a href="#_per_avviare_unattività_dalla_workingdir_root_quindi_prefixare_lattività_con_un">Per avviare un’attività dalla workingDir root, quindi prefixare l’attività con un `:</a></li> <li><a href="#_per_riavviare_le_attività_che_non_sono_riuscite_utilizzare_lopzione_rerun_tasks">Per riavviare le attività che non sono riuscite, utilizzare l’opzione `--rerun-tasks</a></li> <li><a href="#_avviare_unattività_in_un_progetto_specifico_da_unaltra_directory">Avviare un’attività in un progetto specifico da un’altra directory</a></li> </ul> </div> <div class="sect1"> <h2 id="_mostra_laiuto">Mostra l’aiuto</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew --help</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_impostare_la_proprietà_di_sistema_della_jvm_d_system_prop">Impostare la proprietà di sistema della JVM : `-D, --system-prop</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Dmyprop=myvalue #ou ./gradlew --system-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_definire_la_proprietà_del_progetto_per_lo_script_di_build_pmypropmyvalue">Definire la proprietà del progetto per lo script di build : `-Pmyprop=myvalue</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Pmyprop=myvalue #ou ./gradlew --project-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_specifica_la_directory_di_avvio_di_gradle_il_valore_predefinito_è_la_directory_corrente">Specifica la directory di avvio di Gradle. Il valore predefinito è la directory corrente.</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -p ~/src/next_startup #ou ./gradlew --project-dir ~/src/next_startup</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_sovrascrivere_la_proprietà_param_component_tramite_la_riga_di_comando">Sovrascrivere la proprietà 'param_component' tramite la riga di comando :</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Pparam_component=CUSTOM_VALUE</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_aggiungere_una_cartella_a_un_source_set_in_un_progetto_normale_con_il_kotlin_dsl">Aggiungere una cartella a un source-set in un progetto normale con il Kotlin DSL</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sourceSets { getByName("test"){ java.srcDir("src/scripts/groovy") } getByName("test"){ java.srcDir("src/scripts/kscript") } getByName("test"){ java.srcDir("src/test/javascript") } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_aggiungere_una_cartella_a_un_source_set_in_un_progetto_android_con_il_groovy_dsl">Aggiungere una cartella a un source-set in un progetto android con il groovy dsl</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">android { sourceSets { main.java.srcDirs += "src/main/../../../../ceelo/domain/src/main/java/" test.java.srcDirs += "src/test/../../../../ceelo/domain/src/test/java/" } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_evitare_di_costruire_e_testare_un_sottamodulo">Evitare di costruire e testare un sottamodulo</h2> <div class="sectionbody"> <div class="paragraph"> <p>gradle build -x :excluded-module:check -x :excluded-module:assemble -x :excluded-module:build</p> </div> <div class="listingblock"> <div class="title">Spostare i file</div> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("moveWebappNode") { doLast { ant.withGroovyBuilder { "move"( "webapp/node_modules" to "$rootDir/webapp-src/node_modules", ) } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_prendere_un_dossier">prendere un dossier</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register<Tar>("tarWebapp") { dependsOn("moveWebappNpm") group = WEBAPP description = "tar webapp" doLast { setOf( "build", "target", "node_modules" ).forEach { dir -> exclude { it.name .dir } } archiveFileName.set("webapp.tar") destinationDirectory.set(File("${rootDir.absolutePath}$sep$WEBAPP_SRC")) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_mostra_le_dipendenze_di_un_build">Mostra le dipendenze di un build</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("printDependencies") { description = "print project dependencies" group = WEBAPP doLast { println("${project.name} dependencies") mutableMapOf<String, Map<String, String>>( "buildDependencies" to buildDependencies, "domainDeps" to domainDeps, "domainTestDeps" to domainTestDeps, ).apply { putAll(appModules) } .forEach { module -> if (module.value.isNotEmpty()) { println("${module.key}:") module.value.forEach { println(dependency(it)) } println() } } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_esempio_di_utilizzo_di_reduce_concatenazione_di_una_lista_in_una_stringa">Esempio di utilizzo di reduce : concatenazione di una lista in una stringa</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("printWebappSrc") { description = "print webapp sources" group = WEBAPP doLast { webAppSrc .reduce { acc, s -> "$acc\n\t$s" } .run { println("$WEBAPP_SRC: $this\n") } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_recuperare_la_descrizione_di_unattività_particolare">Recuperare la descrizione di un’attività particolare</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -q help --task foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_per_avviare_unattività_dalla_workingdir_root_quindi_prefixare_lattività_con_un">Per avviare un’attività dalla workingDir root, quindi prefixare l’attività con un `:</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew :foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_per_riavviare_le_attività_che_non_sono_riuscite_utilizzare_lopzione_rerun_tasks">Per riavviare le attività che non sono riuscite, utilizzare l’opzione `--rerun-tasks</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew check --rerun-tasks</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_avviare_unattività_in_un_progetto_specifico_da_unaltra_directory">Avviare un’attività in un progetto specifico da un’altra directory</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’opzione`-p` (ou <code>--project-dir</code>) permette di specificare il percorso di un progetto Gradle ed eseguirvi un’attività, anche se la directory corrente è diversa.</p> </div> <div class="paragraph"> <p>Ad esempio, per avviare il compito`build`del progetto situato in`~/projets/mon-autre-projet`pur essendo in un’altra directory:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -p ~/projets/mon-autre-projet build</code></pre> </div> </div> <div class="paragraph"> <p>Questo è particolarmente utile per eseguire script di azioni su più progetti da una posizione centrale.</p> </div> <div class="ulist"> <div class="title">vedere anche :</div> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_warnings">ref</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_options">ref</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/36178581/837404">discussione</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2022/0038_training_kotlin_enum_sealed_class_post.html Tue, 17 May 2022 00:00:00 +0000 blog/2022/0038_training_kotlin_enum_sealed_class_post.html <div class="paragraph"> <p>le sealed classi, non sono delle enumerazioni(parola chiave:enum).<br> Venendo da Java, potresti essere tentato di sovraccaricare la tua enumerazione delle funzionalità: // Java code</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-java" data-lang="java">enum PizzaOrderStatus { ORDER_RECEIVED, PIZZA_BEING_MADE, OUT_FOR_DELIVERY, COMPLETED; public PizzaOrderStatus nextStatus() { switch (this) { case ORDER_RECEIVED: return PIZZA_BEING_MADE; case PIZZA_BEING_MADE: return OUT_FOR_DELIVERY; case OUT_FOR_DELIVERY: return COMPLETED; case COMPLETED:return COMPLETED; } } }</code></pre> </div> </div> <div class="paragraph"> <p>Invece di quello, puoi utilizzare la classe sealed:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sealed class PizzaOrderStatus(protected val orderId: Int) { abstract fun nextStatus() : PizzaOrderStatus class OrderReceived(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return PizzaBeingMade(orderId) } } class PizzaBeingMade(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return OutForDelivery(orderId) } } class OutForDelivery(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return Completed(orderId) } } class Completed(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return this } } }</code></pre> </div> </div> <div class="paragraph"> <p>Il vantaggio di questo approccio è che ora possiamo trasmettere i dati con il stato:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">var status: PizzaOrderStatus = OrderReceived(123) while (status !is Completed) { status = when (status) { is OrderReceived -> status.nextStatus() is PizzaBeingMade -> status.nextStatus() is OutForDelivery -> status.nextStatus() is Completed -> status } }</code></pre> </div> </div> <div class="paragraph"> <p>In generale, le classi sealed sono buone se vuoi avere dei dati associati a un Stato.</p> </div> https://cheroliv.com/blog/2022/0036_training_kotlin_post.html Thu, 12 May 2022 00:00:00 +0000 blog/2022/0036_training_kotlin_post.html <div class="sect1"> <h2 id="_mappa_mentale">Mappa mentale</h2> <div class="sectionbody"> <div class="paragraph"> <p><span class="image"><img src="../../diagram/training_kotlin.png" alt="training_kotlin"></span></p> </div> </div> </div> <div class="sect1"> <h2 id="_programmazione_funzionale">Programmazione funzionale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gli esercizi sono tratti dal libro:<br> Programmazione funzionale in Kotlin tramite tutorial<br> Scritto da Massimo Carli<br> repo: <a href="https://github.com/kodecocodes/fpk-materials" class="bare">https://github.com/kodecocodes/fpk-materials</a></p> </div> <div class="sect2"> <h3 id="_sintassi">Sintassi</h3> <div class="sect3"> <h4 id="_firstprogramtest">FirstProgramTest</h4> <div class="paragraph"> <p>nozioni: visualizzazione schermo, funzione<br> PrimoProgrammaTest:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/FirstProgramTest.kt[(empty)]+</p> </div> </div> <div class="sect3"> <h4 id="_concatfunctiontest">ConcatFunctionTest</h4> <div class="paragraph"> <p>nozioni: memoria, variabile, valore, oggetto, estensione della funzione<br> (Note: Since no French text was provided after "ExampleUnitTest:", and the instructions require translating from French to Italian with no additional context, the translation of an empty string is an empty string.)<a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/ConcatFunctionTest.kt">(No source text provided, so nothing to translate.)</a>+</p> </div> </div> <div class="sect3"> <h4 id="_birthdaymessagetestoutput">BirthdayMessageTestOutput</h4> <div class="paragraph"> <p>nozioni: insiemi, cicli<br> <a href="https://developer.android.com/codelabs/basic-android-kotlin-training-first-kotlin-program?continue=https%3A%2F%2Fdeveloper.android.com%2Fcourses%2Fpathways%2Fandroid-basics-kotlin-one%23codelab-https%3A%2F%2Fdeveloper.android.com%2Fcodelabs%2Fbasic-android-kotlin-training-first-kotlin-program">Introduzione a kotlin</a><br> BirthdayMessageTestOutput:https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/BirthdayMessageTestOutput.kt[fonte]+</p> </div> </div> </div> <div class="sect2"> <h3 id="_corso_di_kotlin">Corso di Kotlin</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/YRjY3jRrQYY?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_tutotiel_sulle_collezioni_in_java">Tutotiel sulle collezioni in java</h3> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/collections/index.html" target="_blank" rel="noopener">Collezioni</a></p> </div> <div class="paragraph"> <p>Il cuore delle interfacce di raccolta<br> <span class="image"><img src="../../img/0036_training_kotlin_post/colls-coreInterfaces.gif" alt="Collections"></span><br></p> </div> </div> <div class="sect2"> <h3 id="_basi_funzionali">Basi funzionali</h3> <div class="sect3"> <h4 id="_approccio_dichiarativo_x_imperativo">Approccio dichiarativo X imperativo</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals class DeclarativeTests { val input = listOf( "123", "abc", "1ds", "987", "abdf", "1d3", "de1", "88", "101" ) fun imperativeSum(list: List<String>): Int { var sum = 0 for (item in list) { try { sum += item.toInt() } catch (_: NumberFormatException) { } } return sum } @Test fun `test imperative approach`() { imperativeSum(input).run { println("Sum $this") assertEquals(1299, this) } } fun isValidNumber(s: String) = try { s.toInt() true } catch (_: NumberFormatException) { false } fun declarativeSum(list: List<String>) = list .filter(::isValidNumber) .map(String::toInt) .sum() @Test fun `test declarative approach`() { assertEquals(1299, declarativeSum(input).apply { println("Sum $this") }) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_esercizio_1_1">Esercizio 1.1</h4> <div class="paragraph"> <p>Implementare la funzione sumInRange, che somma i valori in<br> una List<String> in un intervallo dato. La firma è :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun sumInRange(input: List<String>, range: IntRange): Int</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_1`() { assertEquals(4, sumInRange( listOf("1", "10", "a", "7", "ad2", "3"), 1..5 ).apply { println("sumInRange 1..5: $this") } ) }</code></pre> </div> </div> <div class="paragraph"> <p>Provalo e controlla la tua risposta con lahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/DeclarativeTests.kt[solution, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_funzioni_di_ordine_superiore">funzioni di ordine superiore</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.* import java.lang.Thread.sleep import kotlin.math.sign import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOFTests { val ONE_SECOND = 1000L @Test fun `high order function`() { //capture de la sortie standard val standardOut: PrintStream? = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) //libération de la sortie standard setOut(standardOut) } fun Int.times1(fn: () -> Unit) { for (i in 1..this) { fn() } } fun Int.times2(fn: () -> Unit) { for (i in 1..this) fn() } fun Int.times3(fn: () -> Unit) = (1..this).forEach { fn() } fun Int.times4(fn: () -> Unit) = repeat((1..this).count()) { fn() } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_esercizio_1_2">Esercizio 1.2</h4> <div class="paragraph"> <p>Implementare chrono, che accetta una funzione di tipo`() →`<br> Unità in input e restituisce il tempo di esecuzione. La firma è:<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>Provalo e verifica la tua risposta con lahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solution, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_composizione">composizione</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals fun double(x: Int): Int = 2 * x fun square(x: Int): Int = x * x fun squareAndDouble1(x: Int) = double(square(x)) infix fun <A, B, C> ((A) -> B).compose(g: (B) -> C) : (A) -> C = { a -> g(this(a)) } class CompositionTests { @Test fun composition_impure() { assertEquals(200, double(square(10))) assertEquals(200, squareAndDouble1(10)) } @Test fun composition_pure() { val squareAndDouble = ::square compose ::double assertEquals(200, squareAndDouble(10)) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_funzioni_pure_e_testabilità">Funzioni pure e testabilità</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.Test import kotlin.test.assertEquals var count = 0 //impure car une variable global subit un effet de bord fun impure(value: Int): Int { count++ return value + count } //impure car utilisation de la sortie standard qui fait muter le system fun addOneAndLog(x: Int): Int { val result = x + 1 println("New Value is $result") return result } //pure fun addOne(x: Int) = (x + 1).run { Pair(this, "New Value is $this") } class PureTests { @Test fun `impure fonction`() { assertEquals(3, impure(2)) val standardOut = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) addOneAndLog(3) assertEquals( "New Value is 4", outputStreamCaptor .toString() .trim() ) setOut(standardOut) } @Test fun `pure fonction`() { addOne(3).run { assertEquals(4, first) assertEquals("New Value is 4", second) } } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_gestione_delle_eccezioni">Gestione delle eccezioni</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import org.junit.jupiter.api.assertThrows import kotlin.Result.Companion.failure import kotlin.Result.Companion.success import kotlin.test.Test import kotlin.test.assertEquals //NumberFormatException est un effet de bord qui rend la fonction impure fun strToInt(str: String) = str.toInt() //pure fun strToIntOrNull(str: String) = try { str.toInt() } catch (nfe: NumberFormatException) { null } //pure avec gestion de l'exception plus élégante fun strToIntResult(str: String): Result<Int> = try { success(str.toInt()) } catch (nfe: NumberFormatException) { failure(nfe) } class ExceptionHandlingTests { @Test fun impure() { assertThrows<NumberFormatException> { strToInt("foo") } assertEquals(1, strToInt("1")) } @Test fun pure() { assertEquals(null, strToIntOrNull("foo")) assertEquals(1, strToIntOrNull("1")) } @Test fun `pure avec result`() { assertEquals(1, strToIntResult("1").getOrNull()) assertEquals( "For input string: \"foo\"", strToIntResult("foo") .exceptionOrNull() ?.message ) } }</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_punti_chiave">Punti chiave</h3> <div class="ulist"> <ul> <li> <p>Mentre la programmazione orientata agli oggetti significa programmare con gli oggetti,</p> </li> </ul> </div> <div class="paragraph"> <p>la programmazione funzionale significa programmare con le funzioni. Suddividi un problema in più sotto-problemi, che modelli con le funzioni.</p> </div> <div class="ulist"> <ul> <li> <p>Le funzioni d’ordine superiore accettano altre funzioni in ingresso o restituiscono altre</p> </li> </ul> </div> <div class="paragraph"> <p>funzionano come valori di ritorno. La teoria delle categorie è la teoria della composizione, e la utilizzi per comprendere come comporre le tue funzioni in un programma di lavoro Il valore di output di una funzione pura dipende solo dai suoi parametri di input, e essa non ha effetti collaterali.</p> </div> <div class="ulist"> <ul> <li> <p>Un effetto collaterale è qualcosa che una funzione fa al mondo esterno. Questo</p> </li> </ul> </div> <div class="paragraph"> <p>può essere un registro nell’output standard o la modifica del valore di una variabile globale. La programmazione funzionale funziona per le funzioni pure, ma fornisce anche le strumenti per trasformare funzioni impure in funzioni pure Puoi rendere una funzione impura pura spostando gli effetti per renderli parte del valore di ritorno.</p> </div> <div class="ulist"> <ul> <li> <p>La programmazione funzionale è una questione di composizione.</p> </li> </ul> </div> <div class="paragraph"> <p>La gestione degli errori è un caso tipico di effetti collaterali, e Kotlin ti fornisce gli strumenti per gestirli in modo funzionale</p> </div> </div> <div class="sect2"> <h3 id="_approfondire_java_8_espressioni_lambda_e_interfacce_funzionali">Approfondire Java 8: espressioni lambda e interfacce funzionali</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/20waNRw6wMA?rel=0&list=PLzzeuFUy_Cng0wZhqbnkvWAW0d2fdVfyQ" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_teoria_delle_categorie">Teoria delle categorie</h3> <div class="paragraph"> <p>La teoria matematica delle categorie</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/LVHoROSF3KA?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_fondamenti_delle_funzioni">Fondamenti delle funzioni</h3> <div class="sect3"> <h4 id="_esercizio_2_1">Esercizio 2.1</h4> <div class="paragraph"> <p>Può scrivere un esempio di funzione che mappa valori distinti<br> il cui dominio presenta valori non distinti nell’intervallo, come f(b) e f(c) nella figura sottostante?<br></p> </div> <div class="paragraph"> <p>Provalo, poi verifica il progetto della sfida per vedere come l’hai fatto.<br> Troverete consigli e una spiegazione seguendo il link verso la <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt">soluzione</a>.<br></p> </div> </div> <div class="sect3"> <h4 id="_esercizio_2_2">Esercizio 2.2</h4> <div class="paragraph"> <p>Puoi scrivere la funzione inversa di due volte ?<br> Quali sono il dominio e il codominio della funzione inversa?<br> Dai un’occhiata al progetto della sfida e all’appendice B per la soluzione.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>Provalo e verifica la tua risposta con lahttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[soluzione, windows="_blank].</p> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2022/0031_memo_design_system_post.html Sun, 9 Jan 2022 00:00:00 +0000 blog/2022/0031_memo_design_system_post.html <div class="sect1"> <h2 id="_strumenti">Strumenti</h2> <div class="sectionbody"> <div class="dlist"> <div class="title"><strong>Illustrazioni</strong></div> <dl> <dt class="hdlist1"><a href="https://undraw.co/">undraw.co</a></dt> <dd> <p>Illustrazioni open source per tutte le idee che puoi immaginare e creare.</p> </dd> <dt class="hdlist1"><a href="https://absurd.design/">absurd.design</a></dt> <dd> <p>Illustrazioni assurde che hanno senso.</p> </dd> <dt class="hdlist1"><a href="https://drawkit.com/">drawkit.com</a></dt> <dd> <p>Magnifiche illustrazioni gratuite. Aggiornamenti settimanali.</p> </dd> <dt class="hdlist1"><a href="https://icons8.com/">icons8.com</a></dt> <dd> <p>Icone, illustrazioni, foto, musica e strumenti di design</p> </dd> <dt class="hdlist1"><a href="https://blush.design/">blush.design</a></dt> <dd> <p>Icone, illustrazioni, foto, musica e strumenti di progettazione.</p> </dd> <dt class="hdlist1"><a href="https://www.humaaans.com/">humaaans.com</a></dt> <dd> <p>Mescola e abbina le illustrazioni di persone con una libreria di design.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Colori</strong></div> <dl> <dt class="hdlist1"><a href="https://coolors.co/">coolors.co</a></dt> <dd> <p>Il generatore ultra-rapido di schemi di colori!</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>tendenze</strong></div> <dl> <dt class="hdlist1"><a href="https://fr.pinterest.com">pinterest</a></dt> <dd> <p>Scoperta visiva di idee: immagini, video, raccolte tematiche.</p> </dd> <dt class="hdlist1"><a href="https://dribbble.com">dribbling</a></dt> <dd> <p>Piattaforma per designer che condividono le loro creazioni e interagiscono.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>UX/UI e Design Systems</strong></div> <dl> <dt class="hdlist1"><a href="https://material.io/">Material Design di Google</a></dt> <dd> <p>Sistema di design di Google per interfacce utente unificate e adattabili.</p> </dd> <dt class="hdlist1"><a href="https://developer.apple.com/design/human-interface-guidelines/">Linee guida dell’interfaccia umana di Apple</a></dt> <dd> <p>Consigli di Apple per progettare applicazioni iOS e macOS intuitive.</p> </dd> <dt class="hdlist1"><a href="https://www.uxpin.com/">UXPin</a></dt> <dd> <p>Piattaforma di design e di collaborazione per creare prototipi e sistemi di design.</p> </dd> <dt class="hdlist1"><a href="https://www.frontify.com/">Frontify</a></dt> <dd> <p>Piattaforma di gestione del marchio e dei design systems per garantire la coerenza.</p> </dd> <dt class="hdlist1"><a href="https://designsystemsrepo.com/design-systems/">Repo di sistemi di design</a></dt> <dd> <p>Collezione di risorse ed esempi di design systems per ispirazione.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Sviluppo Frontend</strong></div> <dl> <dt class="hdlist1"><a href="https://htmlcheatsheet.com">htmlcheatsheet.com</a></dt> <dd> <p>Foglio di riferimento HTML</p> </dd> <dt class="hdlist1"><a href="https://fontawesome.com">fontawesome.com</a></dt> <dd> <p>libreria di icone</p> </dd> <dt class="hdlist1"><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a></dt> <dd> <p>Icone native in HTML</p> </dd> <dt class="hdlist1"><a href="https://css-tricks.com/">CSS-Tricks</a></dt> <dd> <p>Essenziale per CSS, con articoli, tutorial e suggerimenti frontend moderni.</p> </dd> <dt class="hdlist1"><a href="https://www.frontendmentor.io/">Frontend Mentor</a></dt> <dd> <p>Sfide di codice frontend basate su progetti reali per migliorare le tue competenze.</p> </dd> <dt class="hdlist1"><a href="https://dev.to/">Dev.to</a></dt> <dd> <p>Comunità di sviluppatori per condividere articoli, tutorial e progetti.</p> </dd> <dt class="hdlist1"><a href="https://codepen.io/">CodePen</a></dt> <dd> <p>Editor di codice online e community per condividere snippet di codice e demo.</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>Sviluppo Frontend assistito dall’IA</strong></div> <dl> <dt class="hdlist1"><a href="https://v0.dev/">v0.dev</a></dt> <dd> <p>v0 converte le descrizioni in linguaggio naturale in codice e interfaccia utente.</p> </dd> <dt class="hdlist1"><a href="https://uizard.io/">Uizard</a></dt> <dd> <p>Uizard si concentra sulla trasformazione di mockup (immagini, schizzi) in codice HTML, CSS e React.</p> </dd> <dt class="hdlist1"><a href="https://www.usegalileo.ai/explore">usegalileo.ai</a></dt> <dd> <p>Galileo AI ti permette di descrivere l’interfaccia che desideri in linguaggio naturale, e l’IA genera progetti Figma modificabili.</p> </dd> <dt class="hdlist1"><a href="https://play.teleporthq.io/">TeleportHQ</a></dt> <dd> <p>TeleportHQ è una piattaforma di sviluppo front-end low-code che utilizza l’IA per aiutarti a creare e distribuire siti web visivamente.</p> </dd> </dl> </div> </div> </div> https://cheroliv.com/blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html Tue, 3 Nov 2020 00:00:00 +0000 blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://microk8s.io/docs/">documentazione ufficiale di microk8s</a>+</p> </div> </div> </div> <div class="sect3"> <h4 id="_installazione_del_pacchetto_microk8s">Installazione del pacchetto microk8s:</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html Mon, 28 Sep 2020 00:00:00 +0000 blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html <div class="sect3"> <h4 id="_gradle_kotlin_dsl">Gradle-Kotlin-DSL:</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html Sun, 27 Sep 2020 00:00:00 +0000 blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html <div class="paragraph"> <p>NotImplementedException NotImplementedError, utilità per i test, permette di sapere dove siamo, e la causa del fallimento.<br> Non ancora implementato, permette di sollevare l’eccezione corretta.<br> Il y a :<br> <a href="http://commons.apache.org/proper/commons-lang/javadocs/api-release/org/apache/commons/lang3/NotImplementedException.html">org.apache.commons.lang3.NotImplementedException</a><br> <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-not-implemented-error/">kotlin.NotImplementedError</a>+</p> </div> https://cheroliv.com/blog/2020/0026_untar_post.html Sat, 26 Sep 2020 00:00:00 +0000 blog/2020/0026_untar_post.html <div class="sect3"> <h4 id="_link_interserver_net">Link: <a href="https://www.interserver.net/tips/kb/extract-tar-gz-files-using-linux-command-line/">interserver.net</a></h4> </div> https://cheroliv.com/blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html Fri, 25 Sep 2020 00:00:00 +0000 blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html https://cheroliv.com/blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html Thu, 24 Sep 2020 00:00:00 +0000 blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html <div class="sect3"> <h4 id="_hackernoon_com"><a href="https://hackernoon.com/dont-install-postgres-docker-pull-postgres-bee20e200198">hackernoon.com</a></h4> </div> https://cheroliv.com/blog/2020/0023_gherkin_en_francais_post.html Wed, 23 Sep 2020 00:00:00 +0000 blog/2020/0023_gherkin_en_francais_post.html https://cheroliv.com/blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html Tue, 22 Sep 2020 00:00:00 +0000 blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ ./gradlew -Pparam_component=CUSTOM ---- ----</code></pre> </div> </div> https://cheroliv.com/blog/2020/0021_memo_git_post.html Mon, 21 Sep 2020 00:00:00 +0000 blog/2020/0021_memo_git_post.html <div class="sect3"> <h4 id="_fonti">Fonti:</h4> <div class="paragraph"> <p>*https://xenovation.com/blog/source-control-management/git/how-to-change-remote-git-repository[xenovation] *https://intellipaat.com/community/3102/git-show-remote-url-how-can-i-determine-the-url-that-a-local-git-repository-was-originally-cloned-from[intellipaat]</p> </div> </div> <div class="sect3"> <h4 id="_cambiare_il_repo_remoto_in_git">cambiare il repo remoto in git</h4> <div class="paragraph"> <p>Mostra l’URL del repository remoto corrente:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0021_aspirer_depuis_une_URL_post.html Sun, 20 Sep 2020 00:00:00 +0000 blog/2020/0021_aspirer_depuis_une_URL_post.html <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ wget -r -k -np http://site.com/docs/manual/ ---- Per definire una cartella di destinazione aggiungere l'argomento -P poi dare il percorso. ----</code></pre> </div> </div> https://cheroliv.com/blog/2020/0020_creer_un_disk_bootable_post.html Sat, 19 Sep 2020 00:00:00 +0000 blog/2020/0020_creer_un_disk_bootable_post.html <div class="sect3"> <h4 id="_collegamenti_etcher">Collegamenti: <a href="https://www.balena.io/etcher/">etcher</a></h4> </div> https://cheroliv.com/blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html Fri, 18 Sep 2020 00:00:00 +0000 blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html <div class="sect3"> <h4 id="_collegamenti_askubuntu">Collegamenti: <a href="https://askubuntu.com/questions/86849/how-to-unzip-a-zip-file-from-the-terminal">askubuntu</a></h4> <div class="paragraph"> <p>Se vuoi estrarre verso una cartella di destinazione specifica, puoi utilizzare : <code>` $ unzip file.zip -d destination_folder </code>` Se le cartelle di origine e di destinazione sono identiche, puoi semplicemente fare: <code>` $ estrai file.zip </code>`</p> </div> </div> https://cheroliv.com/blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html Thu, 17 Sep 2020 00:00:00 +0000 blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html <div class="sect3"> <h4 id="_link_stackexchange">Link: <a href="https://unix.stackexchange.com/questions/72661/show-sum-of-file-sizes-in-directory-listing">stackexchange</a></h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ du -ach --exclude "./.*" /home/troll/ ---- ----</code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0017_detruire_une_branch_sur_github_post.html Wed, 16 Sep 2020 00:00:00 +0000 blog/2020/0017_detruire_une_branch_sur_github_post.html <div class="sect3"> <h4 id="_distruggere_una_branch_su_github">Distruggere una branch su github</h4> </div> <div class="sect3"> <h4 id="_link_gist">Link: <a href="https://gist.github.com/cheroliv/921a13ed23ae6d4d66af8d43dd536987">gist</a></h4> </div> https://cheroliv.com/blog/2020/0016_asciidoc_markdown_memo_post.html Tue, 15 Sep 2020 00:00:00 +0000 blog/2020/0016_asciidoc_markdown_memo_post.html <div class="paragraph"> <p>Perché asciidoc o markdown ? Qui mi oriento verso asciidoc, poiché ho già alcuni ticket scritti in asciidoc.<br> Asciidoc è un linguaggio di markup, che permette di produrre contenuto, apportando un formato che mantiene il testo leggibile per un essere umano.<br> È un modo per standardizzare i trattamenti di testo per contenuti semplici senza software aggiuntivo.</p> </div> <div class="ulist"> <div class="title">Collegamenti :</div> <ul> <li> <p><a href="https://blog.oxiane.com/2018/06/13/asciidoc-documentation-as-code/" target=""_blank">@jmdoudoux su blog.oxiane.com</a>[asciidoc]</p> </li> <li> <p><a href="https://powerman.name/doc/asciidoc" target=""_blank">powerman.name</a>[asciidoc]</p> </li> </ul> </div> https://cheroliv.com/blog/2019/0013_how-to-install-a-deb-file_post.html Mon, 19 Aug 2019 00:00:00 +0000 blog/2019/0013_how-to-install-a-deb-file_post.html <div class="paragraph"> <p>Per installare un pacchetto debian da un file .deb dalla linea di comando.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo dpkg -i /chemin/du/fichier/deb/</code></pre> </div> </div> <div class="paragraph"> <p>vedere qui per lahttps://unix.stackexchange.com/questions/159094/how-to-install-a-deb-file-by-dpkg-i-or-by-apt[riferimento]+</p> </div> https://cheroliv.com/blog/2019/0011_gradle_configuration_ide_jbake_content_post.html Fri, 16 Aug 2019 00:00:00 +0000 blog/2019/0011_gradle_configuration_ide_jbake_content_post.html <div class="paragraph"> <p>In un progetto applicativo gestito dal gestore di build Gradle<br> è più piacevole avere la visibilità su tutte le cartelle<br> partecipante allo sviluppo dell’applicazione,<br> come delle cartelle di risorse che non sono<br> nei percorsi per convenzione.<br> Per esempio voglio che la cartella src/jbake,<br> sia visibile come ‘resource folder’,<br> è possibile farlo entrando nella configurazione del progetto,<br> nei wizard dell’IDE. Tuttavia questa opzione non viene salvata al successivo ricaricamento<br> del progetto Gradle nell’IDE. Per apportare questa configurazione in modo permanente<br> la soluzione consiste nel sovrascrivere la configurazione dei percorsi delle sorgenti<br> nel file di configurazione build.gradle come alle linee 18, 19, 20 e 21 :<br> build.gradle<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">plugins { id "java" id "groovy" id "org.jbake.site" version "5.0.0" id "org.ajoberstar.git-publish" version "2.1.1" } repositories { mavenCentral() jcenter() } group project_group version project_version sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =[ "src/main/resources", "src/jbake"//in order to get site src content in the IDE ] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } test { useJUnitPlatform() } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" implementation "org.asciidoctor:asciidoctor-java-integration:$asciidoctor_java_integration_version" implementation "org.freemarker:freemarker:$freemarker_version" testImplementation "org.junit.jupiter:junit-jupiter-api:$junit5_version" testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$junit5_version" } gitPublish { repoUri = github_pages_blog_repository branch = git_branch contents { from(file(jbake_content_from)) { into jbake_content_to } } } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html Wed, 14 Aug 2019 00:00:00 +0000 blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html <div class="paragraph"> <p>L’argomento del ticket è la configurazione di uno script di build Gradle.<br> Voglio poter utilizzare uno script Groovy senza fare riferimento<br> al progetto Gradle al quale l’ho allegato<br> Voglio avere la possibilità di eseguire questo script Groovy fuori da Gradle<br> senza che le annotazioni Ivy di recupero delle dipendenze esterne<br> non causano problemi di prestazioni o di compilazione<br> del script di build Gradle.<br> Per illustrare la configurazione mi baso su due script:<br> uno script di build Gradle e uno script Groovy.<br> Lo script Groovy contiene all’inizio alla riga 2,<br> un’istruzione per estrarre una dipendenza esterna<br> utilizzando il gestore di dipendenze ivy.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-Groovy" data-lang="Groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import org.apache.commons.io.FileUtils static String getSeparator() { System.getProperty("file.separator") } String from = "${System.getProperty("user.home")}${separator}.config${separator}transmission${separator}torrents" String to = "${System.getProperty("user.home")}${separator}Documents${separator}torrents_completed" File fromDlDir = new File("${System.getProperty("user.home")}${separator}Téléchargements") File fromDir = new File(from) File toDir = new File(to) Collection<File> torrentFiles = FileUtils.listFiles( fromDir, ["torrent"] as String[], false) torrentFiles.addAll(FileUtils.listFiles( fromDlDir, ["torrent", "torrent.added"] as String[], false)) torrentFiles.empty ?: torrentFiles.each { it -> FileUtils.copyFileToDirectory(it, toDir) } println torrentFiles.size()</code></pre> </div> </div> <div class="paragraph"> <p>Nel file build.gradle, ora vediamo come armonizzare<br> i due gestori delle dipendenze, ivy e Gradle. L’accordo tra i due avviene sulle righe:<br> 26, 30, 37, 38 et 39<br> Così posso avviare manualmente il mio script Groovy,<br> e la compilazione di Gradle non è ostacolata da @Grab.<br> Le dipendenze dello script Groovy non devono essere fornite in Gradle.<br> D’altra parte non posso avviare lo script Groovy da Gradle.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-Groovy" data-lang="Groovy">plugins { id "java" id "groovy" } repositories { mavenCentral() jcenter() } sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =["src/main/resources"] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> <div class="paragraph"> <p>riferimento del ticket suhttps://stackoverflow.com/a/18174033/837404[stackoverflow]</p> </div> https://cheroliv.com/blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html Tue, 13 Aug 2019 00:00:00 +0000 blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html <div class="sect2"> <h3 id="_il_ppmc">Il PPMC</h3> <div class="paragraph"> <p><a href="https://fr.wikipedia.org/wiki/Plus_petit_commun_multiple">wiki PPMC oppure minimo comun multiplo</a></p> </div> <div class="paragraph"> <p>AlgebraUtils.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">package com.cheroliv.misc import groovy.transform.CompileStatic @CompileStatic class AlgebraUtils { /** * Great common divisor * Plus grand commun diviseur(pgcd) * Great Common Divisor * @param a * @param b * @return */ static Integer gcd(Integer a, Integer b) { !b ? a : gcd(b, a % b) } /** * Least common multiple * Plus petit commun multiplicateur(ppmc) * @param a * @param b * @return */ static BigInteger lcm(Integer a, Integer b) { (a * b / gcd(a, b)) as BigInteger } static void main(String... args) { Integer a = 96 Integer b = 28 println "gcd($a, $b) = ${gcd(a, b)}" a = 790 b = 990 println "lcm($a, $b) = ${lcm(a, b)}" } }</code></pre> </div> </div> <div class="paragraph"> <p>Risultato:</p> </div> <div class="paragraph"> <p>mcd(96, 28) = 4 lcm(790, 990) = 78210</p> </div> </div> https://cheroliv.com/blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html Mon, 12 Aug 2019 00:00:00 +0000 blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html <div class="paragraph"> <p>Sto cercando file per criteri di nome: la lista dei file che hanno l’estensione .h e .cpp</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' + +</code></pre> </div> </div> <div class="paragraph"> <p>la lista dei file che hanno estensione .h e .cpp<br> il risultato è salvato nel file list_of_txt_files.list</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' -print > list_of_txt_files.list</code></pre> </div> </div> <div class="paragraph"> <p>Sto cercando l’elenco dei file la cui estensione è .chm<br> e io distruggo questa lista.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name "*.chm" -type f -delete</code></pre> </div> </div> https://cheroliv.com/blog/2019/0015_projet_avec_methodologie_en_cascade_post.html Thu, 1 Aug 2019 00:00:00 +0000 blog/2019/0015_projet_avec_methodologie_en_cascade_post.html <div class="sect2"> <h3 id="_analizzare_e_raccogliere_i_bisogni">Analizzare e raccogliere i bisogni</h3> </div> <div class="sect2"> <h3 id="_definire_la_gestione_del_progetto">Definire la gestione del progetto</h3> <div class="imageblock"> <div class="content"> <img src="../../diagram/definir_projet.png" alt="definir la gestion de projet"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/triangle_qcd.png" alt="triangle_qcd"> </div> </div> </div> <div class="sect2"> <h3 id="_contestualizzare_il_progetto">Contestualizzare il progetto</h3> </div> <div class="sect2"> <h3 id="_analizzare_e_raccogliere_i_requisiti">Analizzare e raccogliere i requisiti</h3> <div class="sect3"> <h4 id="_formulare_gli_obiettivi_e_i_risultati">Formulare gli obiettivi e i risultati</h4> </div> </div> <div class="sect2"> <h3 id="_decifrare_una_griglia_di_lettura">Decifrare una griglia di lettura</h3> </div> <div class="sect1"> <h2 id="_definisci_il_progetto_con_il_tuo_team">Definisci il progetto con il tuo team</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/conductor.png" alt="chef d’orchestre"> </div> </div> <div class="sect2"> <h3 id="_consultare_gli_esperti_per_trovare_la_soluzione">Consultare gli esperti per trovare la soluzione</h3> </div> <div class="sect2"> <h3 id="_scegliere_una_metodologia_di_gestione_di_progetto">Scegliere una metodologia di gestione di progetto</h3> <div class="imageblock"> <div class="content"> <img src="../../img/cascading_planning.png" alt="planning en cascade"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/Cycle_V_details.jpeg" alt="cycle en V"> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2019/0014_list_all_databases_in_postgresql_post.html Tue, 30 Jul 2019 00:00:00 +0000 blog/2019/0014_list_all_databases_in_postgresql_post.html <div class="paragraph"> <p>Non ho voglia di installarehttps://www.pgadmin.org/[pgAdmin] ou <a href="http://phppgadmin.sourceforge.net/">phppgadmin</a> mentre tutto è presente dalla riga di comando<br> Per fare ciò dobbiamo avviare il terminale e connetterci come l’utente postgres.<br> l’utente postgres è l’unico a avere per impostazione predefinita il diritto di lanciare l’applicazione psql che è il client da riga di comando (Note: Since no source text was provided, there is nothing to translate.)<a href="https://fr.wikipedia.org/wiki/Interface_en_ligne_de_commande">CLI</a>) postgresql,<br> per poter parlare al database da riga di comando dal terminale<br> Per connettersi, avviare il terminale e digitare questo:<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo -i -u postgres</code></pre> </div> </div> <div class="paragraph"> <p>Per connettersi e arrivare direttamente al prompt dei comandi postgresql, digitare questo :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo -i -u postgres psql</code></pre> </div> </div> <div class="paragraph"> <p>Per elencare le basi di dati di un’istanza di postgresql, ecco il comando :<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-SQL" data-lang="SQL">postgres=# \l</code></pre> </div> </div> <div class="paragraph"> <p>risultato:</p> </div> <div class="paragraph"> <p>Lista delle basi di dati Nome | Proprietario | Codifica | Collazione | Tipo carattere | Diritti di accesso</p> </div> <div class="paragraph"> <p>fiber | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberdev | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberweb | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech postgres | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | template0 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres (6 righe)</p> </div> <div class="paragraph"> <p>premi q per uscire dalla visualizzazione dei risultati<br> <br> per elencare gli schemi di un’istanza di postgresl</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-sql" data-lang="sql">postgres=# SELECT schema_name FROM information_schema.schemata;</code></pre> </div> </div> <div class="paragraph"> <p>risultato</p> </div> <div class="paragraph"> <p>pubblico information_schema pg_catalog pg_toast_temp_1 pg_temp_1 pg_toast (6 righe)</p> </div> <div class="paragraph"> <p>ou</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-sql" data-lang="sql">postgres=# SELECT nspname FROM pg_catalog.pg_namespace;</code></pre> </div> </div> <div class="paragraph"> <p>risultato</p> </div> <div class="paragraph"> <p>pg_toast pg_temp_1 pg_toast_temp_1 pg_catalog information_schema pubblico (6 lignes)</p> </div> https://cheroliv.com/blog/2019/0007_groovy_rename_recursively_files_post.html Mon, 29 Jul 2019 00:00:00 +0000 blog/2019/0007_groovy_rename_recursively_files_post.html <div class="paragraph"> <p>Il mio lettore video sulla mia TV ha il suo modo di passare<br> da un file all’altro in lettura continua<br> e la sua modalità di riproduzione consiste nel passare da 1…​..mp4 a 10…​.mp4,<br> e non da 1…​mp4 a 2…​.mp4.<br> Il problema è che ci sono quasi 900 file e cartelle.<br> Bingo è un ottimo caso d’uso di Groovy per manipolare<br> dei file, rinominaggio, ricerca di pattern nel nome del file<br> o cartella.<br> Qui l’obiettivo è di cambiare i nomi che iniziano con<br> un numero e di cui il secondo carattere del nome<br> non è un numero, aggiungerò a questo nome un 0 all’inizio<br></p> </div> <div class="paragraph"> <p>renameFilesToStartWithTwoDigit.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy /** * get a crossplateform separator * @return */ static String getSeparator() { System.getProperty("file.separator") } /** * rename file * @param file * @param newName * @return the renamed file */ static File rename(File file, String newName) { assert file.renameTo(file .parentFile.path + getSeparator() + newName) new File(file .parentFile.path + getSeparator() + newName) } String rootFolderPath = System.getProperty("user.home") + "/Bureau/ng-courses/Udemy - Angular 7 " + "(formerly Angular 2) - The Complete Guide" File rootFolder = new File(rootFolderPath) assert rootFolder.exists() assert rootFolder.directory assert rootFolder.canRead() List<File> dirList = new ArrayList<>() //Adding rootFolder in dirList // just in case there is some files in it dirList.add(rootFolder) //looping to get list of directories //recursively inside rootFolder rootFolder.traverse { File file -> !file.directory ?: dirList.add(file) } //looping through dirList //to rename directories filling criterias for (int i = dirList.size() - 1; i >= 0; i--) { Character[] chars = dirList.get(i).name.chars !(chars[0].digit && !chars[1].digit) ?: dirList.set(i, rename(dirList.get(i), "0${dirList.get(i).name}")) if (dirList.get(i).directory) { //looping through directory //to rename file filling criterias dirList.get(i).listFiles().each { File f -> Character[] cs = f.name.chars !(cs[0].digit && !cs[1].digit) ?: rename(f, "0${f.name}") } } }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0006_groovy_find_files_copy_to_post.html Fri, 19 Jul 2019 00:00:00 +0000 blog/2019/0006_groovy_find_files_copy_to_post.html <div class="paragraph"> <p>Lo scopo di questo script è cercare dei file,<br> da una directory padre; recuperare la selezione<br> in una lista. Finalmente copiare questa lista di file<br> in una directory di destinazione questo in Groovy.</p> </div> <div class="paragraph"> <p>findCopyTo.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import groovy.io.FileType import org.apache.commons.io.FileUtils /** * un separateur OS independant * @return */ static String getSep() { System.getProperty("file.separator") } /** * la liste des fichiers dont le titre contient un item * de la liste des motifs * * @param path * @param motifs * @return la liste des chemins complet de fichiers */ static List<String> findFilesContainingMotifs( String path, List<String> motifs) { List<String> filePathResultList = new ArrayList<>() new File(path) .eachFileRecurse(FileType.FILES) { if (it.name.toLowerCase().contains('cucumber')) { filePathResultList.add it.path } } filePathResultList } /** * copy vers la liste des fichiers * @param files * @param to */ static void copyFilesTo(List<String> files, String to) { File toDirDest = new File(to) files.each { String filepath -> File file = new File(filepath) //si le dernier caractere de to n'est pas un separateur // alors ajoute le a la chaine (to.substring(to.length() - 1) == sep) ?: to.concat(sep) if (to + file.name != filepath) { FileUtils.copyFileToDirectory(file, toDirDest) file.delete() } } } /** * la list des arguments */ String userName = System.getProperty("user.name") List<String> motifs = ['cucumber'] String path = "/media/$userName/320/Books/" String to = "/media/$userName/320/Books/bdd/" /** * lappel aux methodes */ copyFilesTo(findFilesContainingMotifs(path, motifs), to) //affiche moi les fichiers déplacés findFilesContainingMotifs(path, motifs).each { println it }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0005_groovy_manipulation_files_post.html Thu, 18 Jul 2019 00:00:00 +0000 blog/2019/0005_groovy_manipulation_files_post.html <div class="paragraph"> <p>Ici je vais m’intéresser au chargement d’une propriété dans un build projet <a href="https://docs.gradle.org/current/userguide/userguide.html">gradle</a><br> senza che quella sia disponibile nel codice.<br> La proprietà sarà definita nel file gradle.properties della cartella ~/.gradle/gradle.properties<br> ~ è un’abbreviazione della variabile simbolica HOME_PATH che rappresenta la radice dell’utente di sessione: lehttps://fr.wikipedia.org/wiki/R%C3%A9pertoire_personnel[directory personale].<br> Alla stessa maniera in un build di progettohttps://maven.apache.org/guides/index.html[Maven], con ~/.m2/settings.xml Lo scopo di questo script è eliminare i file che corrisponderebbero ai modelli specificati<br> nella variabile strCriteria. Per questo userò lehttps://fr.wikipedia.org/wiki/Fermeture_(informatique)[chiusure]: ciascuno, trovaTutto, raccogliere<br> così come la classe StringTokenizer che taglierà a pezzi la mia stringa di criteri<br> per ottenere una lista di strings. Se uno dei file della mia cartella da pulire contiene uno dei motivi nel suo nome<br> allora sarà un candidato alla distruzione aggiungendolo alla lista risultato<br> E all’ultima riga un piccolo esempio dihttps://en.wikipedia.org/wiki/Elvis_operator[operatore Elvis]<br> filemanip.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy //Mes criteres de selection des fichiers à detruire String strCriteria = "Dummies Dummie ajax Objective-C Windows blackberry " + "wordpress joomla ios c# f# rails ruby flex asp flash Dreamweaver adobe " + "CoffeeScript c++ .chm .epub .rar .zip .tar drupal drupals .net php javascript " + ".js iphone ipad js _js facebook gwt vaadin linq python py zope window " + "3D scala gaming active_directory tomcat jboss glassfish microsoft 2d " + "lego blogger blog cocoa dojo dom dotnetnuke eclipse .gz unity sharepoint " + ".tgz iwork filemaker .doc .txt" //repertoire personnel String userDir = System.getProperty("user.home") //un separateur de chemin crossplatform String sep = System.getProperty("file.separator") //la variable symbolique String sym_books_vrac_path = "books_vrac_path" //le chemin de mon fichier gradle.properties hors projet String propertiesFilePath = userDir .concat("${sep}.gradle${sep}gradle.properties") File propertiesFile = new File(propertiesFilePath) //je m'aassure que le fichier existe et que ce n'est pas un dossier assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() //on boucle avec un inpustream sur le fichier //gradle.properties pour peupler ma variable gradleProperties propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } //le chemin du dossier books_vrac est la valeur de notre clé books_vrac_path String pathVracDir = gradleProperties.get(sym_books_vrac_path) //j'ai récuperé tous ces livres en tapant cette commande dans le terminal //wget -m -np -c -R "index.html*" "http://the-eye.eu/public/Books/IT%20Various/" //on ouvre le dossier dont le chemin est dans la variable pathVracDir // on s'assure qu'il existe et que c'est un dossier File vracDir = new File(pathVracDir) assert vracDir.exists() && vracDir.directory //separer les élèments de ma liste de critère StringTokenizer tokenizer = new StringTokenizer(strCriteria) //la liste de critere List<String> criteriaList = new ArrayList<>() //j'itère sur les tokens et je construit ma liste de token, // mot clef critère de recherche tokenizer.each { String it -> criteriaList.add(it.toLowerCase()) } //je collect tous les noms de fichier dans le dossier List<String> fileNameList = vracDir .listFiles() .collect { File it -> it.directory ?: it.name } // je collect les noms de fichier qui contiendraient un des criteres List<String> resultList = fileNameList.findAll { String name -> criteriaList.findAll { String crit -> name.toLowerCase().contains(crit) } } // je parcours ma liste de résultat pour les effacer resultList.each { String fileName -> assert new File(vracDir.path + sep + fileName).delete() } println fileNameList.size() println resultList.size() resultList.empty ?: println(vracDir.path + sep + resultList.first())</code></pre> </div> </div> https://cheroliv.com/blog/2019/0004_groovy_replace_string_load_properties_post.html Wed, 17 Jul 2019 00:00:00 +0000 blog/2019/0004_groovy_replace_string_load_properties_post.html <div class="paragraph"> <p>Ecco un pezzo di codice funzionante in Groovy,<br> per cambiare tutte le occorrenze di una sequenza di caratteri in una String<br> e caricare un file .properties in un oggetto properties.<br> Eseguire un comando in una Stringa.<br> replaceTextinFile.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy println System.getProperty("user.home") static String getSeparator_() { System.getProperty("file.separator") } String separator = separator_ String path = System.getProperty("user.home") .concat("${separator}.gradle" + separator + "gradle.properties") File propertiesFile = new File(path) assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } String user_name = gradleProperties.getProperty("user_name") String text String resultText text = new File("${System.getProperty("user.home")}" + separator + "src" + separator + "cheroliv.github.io" + separator + "src" + separator + "main" + separator + "resources" + separator + "eco_space.txt").text String to = separator + "media" + separator + "${user_name}" + separator + "320" + separator + "videoCours" + separator String from = "${System.getProperty("user.home")}" + separator + "p2p" + separator resultText = text.replace(to, from) println resultText //execute command line in a string println "rsync -avr ${resultText} ${to}".execute().text</code></pre> </div> </div> https://cheroliv.com/blog/2019/0003_groovy_char_ascci_post.html Wed, 10 Jul 2019 00:00:00 +0000 blog/2019/0003_groovy_char_ascci_post.html <div class="paragraph"> <p>Ecco un frammento di codice funzionante in Groovy, che genera un file di testo,<br> con i primi 256 caratteri leggibili della tabella ASCII<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy import java.nio.charset.StandardCharsets List<Character> chars = new ArrayList<>() int j = 0 Character jumpLine = '\n' 256.times { Integer idx -> if (Character.isAlphabetic(idx) || Character.isDigit(idx)) { if (j % 10 == 0 && j != 0) { chars.add(jumpLine) chars.add(idx as char) } else chars.add(idx as char) j++ } } String seperator = System.getProperty("file.separator") String path = "${System.getProperty("user.home")}${seperator}ascii.txt" File speCharFile = new File(path) if (speCharFile.exists() && !speCharFile.directory) { speCharFile.text = "" } else { speCharFile.createNewFile() } String text = new String() chars.each { Character it -> text = it == jumpLine ? "$text$it" : "$text $it " } speCharFile.setText(text, StandardCharsets.UTF_8.toString())</code></pre> </div> </div> <div class="paragraph"> <p>Ho nominato il file <code>spe_char.groovy</code>,<br> dalla cartella in cui si trova il file<br> aprire un terminale e copia incolla per eseguire lo script<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ groovy spe_char.groovy</code></pre> </div> </div> <div class="paragraph"> <p>risultato:</p> </div> <div class="paragraph"> <p>0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z ª µ º À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ð Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ</p> </div>