@elia97/officina 0.3.0 → 0.5.0

package/README.md

@@ -18,7 +18,6 @@ pnpm add -D @elia97/officina
     "check:routes": "officina check routes",
     "check:roadmap": "officina check roadmap",
     "check:placeholders": "officina check placeholders",
-    "check:vercel-cli": "officina check vercel-cli",
     "perf:bundle": "officina check bundle",
     "smoke:prod": "officina check smoke",
     "analytics:verify": "officina check analytics",
@@ -43,14 +42,15 @@ I gate leggono dalla cartella corrente, che deve essere la radice del repository
 |---|---|---|
 | `check bundle` | il JavaScript e il CSS di `dist/client`, gzip, contro un budget per rotta | `src/pages` |
 | `check smoke [url]` | la produzione viva: pagine, header di sicurezza, BotID, host canonico, barra finale | `src/pages`, più le rotte non HTML |
-| `check analytics [GTM-…]` | il container GTM pubblico contro gli eventi di `src/lib/analytics/link-tracking.ts` | — |
+| `check analytics [GTM-…]` | il container GTM pubblico contro gli eventi del modulo di link-tracking del progetto (`analytics.linkTracking`) | — |
 | `check lighthouse [--local]` | Lighthouse CI sul `.lighthouserc.json` del progetto; `--local` fa build, server e Chrome da sé | `src/pages` |
-| `gen icons` | le icone del manifest, disegnate da `public/favicon.svg` | — |
+| `gen icons` | le icone del manifest, disegnate dal favicon SVG in `public/` del progetto | — |
 
 Il motore è uguale per tutti; ciò che cambia da un progetto all'altro sta in un file solo, `officina.config.ts` nella radice:
 
 ```ts
-import { type Budget, DEFAULT_CHECKS, defineConfig, type SmokeCheck } from '@elia97/officina'
+import { type Budget, defineConfig, type SmokeCheck } from '@elia97/officina'
+import { DEFAULT_CHECKS } from '@elia97/officina/smoke'
 
 import { SITE } from './src/lib/site.ts'
 
@@ -62,12 +62,96 @@ export default defineConfig({
   icons: { background: SITE.themeColor.light },
   bundle: { budgets: [motion], cssMaxGzip: 14 * 1024 },
   smoke: { checks: [...DEFAULT_CHECKS, checkLanguageRedirect] },
+  features: { analytics: 'required', roadmap: false },
+  routes: { representatives: { '/blog/[slug]': '/blog/ciao-mondo' } },
 })
 ```
 
-Ogni voce è facoltativa, tranne `siteUrl` per `check smoke` e `icons.background` per `gen icons`. I budget del progetto vengono prima del default di 20 KB, nell'ordine in cui sono scritti; `smoke.checks` sostituisce la lista del pacchetto, quindi chi non ha BotID la ricompone senza `checkBotIdChallenge`; `smoke.securityHeaders` e `smoke.nonHtmlRoutes` sostituiscono `SECURITY_HEADERS` e `NON_HTML_ROUTES`. Il file lo carica Node, che fuori da `node_modules` toglie i tipi da sé: niente `enum`, niente alias `@/`.
+La radice del pacchetto esporta `defineConfig` e i tipi; i pezzi del motore stanno nei sottopercorsi, così la radice resta la sola cosa che serve conoscere per configurarsi.
 
-`sharp` è una dipendenza facoltativa del progetto, non del pacchetto: serve solo a `gen icons`, che senza lo dice ed esce 1. `ICON_SPECS` si importa senza caricarlo, per il test che confronta le icone con il manifest del sito.
+| Sottopercorso | Cosa esporta |
+|---|---|
+| `@elia97/officina/smoke` | `DEFAULT_CHECKS`, i cinque controlli, `SECURITY_HEADERS`, `NON_HTML_ROUTES` |
+| `@elia97/officina/bundle` | `CSS_BUDGET_GZIP` |
+| `@elia97/officina/icons` | `ICON_SPECS` |
+
+`siteUrl` serve a `check smoke` e `icons.background` a `gen icons`. I budget del progetto vengono prima del default di 20 KB, nell'ordine in cui sono scritti; `smoke.checks` sostituisce la lista del pacchetto, quindi chi non ha BotID la ricompone senza `checkBotIdChallenge`; `smoke.securityHeaders` e `smoke.nonHtmlRoutes` sostituiscono `SECURITY_HEADERS` e `NON_HTML_ROUTES`.
+
+`features` dice quali controlli il progetto pretende: `'required'` fa fallire il gate quando ciò che deve guardare non c'è, `false` lo spegne dicendolo. Una voce non dichiarata vale `'required'`, e `doctor` la segnala: un gate che esce 0 su un container GTM che non esiste non afferma niente. `routes.representatives` dà a ogni pattern dinamico di `src/pages` un percorso vero, e da lì smoke e Lighthouse guardano anche quelle pagine.
+
+Il file lo carica Node, che fuori da `node_modules` toglie i tipi da sé: niente `enum`, niente alias `@/`. Due file `officina.config.*` insieme sono un errore, come un file senza default export; il resto lo valida `loadConfig` a runtime, nominando il percorso della voce sbagliata — `bundle.cssMaxGzip: atteso un numero, ricevuto una stringa` — e una voce sconosciuta, perché `sitUrl` al posto di `siteUrl` non deve passare in silenzio.
+
+`sharp` è una dipendenza facoltativa del progetto, non del pacchetto: serve solo a `gen icons`, che senza lo dice ed esce 1. `@biomejs/biome` invece è una peer dependency con l'intervallo che il preset regge, e `doctor` confronta la versione del progetto con quello.
+
+## Preset di configurazione
+
+Le regole che valgono per tutti i progetti stanno nel pacchetto; il progetto estende e tiene solo le proprie eccezioni.
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.10/schema.json",
+  "extends": ["@elia97/officina/biome"]
+}
+```
+
+```yaml
+# lefthook.yml
+extends:
+  - node_modules/@elia97/officina/presets/lefthook.yml
+```
+
+## Action per i workflow
+
+I passi dei workflow stanno in `actions/` di questo repository, come composite action: girano dentro il job di chi le chiama, quindi il nome del check e l'`environment` restano del progetto. Il riferimento va fissato a un tag di versione o a uno SHA, mai a `@main`, e deve essere la stessa versione del pacchetto installato — `doctor` lo verifica.
+
+| Action | Passi | Cosa resta nel workflow del progetto |
+|---|---|---|
+| `actions/ci` | checkout, node, install, `pnpm run ci`, build, `perf:bundle`; con `e2e: 'true'` anche Playwright | trigger, permessi, il job `ci` |
+| `actions/review` | `fallow review` sul diff contro il merge-base | il job informativo |
+| `actions/deploy` | risoluzione del tag, gate, `vercel pull`, `build`, `deploy`, smoke; espone `url` | trigger, `environment`, i tre segreti Vercel passati in `with:`, il job che controlla se i segreti ci sono |
+| `actions/lighthouse` | build equivalente alla produzione e `pnpm run lhci` | trigger, etichetta, `continue-on-error` |
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: ${{ steps.deploy.outputs.url }}
+    steps:
+      - uses: Elia97/officina/actions/deploy@v0.4.0
+        id: deploy
+        with:
+          ref: ${{ inputs.ref }}
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
+```
+
+I tre segreti sono input obbligatori e l'action li mette nell'`env` dei soli tre passi che chiamano `vercel`. Nell'`env` del job li vedrebbero anche `pnpm install` e gli script di installazione di ogni dipendenza, che girano codice di terzi con in mano un token di deploy.
+
+Quello che si scarica al volo è fissato a una versione esatta, in un posto solo: la CLI di Vercel in `actions/deploy/action.yml`, `@lhci/cli` in `src/checks/lighthouse.ts`, `serve` in `src/sh/lhci-local.sh`. Che i primi due siano esatti, uguali ovunque e non indietro di una major su npm lo guarda ogni lunedì `.github/workflows/vercel-cli.yml`, con `officina check vercel-cli`.
+
+Perché le action non restino ferme per sempre, Dependabot di questo repository copre l'ecosistema `github-actions` anche dentro `/actions/*`, dove le action di terze parti sono fissate allo SHA intero con la versione nel commento.
+
+## doctor
+
+`officina doctor` dice, in qualunque repository, cosa manca perché il progetto prenda tutto da fuori: i punti di aggancio dei generatori, gli ancoraggi delle pagine a sezioni e dei dizionari, gli script, le dipendenze e gli strumenti di `package.json`, i residui di ciò che è uscito (copia del metodo, script, documenti commerciali), i preset, i workflow di GitHub e Dependabot, `officina.config.ts`. Sta dentro `ci`, quindi un progetto allineato non torna indietro senza che il gate lo dica.
+
+Le prime due sezioni rispondono a due domande diverse. I punti di aggancio sono l'elenco di `src/lib/contract.ts`, e chiedono che una cosa esista: i moduli che il codice generato importa, le cartelle in cui i generatori scrivono, `class-variance-authority` fra le dipendenze, lo script `check` che il post-gen lancia. Gli ancoraggi guardano dentro quei file, e chiedono che abbiano ancora la forma su cui l'iniezione conta:
+
+- per ogni collection a sezioni registrata in `src/content.config.ts` — riconosciuta dall'import di `<nome>CollectionSchema` da `@/lib/schemas/<nome>`, non dai marcatori, che sono proprio ciò che può sparire — la funzione `<nome>CollectionSchema`, la sua `z.discriminatedUnion` sopra un array letterale, il parametro non destrutturato che una sezione con immagine riceve, il `return { … }` di primo livello di `get<Nome>Sections`, e una sola pagina sotto `src/pages/` che porti `{/* @gen:<nome>-sections */}` e, su quella, `// @gen:<nome>-imports`;
+- per ogni dizionario di `src/i18n/strings/`, il suo `export const <lingua> = { … } as const`.
+
+Sono gli stessi controlli del pre-volo dei generatori, non una copia: `doctor` chiama `assertSectionAnchors` e `assertDictionaries`, che vivono in `src/gen/` insieme all'iniezione. Al pre-volo resta ciò che dipende dal nome di quello che sta per nascere — la sezione già nell'unione, l'identificatore già preso nel barrel o nel frontmatter, la chiave già nel dizionario, il file che esiste già — e che quindi si può chiedere solo al lancio del generatore.
+
+Le altre sezioni misurano che il progetto e il pacchetto si muovano insieme:
+
+- **stessa versione**: il riferimento delle action nei workflow — `@v<x.y.z>`, oppure uno SHA con `# v<x.y.z>` nel commento — deve essere la versione del pacchetto installato. Un progetto col pacchetto alla 0.8 e le action alla 0.6 non è un progetto allineato;
+- **una PR sola**: il `.github/dependabot.yml` del progetto deve avere un gruppo `multi-ecosystem-groups` che prende `@elia97/officina` da npm e `Elia97/officina/*` da `github-actions`. Senza, Dependabot ne apre due e il controllo qui sopra le boccia entrambe;
+- **gli strumenti che preset e action danno per scontati**: `@biomejs/biome`, `lefthook`, `@commitlint/cli`, `@commitlint/config-conventional` e `fallow` fra le `devDependencies`, con la versione di Biome dentro l'intervallo che il preset dichiara di reggere.
+
+`package.json`, `.claude/settings.json`, `biome.json` e `.mcp.json` si leggono come JSON, non cercandoci dentro delle stringhe: `"hooks"` in un valore qualunque non è un blocco `hooks`. I workflow restano una ricerca testuale — non c'è un parser YAML nel pacchetto — ma una riga commentata non soddisfa nessun controllo.
 
 ## Sviluppo
 
@@ -76,24 +160,33 @@ pnpm install
 pnpm test        # vitest; i test che leggono dal disco girano in test/fixture-project/
 pnpm typecheck
 pnpm build       # tsc → dist/, l'unica cosa che viene pubblicata
+pnpm test:pack   # pnpm pack, poi il tarball installato in un progetto vuoto
 ```
 
+`ci`, `build` e `test:pack` girano anche in `.github/workflows/ci.yml`, su ogni pull request e su ogni push a `main`.
+
 I sorgenti sono TypeScript, ma il pacchetto pubblica JavaScript: Node toglie i tipi al volo solo fuori da `node_modules`. I test con `--diff` hanno bisogno di almeno un commit su `main`.
 
 ## Pubblicare
 
 ```sh
-pnpm version <patch|minor|major>
-pnpm publish     # prepublishOnly lancia typecheck, test e build
+pnpm version <patch|minor|major>   # scrive package.json e crea il tag
+git push --follow-tags
 ```
 
+Il resto lo fa `.github/workflows/release.yml`, sul push di un tag `v*`: controlla che il tag corrisponda a `version`, rilancia il gate, la build e il test del tarball, pubblica su npm con trusted publishing (OIDC) e provenance, e crea la release su GitHub con le note generate. Niente `pnpm publish` dal terminale: quello che finisce su npm esce da un tag, e da nient'altro.
+
+Le action si richiamano per tag, quindi **una versione senza tag non è adottabile**: `doctor` chiede ai progetti la stessa versione del pacchetto installato, e un tag che non esiste non si può scrivere in un workflow.
+
+Una volta sola, a mano: su npmjs.com il trusted publisher per `Elia97/officina` e `release.yml`; su GitHub un ruleset sui tag `v*` che ne vieta modifica e cancellazione.
+
 ## Generatori
 
 `officina gen` avvolge plop con i generatori e i template del pacchetto, e scrive nel progetto da cui lo lanci: `section`, `page`, `component`, `collection`. `plop` e `ts-morph` sono dipendenze del pacchetto, non del progetto.
 
-I generatori scrivono codice che deve incastrarsi nello scaffold, quindi il progetto deve avere i punti di aggancio che si aspettano: i moduli che il codice generato importa e i file in cui iniettano. L'elenco è `src/lib/contract.ts`, e `officina doctor` dice, in qualunque repository, cosa manca. Finché manca qualcosa il pre-volo del generatore si ferma prima di scrivere un solo file.
+I generatori scrivono codice che deve incastrarsi nello scaffold, quindi il progetto deve avere i punti di aggancio che si aspettano: i moduli che il codice generato importa, l'elenco è `src/lib/contract.ts`, e i file in cui iniettano, con la forma su cui l'iniezione conta. Sono le prime due sezioni di `officina doctor`. Finché manca qualcosa il pre-volo del generatore si ferma prima di scrivere un solo file.
 
-Un progetto aggiunge i propri generatori con un file `officina.generators.mjs` nella radice, con la firma di un plopfile: `export default function (plop)`.
+Un progetto aggiunge i propri generatori con un file `officina.generators.mjs` nella radice, con la firma di un plopfile: `export default function (plop)`. È un'estensione avanzata e non è parte dell'API del pacchetto: è legata alla firma di plop, quindi una major di plop può romperla.
 
 I test dei generatori girano sui punti di aggancio del progetto di prova, copiati da `vetrina`. Che un progetto vero li abbia ancora lo verifica `doctor`, non i test.
 

package/dist/bundle.d.ts

@@ -0,0 +1 @@
+export { CSS_BUDGET_GZIP } from './lib/bundle-budget.ts';

package/dist/bundle.js

@@ -0,0 +1 @@
+export { CSS_BUDGET_GZIP } from './lib/bundle-budget.js';

package/dist/checks/analytics.js

@@ -4,7 +4,7 @@
 import { readFileSync } from 'node:fs';
 import process from 'node:process';
 import { coverageOf, extractLinkEvents } from '../lib/analytics-coverage.js';
-import { loadConfig } from '../lib/config.js';
+import { isRequired, loadConfig } from '../lib/config.js';
 import { extractTriggers, googleTagIds, parseContainerData } from '../lib/gtm-container.js';
 const LINK_TRACKING = 'src/lib/analytics/link-tracking.ts';
 const TIMEOUT_MS = 15_000;
@@ -18,30 +18,36 @@ function reportCoverage(coverage) {
     }
     const missing = coverage.filter(({ covered }) => !covered);
     if (missing.length > 0) {
-        console.error(`\n✗ ${missing.length} event(s) the site pushes and no trigger listens for.`);
+        console.error(`\n✗ ${missing.length} evento/i che il sito emette e nessun trigger ascolta.`);
         return 1;
     }
-    console.log('\n✓ Every event the site pushes has a trigger.');
+    console.log('\n✓ Ogni evento che il sito emette ha un trigger.');
     return 0;
 }
 export async function main(args = []) {
-    const { analytics = {} } = await loadConfig(process.cwd());
+    const config = await loadConfig(process.cwd());
+    const { analytics = {} } = config;
     const gtmId = resolveGtmId(args);
     if (gtmId === null) {
-        console.log('No GTM container to check: pass one as an argument or set PUBLIC_GTM_ID.');
-        return 0;
+        if (!isRequired(config, 'analytics')) {
+            console.log('check:analytics — spento da `features.analytics: false`.');
+            return 0;
+        }
+        console.error('\n✗ Nessun container GTM da controllare: passane uno come argomento, imposta PUBLIC_GTM_ID,\n' +
+            '  oppure dichiara `features.analytics: false` se il progetto non ha analytics.\n');
+        return 1;
     }
     const response = await fetch(`https://www.googletagmanager.com/gtm.js?id=${gtmId}`, {
         signal: AbortSignal.timeout(TIMEOUT_MS),
     });
     if (!response.ok) {
-        console.error(`✗ container ${gtmId} unreadable: HTTP ${response.status}`);
+        console.error(`✗ container ${gtmId} illeggibile: HTTP ${response.status}`);
         return 1;
     }
     const container = parseContainerData(await response.text());
     const source = readFileSync(analytics.linkTracking ?? LINK_TRACKING, 'utf8');
     const coverage = coverageOf(extractLinkEvents(source), extractTriggers(container));
-    console.log(`\nGTM ${gtmId} — measurement IDs: ${googleTagIds(container).join(', ') || '—'}\n`);
+    console.log(`\nGTM ${gtmId} — ID di misurazione: ${googleTagIds(container).join(', ') || '—'}\n`);
     return reportCoverage(coverage);
 }
 if (import.meta.main)

package/dist/checks/bundle.js

@@ -29,16 +29,24 @@ function measurePages(chunks, budgets) {
     return filesWithExtension(DIST, '.html')
         .map((htmlPath) => {
         const route = routeOf(htmlPath, DIST);
-        const reached = staticClosure(htmlEntries(readFileSync(htmlPath, 'utf8')), chunks);
+        const { reached, unknown } = staticClosure(htmlEntries(readFileSync(htmlPath, 'utf8')), chunks);
         return {
             route,
             gzip: total(reached),
             deferredGzip: total(deferredClosure(reached, chunks)),
             budget: budgetFor(route, budgets),
+            unknown: [...unknown].sort(),
         };
     })
         .sort((a, b) => b.gzip - a.gzip);
 }
+// Zero JavaScript su una rotta è un esito normale in Astro; un nome citato che fra i chunk non c'è
+// vuol dire che la misura non copre tutto il bundle, e allora non afferma niente.
+function unknownChunkFailures(pages) {
+    return pages
+        .filter((page) => page.unknown.length > 0)
+        .map((page) => `${page.route}: formato del bundle non riconosciuto — ${page.unknown.join(', ')} non è in ${ASSETS}`);
+}
 function overBudgetFailures(pages) {
     return pages
         .filter((page) => page.gzip > page.budget.maxGzip)
@@ -48,18 +56,18 @@ function overBudgetFailures(pages) {
     });
 }
 function printPages(pages, width) {
-    console.log('\nBundle budget — client JS per route (gzip, static closure)\n');
-    console.log(`${'ROUTE'.padEnd(width)}   ${'STATIC'.padStart(9)}   ${'BUDGET'.padStart(9)}   ${'DEFERRED'.padStart(9)}`);
+    console.log('\nBudget di bundle — JS del client per rotta (gzip, chiusura statica)\n');
+    console.log(`${'ROTTA'.padEnd(width)}   ${'STATICO'.padStart(9)}   ${'BUDGET'.padStart(9)}   ${'DIFFERITO'.padStart(9)}`);
     for (const page of pages) {
         const deferred = page.deferredGzip > 0 ? gz(page.deferredGzip) : '—';
         const line = `${page.route.padEnd(width)}   ${gz(page.gzip).padStart(9)}   ${gz(page.budget.maxGzip).padStart(9)}   ${deferred.padStart(9)}`;
         console.log(page.gzip > page.budget.maxGzip ? `${line}  ✗` : line);
     }
-    console.log('\nDEFERRED = reachable only through `await import()` (loaded after paint, behind a runtime guard).');
+    console.log('\nDIFFERITO = raggiungibile solo da `await import()` (caricato dopo il primo paint, dietro una guardia a runtime).');
 }
 function printStylesheets(stylesheets, cssMaxGzip, failed, width) {
     const worst = heaviestStylesheet(stylesheets);
-    console.log(`\nCSS (render-blocking, heaviest sheet a route links)`);
+    console.log(`\nCSS (blocca il rendering: il foglio più pesante che una rotta collega)`);
     for (const sheet of [...stylesheets].sort((a, b) => b.gzip - a.gzip)) {
         const mark = sheet === worst && failed ? '  ✗' : '';
         console.log(`  ${sheet.file.padEnd(width - 2)}   ${gz(sheet.gzip).padStart(9)}   ${gz(cssMaxGzip).padStart(9)}${mark}`);
@@ -68,7 +76,7 @@ function printStylesheets(stylesheets, cssMaxGzip, failed, width) {
 function printSsrNote(expected) {
     if (expected.ssr.length === 0)
         return;
-    console.log(`\nNOTE  ${expected.ssr.length} page(s) opted out with \`export const prerender = false\` and are outside this budget:`);
+    console.log(`\nNOTA  ${expected.ssr.length} pagina/e con \`export const prerender = false\`, fuori da questo budget:`);
     for (const file of expected.ssr)
         console.log(`      - ${file}`);
 }
@@ -78,8 +86,8 @@ export async function main() {
     const pages = measurePages(readChunks(), bundle.budgets ?? []);
     const expected = expectedRoutes(readPageFiles(PAGES), PAGES);
     const failures = missingRouteFailures(expected, pages.map((page) => page.route), DIST);
-    failures.push(...overBudgetFailures(pages));
-    const width = Math.max('ROUTE'.length, ...pages.map((p) => p.route.length));
+    failures.push(...unknownChunkFailures(pages), ...overBudgetFailures(pages));
+    const width = Math.max('ROTTA'.length, ...pages.map((p) => p.route.length));
     printPages(pages, width);
     const stylesheets = readStylesheets();
     const cssFailure = cssBudgetFailure(stylesheets, cssMaxGzip);
@@ -88,10 +96,10 @@ export async function main() {
     printStylesheets(stylesheets, cssMaxGzip, cssFailure !== null, width);
     printSsrNote(expected);
     if (failures.length > 0) {
-        console.error(`\n✗ Bundle budget:\n${failures.map((f) => `  - ${f}`).join('\n')}\n`);
+        console.error(`\n✗ Budget di bundle:\n${failures.map((f) => `  - ${f}`).join('\n')}\n`);
         return 1;
     }
-    console.log('\n✓ Bundle budget respected on every expected route.\n');
+    console.log('\n✓ Budget di bundle rispettato su ogni rotta attesa.\n');
     return 0;
 }
 if (import.meta.main)

package/dist/checks/doctor.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare function main(): number;
+export declare function main(): Promise<number>;

package/dist/checks/doctor.js

@@ -1,15 +1,79 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import process from 'node:process';
+import { dependencyGaps, leftoverGaps, presetGaps, scriptGaps, } from '../lib/alignment.js';
+import { anchorGaps } from '../lib/anchors.js';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
-import { CONTRACT, contractGaps } from '../lib/contract.js';
-export function main() {
-    const findings = contractGaps(process.cwd()).map((gap) => ({ ...gap, severity: 'error' }));
-    console.log(`\nofficina doctor — ${CONTRACT.length} punti di aggancio dei generatori\n`);
-    printFindings(findings, cliOptions([]).format);
+import { findConfigFile, loadConfig } from '../lib/config.js';
+import { configGaps } from '../lib/config-gaps.js';
+import { contractGaps } from '../lib/contract.js';
+import { trackedAndUntracked } from '../lib/git.js';
+import { expectedRoutes, missingRepresentatives, readPageFiles } from '../lib/routes.js';
+import { toolingGaps } from '../lib/tooling.js';
+import { packageVersion } from '../lib/versions.js';
+import { dependabotGaps, workflowGaps } from '../lib/workflows.js';
+const PAGES = 'src/pages';
+function projectFiles(root) {
+    return {
+        paths: trackedAndUntracked(),
+        read: (path) => (existsSync(join(root, path)) ? readFileSync(join(root, path), 'utf8') : undefined),
+    };
+}
+function readManifest(files) {
+    try {
+        return JSON.parse(files.read('package.json') ?? '{}');
+    }
+    catch {
+        return {};
+    }
+}
+async function loadedConfig(root) {
+    if (findConfigFile(root) === undefined)
+        return undefined;
+    try {
+        return await loadConfig(root);
+    }
+    catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+}
+function orphanPatterns(root, config) {
+    const pages = join(root, PAGES);
+    if (!existsSync(pages) || config === undefined || config instanceof Error)
+        return [];
+    return missingRepresentatives(expectedRoutes(readPageFiles(pages), pages), config.routes?.representatives);
+}
+export async function main() {
+    const root = process.cwd();
+    const files = projectFiles(root);
+    const manifest = readManifest(files);
+    const version = packageVersion();
+    const config = await loadedConfig(root);
+    const sections = [
+        ['punti di aggancio dei generatori', contractGaps(root)],
+        ['ancoraggi delle pagine a sezioni e dei dizionari', anchorGaps(root)],
+        [
+            'script, dipendenze e strumenti di package.json',
+            [...scriptGaps(manifest), ...dependencyGaps(manifest), ...toolingGaps(manifest)],
+        ],
+        ['residui di ciò che è uscito dal repository', leftoverGaps(files)],
+        ['preset di configurazione', presetGaps(files)],
+        ['workflow di GitHub e Dependabot', [...workflowGaps(files, version), ...dependabotGaps(files)]],
+        ['officina.config.ts', configGaps(config, orphanPatterns(root, config))],
+    ];
+    console.log(`\nofficina doctor ${version} — cosa manca al progetto per prendere tutto da fuori\n`);
+    const findings = [];
+    for (const [title, gaps] of sections) {
+        console.log(gaps.length === 0 ? `  ✓ ${title}` : `  ${title}: ${gaps.length}`);
+        const sectionFindings = gaps.map((gap) => ({ ...gap, severity: 'error' }));
+        printFindings(sectionFindings, cliOptions([]).format);
+        findings.push(...sectionFindings);
+    }
     console.log(findings.length === 0
-        ? '  Il progetto ha tutto quello che i generatori si aspettano.\n'
-        : `\n  ${findings.length} su ${CONTRACT.length} da sistemare prima che \`officina gen\` scriva codice che compila.\n`);
+        ? '\n  Il progetto è allineato: metodo, gate, generatori e verifiche arrivano da fuori.\n'
+        : `\n  ${findings.length} da sistemare.\n`);
     return exitCode(findings, false);
 }
 if (import.meta.main)
-    process.exit(main());
+    process.exit(await main());

package/dist/checks/lighthouse.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare function main(args?: string[]): number;
+export declare function main(args?: string[]): Promise<number>;

package/dist/checks/lighthouse.js

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../lib/config.js';
 import { lighthouseConfig } from '../lib/lighthouse.js';
 import { auditRoutes, expectedRoutes, readPageFiles } from '../lib/routes.js';
 const PAGES_DIR = 'src/pages';
@@ -16,22 +17,25 @@ function runLocal() {
     const env = { ...process.env, OFFICINA_BIN: process.argv[1] };
     return spawnSync('bash', [script], { stdio: 'inherit', env }).status ?? 1;
 }
-export function main(args = []) {
+export async function main(args = []) {
     if (args.includes('--local'))
         return runLocal();
+    const { routes: configured = {} } = await loadConfig(process.cwd());
     const rc = JSON.parse(readFileSync(RC_FILE, 'utf8'));
-    const routes = auditRoutes(expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR));
+    const routes = auditRoutes(expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR), configured.representatives);
     const resolved = lighthouseConfig(rc, routes, process.env);
-    console.log(`\nLighthouse CI — ${routes.length} route(s) derived from ${PAGES_DIR}\n`);
+    console.log(`\nLighthouse CI — ${routes.length} rotta/e derivate da ${PAGES_DIR}\n`);
     for (const url of resolved.ci.collect.url ?? [])
         console.log(`  ${url}`);
     console.log();
     const dir = mkdtempSync(join(tmpdir(), 'lhci-'));
     const config = join(dir, 'lighthouserc.json');
     writeFileSync(config, JSON.stringify(resolved, null, 2));
-    const { status } = spawnSync('pnpm', ['dlx', '@lhci/cli', 'autorun', `--config=${config}`], { stdio: 'inherit' });
+    const { status } = spawnSync('pnpm', ['dlx', '@lhci/cli@0.15.1', 'autorun', `--config=${config}`], {
+        stdio: 'inherit',
+    });
     rmSync(dir, { recursive: true, force: true });
     return status ?? 1;
 }
 if (import.meta.main)
-    process.exit(main(process.argv.slice(2)));
+    process.exit(await main(process.argv.slice(2)));

package/dist/checks/roadmap.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare function main(args?: string[]): number;
+export declare function main(args?: string[]): Promise<number>;

package/dist/checks/roadmap.js

@@ -3,15 +3,21 @@ import { existsSync, readFileSync } from 'node:fs';
 import process from 'node:process';
 import { findingsFor } from '../lib/check-roadmap.js';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
+import { isRequired, loadConfig } from '../lib/config.js';
 const ROADMAP = 'docs/ROADMAP.md';
 // Esporta main ed esegue solo se lanciato direttamente: la copertura non segue i sottoprocessi,
 // quindi un gate provato con `node scripts/...` risulterebbe non testato.
-export function main(args) {
+export async function main(args) {
     const options = cliOptions(args);
-    // Un progetto appena creato dal template può non averla ancora scritta.
+    // Che un progetto la roadmap non ce l'abbia è una scelta, e una scelta si dichiara: il silenzio
+    // vale `'required'`, e un gate che esce 0 su un file che non c'è non afferma niente.
     if (!existsSync(ROADMAP)) {
-        console.log(`\ncheck:roadmap — ${ROADMAP} non c'è ancora\n`);
-        return 0;
+        if (!isRequired(await loadConfig(process.cwd()), 'roadmap')) {
+            console.log(`\ncheck:roadmap — spento da \`features.roadmap: false\`\n`);
+            return 0;
+        }
+        console.error(`\n✗ check:roadmap — ${ROADMAP} non c'è: scrivila, o dichiara \`features.roadmap: false\`\n`);
+        return 1;
     }
     const findings = findingsFor(readFileSync(ROADMAP, 'utf8')).map((f) => ({
         path: ROADMAP,
@@ -30,4 +36,4 @@ export function main(args) {
     return exitCode(findings, options.strict);
 }
 if (import.meta.main)
-    process.exit(main());
+    process.exit(await main());

package/dist/checks/smoke.js

@@ -10,26 +10,26 @@ function printResults(results) {
         if (status === 'pass')
             console.log(`✓ ${check}`);
         else if (status === 'skip')
-            console.log(`- ${check} (skipped: ${detail})`);
+            console.log(`- ${check} (saltato: ${detail})`);
         else
             console.error(`✗ ${check} — ${detail}`);
     }
 }
 function printFailures(failures) {
-    console.error(`\n✗ ${failures.length} check(s) failed:`);
+    console.error(`\n✗ ${failures.length} controllo/i falliti:`);
     console.error(`${failures.map(({ check, detail }) => `  - ${check} — ${detail}`).join('\n')}\n`);
-    console.error('Production is live and broken. Roll back from the Vercel dashboard:');
-    console.error('Deployments → the last known-good production deployment → Promote to Production.\n');
+    console.error('La produzione è online e rotta. Torna indietro dalla dashboard di Vercel:');
+    console.error('Deployments → l’ultimo deployment di produzione sano → Promote to Production.\n');
 }
 export async function main(args = []) {
-    const { siteUrl, smoke = {} } = await loadConfig(process.cwd());
+    const { siteUrl, smoke = {}, routes = {} } = await loadConfig(process.cwd());
     const [url] = args;
     if (siteUrl === undefined) {
-        console.error('\n✗ officina.config.ts declares no siteUrl — the canonical-host check has nothing to compare against.\n');
+        console.error('\n✗ officina.config.ts non dichiara siteUrl: il controllo dell’host canonico non ha con cosa confrontarsi.\n');
         return 1;
     }
     if (url === undefined && new URL(siteUrl).host === 'example.com') {
-        console.error('\n✗ siteUrl is still the template placeholder — pass a URL: pnpm smoke:prod https://…\n');
+        console.error('\n✗ siteUrl è ancora il segnaposto del template: passa un URL, pnpm smoke:prod https://…\n');
         return 1;
     }
     // L'apice, non l'URL *.vercel.app che stampa `vercel deploy`: lì la regola `has: host` di vercel.json mette noindex.
@@ -40,8 +40,9 @@ export async function main(args = []) {
         siteUrl,
         securityHeaders: smoke.securityHeaders ?? SECURITY_HEADERS,
     };
-    const pages = smokeRoutes(expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR), smoke.nonHtmlRoutes);
-    console.log(`\nProduction smoke — ${baseUrl}\n`);
+    const expected = expectedRoutes(readPageFiles(PAGES_DIR), PAGES_DIR);
+    const pages = smokeRoutes(expected, smoke.nonHtmlRoutes, routes.representatives);
+    console.log(`\nSmoke di produzione — ${baseUrl}\n`);
     await waitForAlias(context, (ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const results = await runChecks(context, pages, smoke.checks);
     printResults(results);
@@ -50,7 +51,7 @@ export async function main(args = []) {
         printFailures(failures);
         return 1;
     }
-    console.log(`\n✓ Every check passed on ${baseUrl}.\n`);
+    console.log(`\n✓ Tutti i controlli passati su ${baseUrl}.\n`);
     return 0;
 }
 if (import.meta.main)

package/dist/checks/vercel-cli.js

@@ -1,29 +1,45 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import process from 'node:process';
 import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
-import { pinFindings } from '../lib/vercel-cli-pin.js';
-const WORKFLOW = '.github/workflows/deploy.yml';
+import { pinFindings } from '../lib/pins.js';
+// I pin di ciò che si scarica al volo stanno nei file di questo repository: un progetto prende
+// `vercel` dall'action di deploy e `@lhci/cli` dal gate, e non ne pinna nessuno per conto suo.
+const PINNED = [
+    { package: 'vercel', files: ['actions/deploy/action.yml'] },
+    { package: '@lhci/cli', files: ['src/checks/lighthouse.ts'] },
+];
 // Il documento `latest` porta la sola versione pubblicata; quello del pacchetto intero pesa 8 MB.
-const REGISTRY = 'https://registry.npmjs.org/vercel/latest';
+const REGISTRY = 'https://registry.npmjs.org';
 const TIMEOUT_MS = 15_000;
+const read = (path) => ({ path, source: existsSync(path) ? readFileSync(path, 'utf8') : '' });
+async function latestOf(pkg) {
+    const response = await fetch(`${REGISTRY}/${pkg.replace('/', '%2f')}/latest`, {
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!response.ok)
+        return undefined;
+    const { version } = (await response.json());
+    return version;
+}
 export async function main() {
-    const response = await fetch(REGISTRY, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (!response.ok) {
-        console.error(`✗ registry npm illeggibile: HTTP ${response.status}`);
-        return 1;
+    const findings = [];
+    const published = [];
+    for (const { package: pkg, files } of PINNED) {
+        const latest = await latestOf(pkg);
+        if (latest === undefined) {
+            findings.push({ path: files[0], message: `registry npm illeggibile per \`${pkg}\``, severity: 'error' });
+            continue;
+        }
+        published.push(`${pkg}@${latest}`);
+        const sites = [read(files[0]), ...files.slice(1).map(read)];
+        findings.push(...pinFindings(pkg, latest, sites).map((hit) => ({ ...hit, severity: 'error' })));
     }
-    const { version } = (await response.json());
-    const findings = pinFindings(readFileSync(WORKFLOW, 'utf8'), version).map((hit) => ({
-        path: WORKFLOW,
-        ...hit,
-        severity: 'error',
-    }));
-    console.log(`\ncheck:vercel-cli — il pin contro la ${version} pubblicata su npm\n`);
+    console.log(`\ncheck:vercel-cli — i pin contro quello che npm pubblica (${published.join(', ')})\n`);
     printFindings(findings, cliOptions([]).format);
     console.log(findings.length === 0
-        ? '  Il pin è sulla major pubblicata.\n'
-        : `\n  Alza il pin in ${WORKFLOW} e allinea la CLI locale alla stessa major.\n`);
+        ? '  Ogni pin è esatto e sulla major pubblicata.\n'
+        : '\n  Alza i pin e allinea la CLI locale alla stessa versione.\n');
     return exitCode(findings, false);
 }
 if (import.meta.main)

package/dist/gen/hook-points.d.mts

@@ -0,0 +1,6 @@
+export declare class HookPointError extends Error {
+    path: any;
+    problem: any;
+    constructor(message: any, path: any, problem: any);
+}
+export declare const failing: (prefix: any, guide: any) => (path: any, problem: any) => never;

package/dist/gen/hook-points.mjs

@@ -0,0 +1,13 @@
+// Un ancoraggio rotto ha un percorso e un problema. Il pre-volo li impagina nel messaggio che
+// ferma il generatore; `doctor`, che gli stessi controlli li lancia senza generare niente, li
+// rimette in un ritrovamento.
+export class HookPointError extends Error {
+    constructor(message, path, problem) {
+        super(message);
+        this.path = path;
+        this.problem = problem;
+    }
+}
+export const failing = (prefix, guide) => (path, problem) => {
+    throw new HookPointError(`${prefix} in ${path}: ${problem} (contract: ${guide})`, path, problem);
+};