@noeva/etl-core 1.0.1 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. package/CHANGELOG.md +134 -0
  2. package/README.md +6 -11
  3. package/dist/{ai-BoTwcmUg.d.ts → ai-DyDIf-hQ.d.ts} +1 -1
  4. package/dist/{ambiente-della-pipeline-BoymQ6uN.d.ts → ambiente-della-pipeline-BhWsyLUR.d.ts} +2 -2
  5. package/dist/chunk-47NVGHUY.js +2 -0
  6. package/dist/chunk-5OE6F2MK.js +2 -0
  7. package/dist/{chunk-NZR6TZ42.js → chunk-5XVANFXO.js} +1 -1
  8. package/dist/chunk-672L5BGQ.js +1 -0
  9. package/dist/{chunk-4NPSBPBY.js → chunk-6QVYBDIS.js} +1 -1
  10. package/dist/{chunk-PE2QKU34.js → chunk-CEAMQIRO.js} +1 -1
  11. package/dist/chunk-DHQ3YOPX.js +5 -0
  12. package/dist/chunk-FBSNZG34.js +1 -0
  13. package/dist/{chunk-J3PBMWSP.js → chunk-GZWYRO3V.js} +1 -1
  14. package/dist/chunk-IODXIHU2.js +1 -0
  15. package/dist/{chunk-P6B2KLNJ.js → chunk-KEFIGSRS.js} +2 -2
  16. package/dist/chunk-KGWA46Y6.js +2 -0
  17. package/dist/chunk-L25W2QNS.js +1 -0
  18. package/dist/{chunk-JLPK6MMQ.js → chunk-OK3XRTGA.js} +1 -1
  19. package/dist/chunk-UHGHK6NP.js +1 -0
  20. package/dist/chunk-VL7DZWWO.js +2 -0
  21. package/dist/chunk-VVXT66DC.js +1 -0
  22. package/dist/chunk-ZKDCUSM2.js +6 -0
  23. package/dist/cli.js +2 -2
  24. package/dist/{client-DYA3wIyb.d.ts → client-BC_mLuT2.d.ts} +2 -2
  25. package/dist/config-BSdGSRPG.d.ts +37 -0
  26. package/dist/{config-BSUwK4p_.d.ts → config-DMafsY4H.d.ts} +3 -3
  27. package/dist/connector-kit.d.ts +14 -9
  28. package/dist/connector-kit.js +1 -1
  29. package/dist/connectors/excel.d.ts +391 -0
  30. package/dist/connectors/excel.js +10 -0
  31. package/dist/connectors/file.d.ts +12 -5
  32. package/dist/connectors/file.js +1 -1
  33. package/dist/connectors/http.d.ts +7 -7
  34. package/dist/connectors/http.js +1 -1
  35. package/dist/connectors/imap.d.ts +6 -6
  36. package/dist/connectors/imap.js +1 -1
  37. package/dist/connectors/jira.d.ts +6 -6
  38. package/dist/connectors/jira.js +2 -2
  39. package/dist/connectors/mail.d.ts +7 -7
  40. package/dist/connectors/mail.js +1 -1
  41. package/dist/connectors/mysql.d.ts +238 -0
  42. package/dist/connectors/mysql.js +2 -0
  43. package/dist/connectors/noeva.d.ts +6 -6
  44. package/dist/connectors/noeva.js +1 -1
  45. package/dist/connectors/oauth.d.ts +5 -5
  46. package/dist/connectors/oauth.js +1 -1
  47. package/dist/connectors/odoo.d.ts +309 -0
  48. package/dist/connectors/odoo.js +3 -0
  49. package/dist/connectors/postgres.d.ts +7 -6
  50. package/dist/connectors/postgres.js +1 -1
  51. package/dist/connectors/process.d.ts +1 -1
  52. package/dist/connectors/process.js +1 -1
  53. package/dist/connectors/sendgrid.d.ts +7 -7
  54. package/dist/connectors/sendgrid.js +1 -1
  55. package/dist/connectors/smtp.d.ts +8 -8
  56. package/dist/connectors/smtp.js +1 -1
  57. package/dist/connectors/sqlserver.d.ts +7 -6
  58. package/dist/connectors/sqlserver.js +1 -1
  59. package/dist/connectors/zoho.d.ts +6 -6
  60. package/dist/connectors/zoho.js +1 -1
  61. package/dist/contract.d.ts +2 -2
  62. package/dist/{credenziali-posta-f7HB2cYW.d.ts → credenziali-posta-C0az04uV.d.ts} +2 -2
  63. package/dist/{errors-bgSO6lGO.d.ts → errors-CRq1uNYZ.d.ts} +8 -1
  64. package/dist/etl.config.js +3 -3
  65. package/dist/guida/404.html +2 -2
  66. package/dist/guida/GUIDA_SVILUPPO.html +7 -7
  67. package/dist/guida/TECHNICAL_OVERVIEW.html +7 -7
  68. package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.js → GUIDA_SVILUPPO.md.Bvr7RKHN.js} +2 -2
  69. package/dist/guida/assets/TECHNICAL_OVERVIEW.md.C6HYc5_h.js +10 -0
  70. package/dist/guida/assets/{app.DeVEBaIz.js → app.uK-5scpr.js} +1 -1
  71. package/dist/guida/assets/chunks/@localSearchIndexroot.AxYI9rrX.js +1 -0
  72. package/dist/guida/assets/chunks/{VPLocalSearchBox.CsTQzJUK.js → VPLocalSearchBox.CB5vaMvW.js} +1 -1
  73. package/dist/guida/assets/chunks/{theme.Dfy0C_Zf.js → theme.z6u0J2Ii.js} +2 -2
  74. package/dist/guida/assets/connectors_README.md.B5QWzWUK.js +1 -0
  75. package/dist/guida/assets/connectors_README.md.B5QWzWUK.lean.js +1 -0
  76. package/dist/guida/assets/connectors_excel.md.CqGtwEB4.js +92 -0
  77. package/dist/guida/assets/connectors_excel.md.CqGtwEB4.lean.js +1 -0
  78. package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.js → connectors_file.md.Dbofo9W5.js} +3 -3
  79. package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.lean.js → connectors_file.md.Dbofo9W5.lean.js} +1 -1
  80. package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.js +34 -0
  81. package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.lean.js +1 -0
  82. package/dist/guida/assets/connectors_odoo.md.DprabV5e.js +19 -0
  83. package/dist/guida/assets/connectors_odoo.md.DprabV5e.lean.js +1 -0
  84. package/dist/guida/assets/{conventions_node-descriptor.md.MQaGlm8a.js → conventions_node-descriptor.md.C19dB-Tb.js} +4 -4
  85. package/dist/guida/assets/conventions_node-descriptor.md.C19dB-Tb.lean.js +1 -0
  86. package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.js → conventions_run-report.md.iVSN9fNV.js} +1 -1
  87. package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.js → conventions_versioni-di-pipeline.md.DJPSthZ8.js} +1 -1
  88. package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.lean.js → conventions_versioni-di-pipeline.md.DJPSthZ8.lean.js} +1 -1
  89. package/dist/guida/assets/{nodes_README.md.CHGy_go6.js → nodes_README.md.BNAiSoJJ.js} +2 -2
  90. package/dist/guida/assets/{nodes_README.md.CHGy_go6.lean.js → nodes_README.md.BNAiSoJJ.lean.js} +1 -1
  91. package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.js → nodes_lookup.md.DrJFsfOJ.js} +1 -1
  92. package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.js → nodes_sink.md.C1S-lAh2.js} +2 -2
  93. package/dist/guida/assets/{nodes_source.md.DP2i3GFv.js → nodes_source.md.BitUNtug.js} +2 -2
  94. package/dist/guida/assets/{nodes_task.md.Dk6VB7as.js → nodes_task.md.CejEQZcD.js} +2 -2
  95. package/dist/guida/assets/{nodes_task.md.Dk6VB7as.lean.js → nodes_task.md.CejEQZcD.lean.js} +1 -1
  96. package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.js → nodes_transform.md.Ciycywnb.js} +1 -1
  97. package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.js → runbooks_deployment.md.BV8Izw4I.js} +1 -1
  98. package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.js +16 -0
  99. package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.lean.js +1 -0
  100. package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.js → runbooks_sql-task-truncate-swap.md.DAz41942.js} +5 -3
  101. package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.lean.js → runbooks_sql-task-truncate-swap.md.DAz41942.lean.js} +1 -1
  102. package/dist/guida/connectors/README.html +5 -5
  103. package/dist/guida/connectors/excel.html +118 -0
  104. package/dist/guida/connectors/file.html +7 -7
  105. package/dist/guida/connectors/http.html +4 -4
  106. package/dist/guida/connectors/imap.html +4 -4
  107. package/dist/guida/connectors/jira.html +5 -5
  108. package/dist/guida/connectors/mysql.html +60 -0
  109. package/dist/guida/connectors/noeva.html +5 -5
  110. package/dist/guida/connectors/oauth.html +5 -5
  111. package/dist/guida/connectors/odoo.html +45 -0
  112. package/dist/guida/connectors/postgres.html +5 -5
  113. package/dist/guida/connectors/process.html +4 -4
  114. package/dist/guida/connectors/sendgrid.html +4 -4
  115. package/dist/guida/connectors/smtp.html +4 -4
  116. package/dist/guida/connectors/sqlserver.html +4 -4
  117. package/dist/guida/connectors/zoho.html +4 -4
  118. package/dist/guida/conventions/node-columns.html +4 -4
  119. package/dist/guida/conventions/node-descriptor.html +8 -8
  120. package/dist/guida/conventions/run-report.html +6 -6
  121. package/dist/guida/conventions/run-trace.html +4 -4
  122. package/dist/guida/conventions/variabili-del-core.html +4 -4
  123. package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
  124. package/dist/guida/guide/claude-code/index.html +4 -4
  125. package/dist/guida/guide/claude-code/prompt.html +5 -5
  126. package/dist/guida/guide/claude-code/strumenti.html +4 -4
  127. package/dist/guida/guide/grafo.html +4 -4
  128. package/dist/guida/guide/usare/app-desktop.html +4 -4
  129. package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
  130. package/dist/guida/guide/usare/index.html +4 -4
  131. package/dist/guida/hashmap.json +1 -1
  132. package/dist/guida/index.html +4 -4
  133. package/dist/guida/nodes/README.html +5 -5
  134. package/dist/guida/nodes/action.html +4 -4
  135. package/dist/guida/nodes/ai.html +4 -4
  136. package/dist/guida/nodes/join.html +4 -4
  137. package/dist/guida/nodes/lookup.html +6 -6
  138. package/dist/guida/nodes/pipeline.html +4 -4
  139. package/dist/guida/nodes/route.html +4 -4
  140. package/dist/guida/nodes/sink.html +7 -7
  141. package/dist/guida/nodes/source.html +7 -7
  142. package/dist/guida/nodes/task.html +6 -6
  143. package/dist/guida/nodes/transform.html +6 -6
  144. package/dist/guida/nodes/try-catch.html +4 -4
  145. package/dist/guida/nodes/union.html +4 -4
  146. package/dist/guida/pagine.json +4 -0
  147. package/dist/guida/pipelines/README.html +4 -4
  148. package/dist/guida/pipelines/crm-leads-sync.html +4 -4
  149. package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
  150. package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
  151. package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
  152. package/dist/guida/pipelines/test-posta.html +4 -4
  153. package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
  154. package/dist/guida/runbooks/deploy-ecr.html +4 -4
  155. package/dist/guida/runbooks/deployment.html +6 -6
  156. package/dist/guida/runbooks/etl-worker.html +5 -5
  157. package/dist/guida/runbooks/excel-operazioni-distruttive.html +42 -0
  158. package/dist/guida/runbooks/graph-server.html +5 -5
  159. package/dist/guida/runbooks/mask-key.html +4 -4
  160. package/dist/guida/runbooks/oauth-google-posta.html +4 -4
  161. package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
  162. package/dist/guida/runbooks/scd2-rehash.html +4 -4
  163. package/dist/guida/runbooks/sql-task-truncate-swap.html +8 -6
  164. package/dist/guida/runbooks/stato-incrementale.html +4 -4
  165. package/dist/guida/sub-pipelines/README.html +4 -4
  166. package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
  167. package/dist/index.d.ts +9 -9
  168. package/dist/index.js +1 -1
  169. package/dist/{invio-Dwz3J7sP.d.ts → invio-9Ubb_cdR.d.ts} +3 -3
  170. package/dist/{istanza-per-il-piano-CucqUF7b.d.ts → istanza-per-il-piano-74NYhIHc.d.ts} +1 -1
  171. package/dist/{manifest-variabili-U1UfPDfF.d.ts → manifest-variabili-DRWUzmxU.d.ts} +1 -1
  172. package/dist/pipelines.d.ts +3 -3
  173. package/dist/pipelines.js +1 -1
  174. package/dist/{runnable-pipeline-CArkLzfv.d.ts → runnable-pipeline-CWgPwi6w.d.ts} +2 -2
  175. package/dist/{config-DIthC7n7.d.ts → sql-watermark-CQVvxhPZ.d.ts} +9 -40
  176. package/dist/testing.d.ts +3 -3
  177. package/dist/testing.js +1 -1
  178. package/dist/{trasporto-DpPLCEQ1.d.ts → trasporto-BaRdP6Wl.d.ts} +4 -4
  179. package/dist/{types-BVA7BIou.d.ts → types-_3rgLhje.d.ts} +21 -2
  180. package/dist/{variabili-dichiarate-DmfcxsT9.d.ts → variabili-dichiarate-CS-eC53K.d.ts} +1 -1
  181. package/kit/skills/etl-graph/SKILL.md +6 -3
  182. package/kit/skills/etl-graph/references/data-patterns.md +1 -1
  183. package/kit/skills/etl-graph/references/error-handling.md +3 -3
  184. package/kit/skills/etl-graph/references/wiring.md +10 -10
  185. package/kit/skills/new-connector/SKILL.md +2 -2
  186. package/package.json +16 -1
  187. package/dist/chunk-BVUOUBLW.js +0 -1
  188. package/dist/chunk-CRR3Q2C7.js +0 -2
  189. package/dist/chunk-LJ7DVP5F.js +0 -2
  190. package/dist/chunk-PKBSETMV.js +0 -2
  191. package/dist/chunk-QPJC4GWR.js +0 -1
  192. package/dist/chunk-RCRMQPFH.js +0 -5
  193. package/dist/chunk-RS5SGDUU.js +0 -1
  194. package/dist/chunk-RWPHH4E2.js +0 -1
  195. package/dist/chunk-SRFFKE5W.js +0 -6
  196. package/dist/chunk-WVODQB6Z.js +0 -1
  197. package/dist/chunk-XZMCC6VQ.js +0 -1
  198. package/dist/chunk-ZCYGHS7P.js +0 -2
  199. package/dist/guida/assets/TECHNICAL_OVERVIEW.md.DTIhkkg9.js +0 -10
  200. package/dist/guida/assets/chunks/@localSearchIndexroot.NgfCNDyz.js +0 -1
  201. package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +0 -1
  202. package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +0 -1
  203. package/dist/guida/assets/conventions_node-descriptor.md.MQaGlm8a.lean.js +0 -1
  204. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.lean.js → GUIDA_SVILUPPO.md.Bvr7RKHN.lean.js} +0 -0
  205. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js → TECHNICAL_OVERVIEW.md.C6HYc5_h.lean.js} +0 -0
  206. /package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.lean.js → conventions_run-report.md.iVSN9fNV.lean.js} +0 -0
  207. /package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.lean.js → nodes_lookup.md.DrJFsfOJ.lean.js} +0 -0
  208. /package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.lean.js → nodes_sink.md.C1S-lAh2.lean.js} +0 -0
  209. /package/dist/guida/assets/{nodes_source.md.DP2i3GFv.lean.js → nodes_source.md.BitUNtug.lean.js} +0 -0
  210. /package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.lean.js → nodes_transform.md.Ciycywnb.lean.js} +0 -0
  211. /package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.lean.js → runbooks_deployment.md.BV8Izw4I.lean.js} +0 -0
@@ -1 +1 @@
1
- import{_ as o,o as i,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const g=JSON.parse('{"title":"Versioni di pipeline","description":"","frontmatter":{},"headers":[],"relativePath":"conventions/versioni-di-pipeline.md","filePath":"conventions/versioni-di-pipeline.md"}'),t={name:"conventions/versioni-di-pipeline.md"};function s(l,e,c,d,r,p){return i(),a("div",null,[...e[0]||(e[0]=[n('<h1 id="versioni-di-pipeline" tabindex="-1">Versioni di pipeline <a class="header-anchor" href="#versioni-di-pipeline" aria-label="Permalink to &quot;Versioni di pipeline&quot;">​</a></h1><p>Ogni pipeline del catalogo ha una <strong>versione di pipeline</strong>: un intero che parte da 1, cresce di uno e non torna mai indietro. Dice con quale codice della pipeline è girata una run, e la scheda della pipeline ne racconta la storia.</p><p>Una pipeline versionata porta nella sua cartella due cose:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>src/pipelines/&lt;nome&gt;/</span></span>\n<span class="line"><span> changelog.ts # le versioni di pipeline, dalla v1 alla corrente</span></span>\n<span class="line"><span> versions/</span></span>\n<span class="line"><span> v1.plan.json # lo snapshot del piano di ogni versione</span></span>\n<span class="line"><span> v2.plan.json</span></span>\n<span class="line"><span> run.ts # esporta il RunnablePipeline, con `changelog: CHANGELOG`</span></span></code></pre></div><h2 id="in-quale-repo" tabindex="-1">In quale repo <a class="header-anchor" href="#in-quale-repo" aria-label="Permalink to &quot;In quale repo&quot;">​</a></h2><p><code>etl versions</code> è un comando della CLI del core e lavora sul repo che contiene l&#39;<code>etl.config.ts</code> trovato risalendo dalla cartella corrente, o indicato con <code>--config</code>: quello del core come quello di un cliente, con le stesse regole.</p><ul><li><strong>La cartella è fissa:</strong> <code>src/pipelines/</code> accanto all&#39;<code>etl.config.ts</code>, senza chiave di configurazione. La cartella di una pipeline è quella del <code>run.ts</code> che esporta <strong>lo stesso oggetto</strong> dichiarato nel catalogo. Una pipeline dichiarata senza cartella è un errore, salvo le pipeline pronte.</li><li><strong>Le pipeline pronte le versiona solo il core.</strong> In un repo cliente non hanno cartella: il gate le salta e lo dice, <code>snapshot</code> e <code>rollback</code> le rifiutano. Per tornare indietro su una pipeline pronta si fa il rollback del deploy o il downgrade del core (<a href="./../runbooks/rollback-di-pipeline#tre-rollback-tre-nomi">runbook</a>).</li><li><strong>La mappa dei branch è del core</strong>, uguale in ogni repo: <code>dev → staging → main</code>, il gate contro <code>origin/dev</code> (contro <code>origin/main</code> su <code>main</code> e sui <code>hotfix/*</code> verso <code>main</code>), il rollback da <code>origin/main</code>. Non si configura.</li><li>Gli script <code>pipeline:*</code> del <code>package.json</code> sono alias di una riga di <code>etl versions …</code>, nel core come nel boilerplate del cliente.</li></ul><h2 id="il-changelog" tabindex="-1">Il changelog <a class="header-anchor" href="#il-changelog" aria-label="Permalink to &quot;Il changelog&quot;">​</a></h2><p><code>changelog.ts</code> esporta <code>CHANGELOG: PipelineChangelog</code>, e il <code>RunnablePipeline</code> lo dichiara in <code>changelog</code>. È obbligatorio per tipo: una pipeline senza non compila. Ogni voce ha il numero, il giorno del bump (<code>AAAA-MM-GG</code>), uno o più ticket Jira e tre elenchi: <strong>Aggiunte</strong> (<code>added</code>), <strong>Modifiche</strong> (<code>changed</code>) e <strong>Rimozioni</strong> (<code>removed</code>). Una voce nata da un rollback porta anche <code>rollbackTo</code>, con la versione a cui si torna e il motivo.</p><p>Ogni voce scritta da <code>etl versions</code> (il rollback e <code>--realign</code>) registra anche <code>core</code>, la versione del core installata in quel momento, letta dal <code>package.json</code> del pacchetto. Nelle voci scritte a mano è facoltativa; se c&#39;è, dev&#39;essere una versione semver.</p><p>La versione corrente non si dichiara a parte: è l&#39;ultima voce. <code>etl catalog check</code> (regola <code>changelog</code>, in ogni repo) rifiuta numeri non consecutivi da 1, date che tornano indietro e voci con i tre elenchi vuoti. La versione corrente finisce nel report di ogni run, in <code>pipelineVersion</code> (<a href="./run-report#versione-di-pipeline-e-release">run-report</a>).</p><h2 id="lo-snapshot-del-piano" tabindex="-1">Lo snapshot del piano <a class="header-anchor" href="#lo-snapshot-del-piano" aria-label="Permalink to &quot;Lo snapshot del piano&quot;">​</a></h2><p>Ogni versione congela il suo <strong>piano</strong>, il <code>PlanSpec</code> che <code>getSpec()</code> restituisce, in <code>versions/v&lt;N&gt;.plan.json</code>. Lo snapshot della versione corrente deve coincidere con il <code>getSpec()</code> di oggi, a meno degli scopi di nodi e istanze: lo verifica il gate, quindi <code>etl ci</code> (nel core <code>pnpm run check</code>). Lo scopo spiega il nodo e non ne cambia il comportamento, quindi lo snapshot si calcola senza: riscriverlo non chiede un bump.</p><p>È questo che fa scattare il controllo anche quando il piano cambia per un file <strong>fuori</strong> dalla cartella della pipeline: un connettore condiviso che espone una colonna in più, un cambio del core che sposta un arco. Anche quello è un cambio della pipeline, e chiede un bump. Il test elenca in una volta tutte le pipeline toccate, ognuna col comando da lanciare.</p><p>Lo snapshot si calcola <strong>senza <code>.env</code></strong>, come la build della doc: con un <code>.env</code> completo, alcune <code>getSpec()</code> mostrano host e cartelle dell&#39;installazione, e uno snapshot versionato non deve dipendere dalla macchina su cui è stato generato, né portare nel repo i dati di un cliente. Il comando sostituisce <code>process.env</code> con un ambiente vuoto per la durata del calcolo, quindi il risultato è lo stesso con e senza <code>.env</code>, e anche con variabili esportate dalla shell.</p><p>Il file è generato: non si scrive né si ritocca a mano. Le chiavi sono in ordine alfabetico e l&#39;indentazione è di due spazi, così rigenerare uno snapshot senza modifiche non produce diff; gli array restano nell&#39;ordine del piano. Prettier non li formatta (<code>.prettierignore</code>), perché il test li confronta byte per byte con l&#39;uscita del comando.</p><h3 id="quando-il-test-e-rosso" tabindex="-1">Quando il test è rosso <a class="header-anchor" href="#quando-il-test-e-rosso" aria-label="Permalink to &quot;Quando il test è rosso&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Messaggio</th><th>Cosa fare</th></tr></thead><tbody><tr><td><code>manca lo snapshot del piano della vN</code></td><td>Lancia il comando che il messaggio indica. Capita a una pipeline nuova o subito dopo un bump.</td></tr><tr><td><code>il piano non coincide con lo snapshot della vN</code></td><td>Il piano è cambiato. Se la vN è già rilasciata, aggiungi la voce vN+1 al changelog e lancia il comando. Se la vN è la versione che stai scrivendo, rilancialo con <code>--force</code>.</td></tr></tbody></table><h2 id="etl-versions-snapshot" tabindex="-1"><code>etl versions snapshot</code> <a class="header-anchor" href="#etl-versions-snapshot" aria-label="Permalink to &quot;`etl versions snapshot`&quot;">​</a></h2><p>Scrive lo snapshot del piano della versione di pipeline corrente.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:snapshot</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions snapshot &lt;pipeline&gt;</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:snapshot</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --force</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # sovrascrive uno snapshot diverso</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Lo snapshot della versione corrente manca</td><td>Lo scrive in <code>versions/v&lt;N&gt;.plan.json</code>, creando la cartella</td><td>0</td></tr><tr><td>Lo snapshot c&#39;è ed è uguale al piano</td><td>Non tocca nulla e lo dice</td><td>0</td></tr><tr><td>Lo snapshot c&#39;è ed è diverso, senza <code>--force</code></td><td>Non lo sovrascrive: spiega che il piano di una versione rilasciata è congelato e serve un bump</td><td>1</td></tr><tr><td>Lo snapshot c&#39;è ed è diverso, con <code>--force</code></td><td>Lo sovrascrive: è la versione ancora in lavorazione, il cui piano cambia finché la PR non è chiusa</td><td>0</td></tr><tr><td>Nome che non è nel catalogo</td><td>Errore che elenca le pipeline del catalogo; nessun file scritto</td><td>2</td></tr><tr><td>Nome mancante, sottocomando o flag sconosciuto</td><td>Errore d&#39;uso</td><td>2</td></tr><tr><td>Cartella della pipeline non trovata (nessun <code>run.ts</code> in <code>src/pipelines/</code> che esporta la pipeline)</td><td>Errore che dice perché; nessun file scritto</td><td>2</td></tr><tr><td>Pipeline pronta in un repo cliente</td><td>Errore: la versiona il core; nessun file scritto</td><td>2</td></tr><tr><td>Lettura o scrittura su disco fallita</td><td>Errore col messaggio del sistema</td><td>1</td></tr></tbody></table><p>Il rifiuto senza <code>--force</code> esiste perché sovrascrivere in silenzio lo snapshot di una versione già rilasciata farebbe tornare verde il test del catalogo <strong>senza</strong> bump, e la versione dichiarata non direbbe più con quale piano è girata una run. <code>--force</code> da solo non basta a impedirlo, quindi lo impone il gate: lo snapshot di ogni versione che è già sulla base deve restare uguale, e uno riscritto o tolto è una violazione. <code>--force</code> serve solo alla versione che non è ancora sulla base. L&#39;unica eccezione è una versione la cui voce di changelog cambia insieme allo snapshot: il numero è passato a un&#39;altra versione, come nel back-merge di un rollback quando <code>dev</code> aveva già preso quel numero (<a href="./../runbooks/rollback-di-pipeline">runbook</a>, § 5).</p><p>Il comando trova la cartella di una pipeline importando i <code>run.ts</code> sotto <code>src/pipelines/</code> del repo e cercando quello che esporta il suo <code>RunnablePipeline</code> (vedi <a href="#in-quale-repo">In quale repo</a>).</p><h2 id="etl-versions-snapshot-realign" tabindex="-1"><code>etl versions snapshot --realign</code> <a class="header-anchor" href="#etl-versions-snapshot-realign" aria-label="Permalink to &quot;`etl versions snapshot --realign`&quot;">​</a></h2><p>Un bump del core può spostare il piano di una pipeline senza che la sua cartella cambi: un connettore che espone una colonna in più, un nodo che descrive diversamente la sua configurazione. Anche quella deriva chiede una versione di pipeline nuova, e la PR che alza il core la porta. Il comando la scrive al posto dell&#39;autore:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> versions</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> snapshot</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --realign</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Per ogni pipeline versionata dal repo (le pronte no) il cui snapshot della versione corrente non coincide col piano di oggi, aggiunge al <code>changelog.ts</code> la versione successiva con la voce «Piano riallineato al core x.y.z» fra le Modifiche, il ticket, la data di oggi e <code>core</code>, e ne scrive lo snapshot. Il gate poi la tratta come ogni bump: base + 1, con la sua voce.</p><p>Prima di committare, <strong>rivedi gli snapshot nel diff</strong>: ogni spostamento dev&#39;essere spiegato dal <code>CHANGELOG.md</code> del core. Il segnale che serve arriva dalle release marcate «Cambia il piano».</p><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Uno o più piani spostati</td><td>Voce e snapshot della versione nuova per ognuno, ed elenco</td><td>0</td></tr><tr><td>Nessun piano spostato</td><td>Non tocca nulla e lo dice</td><td>0</td></tr><tr><td>Lo snapshot della versione corrente di una pipeline manca</td><td>Errore che indica il comando per scriverlo; nessun file scritto</td><td>2</td></tr><tr><td><code>--ticket</code> mancante o non una chiave Jira, un nome di pipeline, <code>--force</code></td><td>Errore d&#39;uso; nessun file scritto</td><td>2</td></tr></tbody></table><p><code>--realign</code> serve alle versioni <strong>già rilasciate</strong>, il cui piano è congelato. Se la versione corrente è quella che il branch sta scrivendo, il suo snapshot si aggiorna con <code>snapshot &lt;nome&gt; --force</code>, non con una versione in più: il gate vorrebbe la base + 1, non + 2.</p><h2 id="quando-serve-un-bump" tabindex="-1">Quando serve un bump <a class="header-anchor" href="#quando-serve-un-bump" aria-label="Permalink to &quot;Quando serve un bump&quot;">​</a></h2><p>Il comportamento di una pipeline non cambia senza che cambi la sua versione. Lo verifica il <strong>gate delle versioni</strong>, <code>etl versions check</code>, in CI e in <code>etl ci</code> (nel core <code>pnpm run check</code>).</p><p><strong>File di comportamento</strong> sono tutti i file della cartella della pipeline, compreso <code>changelog.ts</code>, <strong>esclusi</strong> i test (<code>*.test.ts</code>) e gli snapshot (<code>versions/</code>). Toccare solo test o doc (le schede in <code>docs/pipelines/</code> stanno fuori dalla cartella) non chiede un bump. Un cambio fuori dalla cartella che sposta il piano (un connettore, il core) lo intercetta lo snapshot: anche quello è un bump.</p><p>Nemmeno lo <strong>scopo dei nodi</strong> chiede un bump: un file di comportamento che differisce dal merge-base solo nelle proprietà <code>purpose: &quot;&lt;stringa letterale&gt;&quot;</code> delle opzioni di un metodo del builder (<code>.source(</code>, <code>.transform(</code>, …, <code>.pipeline(</code> per lo scopo di un&#39;istanza) non conta come cambiato, e lo snapshot del piano si calcola senza gli scopi, di nodi e istanze. Il confronto è a token, quindi ignora anche gli spazi e le virgole finali che Prettier sposta quando aggiunge l&#39;opzione; un <code>{ purpose }</code> rimasto vuoto vale come opzione tolta. Per dare uno scopo a un nodo con opzioni calcolate, stendile in un oggetto: <code>{ ...opzioni, purpose: &quot;…&quot; }</code> vale <code>opzioni</code>, ma solo se accanto allo spread c&#39;è lo scopo e nient&#39;altro. Uno scopo scritto con una costante, una concatenazione o un template con interpolazione invece non si riconosce, e conta come modifica: scrivilo letterale. Un <code>purpose</code> fuori dalle opzioni del builder (un campo di un record, il parametro di una query) è un dato, e il suo cambio chiede il bump. Ne segue anche che un cambio di soli spazi fuori dalle stringhe non chiede un bump, tranne gli a capo che decidono il punto e virgola automatico.</p><p>Se un file di comportamento differisce dalla <strong>base</strong>, la pipeline deve dichiarare <strong>la versione della base più uno</strong>, con la sua voce nel changelog e almeno una riga fra Aggiunte, Modifiche e Rimozioni. Una pipeline che sulla base non c&#39;è, non è ancora versionata o è stata rinominata (un altro nome nello snapshot della base), parte dalla <strong>v1</strong>.</p><p><strong>Senza base restano solo gli snapshot.</strong> Se il riferimento che la mappa qui sotto chiede non c&#39;è (un repo cliente appena creato con <code>etl init</code> e mai pubblicato, il bootstrap di un repo migrato, un clone senza <code>origin/dev</code>), non c&#39;è niente da confrontare: il gate lo dice con un avviso, <code>nessuna base (origin/dev): niente da confrontare</code>, e salta i controlli che leggono la base (il bump richiesto, la versione uguale a base + 1, gli snapshot già sulla base). Applicare lì «nuova ⇒ v1» farebbe fallire il bootstrap di una pipeline che arriva dal core già alla v2 o oltre. Lo snapshot della versione corrente invece si confronta col piano anche senza base, perché la base non serve per saperlo: in un repo appena migrato uno snapshot che non coincide, o che manca, è rosso subito e non al primo push. Dove il gate deve valere tutto la base va scaricata: in CI con il checkout a <code>fetch-depth: 0</code>, in locale con <code>git fetch origin dev main</code>. Una base indicata a mano con <code>--base</code> che non c&#39;è resta un errore.</p><table tabindex="0"><thead><tr><th>Branch</th><th>Base</th></tr></thead><tbody><tr><td><code>hotfix/*</code> diretto a <code>main</code> (o senza PR: in locale, sui push), e <code>main</code> stesso</td><td><code>origin/main</code></td></tr><tr><td>tutti gli altri, compreso il back-merge di un <code>hotfix/*</code> verso <code>dev</code> o <code>staging</code></td><td><code>origin/dev</code></td></tr></tbody></table><p>La base è <code>origin/dev</code> anche quando la PR va verso un branch di feature: così tutti i ticket di una feature che toccano la stessa pipeline <strong>condividono un solo bump</strong>, il primo che lo scrive, e gli altri lo trovano già fatto. Su un <code>hotfix/*</code> il numero si conta da <code>main</code>, perché è lì che il codice torna; la sua PR di back-merge verso <code>dev</code> invece si confronta con <code>dev</code>, ed è lì che una collisione col numero già preso da <code>dev</code> chiede di rinumerare. Su <code>main</code> il codice è già in produzione: il confronto con sé stesso lascia solo il controllo dello snapshot.</p><p>I file cambiati si contano dal <strong>merge-base</strong> con la base, la versione della base si legge <strong>in cima</strong> alla base. Ne segue che:</p><ul><li>un branch rimasto indietro non risponde delle pipeline che <code>dev</code> ha cambiato dopo: non le ha toccate, e il gate non le guarda;</li><li>due PR in parallelo che rivendicano lo stesso numero <strong>si scontrano</strong>: quando la prima entra in <code>dev</code>, la seconda va in rosso finché non allinea il branch e rinumera la sua voce. È lo stesso fenomeno dei numeri degli ADR, reso rosso invece che silenzioso.</li></ul><p>Una cartella <strong>spostata</strong> non perde la sua storia. Se sulla base <code>changelog.ts</code> non c&#39;è nel percorso nuovo, il gate chiede a git da quale cartella vengono i file spostati (basta che ne riconosca uno, anche se il changelog è stato riscritto dal bump) e legge la versione lì. In locale sposta con <code>git mv</code>, o fai <code>git add -A</code> prima del gate: git riconosce uno spostamento solo fra file in indice, mentre in CI è tutto già committato. Lo spostamento muove file di comportamento, quindi chiede un bump, con una voce che lo dice.</p><p>Una pipeline <strong>rinominata</strong> invece è una pipeline nuova e riparte dalla v1, anche se la cartella resta la stessa: la dichiarazione della base conta solo se è della stessa pipeline, e lo dice il nome nello snapshot della base, che il test del catalogo vuole uguale al nome nel catalogo.</p><p>Il gate non vede un cambio del core che altera il comportamento <strong>senza</strong> cambiare il piano: per scelta, lo rende visibile il report di run, che porta sia la versione sia la release.</p><h3 id="il-changelog-contiene-solo-dati" tabindex="-1">Il changelog contiene solo dati <a class="header-anchor" href="#il-changelog-contiene-solo-dati" aria-label="Permalink to &quot;Il changelog contiene solo dati&quot;">​</a></h3><p>Il gate legge la versione della base importando il <code>changelog.ts</code> di quel commit, da solo, fuori dal repo. Per questo <code>changelog.ts</code> contiene solo dati: sono ammessi gli import di <strong>tipo</strong> (<code>import type { PipelineChangelog } …</code>), che spariscono; un import di valore non si risolverebbe e il gate si fermerebbe col percorso del file.</p><h2 id="etl-versions-check" tabindex="-1"><code>etl versions check</code> <a class="header-anchor" href="#etl-versions-check" aria-label="Permalink to &quot;`etl versions check`&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:check</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions check</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:check</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --base</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin/staging</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # confronta con un&#39;altra base</span></span></code></pre></div><p>Per ogni pipeline del catalogo raccoglie i file cambiati dal merge-base (committati, modificati e nuovi non ancora aggiunti), la dichiarazione sulla base e lo snapshot, e li passa alla decisione pura in <code>src/versions/version-gate.ts</code>. Prima toglie dai file cambiati quelli di comportamento che differiscono dal merge-base solo negli scopi dei nodi (vedi <a href="#quando-serve-un-bump">Quando serve un bump</a>). Elenca tutte le violazioni in una volta, ognuna con la pipeline e cosa fare. Le pipeline pronte senza cartella le salta, e l&#39;intestazione le elenca. Il branch lo legge da <code>GITHUB_HEAD_REF</code> (le PR, dove il checkout è il merge commit a HEAD staccato), poi da <code>GITHUB_REF_NAME</code> (i push), poi da git; il branch di destinazione di una PR da <code>GITHUB_BASE_REF</code>.</p><table tabindex="0"><thead><tr><th>Messaggio</th><th>Cosa fare</th></tr></thead><tbody><tr><td><code>i file di comportamento sono cambiati … ancora la vN</code></td><td>Aggiungi la voce vN+1 al changelog e lancia <code>pnpm run pipeline:snapshot &lt;nome&gt;</code>.</td></tr><tr><td><code>dichiara la vX, ma su origin/dev è alla vB</code></td><td>Il numero è sbagliato: è vB+1. Se la base è andata avanti, <code>git merge origin/dev</code> e rinumera la voce.</td></tr><tr><td><code>su origin/dev è nuova (…), quindi parte dalla v1</code></td><td>Una pipeline nuova, o rinominata, ha la sola voce v1.</td></tr><tr><td><code>la vN è già presa su origin/dev da un&#39;altra modifica</code></td><td>Un&#39;altra PR è entrata prima con lo stesso numero: <code>git merge origin/dev</code>, porta la tua voce alla vN+1, snapshot.</td></tr><tr><td><code>il changelog non ha la voce vN</code></td><td>La versione dichiarata deve avere la sua voce.</td></tr><tr><td><code>la voce vN ha Aggiunte, Modifiche e Rimozioni tutte vuote</code></td><td>Scrivi cosa cambia e perché.</td></tr><tr><td><code>manca lo snapshot</code> / <code>il piano non coincide con lo snapshot</code></td><td>Come per il test del catalogo: vedi <a href="#quando-il-test-e-rosso">Quando il test è rosso</a>.</td></tr><tr><td><code>lo snapshot della vN è già su origin/dev e qui è stato riscritto o tolto</code></td><td>Ripristinalo dalla base (<code>git checkout origin/dev -- &lt;cartella&gt;/versions/vN.plan.json</code>). Se il piano è cambiato, serve un bump.</td></tr></tbody></table><table tabindex="0"><thead><tr><th>Situazione</th><th>Exit code</th></tr></thead><tbody><tr><td>Nessuna violazione</td><td>0</td></tr><tr><td>Nessuna base della mappa dei branch: avviso «nessuna base», snapshot della versione corrente a posto</td><td>0</td></tr><tr><td>Almeno una violazione, anche senza base (solo snapshot mancante o diverso dal piano)</td><td>1</td></tr><tr><td>Base data con <code>--base</code> che non c&#39;è, storia insufficiente, git che fallisce, flag sbagliato</td><td>2</td></tr><tr><td><code>changelog.ts</code> o snapshot del piano della base che non si importa, non è JSON o non ha la forma attesa</td><td>2</td></tr></tbody></table><p>In CI il gate è un passo del workflow <code>ci.yml</code>, dopo i test; in un repo cliente è una fase di <code>etl ci</code>, che il <code>ci.yml</code> del boilerplate lancia dopo il setup. Il checkout usa <code>fetch-depth: 0</code>: senza, mancherebbero <code>origin/dev</code>, <code>origin/main</code> e la storia per il merge-base. La CI gira sulle PR verso <code>dev</code> e <code>main</code> e sui push su <code>main</code>; le PR verso un branch di feature non hanno CI, quindi lì il gate si lancia in locale con <code>etl ci</code> (nel core <code>pnpm run check</code>), e in CI scatta sulla PR finale verso <code>dev</code>.</p><h2 id="etl-versions-rollback" tabindex="-1"><code>etl versions rollback</code> <a class="header-anchor" href="#etl-versions-rollback" aria-label="Permalink to &quot;`etl versions rollback`&quot;">​</a></h2><p>Riporta il codice di <strong>una sola</strong> pipeline a una sua versione andata in produzione. La procedura completa, dalla PR di hotfix al back-merge, è nel runbook <a href="./../runbooks/rollback-di-pipeline">Rollback di una pipeline</a>.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:rollback</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">N</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --motivo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;testo&gt;&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions rollback …</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:rollback</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">N</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --motivo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;testo&gt;&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --workspace</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Il <strong>piano</strong> lo decide una funzione pura, <code>src/versions/rollback-plan.ts</code>; il comando raccoglie i fatti da git e lo esegue:</p><ul><li><strong>la vN</strong> è quella dell&#39;<strong>ultimo</strong> commit di <code>origin/main</code> che la dichiarava, cercato solo fra i commit che <code>main</code> ha avuto in cima (<code>git log --first-parent</code>): una versione entrata con un merge e già superata nel suo branch non è mai stata in produzione. Risalendo la storia una versione può solo scendere; se sale, la cartella ospitava una pipeline poi rinominata, e lì la ricerca si ferma;</li><li><strong>il numero nuovo</strong> è la versione corrente su <code>main</code> più uno, non la vN: la voce ha <code>rollbackTo</code> con la vN e il motivo, il ticket di <code>--ticket</code>, la data di oggi, la versione del core installata (<code>core</code>), e una riga fra le Modifiche che dice quali versioni si ritirano;</li><li>crea <code>hotfix/rollback-&lt;pipeline&gt;-v&lt;N&gt;</code> da <code>origin/main</code> e riporta la cartella della pipeline com&#39;era su quel commit, <strong>esclusi</strong> <code>changelog.ts</code> e <code>versions/</code>, che restano quelli di <code>main</code> perché portano la storia arrivata dopo. Aggiunge la voce in fondo a <code>changelog.ts</code>, nella forma che Prettier lascerebbe;</li><li>rigenera lo snapshot della versione nuova con <code>etl versions snapshot</code> <strong>in un processo a parte</strong>, lanciato con la CLI dello stesso pacchetto e lo stesso <code>etl.config.ts</code>: il codice ripristinato si carica solo lì;</li><li><strong>confronta il core</strong> della voce della vN, se la registra, con quello installato: la cartella ripristinata gira sul core di oggi, e se i due differiscono il piano può non essere quello della vN. La riga <strong>Core</strong> del resoconto lo dice;</li><li><strong>legge</strong> lo stato di pipeline (locale, o del workspace con <code>--workspace</code>) e confronta le source degli snapshot della versione ritirata e della vN: elenca lo stato salvato, le source che la versione ritirata aggiungeva o toglieva, e lo stato di nodi che nella vN non sono source. Si guardano le source perché solo loro hanno stato; il piano non dice quali dichiarano un watermark, quindi una source toccata compare anche senza stato salvato.</li></ul><p>Se lo stato non si legge (l&#39;API del workspace non risponde) il rollback va avanti lo stesso, e il resoconto dice il comando <code>etl state show</code> per leggerlo prima di aprire la PR: lo stato serve a decidere cosa dichiarare, non a preparare il branch.</p><p>Non committa, non pusha, e non scrive né dati né stato.</p><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Rollback preparato</td><td>Branch creato, cartella ripristinata, voce e snapshot scritti; stampa stato e prossimi passi</td><td>0</td></tr><tr><td>Lo snapshot non si genera (la cartella vecchia non gira contro il core di oggi)</td><td>Branch, cartella e voce restano: l&#39;errore del processo figlio e cosa fare</td><td>1</td></tr><tr><td>Pipeline fuori dal catalogo, nome o versione mancanti, versione non intera, flag sconosciuto</td><td>Errore d&#39;uso</td><td>2</td></tr><tr><td>Pipeline pronta in un repo cliente</td><td>Errore che indica il rollback del deploy e il downgrade del core</td><td>2</td></tr><tr><td><code>--motivo</code> mancante o vuoto, <code>--ticket</code> mancante o non una chiave Jira</td><td>Errore d&#39;uso, prima di leggere git</td><td>2</td></tr><tr><td>vN mai stata in cima a <code>main</code>, uguale alla versione corrente o successiva</td><td>Errore che elenca le versioni che <code>main</code> ha avuto</td><td>2</td></tr><tr><td>Pipeline senza <code>changelog.ts</code> su <code>origin/main</code>, o <code>origin/main</code> assente (<code>git fetch origin</code>)</td><td>Errore che dice perché</td><td>2</td></tr><tr><td><code>changelog.ts</code> di <code>main</code> senza la forma attesa (l&#39;array chiuso da <code>];</code> a inizio riga)</td><td>Errore: la voce va scritta a mano</td><td>2</td></tr><tr><td>Modifiche non committate, o <code>hotfix/rollback-&lt;pipeline&gt;-v&lt;N&gt;</code> che esiste già</td><td>Errore, prima di cambiare branch</td><td>2</td></tr></tbody></table><p>Ogni esito con exit 2 arriva <strong>prima</strong> di toccare branch e file.</p><h2 id="la-sezione-versioni-della-scheda" tabindex="-1">La sezione Versioni della scheda <a class="header-anchor" href="#la-sezione-versioni-della-scheda" aria-label="Permalink to &quot;La sezione Versioni della scheda&quot;">​</a></h2><p>La scheda di ogni pipeline (<code>docs/pipelines/</code>) chiude con una sezione <code>## Versioni</code> e il componente <code>&lt;PipelineVersions name=&quot;&lt;pipeline&gt;&quot; /&gt;</code>. Mostra la storia completa, dalla versione più recente:</p><ul><li>la voce del changelog scritta dall&#39;autore, cioè il <strong>perché</strong>: Aggiunte, Modifiche e Rimozioni, il ticket, la data e, per una voce nata da un rollback, la versione a cui si torna e il motivo;</li><li>sotto, il <strong>diff generato</strong> rispetto alla versione precedente, cioè il <strong>cosa</strong>: nodi, archi e colonne per nodo aggiunti, cambiati e rimossi, calcolato dagli snapshot <code>v&lt;N-1&gt;</code> e <code>v&lt;N&gt;</code>. La v1 non ha una versione precedente, e la scheda lo dice.</li></ul><p>Nodi e archi si confrontano per <code>id</code>, le colonne per <code>id</code> dentro il loro nodo. Un arco che cambia estremi o porta cambia anche <code>id</code>, quindi compare come rimosso più aggiunto; un arco con lo stesso <code>id</code> e un <code>joinType</code> o un tipo diverso è cambiato.</p><p>Una versione è marcata <strong>«rompe il contratto»</strong> quando una colonna di un nodo <strong>sink</strong> della versione precedente sparisce, cambia nome o cambia <code>dataType</code>: chi legge le tabelle a valle se ne deve accorgere. Il nome conta anche quando l&#39;<code>id</code> della colonna resta lo stesso, perché a valle si legge il nome. Vale anche quando sparisce il sink intero, o quando il nodo smette di essere un sink: le sue colonne non escono più. Una colonna aggiunta, una che cambia solo chiave, o un cambio su un nodo che non è sink non rompono il contratto.</p><p>Il diff lo calcola <code>etl docs build</code> a build time, e il loader della doc lo legge dal file del sito. Nella guida del core lo calcola per le schede che la guida pubblica, cioè le pipeline pronte e gli esempi. Uno snapshot non valido ferma la build col suo percorso, uno mancante col comando che lo scrive, invece di mostrare un diff inventato.</p><h2 id="una-pipeline-nuova" tabindex="-1">Una pipeline nuova <a class="header-anchor" href="#una-pipeline-nuova" aria-label="Permalink to &quot;Una pipeline nuova&quot;">​</a></h2><p>Parte dalla v1: <code>changelog.ts</code> con la sola voce v1, poi <code>pnpm run pipeline:snapshot &lt;nome&gt;</code> dopo averla aggiunta al catalogo in <code>etl.config.ts</code>. Lo scaffold <code>/new-pipeline</code> fa entrambe le cose.</p><h2 id="riferimenti" tabindex="-1">Riferimenti <a class="header-anchor" href="#riferimenti" aria-label="Permalink to &quot;Riferimenti&quot;">​</a></h2><ul><li>Codice: <code>src/versions/changelog.ts</code> (il changelog), <code>src/versions/plan-snapshot.ts</code> (snapshot e confronto), <code>src/versions/plan-diff.ts</code> (il diff fra due piani e «rompe il contratto»), <code>src/versions/pipeline-dirs.ts</code> (la cartella di una pipeline), <code>src/versions/core-version.ts</code> (la versione del core installata), <code>src/versions/version-gate.ts</code> (la decisione del gate), <code>src/versions/rollback-plan.ts</code> (il piano di rollback), <code>src/versions/changelog-source.ts</code> (la voce aggiunta al testo di <code>changelog.ts</code>), <code>src/versions/purpose-diff.ts</code> (il confronto a token che ignora gli scopi di nodi e istanze), <code>src/cli-versions.ts</code> (i comandi), <code>src/cli-versions-check.ts</code> (l&#39;adattatore git del gate), <code>src/cli-versions-realign.ts</code> (<code>snapshot --realign</code>), <code>src/cli-versions-rollback.ts</code> (l&#39;adattatore del rollback, con <code>-io.ts</code> per git e il processo figlio e <code>-report.ts</code> per il resoconto), <code>.github/workflows/ci.yml</code> (il passo in CI).</li><li>Doc: <code>docs/.vitepress/lib/pipeline-versions.ts</code> (la storia per la scheda), <code>docs/.vitepress/lib/pipeline-diagrams.ts</code> (grafi e storia, che <code>src/docs/sito.ts</code> calcola per <code>etl docs</code>), <code>docs/.vitepress/data/pipelines.data.ts</code> (il loader, che li legge dal file del sito), <code>docs/.vitepress/theme/components/PipelineVersions.vue</code> (il componente).</li><li>Test: <code>src/catalog/catalogo-del-core.test.ts</code> (snapshot di ogni pipeline del catalogo del core), <code>tests/cli/catalog-check.test.ts</code> (il changelog, con <code>etl catalog check</code>), <code>src/versions/version-gate.test.ts</code> (i casi del gate), <code>src/versions/purpose-diff.test.ts</code> (cosa conta come cambio a meno degli scopi), <code>src/cli-versions-check.test.ts</code> (il comando su un git finto), <code>tests/integration/versions-check.integration.test.ts</code> (il comando su un repository git temporaneo, in <code>pnpm run test:integration</code>), <code>src/versions/rollback-plan.test.ts</code> (i casi del piano), <code>src/cli-versions-rollback.test.ts</code> (il comando su un git finto), <code>src/cli-versions-rollback-io.test.ts</code> (git e processo figlio), <code>tests/integration/versions-rollback.integration.test.ts</code> (il comando su un repository git temporaneo), <code>tests/cli/versions-repo-cliente.test.ts</code> (gate, pronte, <code>--realign</code> e rollback attraverso la CLI, su un repo cliente con <code>dev</code>, <code>staging</code> e <code>main</code>), <code>src/versions/plan-diff.test.ts</code> (il diff), <code>docs/.vitepress/lib/pipeline-cards.test.ts</code> (ogni scheda ha <code>&lt;PipelineVersions&gt;</code>).</li></ul>',71)])])}const u=o(t,[["render",s]]);export{g as __pageData,u as default};
1
+ import{_ as o,o as i,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const g=JSON.parse('{"title":"Versioni di pipeline","description":"","frontmatter":{},"headers":[],"relativePath":"conventions/versioni-di-pipeline.md","filePath":"conventions/versioni-di-pipeline.md"}'),t={name:"conventions/versioni-di-pipeline.md"};function s(l,e,c,r,d,p){return i(),a("div",null,[...e[0]||(e[0]=[n('<h1 id="versioni-di-pipeline" tabindex="-1">Versioni di pipeline <a class="header-anchor" href="#versioni-di-pipeline" aria-label="Permalink to &quot;Versioni di pipeline&quot;">​</a></h1><p>Ogni pipeline del catalogo ha una <strong>versione di pipeline</strong>: un intero che parte da 1, cresce di uno e non torna mai indietro. Dice con quale codice della pipeline è girata una run, e la scheda della pipeline ne racconta la storia.</p><p>Una pipeline versionata porta nella sua cartella due cose:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>src/pipelines/&lt;nome&gt;/</span></span>\n<span class="line"><span> changelog.ts # le versioni di pipeline, dalla v1 alla corrente</span></span>\n<span class="line"><span> versions/</span></span>\n<span class="line"><span> v1.plan.json # lo snapshot del piano di ogni versione</span></span>\n<span class="line"><span> v2.plan.json</span></span>\n<span class="line"><span> run.ts # esporta il RunnablePipeline, con `changelog: CHANGELOG`</span></span></code></pre></div><h2 id="in-quale-repo" tabindex="-1">In quale repo <a class="header-anchor" href="#in-quale-repo" aria-label="Permalink to &quot;In quale repo&quot;">​</a></h2><p><code>etl versions</code> è un comando della CLI del core e lavora sul repo che contiene l&#39;<code>etl.config.ts</code> trovato risalendo dalla cartella corrente, o indicato con <code>--config</code>: quello del core come quello di un cliente, con le stesse regole.</p><ul><li><strong>La cartella è fissa:</strong> <code>src/pipelines/</code> accanto all&#39;<code>etl.config.ts</code>, senza chiave di configurazione. La cartella di una pipeline è quella del <code>run.ts</code> che esporta <strong>lo stesso oggetto</strong> dichiarato nel catalogo. Una pipeline dichiarata senza cartella è un errore, salvo le pipeline pronte.</li><li><strong>Le pipeline pronte le versiona solo il core.</strong> In un repo cliente non hanno cartella: il gate le salta e lo dice, <code>snapshot</code> e <code>rollback</code> le rifiutano. Per tornare indietro su una pipeline pronta si fa il rollback del deploy o il downgrade del core (<a href="./../runbooks/rollback-di-pipeline#tre-rollback-tre-nomi">runbook</a>).</li><li><strong>La mappa dei branch è del core</strong>, uguale in ogni repo: <code>dev → staging → main</code>, il gate contro <code>origin/dev</code> (contro <code>origin/main</code> su <code>main</code> e sui <code>hotfix/*</code> verso <code>main</code>), il rollback da <code>origin/main</code>. Non si configura.</li><li>Gli script <code>pipeline:*</code> del <code>package.json</code> sono alias di una riga di <code>etl versions …</code>, nel core come nel boilerplate del cliente.</li></ul><h2 id="il-changelog" tabindex="-1">Il changelog <a class="header-anchor" href="#il-changelog" aria-label="Permalink to &quot;Il changelog&quot;">​</a></h2><p><code>changelog.ts</code> esporta <code>CHANGELOG: PipelineChangelog</code>, e il <code>RunnablePipeline</code> lo dichiara in <code>changelog</code>. È obbligatorio per tipo: una pipeline senza non compila. Ogni voce ha il numero, il giorno del bump (<code>AAAA-MM-GG</code>), uno o più ticket Jira e tre elenchi: <strong>Aggiunte</strong> (<code>added</code>), <strong>Modifiche</strong> (<code>changed</code>) e <strong>Rimozioni</strong> (<code>removed</code>). Una voce nata da un rollback porta anche <code>rollbackTo</code>, con la versione a cui si torna e il motivo.</p><p>Ogni voce scritta da <code>etl versions</code> (il rollback e <code>--realign</code>) registra anche <code>core</code>, la versione del core installata in quel momento, letta dal <code>package.json</code> del pacchetto. Nelle voci scritte a mano è facoltativa; se c&#39;è, dev&#39;essere una versione semver.</p><p>La versione corrente non si dichiara a parte: è l&#39;ultima voce. <code>etl catalog check</code> (regola <code>changelog</code>, in ogni repo) rifiuta numeri non consecutivi da 1, date che tornano indietro e voci con i tre elenchi vuoti. La versione corrente finisce nel report di ogni run, in <code>pipelineVersion</code> (<a href="./run-report#versione-di-pipeline-e-release">run-report</a>).</p><h2 id="lo-snapshot-del-piano" tabindex="-1">Lo snapshot del piano <a class="header-anchor" href="#lo-snapshot-del-piano" aria-label="Permalink to &quot;Lo snapshot del piano&quot;">​</a></h2><p>Ogni versione congela il suo <strong>piano</strong>, il <code>PlanSpec</code> che <code>getSpec()</code> restituisce, in <code>versions/v&lt;N&gt;.plan.json</code>. Lo snapshot della versione corrente deve coincidere con il <code>getSpec()</code> di oggi, a meno degli scopi di nodi e istanze: lo verifica il gate, quindi <code>etl ci</code> (nel core <code>pnpm run check</code>). Lo scopo spiega il nodo e non ne cambia il comportamento, quindi lo snapshot si calcola senza: riscriverlo non chiede un bump.</p><p>È questo che fa scattare il controllo anche quando il piano cambia per un file <strong>fuori</strong> dalla cartella della pipeline: un connettore condiviso che espone una colonna in più, un cambio del core che sposta un arco. Anche quello è un cambio della pipeline, e chiede un bump. Il test elenca in una volta tutte le pipeline toccate, ognuna col comando da lanciare.</p><p>Lo snapshot si calcola <strong>senza <code>.env</code></strong>, come la build della doc: con un <code>.env</code> completo, alcune <code>getSpec()</code> mostrano host e cartelle dell&#39;installazione, e uno snapshot versionato non deve dipendere dalla macchina su cui è stato generato, né portare nel repo i dati di un cliente. Il comando sostituisce <code>process.env</code> con un ambiente vuoto per la durata del calcolo, quindi il risultato è lo stesso con e senza <code>.env</code>, e anche con variabili esportate dalla shell.</p><p>Il file è generato: non si scrive né si ritocca a mano. Le chiavi sono in ordine alfabetico e l&#39;indentazione è di due spazi, così rigenerare uno snapshot senza modifiche non produce diff; gli array restano nell&#39;ordine del piano. Prettier non li formatta (<code>.prettierignore</code>), perché il test li confronta byte per byte con l&#39;uscita del comando.</p><h3 id="quando-il-test-e-rosso" tabindex="-1">Quando il test è rosso <a class="header-anchor" href="#quando-il-test-e-rosso" aria-label="Permalink to &quot;Quando il test è rosso&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Messaggio</th><th>Cosa fare</th></tr></thead><tbody><tr><td><code>manca lo snapshot del piano della vN</code></td><td>Lancia il comando che il messaggio indica. Capita a una pipeline nuova o subito dopo un bump.</td></tr><tr><td><code>il piano non coincide con lo snapshot della vN</code></td><td>Il piano è cambiato. Se la vN è già rilasciata, aggiungi la voce vN+1 al changelog e lancia il comando. Se la vN è la versione che stai scrivendo, rilancialo con <code>--force</code>.</td></tr></tbody></table><h2 id="etl-versions-snapshot" tabindex="-1"><code>etl versions snapshot</code> <a class="header-anchor" href="#etl-versions-snapshot" aria-label="Permalink to &quot;`etl versions snapshot`&quot;">​</a></h2><p>Scrive lo snapshot del piano della versione di pipeline corrente.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:snapshot</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions snapshot &lt;pipeline&gt;</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:snapshot</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --force</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # sovrascrive uno snapshot diverso</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Lo snapshot della versione corrente manca</td><td>Lo scrive in <code>versions/v&lt;N&gt;.plan.json</code>, creando la cartella</td><td>0</td></tr><tr><td>Lo snapshot c&#39;è ed è uguale al piano</td><td>Non tocca nulla e lo dice</td><td>0</td></tr><tr><td>Lo snapshot c&#39;è ed è diverso, senza <code>--force</code></td><td>Non lo sovrascrive: spiega che il piano di una versione rilasciata è congelato e serve un bump</td><td>1</td></tr><tr><td>Lo snapshot c&#39;è ed è diverso, con <code>--force</code></td><td>Lo sovrascrive: è la versione ancora in lavorazione, il cui piano cambia finché la PR non è chiusa</td><td>0</td></tr><tr><td>Nome che non è nel catalogo</td><td>Errore che elenca le pipeline del catalogo; nessun file scritto</td><td>2</td></tr><tr><td>Nome mancante, sottocomando o flag sconosciuto</td><td>Errore d&#39;uso</td><td>2</td></tr><tr><td>Cartella della pipeline non trovata (nessun <code>run.ts</code> in <code>src/pipelines/</code> che esporta la pipeline)</td><td>Errore che dice perché; nessun file scritto</td><td>2</td></tr><tr><td>Pipeline pronta in un repo cliente</td><td>Errore: la versiona il core; nessun file scritto</td><td>2</td></tr><tr><td>Lettura o scrittura su disco fallita</td><td>Errore col messaggio del sistema</td><td>1</td></tr></tbody></table><p>Il rifiuto senza <code>--force</code> esiste perché sovrascrivere in silenzio lo snapshot di una versione già rilasciata farebbe tornare verde il test del catalogo <strong>senza</strong> bump, e la versione dichiarata non direbbe più con quale piano è girata una run. <code>--force</code> da solo non basta a impedirlo, quindi lo impone il gate: lo snapshot di ogni versione che è già sulla base deve restare uguale, e uno riscritto o tolto è una violazione. <code>--force</code> serve solo alla versione che non è ancora sulla base. L&#39;unica eccezione è una versione la cui voce di changelog cambia insieme allo snapshot: il numero è passato a un&#39;altra versione, come nel back-merge di un rollback quando <code>dev</code> aveva già preso quel numero (<a href="./../runbooks/rollback-di-pipeline">runbook</a>, § 5).</p><p>Il comando trova la cartella di una pipeline importando i <code>run.ts</code> sotto <code>src/pipelines/</code> del repo e cercando quello che esporta il suo <code>RunnablePipeline</code> (vedi <a href="#in-quale-repo">In quale repo</a>).</p><h2 id="etl-versions-snapshot-realign" tabindex="-1"><code>etl versions snapshot --realign</code> <a class="header-anchor" href="#etl-versions-snapshot-realign" aria-label="Permalink to &quot;`etl versions snapshot --realign`&quot;">​</a></h2><p>Un bump del core può spostare il piano di una pipeline senza che la sua cartella cambi: un connettore che espone una colonna in più, un nodo che descrive diversamente la sua configurazione. Anche quella deriva chiede una versione di pipeline nuova, e la PR che alza il core la porta. Il comando la scrive al posto dell&#39;autore:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> versions</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> snapshot</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --realign</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Per ogni pipeline versionata dal repo (le pronte no) il cui snapshot della versione corrente non coincide col piano di oggi, aggiunge al <code>changelog.ts</code> la versione successiva con la voce «Piano riallineato al core x.y.z» fra le Modifiche, il ticket, la data di oggi e <code>core</code>, e ne scrive lo snapshot. Il gate poi la tratta come ogni bump: base + 1, con la sua voce.</p><p>Prima di committare, <strong>rivedi gli snapshot nel diff</strong>: ogni spostamento dev&#39;essere spiegato dal <code>CHANGELOG.md</code> del core. Il segnale che serve arriva dalle release marcate «Cambia il piano».</p><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Uno o più piani spostati</td><td>Voce e snapshot della versione nuova per ognuno, ed elenco</td><td>0</td></tr><tr><td>Nessun piano spostato</td><td>Non tocca nulla e lo dice</td><td>0</td></tr><tr><td>Lo snapshot della versione corrente di una pipeline manca</td><td>Errore che indica il comando per scriverlo; nessun file scritto</td><td>2</td></tr><tr><td><code>--ticket</code> mancante o non una chiave Jira, un nome di pipeline, <code>--force</code></td><td>Errore d&#39;uso; nessun file scritto</td><td>2</td></tr></tbody></table><p><code>--realign</code> serve alle versioni <strong>già rilasciate</strong>, il cui piano è congelato. Se la versione corrente è quella che il branch sta scrivendo, il suo snapshot si aggiorna con <code>snapshot &lt;nome&gt; --force</code>, non con una versione in più: il gate vorrebbe la base + 1, non + 2.</p><h2 id="quando-serve-un-bump" tabindex="-1">Quando serve un bump <a class="header-anchor" href="#quando-serve-un-bump" aria-label="Permalink to &quot;Quando serve un bump&quot;">​</a></h2><p>Il comportamento di una pipeline non cambia senza che cambi la sua versione. Lo verifica il <strong>gate delle versioni</strong>, <code>etl versions check</code>, in CI e in <code>etl ci</code> (nel core <code>pnpm run check</code>).</p><p><strong>File di comportamento</strong> sono tutti i file della cartella della pipeline, compreso <code>changelog.ts</code>, <strong>esclusi</strong> i test (<code>*.test.ts</code>) e gli snapshot (<code>versions/</code>). Toccare solo test o doc (le schede in <code>docs/pipelines/</code> stanno fuori dalla cartella) non chiede un bump. Un cambio fuori dalla cartella che sposta il piano (un connettore, il core) lo intercetta lo snapshot: anche quello è un bump.</p><p>Nemmeno lo <strong>scopo dei nodi</strong> chiede un bump: un file di comportamento che differisce dal merge-base solo nelle proprietà <code>purpose: &quot;&lt;stringa letterale&gt;&quot;</code> delle opzioni di un metodo del builder (<code>.source(</code>, <code>.transform(</code>, …, <code>.pipeline(</code> per lo scopo di un&#39;istanza) non conta come cambiato, e lo snapshot del piano si calcola senza gli scopi, di nodi e istanze. Il confronto è a token, quindi ignora anche gli spazi e le virgole finali che Prettier sposta quando aggiunge l&#39;opzione; un <code>{ purpose }</code> rimasto vuoto vale come opzione tolta. Per dare uno scopo a un nodo con opzioni calcolate, stendile in un oggetto: <code>{ ...opzioni, purpose: &quot;…&quot; }</code> vale <code>opzioni</code>, ma solo se accanto allo spread c&#39;è lo scopo e nient&#39;altro. Uno scopo scritto con una costante, una concatenazione o un template con interpolazione invece non si riconosce, e conta come modifica: scrivilo letterale. Un <code>purpose</code> fuori dalle opzioni del builder (un campo di un record, il parametro di una query) è un dato, e il suo cambio chiede il bump. Ne segue anche che un cambio di soli spazi fuori dalle stringhe non chiede un bump, tranne gli a capo che decidono il punto e virgola automatico.</p><p>Se un file di comportamento differisce dalla <strong>base</strong>, la pipeline deve dichiarare <strong>la versione della base più uno</strong>, con la sua voce nel changelog e almeno una riga fra Aggiunte, Modifiche e Rimozioni. Una pipeline che sulla base non c&#39;è, non è ancora versionata o è stata rinominata (un altro nome nello snapshot della base), parte dalla <strong>v1</strong>.</p><p><strong>Senza base restano solo gli snapshot.</strong> Se il riferimento che la mappa qui sotto chiede non c&#39;è (un repo cliente appena creato con <code>etl init</code> e mai pubblicato, il bootstrap di un repo migrato, un clone senza <code>origin/dev</code>), non c&#39;è niente da confrontare: il gate lo dice con un avviso, <code>nessuna base (origin/dev): niente da confrontare</code>, e salta i controlli che leggono la base (il bump richiesto, la versione uguale a base + 1, gli snapshot già sulla base). Applicare lì «nuova ⇒ v1» farebbe fallire il bootstrap di una pipeline che arriva dal core già alla v2 o oltre. Lo snapshot della versione corrente invece si confronta col piano anche senza base, perché la base non serve per saperlo: in un repo appena migrato uno snapshot che non coincide, o che manca, è rosso subito e non al primo push. Dove il gate deve valere tutto la base va scaricata: in CI con il checkout a <code>fetch-depth: 0</code>, in locale con <code>git fetch origin dev main</code>. Una base indicata a mano con <code>--base</code> che non c&#39;è resta un errore.</p><table tabindex="0"><thead><tr><th>Branch</th><th>Base</th></tr></thead><tbody><tr><td><code>hotfix/*</code> diretto a <code>main</code> (o senza PR: in locale, sui push), e <code>main</code> stesso</td><td><code>origin/main</code></td></tr><tr><td>tutti gli altri, compreso il back-merge di un <code>hotfix/*</code> verso <code>dev</code> o <code>staging</code></td><td><code>origin/dev</code></td></tr></tbody></table><p>La base è <code>origin/dev</code> anche quando la PR va verso un branch di feature: così tutti i ticket di una feature che toccano la stessa pipeline <strong>condividono un solo bump</strong>, il primo che lo scrive, e gli altri lo trovano già fatto. Su un <code>hotfix/*</code> il numero si conta da <code>main</code>, perché è lì che il codice torna; la sua PR di back-merge verso <code>dev</code> invece si confronta con <code>dev</code>, ed è lì che una collisione col numero già preso da <code>dev</code> chiede di rinumerare. Su <code>main</code> il codice è già in produzione: il confronto con sé stesso lascia solo il controllo dello snapshot.</p><p>I file cambiati si contano dal <strong>merge-base</strong> con la base, la versione della base si legge <strong>in cima</strong> alla base. Ne segue che:</p><ul><li>un branch rimasto indietro non risponde delle pipeline che <code>dev</code> ha cambiato dopo: non le ha toccate, e il gate non le guarda;</li><li>due PR in parallelo che rivendicano lo stesso numero <strong>si scontrano</strong>: quando la prima entra in <code>dev</code>, la seconda va in rosso finché non allinea il branch e rinumera la sua voce. È lo stesso fenomeno dei numeri degli ADR, reso rosso invece che silenzioso.</li></ul><p>Una cartella <strong>spostata</strong> non perde la sua storia. Se sulla base <code>changelog.ts</code> non c&#39;è nel percorso nuovo, il gate chiede a git da quale cartella vengono i file spostati (basta che ne riconosca uno, anche se il changelog è stato riscritto dal bump) e legge la versione lì. In locale sposta con <code>git mv</code>, o fai <code>git add -A</code> prima del gate: git riconosce uno spostamento solo fra file in indice, mentre in CI è tutto già committato. Lo spostamento muove file di comportamento, quindi chiede un bump, con una voce che lo dice.</p><p>Una pipeline <strong>rinominata</strong> invece è una pipeline nuova e riparte dalla v1, anche se la cartella resta la stessa: la dichiarazione della base conta solo se è della stessa pipeline, e lo dice il nome nello snapshot della base, che il test del catalogo vuole uguale al nome nel catalogo.</p><p>Il gate non vede un cambio del core che altera il comportamento <strong>senza</strong> cambiare il piano: per scelta, lo rende visibile il report di run, che porta sia la versione sia la release.</p><h3 id="il-changelog-contiene-solo-dati" tabindex="-1">Il changelog contiene solo dati <a class="header-anchor" href="#il-changelog-contiene-solo-dati" aria-label="Permalink to &quot;Il changelog contiene solo dati&quot;">​</a></h3><p>Il gate legge la versione della base importando il <code>changelog.ts</code> di quel commit, da solo, fuori dal repo. Per questo <code>changelog.ts</code> contiene solo dati: sono ammessi gli import di <strong>tipo</strong> (<code>import type { PipelineChangelog } …</code>), che spariscono; un import di valore non si risolverebbe e il gate si fermerebbe col percorso del file.</p><h2 id="etl-versions-check" tabindex="-1"><code>etl versions check</code> <a class="header-anchor" href="#etl-versions-check" aria-label="Permalink to &quot;`etl versions check`&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:check</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions check</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:check</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --base</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> origin/staging</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # confronta con un&#39;altra base</span></span></code></pre></div><p>Per ogni pipeline del catalogo raccoglie i file cambiati dal merge-base (committati, modificati e nuovi non ancora aggiunti), la dichiarazione sulla base e lo snapshot, e li passa alla decisione pura in <code>src/versions/version-gate.ts</code>. Prima toglie dai file cambiati quelli di comportamento che differiscono dal merge-base solo negli scopi dei nodi (vedi <a href="#quando-serve-un-bump">Quando serve un bump</a>). Elenca tutte le violazioni in una volta, ognuna con la pipeline e cosa fare. Le pipeline pronte senza cartella le salta, e l&#39;intestazione le elenca. Il branch lo legge da <code>GITHUB_HEAD_REF</code> (le PR, dove il checkout è il merge commit a HEAD staccato), poi da <code>GITHUB_REF_NAME</code> (i push), poi da git; il branch di destinazione di una PR da <code>GITHUB_BASE_REF</code>.</p><table tabindex="0"><thead><tr><th>Messaggio</th><th>Cosa fare</th></tr></thead><tbody><tr><td><code>i file di comportamento sono cambiati … ancora la vN</code></td><td>Aggiungi la voce vN+1 al changelog e lancia <code>pnpm run pipeline:snapshot &lt;nome&gt;</code>.</td></tr><tr><td><code>dichiara la vX, ma su origin/dev è alla vB</code></td><td>Il numero è sbagliato: è vB+1. Se la base è andata avanti, <code>git merge origin/dev</code> e rinumera la voce.</td></tr><tr><td><code>su origin/dev è nuova (…), quindi parte dalla v1</code></td><td>Una pipeline nuova, o rinominata, ha la sola voce v1.</td></tr><tr><td><code>la vN è già presa su origin/dev da un&#39;altra modifica</code></td><td>Un&#39;altra PR è entrata prima con lo stesso numero: <code>git merge origin/dev</code>, porta la tua voce alla vN+1, snapshot.</td></tr><tr><td><code>il changelog non ha la voce vN</code></td><td>La versione dichiarata deve avere la sua voce.</td></tr><tr><td><code>la voce vN ha Aggiunte, Modifiche e Rimozioni tutte vuote</code></td><td>Scrivi cosa cambia e perché.</td></tr><tr><td><code>manca lo snapshot</code> / <code>il piano non coincide con lo snapshot</code></td><td>Come per il test del catalogo: vedi <a href="#quando-il-test-e-rosso">Quando il test è rosso</a>.</td></tr><tr><td><code>lo snapshot della vN è già su origin/dev e qui è stato riscritto o tolto</code></td><td>Ripristinalo dalla base (<code>git checkout origin/dev -- &lt;cartella&gt;/versions/vN.plan.json</code>). Se il piano è cambiato, serve un bump.</td></tr></tbody></table><table tabindex="0"><thead><tr><th>Situazione</th><th>Exit code</th></tr></thead><tbody><tr><td>Nessuna violazione</td><td>0</td></tr><tr><td>Nessuna base della mappa dei branch: avviso «nessuna base», snapshot della versione corrente a posto</td><td>0</td></tr><tr><td>Almeno una violazione, anche senza base (solo snapshot mancante o diverso dal piano)</td><td>1</td></tr><tr><td>Base data con <code>--base</code> che non c&#39;è, storia insufficiente, git che fallisce, flag sbagliato</td><td>2</td></tr><tr><td><code>changelog.ts</code> o snapshot del piano della base che non si importa, non è JSON o non ha la forma attesa</td><td>2</td></tr></tbody></table><p>In CI il gate è un passo del workflow <code>ci.yml</code>, dopo i test; in un repo cliente è una fase di <code>etl ci</code>, che il <code>ci.yml</code> del boilerplate lancia dopo il setup. Il checkout usa <code>fetch-depth: 0</code>: senza, mancherebbero <code>origin/dev</code>, <code>origin/main</code> e la storia per il merge-base. La CI del core gira solo sulle PR verso <code>dev</code>; le PR verso un branch di feature non hanno CI, quindi lì il gate si lancia in locale con <code>etl ci</code> (nel core <code>pnpm run check</code>), e in CI scatta sulla PR finale verso <code>dev</code>.</p><h2 id="etl-versions-rollback" tabindex="-1"><code>etl versions rollback</code> <a class="header-anchor" href="#etl-versions-rollback" aria-label="Permalink to &quot;`etl versions rollback`&quot;">​</a></h2><p>Riporta il codice di <strong>una sola</strong> pipeline a una sua versione andata in produzione. La procedura completa, dalla PR di hotfix al back-merge, è nel runbook <a href="./../runbooks/rollback-di-pipeline">Rollback di una pipeline</a>.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:rollback</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">N</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --motivo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;testo&gt;&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # alias di: pnpm run etl versions rollback …</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pipeline:rollback</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">N</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --motivo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;testo&gt;&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ticket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">chiav</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --workspace</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Il <strong>piano</strong> lo decide una funzione pura, <code>src/versions/rollback-plan.ts</code>; il comando raccoglie i fatti da git e lo esegue:</p><ul><li><strong>la vN</strong> è quella dell&#39;<strong>ultimo</strong> commit di <code>origin/main</code> che la dichiarava, cercato solo fra i commit che <code>main</code> ha avuto in cima (<code>git log --first-parent</code>): una versione entrata con un merge e già superata nel suo branch non è mai stata in produzione. Risalendo la storia una versione può solo scendere; se sale, la cartella ospitava una pipeline poi rinominata, e lì la ricerca si ferma;</li><li><strong>il numero nuovo</strong> è la versione corrente su <code>main</code> più uno, non la vN: la voce ha <code>rollbackTo</code> con la vN e il motivo, il ticket di <code>--ticket</code>, la data di oggi, la versione del core installata (<code>core</code>), e una riga fra le Modifiche che dice quali versioni si ritirano;</li><li>crea <code>hotfix/rollback-&lt;pipeline&gt;-v&lt;N&gt;</code> da <code>origin/main</code> e riporta la cartella della pipeline com&#39;era su quel commit, <strong>esclusi</strong> <code>changelog.ts</code> e <code>versions/</code>, che restano quelli di <code>main</code> perché portano la storia arrivata dopo. Aggiunge la voce in fondo a <code>changelog.ts</code>, nella forma che Prettier lascerebbe;</li><li>rigenera lo snapshot della versione nuova con <code>etl versions snapshot</code> <strong>in un processo a parte</strong>, lanciato con la CLI dello stesso pacchetto e lo stesso <code>etl.config.ts</code>: il codice ripristinato si carica solo lì;</li><li><strong>confronta il core</strong> della voce della vN, se la registra, con quello installato: la cartella ripristinata gira sul core di oggi, e se i due differiscono il piano può non essere quello della vN. La riga <strong>Core</strong> del resoconto lo dice;</li><li><strong>legge</strong> lo stato di pipeline (locale, o del workspace con <code>--workspace</code>) e confronta le source degli snapshot della versione ritirata e della vN: elenca lo stato salvato, le source che la versione ritirata aggiungeva o toglieva, e lo stato di nodi che nella vN non sono source. Si guardano le source perché solo loro hanno stato; il piano non dice quali dichiarano un watermark, quindi una source toccata compare anche senza stato salvato.</li></ul><p>Se lo stato non si legge (l&#39;API del workspace non risponde) il rollback va avanti lo stesso, e il resoconto dice il comando <code>etl state show</code> per leggerlo prima di aprire la PR: lo stato serve a decidere cosa dichiarare, non a preparare il branch.</p><p>Non committa, non pusha, e non scrive né dati né stato.</p><table tabindex="0"><thead><tr><th>Situazione</th><th>Esito</th><th>Exit code</th></tr></thead><tbody><tr><td>Rollback preparato</td><td>Branch creato, cartella ripristinata, voce e snapshot scritti; stampa stato e prossimi passi</td><td>0</td></tr><tr><td>Lo snapshot non si genera (la cartella vecchia non gira contro il core di oggi)</td><td>Branch, cartella e voce restano: l&#39;errore del processo figlio e cosa fare</td><td>1</td></tr><tr><td>Pipeline fuori dal catalogo, nome o versione mancanti, versione non intera, flag sconosciuto</td><td>Errore d&#39;uso</td><td>2</td></tr><tr><td>Pipeline pronta in un repo cliente</td><td>Errore che indica il rollback del deploy e il downgrade del core</td><td>2</td></tr><tr><td><code>--motivo</code> mancante o vuoto, <code>--ticket</code> mancante o non una chiave Jira</td><td>Errore d&#39;uso, prima di leggere git</td><td>2</td></tr><tr><td>vN mai stata in cima a <code>main</code>, uguale alla versione corrente o successiva</td><td>Errore che elenca le versioni che <code>main</code> ha avuto</td><td>2</td></tr><tr><td>Pipeline senza <code>changelog.ts</code> su <code>origin/main</code>, o <code>origin/main</code> assente (<code>git fetch origin</code>)</td><td>Errore che dice perché</td><td>2</td></tr><tr><td><code>changelog.ts</code> di <code>main</code> senza la forma attesa (l&#39;array chiuso da <code>];</code> a inizio riga)</td><td>Errore: la voce va scritta a mano</td><td>2</td></tr><tr><td>Modifiche non committate, o <code>hotfix/rollback-&lt;pipeline&gt;-v&lt;N&gt;</code> che esiste già</td><td>Errore, prima di cambiare branch</td><td>2</td></tr></tbody></table><p>Ogni esito con exit 2 arriva <strong>prima</strong> di toccare branch e file.</p><h2 id="la-sezione-versioni-della-scheda" tabindex="-1">La sezione Versioni della scheda <a class="header-anchor" href="#la-sezione-versioni-della-scheda" aria-label="Permalink to &quot;La sezione Versioni della scheda&quot;">​</a></h2><p>La scheda di ogni pipeline (<code>docs/pipelines/</code>) chiude con una sezione <code>## Versioni</code> e il componente <code>&lt;PipelineVersions name=&quot;&lt;pipeline&gt;&quot; /&gt;</code>. Mostra la storia completa, dalla versione più recente:</p><ul><li>la voce del changelog scritta dall&#39;autore, cioè il <strong>perché</strong>: Aggiunte, Modifiche e Rimozioni, il ticket, la data e, per una voce nata da un rollback, la versione a cui si torna e il motivo;</li><li>sotto, il <strong>diff generato</strong> rispetto alla versione precedente, cioè il <strong>cosa</strong>: nodi, archi e colonne per nodo aggiunti, cambiati e rimossi, calcolato dagli snapshot <code>v&lt;N-1&gt;</code> e <code>v&lt;N&gt;</code>. La v1 non ha una versione precedente, e la scheda lo dice.</li></ul><p>Nodi e archi si confrontano per <code>id</code>, le colonne per <code>id</code> dentro il loro nodo. Un arco che cambia estremi o porta cambia anche <code>id</code>, quindi compare come rimosso più aggiunto; un arco con lo stesso <code>id</code> e un <code>joinType</code> o un tipo diverso è cambiato.</p><p>Una versione è marcata <strong>«rompe il contratto»</strong> quando una colonna di un nodo <strong>sink</strong> della versione precedente sparisce, cambia nome o cambia <code>dataType</code>: chi legge le tabelle a valle se ne deve accorgere. Il nome conta anche quando l&#39;<code>id</code> della colonna resta lo stesso, perché a valle si legge il nome. Vale anche quando sparisce il sink intero, o quando il nodo smette di essere un sink: le sue colonne non escono più. Una colonna aggiunta, una che cambia solo chiave, o un cambio su un nodo che non è sink non rompono il contratto.</p><p>Il diff lo calcola <code>etl docs build</code> a build time, e il loader della doc lo legge dal file del sito. Nella guida del core lo calcola per le schede che la guida pubblica, cioè le pipeline pronte e gli esempi. Uno snapshot non valido ferma la build col suo percorso, uno mancante col comando che lo scrive, invece di mostrare un diff inventato.</p><h2 id="una-pipeline-nuova" tabindex="-1">Una pipeline nuova <a class="header-anchor" href="#una-pipeline-nuova" aria-label="Permalink to &quot;Una pipeline nuova&quot;">​</a></h2><p>Parte dalla v1: <code>changelog.ts</code> con la sola voce v1, poi <code>pnpm run pipeline:snapshot &lt;nome&gt;</code> dopo averla aggiunta al catalogo in <code>etl.config.ts</code>. Lo scaffold <code>/new-pipeline</code> fa entrambe le cose.</p><h2 id="riferimenti" tabindex="-1">Riferimenti <a class="header-anchor" href="#riferimenti" aria-label="Permalink to &quot;Riferimenti&quot;">​</a></h2><ul><li>Codice: <code>src/versions/changelog.ts</code> (il changelog), <code>src/versions/plan-snapshot.ts</code> (snapshot e confronto), <code>src/versions/plan-diff.ts</code> (il diff fra due piani e «rompe il contratto»), <code>src/versions/pipeline-dirs.ts</code> (la cartella di una pipeline), <code>src/versions/core-version.ts</code> (la versione del core installata), <code>src/versions/version-gate.ts</code> (la decisione del gate), <code>src/versions/rollback-plan.ts</code> (il piano di rollback), <code>src/versions/changelog-source.ts</code> (la voce aggiunta al testo di <code>changelog.ts</code>), <code>src/versions/purpose-diff.ts</code> (il confronto a token che ignora gli scopi di nodi e istanze), <code>src/cli-versions.ts</code> (i comandi), <code>src/cli-versions-check.ts</code> (l&#39;adattatore git del gate), <code>src/cli-versions-realign.ts</code> (<code>snapshot --realign</code>), <code>src/cli-versions-rollback.ts</code> (l&#39;adattatore del rollback, con <code>-io.ts</code> per git e il processo figlio e <code>-report.ts</code> per il resoconto), <code>.github/workflows/ci.yml</code> (il passo in CI).</li><li>Doc: <code>docs/.vitepress/lib/pipeline-versions.ts</code> (la storia per la scheda), <code>docs/.vitepress/lib/pipeline-diagrams.ts</code> (grafi e storia, che <code>src/docs/sito.ts</code> calcola per <code>etl docs</code>), <code>docs/.vitepress/data/pipelines.data.ts</code> (il loader, che li legge dal file del sito), <code>docs/.vitepress/theme/components/PipelineVersions.vue</code> (il componente).</li><li>Test: <code>src/catalog/catalogo-del-core.test.ts</code> (snapshot di ogni pipeline del catalogo del core), <code>tests/cli/catalog-check.test.ts</code> (il changelog, con <code>etl catalog check</code>), <code>src/versions/version-gate.test.ts</code> (i casi del gate), <code>src/versions/purpose-diff.test.ts</code> (cosa conta come cambio a meno degli scopi), <code>src/cli-versions-check.test.ts</code> (il comando su un git finto), <code>tests/integration/versions-check.integration.test.ts</code> (il comando su un repository git temporaneo, in <code>pnpm run test:integration</code>), <code>src/versions/rollback-plan.test.ts</code> (i casi del piano), <code>src/cli-versions-rollback.test.ts</code> (il comando su un git finto), <code>src/cli-versions-rollback-io.test.ts</code> (git e processo figlio), <code>tests/integration/versions-rollback.integration.test.ts</code> (il comando su un repository git temporaneo), <code>tests/cli/versions-repo-cliente.test.ts</code> (gate, pronte, <code>--realign</code> e rollback attraverso la CLI, su un repo cliente con <code>dev</code>, <code>staging</code> e <code>main</code>), <code>src/versions/plan-diff.test.ts</code> (il diff), <code>docs/.vitepress/lib/pipeline-cards.test.ts</code> (ogni scheda ha <code>&lt;PipelineVersions&gt;</code>).</li></ul>',71)])])}const u=o(t,[["render",s]]);export{g as __pageData,u as default};
@@ -1 +1 @@
1
- import{_ as o,o as i,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const g=JSON.parse('{"title":"Versioni di pipeline","description":"","frontmatter":{},"headers":[],"relativePath":"conventions/versioni-di-pipeline.md","filePath":"conventions/versioni-di-pipeline.md"}'),t={name:"conventions/versioni-di-pipeline.md"};function s(l,e,c,d,r,p){return i(),a("div",null,[...e[0]||(e[0]=[n("",71)])])}const u=o(t,[["render",s]]);export{g as __pageData,u as default};
1
+ import{_ as o,o as i,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const g=JSON.parse('{"title":"Versioni di pipeline","description":"","frontmatter":{},"headers":[],"relativePath":"conventions/versioni-di-pipeline.md","filePath":"conventions/versioni-di-pipeline.md"}'),t={name:"conventions/versioni-di-pipeline.md"};function s(l,e,c,r,d,p){return i(),a("div",null,[...e[0]||(e[0]=[n("",71)])])}const u=o(t,[["render",s]]);export{g as __pageData,u as default};
@@ -1,4 +1,4 @@
1
- import{_ as i,o,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Tipi di nodo","description":"","frontmatter":{"aside":false,"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/README.md","filePath":"nodes/README.md"}'),s={name:"nodes/README.md"};function d(n,e,r,l,c,p){return o(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="tipi-di-nodo" tabindex="-1">Tipi di nodo <a class="header-anchor" href="#tipi-di-nodo" aria-label="Permalink to &quot;Tipi di nodo&quot;">​</a></h1><p>Ogni processo è un grafo costruito col DSL <code>graph()…build()</code>, e ogni passaggio del grafo è un <strong>nodo</strong> di uno di questi undici tipi, più il nodo <a href="./pipeline"><code>pipeline</code></a>, che istanzia una sub-pipeline e alla costruzione diventa i nodi che contiene. Questa pagina è il <strong>cheatsheet</strong>: tutto quello che serve per scegliere il nodo giusto e scriverne la firma. Ogni tipo ha poi una scheda di dettaglio, con opzioni, errori ed esempi, che si apre con una breve demo animata del nodo al lavoro.</p><p>Codice in <code>src/core/</code> (<code>graph.ts</code> per i tipi, <code>graph-builder.ts</code> per il DSL, <code>graph-builder-options.ts</code> per le sue opzioni). Una pipeline importa tutto dalla radice del pacchetto, <code>@noeva/etl-core</code>; dentro il core lo si raggiunge dal barrel <code>src/core/index.ts</code>.</p><h2 id="indice" tabindex="-1">Indice <a class="header-anchor" href="#indice" aria-label="Permalink to &quot;Indice&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Nodo</th><th>Metodo</th><th>Cosa fa</th><th>Ingressi</th><th>Uscite</th><th>Dead-letter</th></tr></thead><tbody><tr><td><a href="./source"><code>source</code></a></td><td><code>.source(id, source)</code></td><td>Estrae da un sistema esterno, in streaming</td><td>0</td><td>≥1</td><td>no</td></tr><tr><td><a href="./transform"><code>transform</code></a></td><td><code>.transform(from, id, t, opts)</code></td><td>Trasforma record → record, <strong>puro</strong> (niente IO)</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./lookup"><code>lookup</code></a></td><td><code>.lookup(from, id, config, opts)</code></td><td>Legge <strong>in sola lettura</strong> da un DB o un&#39;API, a batch di chiavi</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./ai"><code>ai</code></a></td><td><code>.ai(from, id, config, opts)</code></td><td>Chiede a un <strong>modello</strong>, la risposta arricchisce il record</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./action"><code>action</code></a></td><td><code>.action(from, id, action, opts)</code></td><td><strong>Scrive</strong> per record e prosegue col risultato</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./route"><code>route</code></a></td><td><code>.route(from, id, { routes }, opts)</code></td><td>Manda ogni record su <strong>una sola</strong> porta con nome</td><td>1</td><td>≥1 per porta, <code>default</code> compresa</td><td>sì</td></tr><tr><td><a href="./join"><code>join</code></a></td><td><code>.join(id, { build, probe, … })</code></td><td>Accoppia due flussi <strong>per chiave</strong> (inner/left)</td><td>2 (<code>build</code> + <code>probe</code>)</td><td>≥1</td><td>sì (lato probe)</td></tr><tr><td><a href="./union"><code>union</code></a></td><td><code>.union(id, { from, order })</code></td><td>Mette in fila N flussi con la stessa forma, record invariati</td><td>≥2</td><td>≥1</td><td>no</td></tr><tr><td><a href="./try-catch"><code>try-catch</code></a></td><td><code>.tryCatch(from, id, opts)</code></td><td>Apre uno scope di gestione errori sui nodi a valle</td><td>1</td><td>≥1 su <code>out</code> + esattamente 1 su <code>catch</code></td><td>no</td></tr><tr><td><a href="./sink"><code>sink</code></a></td><td><code>.sink(from, sink, opts)</code></td><td>Carica su un sistema esterno, in modo idempotente</td><td>1</td><td>0</td><td>no</td></tr><tr><td><a href="./task"><code>task</code></a></td><td><code>.task(id, task, opts)</code></td><td>Esegue un&#39;operazione <strong>senza record</strong> (truncate, scambio)</td><td>0 (solo <code>after</code>)</td><td>0</td><td>no</td></tr><tr><td><a href="./pipeline"><code>pipeline</code></a></td><td><code>.pipeline(from, id, sub, opts)</code></td><td>Istanzia una <strong>sub-pipeline</strong>, appiattita alla costruzione</td><td>1</td><td>≥1 per uscita della sub-pipeline</td><td>sì, solo root</td></tr></tbody></table><h2 id="quale-nodo-mi-serve" tabindex="-1">Quale nodo mi serve? <a class="header-anchor" href="#quale-nodo-mi-serve" aria-label="Permalink to &quot;Quale nodo mi serve?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Devo…</th><th>Nodo</th></tr></thead><tbody><tr><td>leggere dati da un DB, un file, una casella di posta, un workspace Noeva</td><td><a href="./source"><code>source</code></a></td></tr><tr><td>validare, mappare, filtrare, aggregare</td><td><a href="./transform"><code>transform</code></a></td></tr><tr><td>tenere, rinominare, convertire o calcolare colonne</td><td><a href="./transform#mappare-le-colonne-mapcolumns"><code>transform</code></a> con <code>mapColumns</code></td></tr><tr><td>espandere un record in N (righe d&#39;ordine, elementi di un array)</td><td><a href="./transform#espansione"><code>transform</code></a></td></tr><tr><td>passare da colonne a righe e viceversa (<code>mese_01</code>…<code>mese_12</code> ↔ <code>mese</code>/<code>valore</code>)</td><td><a href="./transform#largo-e-lungo-unpivot-e-pivot"><code>transform</code></a> con <code>unpivot</code> e <code>pivot</code></td></tr><tr><td>ordinare i record (un file per un cliente, un report)</td><td><a href="./transform#ordinamento"><code>transform</code></a> con <code>sort</code></td></tr><tr><td>mandare i record a un sink o a un&#39;API in lotti di N</td><td><a href="./transform#lotti"><code>transform</code></a> con <code>chunk</code></td></tr><tr><td>decodificare i byte di un file arrivati da un&#39;altra source (CSV, JSON, XLSX…)</td><td><a href="./transform#file-parse-e-serialize"><code>transform</code></a> con <code>parse</code></td></tr><tr><td>comporre file dai record (uno per gruppo) per un sink che vuole i byte</td><td><a href="./transform#file-parse-e-serialize"><code>transform</code></a> con <code>serialize</code></td></tr><tr><td>rilevare le righe cambiate senza CDC (hash delle colonne tracciate)</td><td><a href="./transform#hash-di-riga-e-chiave-surrogata"><code>transform</code></a> con <code>hashRow</code></td></tr><tr><td>dare a una dimensione chiavi surrogate stabili fra le run</td><td><a href="./transform#hash-di-riga-e-chiave-surrogata"><code>transform</code></a> con <code>surrogateKey</code></td></tr><tr><td>mascherare o pseudonimizzare colonne con dati personali prima di un sink</td><td><a href="./transform#mascheramento-e-pseudonimizzazione"><code>transform</code></a> con <code>mask</code></td></tr><tr><td>vedere nel report null, estremi e distinti di ogni colonna</td><td><a href="./transform#profilo-delle-colonne"><code>transform</code></a> con <code>profile</code></td></tr><tr><td>vedere nel report che cosa un nodo ha fatto a ogni record</td><td><code>recordReport</code> su <a href="./lookup#righe-per-record-recordreport"><code>lookup</code></a>, <code>ai</code>, <code>action</code></td></tr><tr><td>fermare un caricamento se il dataset è vuoto, pieno di null o con duplicati</td><td><a href="./transform#controlli-sul-dataset-assert"><code>transform</code></a> con <code>assert</code></td></tr><tr><td>arricchire ogni record con dati di un DB o di un&#39;API (grande, selettivo)</td><td><a href="./lookup"><code>lookup</code></a></td></tr><tr><td>ricavare un dato che nessuna query sa dare: estrarre, classificare</td><td><a href="./ai"><code>ai</code></a></td></tr><tr><td>arricchire con un secondo flusso che sta in memoria</td><td><a href="./join"><code>join</code></a></td></tr><tr><td>scrivere a metà grafo e usare il risultato (un id, un esito)</td><td><a href="./action"><code>action</code></a></td></tr><tr><td>fare più scritture in ordine sullo stesso record</td><td>più <a href="./action"><code>action</code></a> in catena</td></tr><tr><td>mandare ogni record su un ramo diverso secondo una condizione</td><td><a href="./route"><code>route</code></a></td></tr><tr><td>mandare <strong>lo stesso</strong> record a più rami</td><td>nessun nodo: fan-out, più nodi con lo stesso <code>from</code></td></tr><tr><td>riunire N flussi con lo stesso tracciato (N workspace, N file)</td><td><a href="./union"><code>union</code></a></td></tr><tr><td>non fermare la run per un record che fallisce in un solo nodo</td><td><code>deadLetter</code> sul nodo</td></tr><tr><td>gestire gli errori di un tratto di grafo, e decidere dove vanno i record</td><td><a href="./try-catch"><code>try-catch</code></a></td></tr><tr><td>scrivere il risultato finale</td><td><a href="./sink"><code>sink</code></a></td></tr><tr><td>conservare la storia di una dimensione (SCD tipo 2)</td><td><a href="./sink#scd2"><code>sink</code></a> con <code>mode: &quot;scd2&quot;</code></td></tr><tr><td>svuotare uno staging prima di caricare, scambiare le tabelle dopo</td><td><a href="./task"><code>task</code></a> con <code>after</code></td></tr><tr><td>caricare un ramo prima di un altro (le dimensioni prima dei fatti)</td><td><code>after</code> sulla source del secondo ramo: <a href="./task#edge-di-controllo-after"><code>task</code></a></td></tr><tr><td>riusare un pezzo di grafo, con un contratto d&#39;ingresso e d&#39;uscita</td><td><a href="./pipeline"><code>pipeline</code></a>, che istanzia una sub-pipeline</td></tr></tbody></table><p>Scelte che si confondono spesso:</p><ul><li><strong><code>lookup</code> o <code>join</code>?</strong> Il <code>join</code> tiene in memoria tutto il lato <code>build</code>: va bene se è piccolo. Il <code>lookup</code> interroga solo le chiavi che servono: è la scelta quando il lato di destra è grande, o quando un record porta più chiavi candidate.</li><li><strong><code>action</code> o <code>sink</code>?</strong> Se la scrittura è l&#39;ultima cosa che succede al record, è un <code>sink</code>. Se a valle serve il suo risultato, è un&#39;<code>action</code>. Se è una lettura, è un <code>lookup</code>.</li><li><strong><code>route</code> o fan-out?</strong> Il fan-out manda lo stesso record a tutti i rami; il <code>route</code> lo manda a uno solo. Più <code>filterTransform</code> al posto di un <code>route</code> valutano il predicato N volte, non garantiscono rami esclusivi e perdono i record che non passano nessun filtro.</li><li><strong><code>union</code> o <code>join</code>?</strong> Il <code>join</code> accoppia due record per chiave; il <code>union</code> mette in fila i record così come sono.</li><li><strong><code>task</code>, <code>action</code> o <code>sink</code>?</strong> Un <code>task</code> non vede record: gira una volta per run, quando i nodi in <code>after</code> sono riusciti. Se l&#39;operazione riguarda ogni record è un <code>action</code> o un <code>sink</code>.</li></ul><h2 id="firme-del-builder" tabindex="-1">Firme del builder <a class="header-anchor" href="#firme-del-builder" aria-label="Permalink to &quot;Firme del builder&quot;">​</a></h2><p>Ogni metodo restituisce un <strong>nuovo</strong> builder: si concatena. <code>build()</code> valida la forma e lancia <code>GraphValidationError</code> al primo problema.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(name, { recordIds?, commitOn?, runParams? }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// runParams: parametri di lancio</span></span>
1
+ import{_ as i,o,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Tipi di nodo","description":"","frontmatter":{"aside":false,"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/README.md","filePath":"nodes/README.md"}'),s={name:"nodes/README.md"};function n(d,e,r,l,c,p){return o(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="tipi-di-nodo" tabindex="-1">Tipi di nodo <a class="header-anchor" href="#tipi-di-nodo" aria-label="Permalink to &quot;Tipi di nodo&quot;">​</a></h1><p>Ogni processo è un grafo costruito col DSL <code>graph()…build()</code>, e ogni passaggio del grafo è un <strong>nodo</strong> di uno di questi undici tipi, più il nodo <a href="./pipeline"><code>pipeline</code></a>, che istanzia una sub-pipeline e alla costruzione diventa i nodi che contiene. Questa pagina è il <strong>cheatsheet</strong>: tutto quello che serve per scegliere il nodo giusto e scriverne la firma. Ogni tipo ha poi una scheda di dettaglio, con opzioni, errori ed esempi, che si apre con una breve demo animata del nodo al lavoro.</p><p>Codice in <code>src/core/</code> (<code>graph.ts</code> per i tipi, <code>graph-builder.ts</code> per il DSL, <code>graph-builder-options.ts</code> per le sue opzioni). Una pipeline importa tutto dalla radice del pacchetto, <code>@noeva/etl-core</code>; dentro il core lo si raggiunge dal barrel <code>src/core/index.ts</code>.</p><h2 id="indice" tabindex="-1">Indice <a class="header-anchor" href="#indice" aria-label="Permalink to &quot;Indice&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Nodo</th><th>Metodo</th><th>Cosa fa</th><th>Ingressi</th><th>Uscite</th><th>Dead-letter</th></tr></thead><tbody><tr><td><a href="./source"><code>source</code></a></td><td><code>.source(id, source)</code></td><td>Estrae da un sistema esterno, in streaming</td><td>0</td><td>≥1</td><td>no</td></tr><tr><td><a href="./transform"><code>transform</code></a></td><td><code>.transform(from, id, t, opts)</code></td><td>Trasforma record → record, <strong>puro</strong> (niente IO)</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./lookup"><code>lookup</code></a></td><td><code>.lookup(from, id, config, opts)</code></td><td>Legge <strong>in sola lettura</strong> da un DB o un&#39;API, a batch di chiavi</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./ai"><code>ai</code></a></td><td><code>.ai(from, id, config, opts)</code></td><td>Chiede a un <strong>modello</strong>, la risposta arricchisce il record</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./action"><code>action</code></a></td><td><code>.action(from, id, action, opts)</code></td><td><strong>Scrive</strong> per record e prosegue col risultato</td><td>1</td><td>≥1</td><td>sì</td></tr><tr><td><a href="./route"><code>route</code></a></td><td><code>.route(from, id, { routes }, opts)</code></td><td>Manda ogni record su <strong>una sola</strong> porta con nome</td><td>1</td><td>≥1 per porta, <code>default</code> compresa</td><td>sì</td></tr><tr><td><a href="./join"><code>join</code></a></td><td><code>.join(id, { build, probe, … })</code></td><td>Accoppia due flussi <strong>per chiave</strong> (inner/left)</td><td>2 (<code>build</code> + <code>probe</code>)</td><td>≥1</td><td>sì (lato probe)</td></tr><tr><td><a href="./union"><code>union</code></a></td><td><code>.union(id, { from, order })</code></td><td>Mette in fila N flussi con la stessa forma, record invariati</td><td>≥2</td><td>≥1</td><td>no</td></tr><tr><td><a href="./try-catch"><code>try-catch</code></a></td><td><code>.tryCatch(from, id, opts)</code></td><td>Apre uno scope di gestione errori sui nodi a valle</td><td>1</td><td>≥1 su <code>out</code> + esattamente 1 su <code>catch</code></td><td>no</td></tr><tr><td><a href="./sink"><code>sink</code></a></td><td><code>.sink(from, sink, opts)</code></td><td>Carica su un sistema esterno, in modo idempotente</td><td>1</td><td>0</td><td>no</td></tr><tr><td><a href="./task"><code>task</code></a></td><td><code>.task(id, task, opts)</code></td><td>Esegue un&#39;operazione <strong>senza record</strong> (truncate, scambio, operazioni su fogli e colonne Excel)</td><td>0 (solo <code>after</code>)</td><td>0</td><td>no</td></tr><tr><td><a href="./pipeline"><code>pipeline</code></a></td><td><code>.pipeline(from, id, sub, opts)</code></td><td>Istanzia una <strong>sub-pipeline</strong>, appiattita alla costruzione</td><td>1</td><td>≥1 per uscita della sub-pipeline</td><td>sì, solo root</td></tr></tbody></table><h2 id="quale-nodo-mi-serve" tabindex="-1">Quale nodo mi serve? <a class="header-anchor" href="#quale-nodo-mi-serve" aria-label="Permalink to &quot;Quale nodo mi serve?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Devo…</th><th>Nodo</th></tr></thead><tbody><tr><td>leggere dati da un DB, un file, una casella di posta, un workspace Noeva</td><td><a href="./source"><code>source</code></a></td></tr><tr><td>validare, mappare, filtrare, aggregare</td><td><a href="./transform"><code>transform</code></a></td></tr><tr><td>tenere, rinominare, convertire o calcolare colonne</td><td><a href="./transform#mappare-le-colonne-mapcolumns"><code>transform</code></a> con <code>mapColumns</code></td></tr><tr><td>espandere un record in N (righe d&#39;ordine, elementi di un array)</td><td><a href="./transform#espansione"><code>transform</code></a></td></tr><tr><td>passare da colonne a righe e viceversa (<code>mese_01</code>…<code>mese_12</code> ↔ <code>mese</code>/<code>valore</code>)</td><td><a href="./transform#largo-e-lungo-unpivot-e-pivot"><code>transform</code></a> con <code>unpivot</code> e <code>pivot</code></td></tr><tr><td>ordinare i record (un file per un cliente, un report)</td><td><a href="./transform#ordinamento"><code>transform</code></a> con <code>sort</code></td></tr><tr><td>mandare i record a un sink o a un&#39;API in lotti di N</td><td><a href="./transform#lotti"><code>transform</code></a> con <code>chunk</code></td></tr><tr><td>decodificare i byte di un file arrivati da un&#39;altra source (CSV, JSON, XLSX…)</td><td><a href="./transform#file-parse-e-serialize"><code>transform</code></a> con <code>parse</code></td></tr><tr><td>comporre file dai record (uno per gruppo) per un sink che vuole i byte</td><td><a href="./transform#file-parse-e-serialize"><code>transform</code></a> con <code>serialize</code></td></tr><tr><td>rilevare le righe cambiate senza CDC (hash delle colonne tracciate)</td><td><a href="./transform#hash-di-riga-e-chiave-surrogata"><code>transform</code></a> con <code>hashRow</code></td></tr><tr><td>dare a una dimensione chiavi surrogate stabili fra le run</td><td><a href="./transform#hash-di-riga-e-chiave-surrogata"><code>transform</code></a> con <code>surrogateKey</code></td></tr><tr><td>mascherare o pseudonimizzare colonne con dati personali prima di un sink</td><td><a href="./transform#mascheramento-e-pseudonimizzazione"><code>transform</code></a> con <code>mask</code></td></tr><tr><td>vedere nel report null, estremi e distinti di ogni colonna</td><td><a href="./transform#profilo-delle-colonne"><code>transform</code></a> con <code>profile</code></td></tr><tr><td>vedere nel report che cosa un nodo ha fatto a ogni record</td><td><code>recordReport</code> su <a href="./lookup#righe-per-record-recordreport"><code>lookup</code></a>, <code>ai</code>, <code>action</code></td></tr><tr><td>fermare un caricamento se il dataset è vuoto, pieno di null o con duplicati</td><td><a href="./transform#controlli-sul-dataset-assert"><code>transform</code></a> con <code>assert</code></td></tr><tr><td>arricchire ogni record con dati di un DB o di un&#39;API (grande, selettivo)</td><td><a href="./lookup"><code>lookup</code></a></td></tr><tr><td>ricavare un dato che nessuna query sa dare: estrarre, classificare</td><td><a href="./ai"><code>ai</code></a></td></tr><tr><td>arricchire con un secondo flusso che sta in memoria</td><td><a href="./join"><code>join</code></a></td></tr><tr><td>scrivere a metà grafo e usare il risultato (un id, un esito)</td><td><a href="./action"><code>action</code></a></td></tr><tr><td>fare più scritture in ordine sullo stesso record</td><td>più <a href="./action"><code>action</code></a> in catena</td></tr><tr><td>mandare ogni record su un ramo diverso secondo una condizione</td><td><a href="./route"><code>route</code></a></td></tr><tr><td>mandare <strong>lo stesso</strong> record a più rami</td><td>nessun nodo: fan-out, più nodi con lo stesso <code>from</code></td></tr><tr><td>riunire N flussi con lo stesso tracciato (N workspace, N file)</td><td><a href="./union"><code>union</code></a></td></tr><tr><td>non fermare la run per un record che fallisce in un solo nodo</td><td><code>deadLetter</code> sul nodo</td></tr><tr><td>gestire gli errori di un tratto di grafo, e decidere dove vanno i record</td><td><a href="./try-catch"><code>try-catch</code></a></td></tr><tr><td>scrivere il risultato finale</td><td><a href="./sink"><code>sink</code></a></td></tr><tr><td>conservare la storia di una dimensione (SCD tipo 2)</td><td><a href="./sink#scd2"><code>sink</code></a> con <code>mode: &quot;scd2&quot;</code></td></tr><tr><td>svuotare uno staging prima di caricare, scambiare le tabelle dopo</td><td><a href="./task"><code>task</code></a> con <code>after</code></td></tr><tr><td>caricare un ramo prima di un altro (le dimensioni prima dei fatti)</td><td><code>after</code> sulla source del secondo ramo: <a href="./task#edge-di-controllo-after"><code>task</code></a></td></tr><tr><td>riusare un pezzo di grafo, con un contratto d&#39;ingresso e d&#39;uscita</td><td><a href="./pipeline"><code>pipeline</code></a>, che istanzia una sub-pipeline</td></tr></tbody></table><p>Scelte che si confondono spesso:</p><ul><li><strong><code>lookup</code> o <code>join</code>?</strong> Il <code>join</code> tiene in memoria tutto il lato <code>build</code>: va bene se è piccolo. Il <code>lookup</code> interroga solo le chiavi che servono: è la scelta quando il lato di destra è grande, o quando un record porta più chiavi candidate.</li><li><strong><code>action</code> o <code>sink</code>?</strong> Se la scrittura è l&#39;ultima cosa che succede al record, è un <code>sink</code>. Se a valle serve il suo risultato, è un&#39;<code>action</code>. Se è una lettura, è un <code>lookup</code>.</li><li><strong><code>route</code> o fan-out?</strong> Il fan-out manda lo stesso record a tutti i rami; il <code>route</code> lo manda a uno solo. Più <code>filterTransform</code> al posto di un <code>route</code> valutano il predicato N volte, non garantiscono rami esclusivi e perdono i record che non passano nessun filtro.</li><li><strong><code>union</code> o <code>join</code>?</strong> Il <code>join</code> accoppia due record per chiave; il <code>union</code> mette in fila i record così come sono.</li><li><strong><code>task</code>, <code>action</code> o <code>sink</code>?</strong> Un <code>task</code> non vede record: gira una volta per run, quando i nodi in <code>after</code> sono riusciti. Se l&#39;operazione riguarda ogni record è un <code>action</code> o un <code>sink</code>.</li></ul><h2 id="firme-del-builder" tabindex="-1">Firme del builder <a class="header-anchor" href="#firme-del-builder" aria-label="Permalink to &quot;Firme del builder&quot;">​</a></h2><p>Ogni metodo restituisce un <strong>nuovo</strong> builder: si concatena. <code>build()</code> valida la forma e lancia <code>GraphValidationError</code> al primo problema.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(name, { recordIds?, commitOn?, runParams? }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// runParams: parametri di lancio</span></span>
2
2
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(id, source, { after?, purpose?, writeReport? })</span></span>
3
3
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(from, id, transform, { deadLetter?, fromPort?, purpose?, statefulLineage?, writeReport? })</span></span>
4
4
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lookup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(from, id,</span></span>
@@ -48,4 +48,4 @@ import{_ as i,o,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON
48
48
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> )</span></span>
49
49
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;contratto-fatto&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sinks.fatti)</span></span>
50
50
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
51
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Un nodo per passaggio: il DAG mostrato nell&#39;app è quello eseguito, e deve dire dove un record si è fermato. Per vederli tutti insieme in un grafo interattivo: <a href="./../guide/grafo">Il grafo, nodo per nodo</a>.</p>`,34)])])}const u=i(s,[["render",d]]);export{k as __pageData,u as default};
51
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Un nodo per passaggio: il DAG mostrato nell&#39;app è quello eseguito, e deve dire dove un record si è fermato. Per vederli tutti insieme in un grafo interattivo: <a href="./../guide/grafo">Il grafo, nodo per nodo</a>.</p>`,34)])])}const u=i(s,[["render",n]]);export{k as __pageData,u as default};
@@ -1 +1 @@
1
- import{_ as i,o,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Tipi di nodo","description":"","frontmatter":{"aside":false,"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/README.md","filePath":"nodes/README.md"}'),s={name:"nodes/README.md"};function d(n,e,r,l,c,p){return o(),a("div",null,[...e[0]||(e[0]=[t("",34)])])}const u=i(s,[["render",d]]);export{k as __pageData,u as default};
1
+ import{_ as i,o,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Tipi di nodo","description":"","frontmatter":{"aside":false,"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/README.md","filePath":"nodes/README.md"}'),s={name:"nodes/README.md"};function n(d,e,r,l,c,p){return o(),a("div",null,[...e[0]||(e[0]=[t("",34)])])}const u=i(s,[["render",n]]);export{k as __pageData,u as default};
@@ -1,4 +1,4 @@
1
- import{_ as a,C as o,o as n,c as r,j as e,a as s,E as d,a5 as l}from"./chunks/framework.qdetmeNX.js";const F=JSON.parse('{"title":"Nodo: lookup","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/lookup.md","filePath":"nodes/lookup.md"}'),h={name:"nodes/lookup.md"};function p(c,i,k,E,u,g){const t=o("NodeDemo");return n(),r("div",null,[i[0]||(i[0]=e("h1",{id:"nodo-lookup",tabindex:"-1"},[s("Nodo: lookup "),e("a",{class:"header-anchor",href:"#nodo-lookup","aria-label":'Permalink to "Nodo: lookup"'},"​")],-1)),i[1]||(i[1]=e("p",null,[s("Arricchisce ogni record leggendo da un sistema esterno — un database o un'API REST — "),e("strong",null,"in sola lettura"),s(" e a batch di chiavi. La query è configurazione del nodo, non una closure: l'accesso al sistema esterno resta visibile nel DAG e in review.")],-1)),d(t,{kind:"lookup"}),i[2]||(i[2]=l(`<table tabindex="0"><thead><tr><th>Metodo</th><th><code>.lookup(from, id, config, { deadLetter?, fromPort?, purpose?, recordReport?, writeReport? })</code></th></tr></thead><tbody><tr><td>Ingressi</td><td>1</td></tr><tr><td>Uscite</td><td>≥1 (fan-out libero)</td></tr><tr><td>Dead-letter</td><td>sì, per record</td></tr><tr><td>Codice</td><td><code>src/core/lookup.ts</code>; resolver nei connettori</td></tr></tbody></table><h2 id="quando-usarlo" tabindex="-1">Quando usarlo <a class="header-anchor" href="#quando-usarlo" aria-label="Permalink to &quot;Quando usarlo&quot;">​</a></h2><ul><li>Il lato di destra è <strong>grande</strong> e serve solo per le chiavi presenti nel flusso.</li><li>Un record porta <strong>più chiavi</strong> candidate, da provare in ordine.</li><li>I dati stanno dietro un&#39;API, non in un flusso che si possa leggere per intero.</li></ul><p>Se il lato di destra è piccolo e si legge tutto, un <a href="./join"><code>join</code></a> fra due source è più semplice. Se l&#39;operazione <strong>scrive</strong>, è un&#39;<a href="./action"><code>action</code></a>; se la risposta la dà un <strong>modello</strong> — <code>noevaAiExtract</code> — è un nodo <a href="./ai"><code>ai</code></a>, che ha la stessa configurazione ma lo dichiara nel DAG.</p><h2 id="la-configurazione" tabindex="-1">La configurazione <a class="header-anchor" href="#la-configurazione" aria-label="Permalink to &quot;La configurazione&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Campo</th><th>Default</th><th>Effetto</th></tr></thead><tbody><tr><td><code>resolver</code></td><td>—</td><td>Il <code>LookupResolver</code>: risolve un batch di chiavi in un round-trip. Porta il <code>descriptor</code> del DAG</td></tr><tr><td><code>key</code></td><td>—</td><td><code>(record) =&gt; chiave</code> o un array di chiavi; <code>null</code>, <code>undefined</code>, <code>&quot;&quot;</code> o <code>[]</code> = nessuna query</td></tr><tr><td><code>merge</code></td><td>—</td><td><code>(rows, record) =&gt; output</code>: combina le righe trovate col record</td></tr><tr><td><code>onNotFound</code></td><td><code>&quot;null&quot;</code></td><td><code>&quot;null&quot;</code>: il record passa con zero righe, come un left join. <code>&quot;error&quot;</code>: <code>LookupError</code></td></tr><tr><td><code>batchSize</code></td><td><code>200</code></td><td>Chiavi per round-trip</td></tr><tr><td><code>cache</code></td><td><code>true</code></td><td>Tiene i risultati per la durata della run</td></tr><tr><td><code>maxCacheEntries</code></td><td><code>50000</code></td><td>Oltre, la cache smette di crescere</td></tr><tr><td><code>outputSchema</code></td><td>—</td><td>Colonne del nodo nel DAG (non valida i record)</td></tr><tr><td><code>retry</code></td><td>—</td><td><code>{ attempts, baseMs?, maxMs?, jitter? }</code>: ritenta il round-trip sugli errori transitori</td></tr><tr><td><code>rateLimit</code></td><td>—</td><td><code>{ perSecond }</code>: distanzia i round-trip</td></tr></tbody></table><p>Con più chiavi per record, le righe arrivano concatenate <strong>nell&#39;ordine delle chiavi</strong>: a valle si può scegliere per rango.</p><h2 id="resolver-pronti" tabindex="-1">Resolver pronti <a class="header-anchor" href="#resolver-pronti" aria-label="Permalink to &quot;Resolver pronti&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Resolver</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresLookup</code></td><td>PostgreSQL</td><td><a href="./../connectors/postgres#lookup--postgreslookup">postgres § Lookup</a></td></tr><tr><td><code>mssqlLookup</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver#lookup--mssqllookup">sqlserver § Lookup</a></td></tr><tr><td><code>httpLookup</code></td><td>API REST (<code>batch</code> o <code>per-key</code>)</td><td><a href="./../connectors/http">http</a></td></tr><tr><td><code>jiraIssueLookup</code></td><td>Jira Cloud (issue per chiave)</td><td><a href="./../connectors/jira#jiraissuelookup--le-issue-per-chiave">jira</a></td></tr><tr><td><code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code>, <code>jiraWorklogsLookup</code></td><td>Jira Cloud (liste di una issue)</td><td><a href="./../connectors/jira#le-liste-di-una-issue--changelog-commenti-e-worklog">jira</a></td></tr><tr><td><code>noevaElaborazioneLookup</code>, <code>noevaContenutoLookup</code></td><td>Stato e testo di un file Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr></tbody></table><p>I resolver SQL condividono la stessa query, col segnaposto <code>@chiavi</code>, e rifiutano a <code>build()</code> tutto ciò che non sia una singola <code>SELECT</code>/<code>WITH</code>. Con <code>keysAs: &quot;rows&quot;</code> le chiavi entrano come tabella (<code>FROM @chiavi AS k(chiave) JOIN …</code>), per i confronti che non sono un&#39;uguaglianza.</p><h2 id="esempi" tabindex="-1">Esempi <a class="header-anchor" href="#esempi" aria-label="Permalink to &quot;Esempi&quot;">​</a></h2><p>Da un database:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lookup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Riga</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">RigaConCliente</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;righe&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cliente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
1
+ import{_ as a,C as o,o as n,c as r,j as e,a as s,E as d,a5 as l}from"./chunks/framework.qdetmeNX.js";const F=JSON.parse('{"title":"Nodo: lookup","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/lookup.md","filePath":"nodes/lookup.md"}'),h={name:"nodes/lookup.md"};function p(c,i,k,E,u,g){const t=o("NodeDemo");return n(),r("div",null,[i[0]||(i[0]=e("h1",{id:"nodo-lookup",tabindex:"-1"},[s("Nodo: lookup "),e("a",{class:"header-anchor",href:"#nodo-lookup","aria-label":'Permalink to "Nodo: lookup"'},"​")],-1)),i[1]||(i[1]=e("p",null,[s("Arricchisce ogni record leggendo da un sistema esterno — un database o un'API REST — "),e("strong",null,"in sola lettura"),s(" e a batch di chiavi. La query è configurazione del nodo, non una closure: l'accesso al sistema esterno resta visibile nel DAG e in review.")],-1)),d(t,{kind:"lookup"}),i[2]||(i[2]=l(`<table tabindex="0"><thead><tr><th>Metodo</th><th><code>.lookup(from, id, config, { deadLetter?, fromPort?, purpose?, recordReport?, writeReport? })</code></th></tr></thead><tbody><tr><td>Ingressi</td><td>1</td></tr><tr><td>Uscite</td><td>≥1 (fan-out libero)</td></tr><tr><td>Dead-letter</td><td>sì, per record</td></tr><tr><td>Codice</td><td><code>src/core/lookup.ts</code>; resolver nei connettori</td></tr></tbody></table><h2 id="quando-usarlo" tabindex="-1">Quando usarlo <a class="header-anchor" href="#quando-usarlo" aria-label="Permalink to &quot;Quando usarlo&quot;">​</a></h2><ul><li>Il lato di destra è <strong>grande</strong> e serve solo per le chiavi presenti nel flusso.</li><li>Un record porta <strong>più chiavi</strong> candidate, da provare in ordine.</li><li>I dati stanno dietro un&#39;API, non in un flusso che si possa leggere per intero.</li></ul><p>Se il lato di destra è piccolo e si legge tutto, un <a href="./join"><code>join</code></a> fra due source è più semplice. Se l&#39;operazione <strong>scrive</strong>, è un&#39;<a href="./action"><code>action</code></a>; se la risposta la dà un <strong>modello</strong> — <code>noevaAiExtract</code> — è un nodo <a href="./ai"><code>ai</code></a>, che ha la stessa configurazione ma lo dichiara nel DAG.</p><h2 id="la-configurazione" tabindex="-1">La configurazione <a class="header-anchor" href="#la-configurazione" aria-label="Permalink to &quot;La configurazione&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Campo</th><th>Default</th><th>Effetto</th></tr></thead><tbody><tr><td><code>resolver</code></td><td>—</td><td>Il <code>LookupResolver</code>: risolve un batch di chiavi in un round-trip. Porta il <code>descriptor</code> del DAG</td></tr><tr><td><code>key</code></td><td>—</td><td><code>(record) =&gt; chiave</code> o un array di chiavi; <code>null</code>, <code>undefined</code>, <code>&quot;&quot;</code> o <code>[]</code> = nessuna query</td></tr><tr><td><code>merge</code></td><td>—</td><td><code>(rows, record) =&gt; output</code>: combina le righe trovate col record</td></tr><tr><td><code>onNotFound</code></td><td><code>&quot;null&quot;</code></td><td><code>&quot;null&quot;</code>: il record passa con zero righe, come un left join. <code>&quot;error&quot;</code>: <code>LookupError</code></td></tr><tr><td><code>batchSize</code></td><td><code>200</code></td><td>Chiavi per round-trip</td></tr><tr><td><code>cache</code></td><td><code>true</code></td><td>Tiene i risultati per la durata della run</td></tr><tr><td><code>maxCacheEntries</code></td><td><code>50000</code></td><td>Oltre, la cache smette di crescere</td></tr><tr><td><code>outputSchema</code></td><td>—</td><td>Colonne del nodo nel DAG (non valida i record)</td></tr><tr><td><code>retry</code></td><td>—</td><td><code>{ attempts, baseMs?, maxMs?, jitter? }</code>: ritenta il round-trip sugli errori transitori</td></tr><tr><td><code>rateLimit</code></td><td>—</td><td><code>{ perSecond }</code>: distanzia i round-trip</td></tr></tbody></table><p>Con più chiavi per record, le righe arrivano concatenate <strong>nell&#39;ordine delle chiavi</strong>: a valle si può scegliere per rango.</p><h2 id="resolver-pronti" tabindex="-1">Resolver pronti <a class="header-anchor" href="#resolver-pronti" aria-label="Permalink to &quot;Resolver pronti&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Resolver</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresLookup</code></td><td>PostgreSQL</td><td><a href="./../connectors/postgres#lookup--postgreslookup">postgres § Lookup</a></td></tr><tr><td><code>mssqlLookup</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver#lookup--mssqllookup">sqlserver § Lookup</a></td></tr><tr><td><code>mysqlLookup</code></td><td>MySQL, MariaDB</td><td><a href="./../connectors/mysql#lookup--mysqllookup">mysql § Lookup</a></td></tr><tr><td><code>httpLookup</code></td><td>API REST (<code>batch</code> o <code>per-key</code>)</td><td><a href="./../connectors/http">http</a></td></tr><tr><td><code>jiraIssueLookup</code></td><td>Jira Cloud (issue per chiave)</td><td><a href="./../connectors/jira#jiraissuelookup--le-issue-per-chiave">jira</a></td></tr><tr><td><code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code>, <code>jiraWorklogsLookup</code></td><td>Jira Cloud (liste di una issue)</td><td><a href="./../connectors/jira#le-liste-di-una-issue--changelog-commenti-e-worklog">jira</a></td></tr><tr><td><code>noevaElaborazioneLookup</code>, <code>noevaContenutoLookup</code></td><td>Stato e testo di un file Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr></tbody></table><p>I resolver SQL condividono la stessa query, col segnaposto <code>@chiavi</code>, e rifiutano a <code>build()</code> tutto ciò che non sia una singola <code>SELECT</code>/<code>WITH</code>. Con <code>keysAs: &quot;rows&quot;</code> le chiavi entrano come tabella (<code>FROM @chiavi AS k(chiave) JOIN …</code>), per i confronti che non sono un&#39;uguaglianza.</p><h2 id="esempi" tabindex="-1">Esempi <a class="header-anchor" href="#esempi" aria-label="Permalink to &quot;Esempi&quot;">​</a></h2><p>Da un database:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lookup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Riga</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">RigaConCliente</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;righe&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cliente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
2
2
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> resolver: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mssqlLookup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
3
3
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pool,</span></span>
4
4
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> instanceId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;dwh&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -18,7 +18,7 @@ import{_ as t,C as n,o,c as l,j as s,a,E as r,a5 as d}from"./chunks/framework.qd
18
18
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> held</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> RunContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// righe nel batch non ancora scritte</span></span>
19
19
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> descriptor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDescriptor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
20
20
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> columns</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> PlanColumn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
21
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="sink-pronti" tabindex="-1">Sink pronti <a class="header-anchor" href="#sink-pronti" aria-label="Permalink to &quot;Sink pronti&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th><code>retrySafe</code></th><th><code>loadOne</code></th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSink</code></td><td>PostgreSQL, upsert <code>ON CONFLICT</code></td><td>✅</td><td>—</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>postgresSink</code> con <code>mode: &quot;scd2&quot;</code></td><td>PostgreSQL, dimensione storicizzata</td><td>✅</td><td>—</td><td><a href="./../connectors/postgres#scd2">postgres</a></td></tr><tr><td><code>mssqlSink</code></td><td>SQL Server, <code>MERGE</code></td><td>✅</td><td>—</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>mssqlSink</code> con <code>mode: &quot;scd2&quot;</code></td><td>SQL Server, dimensione storicizzata</td><td>✅</td><td>—</td><td><a href="./../connectors/sqlserver#scd2">sqlserver</a></td></tr><tr><td><code>fileSink</code></td><td>File (storage × codec)</td><td>—</td><td>—</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>noevaFileSink</code>, <code>noevaFilesSink</code></td><td>Workspace Noeva</td><td>—</td><td><code>noevaFilesSink</code></td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>smtpSink</code></td><td>Una mail per record</td><td>—</td><td>✅</td><td><a href="./../connectors/smtp">smtp</a></td></tr><tr><td><code>mailSink</code></td><td><code>smtpSink</code> o <code>sendgridSink</code>, dalla configurazione</td><td>—</td><td>✅</td><td><a href="./../connectors/sendgrid">sendgrid</a></td></tr><tr><td><code>sendgridSink</code></td><td>Una mail per record via SendGrid</td><td>—</td><td>✅</td><td><a href="./../connectors/sendgrid">sendgrid</a></td></tr><tr><td><code>arraySink(name)</code></td><td>In memoria: test</td><td>—</td><td>✅</td><td>—</td></tr></tbody></table><h2 id="esempi" tabindex="-1">Esempi <a class="header-anchor" href="#esempi" aria-label="Permalink to &quot;Esempi&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;contratto-fatto&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sinks.fatti)</span></span>
21
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="sink-pronti" tabindex="-1">Sink pronti <a class="header-anchor" href="#sink-pronti" aria-label="Permalink to &quot;Sink pronti&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th><code>retrySafe</code></th><th><code>loadOne</code></th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSink</code></td><td>PostgreSQL, upsert <code>ON CONFLICT</code></td><td>✅</td><td>—</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>postgresSink</code> con <code>mode: &quot;scd2&quot;</code></td><td>PostgreSQL, dimensione storicizzata</td><td>✅</td><td>—</td><td><a href="./../connectors/postgres#scd2">postgres</a></td></tr><tr><td><code>mssqlSink</code></td><td>SQL Server, <code>MERGE</code></td><td>✅</td><td>—</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>mysqlSink</code></td><td>MySQL, MariaDB, <code>ON DUPLICATE KEY UPDATE</code></td><td>✅</td><td>—</td><td><a href="./../connectors/mysql">mysql</a></td></tr><tr><td><code>mssqlSink</code> con <code>mode: &quot;scd2&quot;</code></td><td>SQL Server, dimensione storicizzata</td><td>✅</td><td>—</td><td><a href="./../connectors/sqlserver#scd2">sqlserver</a></td></tr><tr><td><code>fileSink</code></td><td>File (storage × codec)</td><td>—</td><td>—</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>excelSink</code> con <code>mode: &quot;upsert&quot;</code></td><td>Excel, aggiorna per chiave</td><td>✅</td><td>—</td><td><a href="./../connectors/excel#upsert-aggiorna-per-chiave-o-aggiunge">excel</a></td></tr><tr><td><code>excelSink</code> con <code>mode: &quot;append&quot;</code> o <code>&quot;replace&quot;</code></td><td>Excel, aggiunge o sostituisce</td><td>—</td><td>—</td><td><a href="./../connectors/excel">excel</a></td></tr><tr><td><code>noevaFileSink</code>, <code>noevaFilesSink</code></td><td>Workspace Noeva</td><td>—</td><td><code>noevaFilesSink</code></td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>smtpSink</code></td><td>Una mail per record</td><td>—</td><td>✅</td><td><a href="./../connectors/smtp">smtp</a></td></tr><tr><td><code>mailSink</code></td><td><code>smtpSink</code> o <code>sendgridSink</code>, dalla configurazione</td><td>—</td><td>✅</td><td><a href="./../connectors/sendgrid">sendgrid</a></td></tr><tr><td><code>sendgridSink</code></td><td>Una mail per record via SendGrid</td><td>—</td><td>✅</td><td><a href="./../connectors/sendgrid">sendgrid</a></td></tr><tr><td><code>arraySink(name)</code></td><td>In memoria: test</td><td>—</td><td>✅</td><td>—</td></tr></tbody></table><h2 id="esempi" tabindex="-1">Esempi <a class="header-anchor" href="#esempi" aria-label="Permalink to &quot;Esempi&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;contratto-fatto&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sinks.fatti)</span></span>
22
22
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;smista&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sinks.esteri, { fromPort: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;esteri&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// da una porta di un route</span></span>
23
23
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;contratto-fatto&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, dwhSink, {</span></span>
24
24
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> retry: { attempts: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, batchSize: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">500</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// solo su un sink retrySafe</span></span>
@@ -40,4 +40,4 @@ import{_ as t,C as n,o,c as l,j as s,a,E as r,a5 as d}from"./chunks/framework.qd
40
40
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> validTo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;valid_to&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
41
41
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> versionKey: { column: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;versione_sk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, entity: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cliente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
42
42
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> executionIdColumn: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;execution_id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
43
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}))</span></span></code></pre></div><ul><li>La run deve passare <strong><code>referenceDate</code></strong> (<code>YYYY-MM-DD</code>) fra i parametri: è l&#39;inizio di validità delle versioni aperte. Non c&#39;è fallback all&#39;orologio, quindi rieseguire la stessa data dà lo stesso risultato.</li><li><code>conflictTarget</code> insieme a <code>mode: &quot;scd2&quot;</code> non compila.</li><li>A monte servono <code>surrogateKey</code> (chiave durevole) e <code>hashRow</code> (hash di riga): il sink confronta l&#39;hash, non lo calcola.</li><li>Il sink è <code>retrySafe</code> ma <strong>non</strong> ha <code>loadOne</code>.</li><li><code>scd2Rehash: true</code> fra i parametri trasforma la run in un <a href="./../runbooks/scd2-rehash">rehash</a>.</li></ul><p>Opzioni, DDL di riferimento, errori e i due avvisi che il sink non può verificare: schede <a href="./../connectors/postgres#scd2">postgres</a> e <a href="./../connectors/sqlserver#scd2">sqlserver</a>.</p><h2 id="retry-e-rate-limit" tabindex="-1">Retry e rate limit <a class="header-anchor" href="#retry-e-rate-limit" aria-label="Permalink to &quot;Retry e rate limit&quot;">​</a></h2><p>Solo su un sink che dichiara <code>retrySafe: true</code> (oggi i sink Postgres e SQL Server): su uno che riscrive un file intero o manda messaggi <code>build()</code> rifiuta la policy, perché ripetere perderebbe o duplicherebbe dati.</p><ul><li>Con una policy il runner scrive a <strong>blocchi</strong> di <code>batchSize</code> (default 1000) e ritenta il blocco intero sugli errori <strong>transitori</strong> (deadlock, timeout, rete).</li><li>Default del retry: <code>attempts: 3</code> (primo tentativo compreso), <code>baseMs: 200</code>, <code>maxMs: 5000</code>, <code>jitter: 0.5</code>.</li><li>L&#39;atomicità diventa per blocco: dopo un errore definitivo i blocchi già confermati restano scritti. È sicuro perché il sink è idempotente.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><p><code>load</code> è un contratto <strong>opaco</strong>: non sa dire quale record del batch ha fallito. Fuori da un guard, un <code>LoadError</code> ferma la run. Dentro lo scope di un <code>try-catch</code> in modalità <code>per-record</code>, un sink con <code>loadOne</code> viene chiamato record per record e un fallimento arriva al ramo <code>catch</code> con il record in <code>raw</code>; senza <code>loadOne</code> arriva al <code>catch</code> senza <code>raw</code>.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to &quot;Nel DAG e nel report&quot;">​</a></h2><p>Il nodo mostra il <code>descriptor</code> (destinazione, mai segreti). Le colonne arrivano dal nodo a monte, o da <code>columns</code> se il sink le dichiara. Nel report, <code>written</code> conta i record scritti e <code>retries</code> i tentativi ripetuti. Un sink in modalità SCD2 riporta anche <code>versions</code>, con le versioni aperte, chiuse, corrette e invariate: lì <code>written</code> è <code>opened + corrected</code>, quindi una run con tutto invariato ha <code>written: 0</code>.</p><p>Un sink può risultare <strong>saltato</strong> (<code>skipped: { because }</code> nel report, <code>success: false</code>). In quel caso <code>load</code> <strong>non viene chiamata</strong>: un sink che riscrive un file intero lo riscriverebbe vuoto. Succede in due casi:</p><ul><li>non gli arriva nessun record perché un nodo a monte, dentro un <code>try-catch</code>, è fallito senza aver emesso niente. Lo stream si è chiuso pulito, ma non è un dataset vuoto. Un input vuoto di suo resta un <code>load</code> su zero record, e se il nodo a monte fallisce <strong>dopo</strong> aver emesso dei record il sink li ha già ricevuti e li scrive;</li><li>una delle source a monte ha un edge di controllo (<code>after</code>) e il suo predecessore non è riuscito: la source è saltata, e con lei tutto ciò che ne discende.</li></ul><h2 id="dal-vivo" tabindex="-1">Dal vivo <a class="header-anchor" href="#dal-vivo" aria-label="Permalink to &quot;Dal vivo&quot;">​</a></h2><p>Nei contatori dal vivo gli <strong>usciti</strong> di un sink salgono quando il sink dice di aver scritto, e l&#39;<strong>in lavorazione</strong> dice quante righe aspettano di esserlo. C&#39;è in due casi:</p><ul><li><strong>con <code>retry</code> o <code>rateLimit</code></strong>: il blocco del runner, sia mentre si riempie sia mentre il <code>load</code> lo scrive, retry compresi; sotto un guard per-record, il record di un <code>loadOne</code> in volo;</li><li><strong>senza policy, su un sink che dichiara <code>held</code></strong>: le righe accumulate nel suo batch e non ancora scritte. Lo dichiarano i sink Postgres e SQL Server, anche in SCD2. Il batch conta finché lo statement non risponde. Le righe già scritte aspettano il commit a fine <code>load</code>: non sono più in lavorazione, e non sono ancora uscite.</li></ul><p>Con una policy il blocco del runner comprende già il batch del sink, quindi il runner conta il proprio e non somma l&#39;altro. Un sink che non accumula (<code>arraySink</code>, un file riscritto intero) non ha il campo.</p><p>Un sink custom che accumula lo dichiara come una transform: <code>const held = heldCounter()</code> nella factory, <code>held: held.read</code> sul sink, <code>held.set(ctx, n)</code> dentro <code>load</code> a ogni riga accumulata e a ogni batch scritto, e zero in un <code>finally</code> (<a href="./../conventions/run-report#contatori-dal-vivo">convenzione del report</a>).</p><h2 id="edge-di-controllo" tabindex="-1">Edge di controllo <a class="header-anchor" href="#edge-di-controllo" aria-label="Permalink to &quot;Edge di controllo&quot;">​</a></h2><p>Un sink può essere l&#39;<strong>origine</strong> di un edge di controllo: un <a href="./task"><code>task</code></a> o una source con <code>after: [&quot;&lt;nome del sink&gt;&quot;]</code> parte solo dopo che il sink è <strong>riuscito</strong>. È il modo di scambiare le tabelle dopo il caricamento, o di caricare le dimensioni prima dei fatti.</p><ul><li>Il sink <strong>non è riuscito</strong> se è fallito (anche con l&#39;errore catturato da un guard), se è stato saltato, o se il suo input è stato <strong>troncato</strong>: un guard ha catturato l&#39;errore di un nodo a monte. In quest&#39;ultimo caso il sink ha scritto e nel report ha <code>success: true</code>, ma i suoi successori sono saltati.</li><li>Un sink con una source con <code>after</code> a monte chiama <code>load</code> solo quando i gate di <strong>tutte</strong> le source a monte sono aperti: finché aspetta non scrive nulla, nemmeno la parte che arriverebbe dalle altre source.</li><li>Un sink non può essere la <strong>destinazione</strong> di un edge di controllo: per fare qualcosa prima della scrittura si mette <code>after</code> sulla source che lo alimenta.</li></ul><p><strong>Fail-fast.</strong> Quando un altro nodo fa fallire la run, il sink viene annullato: il suo stream d&#39;ingresso rigetta subito e <code>load</code> deve chiudere. Un sink SQL fa rollback. Il runner aspetta che ogni <code>load</code> si concluda prima di riportare la run <code>failed</code>.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to &quot;Anti-pattern&quot;">​</a></h2><ul><li>Un <code>INSERT</code> semplice senza chiave naturale: una seconda run duplica tutto.</li><li>Più sink con <code>name: &quot;memory&quot;</code> nello stesso grafo: collidono.</li><li>Una scrittura il cui risultato serve a valle, fatta con un sink e riletta dopo: è un&#39;<code>action</code>.</li><li>Un upsert su una dimensione che deve conservare la storia: sovrascrive la versione precedente. Serve <code>mode: &quot;scd2&quot;</code>.</li></ul>`,36))])}const m=t(h,[["render",k]]);export{F as __pageData,m as default};
43
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}))</span></span></code></pre></div><ul><li>La run deve passare <strong><code>referenceDate</code></strong> (<code>YYYY-MM-DD</code>) fra i parametri: è l&#39;inizio di validità delle versioni aperte. Non c&#39;è fallback all&#39;orologio, quindi rieseguire la stessa data dà lo stesso risultato.</li><li><code>conflictTarget</code> insieme a <code>mode: &quot;scd2&quot;</code> non compila.</li><li>A monte servono <code>surrogateKey</code> (chiave durevole) e <code>hashRow</code> (hash di riga): il sink confronta l&#39;hash, non lo calcola.</li><li>Il sink è <code>retrySafe</code> ma <strong>non</strong> ha <code>loadOne</code>.</li><li><code>scd2Rehash: true</code> fra i parametri trasforma la run in un <a href="./../runbooks/scd2-rehash">rehash</a>.</li></ul><p>Opzioni, DDL di riferimento, errori e i due avvisi che il sink non può verificare: schede <a href="./../connectors/postgres#scd2">postgres</a> e <a href="./../connectors/sqlserver#scd2">sqlserver</a>.</p><h2 id="retry-e-rate-limit" tabindex="-1">Retry e rate limit <a class="header-anchor" href="#retry-e-rate-limit" aria-label="Permalink to &quot;Retry e rate limit&quot;">​</a></h2><p>Solo su un sink che dichiara <code>retrySafe: true</code> (oggi i sink Postgres, SQL Server e MySQL, e <code>excelSink</code> in <code>upsert</code>): su uno che riscrive un file intero o manda messaggi <code>build()</code> rifiuta la policy, perché ripetere perderebbe o duplicherebbe dati.</p><ul><li>Con una policy il runner scrive a <strong>blocchi</strong> di <code>batchSize</code> (default 1000) e ritenta il blocco intero sugli errori <strong>transitori</strong> (deadlock, timeout, rete).</li><li>Default del retry: <code>attempts: 3</code> (primo tentativo compreso), <code>baseMs: 200</code>, <code>maxMs: 5000</code>, <code>jitter: 0.5</code>.</li><li>L&#39;atomicità diventa per blocco: dopo un errore definitivo i blocchi già confermati restano scritti. È sicuro perché il sink è idempotente.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><p><code>load</code> è un contratto <strong>opaco</strong>: non sa dire quale record del batch ha fallito. Fuori da un guard, un <code>LoadError</code> ferma la run. Dentro lo scope di un <code>try-catch</code> in modalità <code>per-record</code>, un sink con <code>loadOne</code> viene chiamato record per record e un fallimento arriva al ramo <code>catch</code> con il record in <code>raw</code>; senza <code>loadOne</code> arriva al <code>catch</code> senza <code>raw</code>.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to &quot;Nel DAG e nel report&quot;">​</a></h2><p>Il nodo mostra il <code>descriptor</code> (destinazione, mai segreti). Le colonne arrivano dal nodo a monte, o da <code>columns</code> se il sink le dichiara. Nel report, <code>written</code> conta i record scritti e <code>retries</code> i tentativi ripetuti. Un sink in modalità SCD2 riporta anche <code>versions</code>, con le versioni aperte, chiuse, corrette e invariate: lì <code>written</code> è <code>opened + corrected</code>, quindi una run con tutto invariato ha <code>written: 0</code>.</p><p>Un sink può risultare <strong>saltato</strong> (<code>skipped: { because }</code> nel report, <code>success: false</code>). In quel caso <code>load</code> <strong>non viene chiamata</strong>: un sink che riscrive un file intero lo riscriverebbe vuoto. Succede in due casi:</p><ul><li>non gli arriva nessun record perché un nodo a monte, dentro un <code>try-catch</code>, è fallito senza aver emesso niente. Lo stream si è chiuso pulito, ma non è un dataset vuoto. Un input vuoto di suo resta un <code>load</code> su zero record, e se il nodo a monte fallisce <strong>dopo</strong> aver emesso dei record il sink li ha già ricevuti e li scrive;</li><li>una delle source a monte ha un edge di controllo (<code>after</code>) e il suo predecessore non è riuscito: la source è saltata, e con lei tutto ciò che ne discende.</li></ul><h2 id="dal-vivo" tabindex="-1">Dal vivo <a class="header-anchor" href="#dal-vivo" aria-label="Permalink to &quot;Dal vivo&quot;">​</a></h2><p>Nei contatori dal vivo gli <strong>usciti</strong> di un sink salgono quando il sink dice di aver scritto, e l&#39;<strong>in lavorazione</strong> dice quante righe aspettano di esserlo. C&#39;è in due casi:</p><ul><li><strong>con <code>retry</code> o <code>rateLimit</code></strong>: il blocco del runner, sia mentre si riempie sia mentre il <code>load</code> lo scrive, retry compresi; sotto un guard per-record, il record di un <code>loadOne</code> in volo;</li><li><strong>senza policy, su un sink che dichiara <code>held</code></strong>: le righe accumulate nel suo batch e non ancora scritte. Lo dichiarano i sink Postgres, SQL Server e MySQL, anche in SCD2 dove c&#39;è. Il batch conta finché lo statement non risponde. Le righe già scritte aspettano il commit a fine <code>load</code>: non sono più in lavorazione, e non sono ancora uscite.</li></ul><p>Con una policy il blocco del runner comprende già il batch del sink, quindi il runner conta il proprio e non somma l&#39;altro. Un sink che non accumula (<code>arraySink</code>, un file riscritto intero) non ha il campo.</p><p>Un sink custom che accumula lo dichiara come una transform: <code>const held = heldCounter()</code> nella factory, <code>held: held.read</code> sul sink, <code>held.set(ctx, n)</code> dentro <code>load</code> a ogni riga accumulata e a ogni batch scritto, e zero in un <code>finally</code> (<a href="./../conventions/run-report#contatori-dal-vivo">convenzione del report</a>).</p><h2 id="edge-di-controllo" tabindex="-1">Edge di controllo <a class="header-anchor" href="#edge-di-controllo" aria-label="Permalink to &quot;Edge di controllo&quot;">​</a></h2><p>Un sink può essere l&#39;<strong>origine</strong> di un edge di controllo: un <a href="./task"><code>task</code></a> o una source con <code>after: [&quot;&lt;nome del sink&gt;&quot;]</code> parte solo dopo che il sink è <strong>riuscito</strong>. È il modo di scambiare le tabelle dopo il caricamento, o di caricare le dimensioni prima dei fatti.</p><ul><li>Il sink <strong>non è riuscito</strong> se è fallito (anche con l&#39;errore catturato da un guard), se è stato saltato, o se il suo input è stato <strong>troncato</strong>: un guard ha catturato l&#39;errore di un nodo a monte. In quest&#39;ultimo caso il sink ha scritto e nel report ha <code>success: true</code>, ma i suoi successori sono saltati.</li><li>Un sink con una source con <code>after</code> a monte chiama <code>load</code> solo quando i gate di <strong>tutte</strong> le source a monte sono aperti: finché aspetta non scrive nulla, nemmeno la parte che arriverebbe dalle altre source.</li><li>Un sink non può essere la <strong>destinazione</strong> di un edge di controllo: per fare qualcosa prima della scrittura si mette <code>after</code> sulla source che lo alimenta.</li></ul><p><strong>Fail-fast.</strong> Quando un altro nodo fa fallire la run, il sink viene annullato: il suo stream d&#39;ingresso rigetta subito e <code>load</code> deve chiudere. Un sink SQL fa rollback. Il runner aspetta che ogni <code>load</code> si concluda prima di riportare la run <code>failed</code>.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to &quot;Anti-pattern&quot;">​</a></h2><ul><li>Un <code>INSERT</code> semplice senza chiave naturale: una seconda run duplica tutto.</li><li>Più sink con <code>name: &quot;memory&quot;</code> nello stesso grafo: collidono.</li><li>Una scrittura il cui risultato serve a valle, fatta con un sink e riletta dopo: è un&#39;<code>action</code>.</li><li>Un upsert su una dimensione che deve conservare la storia: sovrascrive la versione precedente. Serve <code>mode: &quot;scd2&quot;</code>.</li></ul>`,36))])}const m=t(h,[["render",k]]);export{F as __pageData,m as default};